runwork 0.13.4 → 0.15.0

package/bundled-types/core-endpoints.d.ts

@@ -10,9 +10,16 @@ import { z } from 'zod';
 import type { Hono } from 'hono';
 type ZodSchema = z.ZodType<any, any, any>;
 /**
- * Authentication type for public endpoints
+ * Authentication requirement declared by an endpoint definition.
  */
 export type EndpointAuthType = 'apiKey' | 'public';
+/**
+ * Caller principal type resolved by the platform and passed via the
+ * `X-Public-Endpoint-Auth-Type` header. `user` and `workspace_key` are
+ * authenticated principals the platform has already authorized; `api_key`
+ * additionally carries a validated key id; `none` is unauthenticated.
+ */
+export type EndpointPrincipalType = 'none' | 'api_key' | 'workspace_key' | 'user';
 /**
  * HTTP methods supported by endpoints
  */
@@ -53,10 +60,14 @@ export interface EndpointContext<TQuery = Record<string, unknown>, TBody = unkno
  * Authentication information passed to handlers
  */
 export interface EndpointAuthInfo {
-    /** Authentication type used */
+    /** Authentication requirement declared by the endpoint */
     type: EndpointAuthType;
-    /** API key ID (if authenticated with API key) */
+    /** Resolved caller principal type (api_key, workspace_key, user, none) */
+    principalType?: EndpointPrincipalType;
+    /** API key ID (if authenticated with an API key) */
     apiKeyId?: string;
+    /** User ID (if authenticated as a workspace member) */
+    userId?: string;
     /** Scopes granted to the API key */
     scopes?: string[];
     /** Whether request is authenticated */
@@ -112,8 +123,9 @@ export declare function isEndpointDefinition(entry: unknown): entry is EndpointD
 export interface ParsedEndpointRequest {
     endpointId: string;
     appId: string;
-    authType: EndpointAuthType;
+    authType: EndpointPrincipalType;
     apiKeyId?: string;
+    userId?: string;
     scopes?: string[];
 }
 /**

package/dist/__tests__/install-scripts.test.js

@@ -165,6 +165,39 @@ describe('install.sh (end-to-end)', () => {
         const defaultBinary = join(workDir, '.runwork', 'bin', 'runwork');
         expect(existsSync(defaultBinary)).toBe(true);
     });
+    it('persists ~/.runwork/bin to a shell profile, idempotently, on a default install', async () => {
+        const linkDir = join(workDir, 'link');
+        const exportLine = 'export PATH="$HOME/.runwork/bin:$PATH"';
+        const marker = '# Added by Runwork CLI installer';
+        const profiles = ['.zshrc', '.bashrc', '.bash_profile', '.profile'].map((p) => join(workDir, p));
+        const read = (p) => (existsSync(p) ? readFileSync(p, 'utf-8') : '');
+        // First install with the default install dir ($HOME/.runwork/bin) triggers
+        // PATH persistence.
+        const r1 = await runInstallSh(envFor({ RUNWORK_BIN_LINK_DIR: linkDir }));
+        expect(r1.status, `installer failed:\n${r1.stdout}\n${r1.stderr}`).toBe(0);
+        const written = profiles.filter((p) => read(p).includes(exportLine));
+        expect(written.length, 'expected the export line in at least one profile').toBeGreaterThan(0);
+        expect(profiles.some((p) => read(p).includes(marker))).toBe(true);
+        // Re-running must NOT append a second time (guarded on .runwork/bin).
+        const r2 = await runInstallSh(envFor({ RUNWORK_BIN_LINK_DIR: linkDir }));
+        expect(r2.status).toBe(0);
+        for (const p of written) {
+            const occurrences = read(p).split('.runwork/bin').length - 1;
+            expect(occurrences, `profile ${p} should reference .runwork/bin exactly once`).toBe(1);
+        }
+    });
+    it('does NOT touch shell profiles when a custom RUNWORK_INSTALL_DIR is used', async () => {
+        const result = await runInstallSh(envFor({
+            RUNWORK_INSTALL_DIR: join(workDir, 'install'),
+            RUNWORK_BIN_LINK_DIR: join(workDir, 'link'),
+        }));
+        expect(result.status).toBe(0);
+        const profiles = ['.zshrc', '.bashrc', '.bash_profile', '.profile'].map((p) => join(workDir, p));
+        for (const p of profiles) {
+            if (existsSync(p))
+                expect(readFileSync(p, 'utf-8')).not.toContain('.runwork/bin');
+        }
+    });
     it('aborts on sha256 mismatch and leaves the install directory untouched', async () => {
         // Tamper with the archive the server is about to serve.
         writeFileSync(archivePath, Buffer.from('tampered payload'));

package/dist/agents/__tests__/chatgpt-registry.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/agents/__tests__/chatgpt-registry.test.js

@@ -0,0 +1,61 @@
+import { describe, it, expect } from 'vitest';
+import { getAgent, getAgentFamily, getFamilyAgents, isConnectOnlyAgent, isWebAgent, } from '../registry-data.js';
+describe('ChatGPT registry entries', () => {
+    it('registers both Web and Desktop entries', () => {
+        const web = getAgent('chatgpt');
+        const app = getAgent('chatgpt-app');
+        expect(web).toBeDefined();
+        expect(app).toBeDefined();
+        expect(web?.category).toBe('web');
+        expect(app?.category).toBe('desktop');
+        expect(web?.firstClass).toBe(true);
+        expect(app?.firstClass).toBe(true);
+    });
+    it('treats Web entry as always-available with a URL launch', () => {
+        const web = getAgent('chatgpt');
+        expect(web?.detection).toEqual({ method: 'always' });
+        expect(web?.launch?.url).toContain('chatgpt.com');
+        expect(isWebAgent('chatgpt')).toBe(true);
+        expect(isWebAgent('chatgpt-app')).toBe(false);
+    });
+    it('marks both entries connect-only (no local config paths)', () => {
+        for (const slug of ['chatgpt', 'chatgpt-app']) {
+            const agent = getAgent(slug);
+            expect(isConnectOnlyAgent(agent)).toBe(true);
+            expect(agent?.skillsPaths).toBeUndefined();
+            expect(agent?.mcpConfigPath).toBeUndefined();
+            expect(agent?.instructionFile).toBeUndefined();
+        }
+    });
+    it('does not mark file-backed agents as connect-only', () => {
+        expect(isConnectOnlyAgent(getAgent('claude-code'))).toBe(false);
+        expect(isConnectOnlyAgent(getAgent('codex'))).toBe(false);
+    });
+    it('groups both entries under one family', () => {
+        expect(getAgentFamily('chatgpt')).toBe('chatgpt');
+        expect(getAgentFamily('chatgpt-app')).toBe('chatgpt');
+        const family = getFamilyAgents('chatgpt').map((a) => a.slug).sort();
+        expect(family).toEqual(['chatgpt', 'chatgpt-app']);
+    });
+    it('falls back to the slug as family for standalone agents', () => {
+        expect(getAgentFamily('claude-code')).toBe('claude-code');
+        expect(getFamilyAgents('claude-code').map((a) => a.slug)).toEqual(['claude-code']);
+    });
+    it('provides team/personal manual-setup variants and a copyable MCP URL', () => {
+        for (const slug of ['chatgpt', 'chatgpt-app']) {
+            const setup = getAgent(slug)?.manualSetup;
+            expect(setup?.showAfter).toBe('connecting');
+            expect(setup?.copyValue?.token).toBe('{mcpUrl}');
+            const keys = setup?.variants?.map((v) => v.key).sort();
+            expect(keys).toEqual(['personal', 'team']);
+            // Every variant carries at least one step.
+            for (const variant of setup?.variants ?? []) {
+                expect(variant.steps.length).toBeGreaterThan(0);
+            }
+        }
+    });
+    it('uses url-prompt resume for connect-only ChatGPT entries', () => {
+        expect(getAgent('chatgpt')?.resumeCapability?.mode).toBe('url-prompt');
+        expect(getAgent('chatgpt-app')?.resumeCapability?.mode).toBe('url-prompt');
+    });
+});

package/dist/agents/__tests__/detection.test.js

@@ -83,4 +83,7 @@ describe('runAgentDetection', () => {
             ],
         })).toBe(false);
     });
+    it('always method reports true without any local probe (web-only agents)', async () => {
+        expect(await runAgentDetection({ method: 'always' })).toBe(true);
+    });
 });

package/dist/agents/claude-desktop-plugin-tree.js

@@ -1,6 +1,6 @@
 import { chmodSync, mkdirSync, rmSync, existsSync, writeFileSync } from 'fs';
 import { join } from 'path';
-import { appendTokenToUrl, buildSkillMd } from './types.js';
+import { appendTokenToUrl, buildSkillMd, RUNWORK_WORKSPACE_MCP_NAME } from './types.js';
 import { SESSION_START_HOOK_SCRIPT } from './session-start-hook.js';
 /**
  * Write <destDir>/.claude-plugin/plugin.json.
@@ -24,13 +24,28 @@ export function writePluginMcpConfig(destDir, mcpServers) {
     mkdirSync(destDir, { recursive: true });
     const mcpEntries = {};
     for (const server of mcpServers) {
-        const token = server.headers?.Authorization?.replace(/^Bearer\s+/i, '');
-        const connectorUrl = token ? appendTokenToUrl(server.url, token) : server.url;
-        mcpEntries[server.name] = {
-            type: 'http',
-            url: connectorUrl,
-            ...(server.description ? { description: server.description } : {}),
-        };
+        if (server.name === RUNWORK_WORKSPACE_MCP_NAME) {
+            // Preserve the exact, known-working behavior for the Runwork connector: embed
+            // the workspace key in the URL, no headers field. Claude Desktop's native
+            // connector did not reliably honor request headers here, which is why the token
+            // lives in the URL — do NOT change this.
+            const token = server.headers?.Authorization?.replace(/^Bearer\s+/i, '');
+            mcpEntries[server.name] = {
+                type: 'http',
+                url: token ? appendTokenToUrl(server.url, token) : server.url,
+                ...(server.description ? { description: server.description } : {}),
+            };
+        }
+        else {
+            // Third-party servers: forward the auth header map (same .mcp.json schema
+            // claude-code uses). Their secrets must NEVER be placed in the URL.
+            mcpEntries[server.name] = {
+                type: 'http',
+                url: server.url,
+                ...(server.headers ? { headers: server.headers } : {}),
+                ...(server.description ? { description: server.description } : {}),
+            };
+        }
     }
     writeFileSync(join(destDir, '.mcp.json'), JSON.stringify({ mcpServers: mcpEntries }, null, 2));
 }

package/dist/agents/claude-desktop.js

@@ -189,12 +189,15 @@ export class ClaudeDesktopAdapter {
         // For cowork connectors, embed the auth token in the URL query string.
         // This lets Claude Desktop connect without requiring the user to go through
         // an OAuth flow or manually click "Connect" in the Connectors UI.
-        // Write to claude_desktop_config.json via mcp-remote (chat mode fallback)
+        // Write to claude_desktop_config.json via mcp-remote (chat mode fallback).
+        // Forward every auth header (Authorization, X-Api-Key, etc.) as a --header arg.
         const entries = {};
         for (const s of servers) {
             const args = ['mcp-remote', s.url];
-            if (s.headers?.Authorization) {
-                args.push('--header', `Authorization:${s.headers.Authorization}`);
+            if (s.headers) {
+                for (const [name, value] of Object.entries(s.headers)) {
+                    args.push('--header', `${name}:${value}`);
+                }
             }
             entries[s.name] = {
                 command: 'npx',

package/dist/agents/codex.js

@@ -45,15 +45,23 @@ export class CodexAdapter {
                 delete mcpServers[key];
             }
         }
-        // Add new entries (sanitize names to match Codex's ^[a-zA-Z0-9_-]+$ requirement)
+        // Add new entries (sanitize names to match Codex's ^[a-zA-Z0-9_-]+$ requirement).
         for (const s of servers) {
             const safeName = s.name.replace(/[^a-zA-Z0-9_-]/g, '-').replace(/-+/g, '-').replace(/^-|-$/g, '');
-            // Embed auth token in URL so Codex doesn't need a separate env var
-            const token = s.headers?.Authorization?.replace(/^Bearer\s+/i, '');
-            const serverUrl = token ? appendTokenToUrl(s.url, token) : s.url;
-            mcpServers[safeName] = {
-                url: serverUrl,
-            };
+            const entry = { url: s.url };
+            if (s.name === RUNWORK_WORKSPACE_MCP_NAME) {
+                // Preserve the known-working behavior: embed the workspace key in the URL.
+                // Codex's header-based auth was historically unreliable here, so do NOT change it.
+                const token = s.headers?.Authorization?.replace(/^Bearer\s+/i, '');
+                if (token)
+                    entry.url = appendTokenToUrl(s.url, token);
+            }
+            else if (s.headers && Object.keys(s.headers).length > 0) {
+                // External servers: forward headers via Codex's documented http_headers field
+                // (static literal values). These had no prior working path, so this is additive.
+                entry.http_headers = s.headers;
+            }
+            mcpServers[safeName] = entry;
         }
         mkdirSync(join(configPath, '..'), { recursive: true });
         writeFileSync(configPath, stringify(parsed));

package/dist/agents/detection.js

@@ -85,6 +85,9 @@ export async function runAgentDetection(detection) {
             const probes = await Promise.all(detection.target.map((p) => runAgentDetection(p)));
             return probes.some(Boolean);
         }
+        case 'always':
+            // Web-only agents have no local footprint; always treated as available.
+            return true;
         default:
             return false;
     }

package/dist/agents/intro-skill.js

@@ -300,14 +300,14 @@ export function generateIntroSkill(ctx) {
     lines.push('| `runwork info --json` | Full workspace and app context |');
     lines.push('| `runwork init my-app` | Create a new app |');
     lines.push('| `runwork dev` | Start local development (watches files, syncs automatically) |');
-    lines.push('| `runwork deploy` | Deploy to production |');
+    lines.push('| `runwork deploy` | Deploy to production (`--detach` runs in the background to survive shell timeouts; `runwork deploy --status` polls the result) |');
     lines.push('| `runwork entities list` | Browse data across apps |');
     lines.push('| `runwork entities records <name>` | Query entity records |');
     lines.push('| `runwork workflows trigger <name>` | Trigger a workflow |');
     lines.push('| `runwork integrations call <id> <method> <path>` | Call an integration API |');
     lines.push('| `runwork integrations search <query>` | Search 3,200+ available integrations |');
     lines.push('| `runwork logs` | View app logs |');
-    lines.push('| `runwork doctor` | Check system health |');
+    lines.push('| `runwork doctor` | Check system health (`--fix` auto-remediates git auth/remote; `--check <names>` scopes output) |');
     lines.push('| `runwork setup` | Set up workspace connection and sync to agents |');
     lines.push('| `runwork sync` | Sync skills, MCP servers, and settings to local agents |');
     lines.push('');
@@ -323,6 +323,8 @@ export function generateIntroSkill(ctx) {
     lines.push('');
     lines.push('> By default, `runwork init` scaffolds into `~/.runwork/apps/<slug>` so every app has a predictable home. Pass `--here` to scaffold in the current directory instead.');
     lines.push('');
+    lines.push('> Clone/init into a normal working directory (e.g. under your home folder). Some sandboxed "outputs" mounts disallow the unlink operations git uses for pack files, which can corrupt the repo ("unable to unlink \'.git/objects/pack/...\': Operation not permitted"). If you hit that, switch to a standard path.');
+    lines.push('');
     lines.push('**CLI development workflow:**');
     lines.push('1. `runwork init my-app` -- scaffold the app (created at `~/.runwork/apps/my-app`)');
     lines.push('2. `cd ~/.runwork/apps/my-app` -- enter the app directory');
@@ -385,7 +387,7 @@ export function generateIntroSkill(ctx) {
     lines.push('- **Connect workspace:** `runwork login` then `runwork setup`');
     lines.push('- **Connect an integration:** Visit the workspace settings in the web dashboard at https://runwork.ai, or use `runwork integrations search <query>` to find services');
     lines.push('- **Web dashboard:** https://runwork.ai for visual management of everything');
-    lines.push('- **Troubleshoot:** `runwork doctor` checks system health; `runwork logs` shows app output');
+    lines.push('- **Troubleshoot:** `runwork doctor` checks system health (`runwork doctor --fix` auto-repairs git auth and the runwork remote); `runwork logs` shows app output');
     lines.push('');
     // References
     lines.push('### References');

package/dist/agents/registry-data.d.ts

@@ -8,7 +8,7 @@
  * Keep this file browser-safe: no `os`, `path`, `fs`, or other Node-only
  * imports. Node-only path resolvers live next to this file in `./registry.ts`.
  */
-export type AgentCategory = 'cli' | 'ide' | 'desktop' | 'extension';
+export type AgentCategory = 'cli' | 'ide' | 'desktop' | 'extension' | 'web';
 export type { PlatformString, Detection, InstallableTool } from '../tools/types.js';
 import type { InstallableTool, Detection, PlatformString } from '../tools/types.js';
 /** @deprecated use `Detection` from ../tools/types — kept as alias for back-compat. */
@@ -21,6 +21,13 @@ export interface AgentLaunch {
     };
     cli?: string;
     cliAcceptsPrompt?: boolean;
+    /**
+     * Web/URL launch target opened in the default browser. `{prompt}` is
+     * substituted with a URL-encoded prompt (e.g. ChatGPT's `?prompt=`), or
+     * stripped when no prompt is supplied. Used by web-only agents and as the
+     * fallback for desktop agents whose app is not installed.
+     */
+    url?: string;
 }
 export interface AgentQuickStart {
     launchHint?: string;
@@ -44,6 +51,28 @@ export interface AgentManualSetupArtifact {
 }
 /** Where a manual-setup step is inserted in the onboarding journey. */
 export type ManualSetupSlot = 'installation' | 'connecting' | 'try-it';
+/**
+ * A plan-conditional variant of a manual-setup checklist. When an agent's
+ * connector setup differs by account plan (e.g. ChatGPT Team vs Personal),
+ * each variant carries its own steps; the onboarding UI selects the variant
+ * matching the workspace's stored plan. Agents without plan branching omit
+ * `variants` and use the flat `steps`.
+ */
+export interface AgentManualSetupVariant {
+    key: 'team' | 'personal';
+    label: string;
+    title?: string;
+    steps: ManualSetupStep[];
+}
+/**
+ * A copy-to-clipboard value surfaced alongside the manual-setup steps. The
+ * onboarding UI substitutes `token` with a real value (e.g. `{mcpUrl}` →
+ * the workspace MCP URL) before rendering the copy control.
+ */
+export interface AgentManualSetupCopyValue {
+    label: string;
+    token: '{mcpUrl}';
+}
 export interface AgentManualSetup {
     title: string;
     steps: ManualSetupStep[];
@@ -51,6 +80,10 @@ export interface AgentManualSetup {
     /** Where in the journey to show this step. Defaults to 'try-it'. */
     showAfter?: ManualSetupSlot;
     downloadArtifact?: AgentManualSetupArtifact;
+    /** Plan-conditional step lists. When present, the UI renders the variant matching the workspace plan instead of `steps`. */
+    variants?: AgentManualSetupVariant[];
+    /** A value the user copies into the agent during setup (e.g. the workspace MCP URL). */
+    copyValue?: AgentManualSetupCopyValue;
 }
 /**
  * How a recipient can resume a shared conversation locally in this agent.
@@ -72,12 +105,18 @@ export interface AgentManualSetup {
  *                       paste-prompt path. Used for walled-garden agents like
  *                       Microsoft Copilot or Claude Desktop Chat mode.
  *
+ *   - 'url-prompt'      Open the agent's `launch.url` (or app) with a prefilled
+ *                       prompt that instructs the agent to fetch and continue
+ *                       the shared conversation via Runwork's MCP tools. Used by
+ *                       connect-only agents (ChatGPT) that have MCP access but no
+ *                       local session files to drop into.
+ *
  * Bundle placement logic (which directory, which filename) is per-agent and
  * lives in the resume command implementation, not here. This data field stays
  * declarative.
  */
 export interface AgentResumeCapability {
-    mode: 'cli-resume' | 'file-drop-only' | 'unsupported';
+    mode: 'cli-resume' | 'file-drop-only' | 'unsupported' | 'url-prompt';
     /** Bundle format this agent reads natively (must match a bundle's `format`). */
     nativeBundleFormat?: 'claude-jsonl' | 'codex-rollout' | string;
     /** Template for the resume command (cli-resume only). `{uuid}` is substituted with the share's session id. */
@@ -88,6 +127,13 @@ export interface AgentResumeCapability {
 export interface AgentDefinition extends InstallableTool {
     aliases?: string[];
     category: AgentCategory;
+    /**
+     * Family identifier grouping multiple entries that share one account/
+     * connector/OAuth identity (e.g. `chatgpt` + `chatgpt-app` → 'chatgpt').
+     * Drives the shared plan toggle, connect-step dedup, and family-level
+     * adoption. Undefined for standalone agents.
+     */
+    family?: string;
     /** Desktop launch hints (GUI app name, CLI command) */
     launch?: AgentLaunch;
     /** Whether the CLI knows how to auto-install this agent */
@@ -127,6 +173,17 @@ export declare function getAgentsByCategory(category: AgentCategory): AgentDefin
 export declare function isCLIAgent(slug: string): boolean;
 export declare function isIDEAgent(slug: string): boolean;
 export declare function isDesktopAgent(slug: string): boolean;
+export declare function isWebAgent(slug: string): boolean;
+/**
+ * Connect-only agents have no local footprint to write: no skills directory,
+ * no MCP config file, no instruction file. The connector lives in the user's
+ * account (e.g. ChatGPT). `runwork sync` skips these for all local writes.
+ */
+export declare function isConnectOnlyAgent(agent: AgentDefinition | undefined): boolean;
+/** Family identifier for an agent (e.g. 'chatgpt' for both ChatGPT entries), or its slug when standalone. */
+export declare function getAgentFamily(slug: string): string | undefined;
+/** All agents sharing the given family identifier. */
+export declare function getFamilyAgents(family: string): AgentDefinition[];
 /** Alias of {@link getAgent} kept for backward compatibility with CLI callers. */
 export declare const getRegistryAgent: typeof getAgent;
 /** Alias of {@link getAgents} kept for backward compatibility with CLI callers. */

package/dist/agents/registry-data.js

@@ -246,6 +246,158 @@ const AGENT_REGISTRY = [
             ],
         },
     },
+    {
+        // ChatGPT Web. Connect-only: no local files. Shares one account/connector/
+        // OAuth identity with `chatgpt-app` (family: 'chatgpt'). Launches in the
+        // browser; chatgpt.com supports `?prompt=` for open + resume.
+        slug: 'chatgpt',
+        name: 'ChatGPT (Web)',
+        aliases: ['ChatGPT'],
+        description: "OpenAI's ChatGPT in the browser, connected to your workspace via MCP",
+        category: 'web',
+        family: 'chatgpt',
+        detection: { method: 'always' },
+        launch: { url: 'https://chatgpt.com/?prompt={prompt}' },
+        logo: 'openai',
+        downloadUrl: 'https://chatgpt.com',
+        firstClass: true,
+        resumeCapability: {
+            mode: 'url-prompt',
+            manualOpenHint: 'Opens ChatGPT with a prompt that fetches and continues the shared conversation via your Runwork workspace tools.',
+        },
+        quickStart: {
+            launchHint: 'Open chatgpt.com',
+            examplePrompts: [
+                "What can my team's Runwork workspace do?",
+                "Check my team's recent activity",
+            ],
+        },
+        manualSetup: {
+            title: 'Connect Runwork in ChatGPT',
+            showAfter: 'connecting',
+            copyValue: { label: 'Workspace MCP URL', token: '{mcpUrl}' },
+            // Flat steps mirror the 'personal' variant as a safe fallback when no
+            // plan is resolved. The onboarding UI prefers `variants` by plan.
+            steps: [
+                { id: 'open', label: 'Open chatgpt.com and sign in' },
+                { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                { id: 'dev-mode', label: 'Click "Advanced settings" and turn on "Developer mode" (skip if it is already on)' },
+                { id: 'create-app', label: 'Go back to Apps and click "Create app"' },
+                { id: 'fill', label: 'In the New App dialog, set Name to "Runwork", keep Connection on "Server URL", and paste the Workspace MCP URL above into the Server URL field' },
+                { id: 'oauth', label: 'Leave Authentication set to "OAuth", check "I understand and want to continue", then click Create' },
+                { id: 'authorize', label: 'Complete the OAuth sign-in to authorize Runwork for your account' },
+                { id: 'confirm', label: 'In a new chat, ask "Do you have access to Runwork tools?" to confirm (or check Settings, then Apps, for Runwork)' },
+            ],
+            variants: [
+                {
+                    key: 'team',
+                    label: 'Team / Enterprise',
+                    title: 'Connect the Runwork app in ChatGPT',
+                    steps: [
+                        { id: 'open', label: 'Open chatgpt.com and sign in' },
+                        { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                        { id: 'find', label: 'Find the Runwork app published by your workspace admin and open it' },
+                        { id: 'connect', label: 'Click Connect and complete the OAuth sign-in to authorize Runwork' },
+                        { id: 'confirm', label: 'In a new chat, ask "Do you have access to Runwork tools?" to confirm (or check Settings, then Apps, for Runwork)' },
+                    ],
+                },
+                {
+                    key: 'personal',
+                    label: 'Personal',
+                    title: 'Create the Runwork connector in ChatGPT',
+                    steps: [
+                        { id: 'open', label: 'Open chatgpt.com and sign in' },
+                        { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                        { id: 'dev-mode', label: 'Click "Advanced settings" and turn on "Developer mode" (skip if it is already on)' },
+                        { id: 'create-app', label: 'Go back to Apps and click "Create app"' },
+                        { id: 'fill', label: 'In the New App dialog, set Name to "Runwork", keep Connection on "Server URL", and paste the Workspace MCP URL above into the Server URL field' },
+                        { id: 'oauth', label: 'Leave Authentication set to "OAuth", check "I understand and want to continue", then click Create' },
+                        { id: 'authorize', label: 'Complete the OAuth sign-in to authorize Runwork for your account' },
+                        { id: 'confirm', label: 'In a new chat, ask "Do you have access to Runwork tools?" to confirm (or check Settings, then Apps, for Runwork)' },
+                    ],
+                },
+            ],
+        },
+    },
+    {
+        // ChatGPT Desktop app. Connect-only (no local files); shares the same
+        // account/connector/OAuth identity as `chatgpt` Web. Launches the app,
+        // falling back to the web URL when the app is not installed.
+        slug: 'chatgpt-app',
+        name: 'ChatGPT Desktop',
+        description: "OpenAI's ChatGPT desktop app, connected to your workspace via MCP",
+        category: 'desktop',
+        family: 'chatgpt',
+        detection: {
+            method: 'any',
+            target: [
+                { method: 'path', target: { macos: '/Applications/ChatGPT.app' } },
+                { method: 'windows-appx', target: 'OpenAI.ChatGPT' },
+            ],
+        },
+        launch: { app: { macos: 'ChatGPT', windows: 'ChatGPT' }, url: 'https://chatgpt.com/?prompt={prompt}' },
+        logo: 'openai',
+        downloadUrl: 'https://chatgpt.com/download',
+        firstClass: true,
+        resumeCapability: {
+            mode: 'url-prompt',
+            manualOpenHint: 'Opens ChatGPT with a prompt that fetches and continues the shared conversation via your Runwork workspace tools.',
+        },
+        quickStart: {
+            launchHint: 'Open the ChatGPT desktop app',
+            examplePrompts: [
+                "What can my team's Runwork workspace do?",
+                "Check my team's recent activity",
+            ],
+        },
+        manualSetup: {
+            title: 'Connect Runwork in ChatGPT',
+            showAfter: 'connecting',
+            copyValue: { label: 'Workspace MCP URL', token: '{mcpUrl}' },
+            steps: [
+                { id: 'install', label: 'Install the ChatGPT desktop app from chatgpt.com/download if you have not already' },
+                { id: 'open-web', label: 'Connectors are created on chatgpt.com: open it in your browser and sign in' },
+                { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                { id: 'dev-mode', label: 'Click "Advanced settings" and turn on "Developer mode" (skip if it is already on)' },
+                { id: 'create-app', label: 'Go back to Apps and click "Create app"' },
+                { id: 'fill', label: 'In the New App dialog, set Name to "Runwork", keep Connection on "Server URL", and paste the Workspace MCP URL above into the Server URL field' },
+                { id: 'oauth', label: 'Leave Authentication set to "OAuth", check "I understand and want to continue", then click Create' },
+                { id: 'authorize', label: 'Complete the OAuth sign-in to authorize Runwork for your account' },
+                { id: 'confirm', label: 'Open the ChatGPT desktop app and, in a new chat, ask "Do you have access to Runwork tools?" to confirm' },
+            ],
+            variants: [
+                {
+                    key: 'team',
+                    label: 'Team / Enterprise',
+                    title: 'Connect the Runwork app in ChatGPT',
+                    steps: [
+                        { id: 'install', label: 'Install the ChatGPT desktop app from chatgpt.com/download if you have not already' },
+                        { id: 'open', label: 'Open the ChatGPT desktop app and sign in' },
+                        { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                        { id: 'find', label: 'Find the Runwork app published by your workspace admin and open it' },
+                        { id: 'connect', label: 'Click Connect and complete the OAuth sign-in to authorize Runwork' },
+                        { id: 'confirm', label: 'In a new chat, ask "Do you have access to Runwork tools?" to confirm (or check Settings, then Apps, for Runwork)' },
+                    ],
+                },
+                {
+                    key: 'personal',
+                    label: 'Personal',
+                    title: 'Create the Runwork connector in ChatGPT',
+                    steps: [
+                        { id: 'install', label: 'Install the ChatGPT desktop app from chatgpt.com/download if you have not already' },
+                        { id: 'open-web', label: 'Connectors are created on chatgpt.com: open it in your browser and sign in' },
+                        { id: 'settings-apps', label: 'Open the profile menu (bottom-left), then Settings, then Apps' },
+                        { id: 'dev-mode', label: 'Click "Advanced settings" and turn on "Developer mode" (skip if it is already on)' },
+                        { id: 'create-app', label: 'Go back to Apps and click "Create app"' },
+                        { id: 'fill', label: 'In the New App dialog, set Name to "Runwork", keep Connection on "Server URL", and paste the Workspace MCP URL above into the Server URL field' },
+                        { id: 'oauth', label: 'Leave Authentication set to "OAuth", check "I understand and want to continue", then click Create' },
+                        { id: 'authorize', label: 'Complete the OAuth sign-in to authorize Runwork for your account' },
+                        { id: 'confirm', label: 'Open the ChatGPT desktop app and, in a new chat, ask "Do you have access to Runwork tools?" to confirm' },
+                    ],
+                },
+            ],
+        },
+    },
     {
         slug: 'windsurf',
         name: 'Windsurf',
@@ -481,6 +633,30 @@ export function isIDEAgent(slug) {
 export function isDesktopAgent(slug) {
     return getAgent(slug)?.category === 'desktop';
 }
+export function isWebAgent(slug) {
+    return getAgent(slug)?.category === 'web';
+}
+/**
+ * Connect-only agents have no local footprint to write: no skills directory,
+ * no MCP config file, no instruction file. The connector lives in the user's
+ * account (e.g. ChatGPT). `runwork sync` skips these for all local writes.
+ */
+export function isConnectOnlyAgent(agent) {
+    if (!agent)
+        return false;
+    return !agent.skillsPaths && !agent.mcpConfigPath && !agent.instructionFile;
+}
+/** Family identifier for an agent (e.g. 'chatgpt' for both ChatGPT entries), or its slug when standalone. */
+export function getAgentFamily(slug) {
+    const agent = getAgent(slug);
+    if (!agent)
+        return undefined;
+    return agent.family ?? agent.slug;
+}
+/** All agents sharing the given family identifier. */
+export function getFamilyAgents(family) {
+    return AGENT_REGISTRY.filter((a) => (a.family ?? a.slug) === family);
+}
 /** Alias of {@link getAgent} kept for backward compatibility with CLI callers. */
 export const getRegistryAgent = getAgent;
 /** Alias of {@link getAgents} kept for backward compatibility with CLI callers. */

package/dist/api/client.d.ts

@@ -141,6 +141,11 @@ export declare class ApiClient {
         transport: 'sse' | 'streamable-http';
     }): Promise<McpServerConfig>;
     removeMcpServer(workspaceId: string, serverId: string): Promise<void>;
+    /**
+     * Resolve decrypted auth headers for header-auth MCP servers, scoped to the
+     * authenticated user (their own + workspace-wide credentials). Keyed by server id.
+     */
+    resolveMcpCredentials(workspaceId: string): Promise<Record<string, Record<string, string>>>;
     searchCommunitySkills(query: string, limit?: number, includeContent?: boolean): Promise<{
         query: string;
         count: number;

package/dist/api/client.js

@@ -194,6 +194,14 @@ export class ApiClient {
     async removeMcpServer(workspaceId, serverId) {
         await this.request(`/api/workspaces/${workspaceId}/mcp-servers/${serverId}`, { method: 'DELETE' });
     }
+    /**
+     * Resolve decrypted auth headers for header-auth MCP servers, scoped to the
+     * authenticated user (their own + workspace-wide credentials). Keyed by server id.
+     */
+    async resolveMcpCredentials(workspaceId) {
+        const res = await this.request(`/api/workspaces/${workspaceId}/mcp-credentials/resolved`);
+        return res.data.servers;
+    }
     // --- Community Marketplace ---
     async searchCommunitySkills(query, limit = 10, includeContent = false) {
         const res = await this.request(`/api/community/skills/search?q=${encodeURIComponent(query)}&limit=${limit}&include_content=${includeContent}`);