Mason/agent auth (#152)

* Add Agent Auth documentation

Add documentation for the Agent Auth feature including overview, hosted UI, programmatic usage, credentials management, session monitoring, and early preview information. Also adds MCP CLI reference to docs.json.

* Update status values in Agent Auth documentation to use uppercase constants for consistency and clarity

* docs: Remove "NEW" badges from feature list

* Update Agent Auth documentation to use uppercase status constants for consistency across all sections

* docs(agent-auth): add auto-login and update flows

* docs(agent-auth): update target_domain to domain param

* docs(agent-auth): update wording on credential exposure

* docs(session-monitoring): update diagrams and tips

* docs(credentials): document TOTP secret for 2FA

* docs(credentials): Add 2FA setup instructions with TOTP

* docs: Update agent auth docs structure

* docs: Rewrite and condense Agent Auth overview

* docs(auth): update docs for new invocation flow (#155)

* docs(auth): update docs for new invocation flow

* docs: Add section on updating existing credentials

* docs(agent-auth): update status handling examples

* docs(auth): move files to agents/auth directory

* docs(auth): update and clarify auth agent docs

* docs(auth): update early preview SDK URLs

* docs(auth): add SSO and external action docs

* docs(auth): update preview SDK and Python URLs

* docs(auth): reorganize and update authentication documentation

- Renamed "Agents" group to "Agent Auth" in docs.json for clarity.
- Removed the "Auto-Login" section from early preview documentation as it is now covered in the main docs.
- Updated "Credentials" section to reflect the new "Credentials Vault" terminology and streamlined content.
- Consolidated and clarified the "Hosted UI" documentation to emphasize its role in user authentication.
- Removed the "Session Monitoring" documentation as it is no longer relevant.
- Enhanced overall structure and readability of the authentication documentation.

* docs(auth): enhance authentication documentation with code examples and clarity

- Updated "Credentials" section to simplify language and improve clarity on automated authentication.
- Revised "Hosted UI" documentation to include clearer code examples for creating auth agents and handling login flows.
- Streamlined the "Programmatic" flow section, consolidating steps and providing comprehensive code snippets for better understanding.
- Improved overall structure and readability across all sections to facilitate easier navigation and comprehension.

* docs: Update SDK dependency URLs in guide

* Refactor Agent Auth docs: simplify framing and examples

- Change framing to 'Create authenticated browser sessions for your automations'
- Simplify polling examples to single unified loop pattern
- Add CodeGroups with TypeScript + Python for all code examples
- Remove jargon (form discovery, idempotent, etc.)
- Add SSO/OAuth and TOTP sections to credentials.mdx
- Use realistic domains (netflix, linkedin, github, doordash)
- Recommend Hosted UI as primary integration path

* docs(auth): update preview SDK install URLs

* docs(auth): update SDK preview URLs in docs

* Restructure auth docs: move from agents/auth/ to auth/agent/

- Move agent auth docs from agents/auth/ to auth/agent/ directory
- Move credentials to auth/credentials.mdx (sibling to agent/)
- Update docs.json navigation paths
- Add post_login_url documentation in Adding Features section
- Update examples to show page.goto() usage for clarity

* Update early preview SDK versions to 0.26.0

* Add Go SDK installation instructions (v0.26.0) to early preview

* Fix Go SDK module name to github.com/kernel/kernel-go-sdk

* docs(1password): add 1Password integration guide

* docs: Update SDK versions in early preview guide

* docs: Update API Reference OpenAPI spec URL

* docs: Update API URL to use HTTPS

Author: masnwilliams

auth/agent/early-preview.mdx

@@ -0,0 +1,68 @@
+---
+title: "Early Preview"
+description: "Agent Auth early preview documentation"
+---
+
+<Info>
+Agent Auth is now documented in the main docs. See the pages below for current documentation.
+</Info>
+
+<CardGroup cols={2}>
+  <Card title="Overview" icon="book" href="/auth/agent/overview">
+    Introduction to Agent Auth and key concepts
+  </Card>
+  <Card title="Hosted UI" icon="browser" href="/auth/agent/hosted-ui">
+    Redirect users to complete login themselves
+  </Card>
+  <Card title="Programmatic" icon="code" href="/auth/agent/programmatic">
+    Build custom auth flows with full control
+  </Card>
+  <Card title="Credentials" icon="key" href="/auth/credentials">
+    Store credentials for automated re-auth
+  </Card>
+</CardGroup>
+
+## Early Preview SDK Installation
+
+For early preview testers, install the preview SDK:
+
+**TypeScript/Node.js:**
+
+```json
+{
+  "dependencies": {
+    "@onkernel/sdk": "0.27.0"
+  }
+}
+```
+
+**Python (requirements.txt):**
+
+```
+kernel==0.27.0
+```
+
+Or in pyproject.toml:
+
+```toml
+[project]
+dependencies = [
+    "kernel==0.27.0",
+]
+```
+
+**Go:**
+
+```bash
+go get -u 'github.com/kernel/kernel-go-sdk@v0.27.0'
+```
+
+Or in go.mod:
+
+```go
+require github.com/kernel/kernel-go-sdk v0.27.0
+```
+
+## Support
+
+Questions or issues? Reach out to us on Slack!

auth/agent/hosted-ui.mdx

@@ -0,0 +1,308 @@
+---
+title: "Hosted UI"
+description: "The simplest way to create authenticated browser sessions"
+---
+
+Collect credentials via Kernel's hosted page, then use the authenticated session in your automations. This is the recommended approach for most applications.
+
+Use the Hosted UI when:
+- You need users to provide their credentials
+- You want the simplest integration with minimal code
+- You want Kernel to handle 2FA and multi-step login flows
+
+## Getting started
+
+### 1. Create an Auth Agent
+
+An Auth Agent represents a login session for a specific website and profile.
+
+<CodeGroup>
+```typescript TypeScript
+const agent = await kernel.agents.auth.create({
+  domain: 'linkedin.com',
+  profile_name: 'linkedin-profile',
+});
+```
+
+```python Python
+agent = await kernel.agents.auth.create(
+    domain="linkedin.com",
+    profile_name="linkedin-profile",
+)
+```
+</CodeGroup>
+
+### 2. Start Authentication
+
+Create an invocation to get the hosted login URL.
+
+<CodeGroup>
+```typescript TypeScript
+const invocation = await kernel.agents.auth.invocations.create({
+  auth_agent_id: agent.id,
+});
+```
+
+```python Python
+invocation = await kernel.agents.auth.invocations.create(
+    auth_agent_id=agent.id,
+)
+```
+</CodeGroup>
+
+### 3. Collect Credentials
+
+Send the user to the hosted login page:
+
+<CodeGroup>
+```typescript TypeScript
+window.location.href = invocation.hosted_url;
+```
+
+```python Python
+# Return the URL to your frontend
+print(f"Redirect to: {invocation.hosted_url}")
+```
+</CodeGroup>
+
+The user will:
+1. See the login page for the target website
+2. Enter their credentials
+3. Complete 2FA if needed
+
+### 4. Poll for Completion
+
+On your backend, poll until authentication completes:
+
+<CodeGroup>
+```typescript TypeScript
+let state = await kernel.agents.auth.invocations.retrieve(invocation.invocation_id);
+
+while (state.status === 'IN_PROGRESS') {
+  await new Promise(r => setTimeout(r, 2000));
+  state = await kernel.agents.auth.invocations.retrieve(invocation.invocation_id);
+}
+
+if (state.status === 'SUCCESS') {
+  console.log('Authentication successful!');
+}
+```
+
+```python Python
+state = await kernel.agents.auth.invocations.retrieve(invocation.invocation_id)
+
+while state.status == "IN_PROGRESS":
+    await asyncio.sleep(2)
+    state = await kernel.agents.auth.invocations.retrieve(invocation.invocation_id)
+
+if state.status == "SUCCESS":
+    print("Authentication successful!")
+```
+</CodeGroup>
+
+<Info>
+Poll every 2 seconds. The session expires after 5 minutes if not completed.
+</Info>
+
+### 5. Use the Profile
+
+Create browsers with the profile and navigate to the site—the session is already authenticated:
+
+<CodeGroup>
+```typescript TypeScript
+const browser = await kernel.browsers.create({
+  profile: { name: 'linkedin-profile' },
+  stealth: true,
+});
+
+// Navigate to the site—you're already logged in
+await page.goto('https://linkedin.com');
+```
+
+```python Python
+browser = await kernel.browsers.create(
+    profile={"name": "linkedin-profile"},
+    stealth=True,
+)
+
+# Navigate to the site—you're already logged in
+await page.goto("https://linkedin.com")
+```
+</CodeGroup>
+
+<Info>
+Use `stealth: true` when creating browsers for authenticated sessions.
+</Info>
+
+
+## Complete Example
+
+<CodeGroup>
+```typescript TypeScript
+import Kernel from '@onkernel/sdk';
+
+const kernel = new Kernel();
+
+// Create auth agent
+const agent = await kernel.agents.auth.create({
+  domain: 'doordash.com',
+  profile_name: 'doordash-user-123',
+});
+
+// Start authentication
+const invocation = await kernel.agents.auth.invocations.create({
+  auth_agent_id: agent.id,
+});
+
+// Send user to hosted page
+console.log('Login URL:', invocation.hosted_url);
+
+// Poll for completion
+let state = await kernel.agents.auth.invocations.retrieve(invocation.invocation_id);
+while (state.status === 'IN_PROGRESS') {
+  await new Promise(r => setTimeout(r, 2000));
+  state = await kernel.agents.auth.invocations.retrieve(invocation.invocation_id);
+}
+
+if (state.status === 'SUCCESS') {
+  const browser = await kernel.browsers.create({
+    profile: { name: 'doordash-user-123' },
+    stealth: true,
+  });
+  
+  // Navigate to the site—you're already logged in
+  await page.goto('https://doordash.com');
+}
+```
+
+```python Python
+from kernel import Kernel
+import asyncio
+
+kernel = Kernel()
+
+# Create auth agent
+agent = await kernel.agents.auth.create(
+    domain="doordash.com",
+    profile_name="doordash-user-123",
+)
+
+# Start authentication
+invocation = await kernel.agents.auth.invocations.create(
+    auth_agent_id=agent.id,
+)
+
+# Send user to hosted page
+print(f"Login URL: {invocation.hosted_url}")
+
+# Poll for completion
+state = await kernel.agents.auth.invocations.retrieve(invocation.invocation_id)
+while state.status == "IN_PROGRESS":
+    await asyncio.sleep(2)
+    state = await kernel.agents.auth.invocations.retrieve(invocation.invocation_id)
+
+if state.status == "SUCCESS":
+    browser = await kernel.browsers.create(
+        profile={"name": "doordash-user-123"},
+        stealth=True,
+    )
+    
+    # Navigate to the site—you're already logged in
+    await page.goto("https://doordash.com")
+```
+</CodeGroup>
+
+## Adding Features
+
+The basic flow above gets you started. Add these features as needed:
+
+### Save Credentials for Auto-Reauth
+
+Capture the user's credentials during login so future sessions can re-authenticate automatically when the session expires:
+
+<CodeGroup>
+```typescript TypeScript
+const invocation = await kernel.agents.auth.invocations.create({
+  auth_agent_id: agent.id,
+  save_credential_as: 'my-saved-creds',
+});
+```
+
+```python Python
+invocation = await kernel.agents.auth.invocations.create(
+    auth_agent_id=agent.id,
+    save_credential_as="my-saved-creds",
+)
+```
+</CodeGroup>
+
+After successful login, future invocations for this agent will automatically use the saved credentials—no user interaction needed. See [Credentials](/auth/credentials) for more on automated authentication.
+
+### Custom Login URL
+
+If the site's login page isn't at the default location, specify it when creating the agent:
+
+<CodeGroup>
+```typescript TypeScript
+const agent = await kernel.agents.auth.create({
+  domain: 'example.com',
+  profile_name: 'my-profile',
+  login_url: 'https://example.com/auth/signin',
+});
+```
+
+```python Python
+agent = await kernel.agents.auth.create(
+    domain="example.com",
+    profile_name="my-profile",
+    login_url="https://example.com/auth/signin",
+)
+```
+</CodeGroup>
+
+### SSO/OAuth Support
+
+For sites with "Sign in with Google/GitHub/Microsoft", add the OAuth provider's domains to `allowed_domains`:
+
+<CodeGroup>
+```typescript TypeScript
+const agent = await kernel.agents.auth.create({
+  domain: 'example.com',
+  profile_name: 'my-profile',
+  allowed_domains: ['accounts.google.com', 'google.com'],
+});
+```
+
+```python Python
+agent = await kernel.agents.auth.create(
+    domain="example.com",
+    profile_name="my-profile",
+    allowed_domains=["accounts.google.com", "google.com"],
+)
+```
+</CodeGroup>
+
+The user can click the SSO button on the hosted page, complete OAuth with the provider, and the authenticated session is saved to the profile.
+
+### Post-Login URL
+
+After successful authentication, retrieve the auth agent to get `post_login_url`—the page where the login landed. Use this to start your automation from the right place:
+
+<CodeGroup>
+```typescript TypeScript
+const authAgent = await kernel.agents.auth.retrieve(agent.id);
+
+if (authAgent.post_login_url) {
+  await page.goto(authAgent.post_login_url);
+  // Start automation from the dashboard/home page
+}
+```
+
+```python Python
+auth_agent = await kernel.agents.auth.retrieve(agent.id)
+
+if auth_agent.post_login_url:
+    await page.goto(auth_agent.post_login_url)
+    # Start automation from the dashboard/home page
+```
+</CodeGroup>