@tangle-network/chatgpt-agents-kit 0.1.0 → 0.1.1

package/dist/skills/operate-existing-agent/SKILL.md

@@ -3,10 +3,12 @@ name: operate-existing-agent
 description: Connect an existing Tangle agent, hand over reviewed work, and retrieve actual outputs without changing its identity or workspace.
 ---
 
-Call agent_profile and agent_capabilities before doing work. Treat tools/list as
-the authority for this app and this account. Do not invent an endpoint or fall
-back to a broader credential when an action is missing. Never request API keys,
-cookies, bearer tokens or provider credentials in chat.
+Call agent_profile and agent_capabilities before doing work.
+Treat tools/list and its schemas as the tool discovery authority.
+agent_capabilities describes permissions available under the current grant.
+An action omitted there can still be advertised for additional consent.
+Tools absent from tools/list stay unavailable.
+Never invent endpoints or request API keys, cookies, bearer tokens, or provider credentials in chat.
 
 Offer “Connect my agent”. List accessible agents, then use the exact existing
 workspaceId and threadId the user selects. Reconnect using those same IDs; do not
@@ -36,6 +38,17 @@ list delegate_task use that name and its brief argument. Do not offer both as
 separate ways to run an agent. Use the saved target and a fresh UUID turnId for a
 new instruction; pass the connect_my_agent contextVersion when supported. Do not
 force a file handoff for an ordinary prompt or a retained text answer.
+
+For an explicitly requested task, invoke the advertised prompt tool with the approved target and input, following normal tool confirmation.
+Do this even when agent_capabilities omits it because the current grant lacks its advertised scopes.
+An mcp/www_authenticate challenge means permission is required; it is not task admission.
+Present the client's normal reconnect or consent flow and explain that permission to run the agent is needed.
+Wait for the user's consent; never approve it or substitute credentials.
+If consent is declined, fails, or remains pending, retain the task intent and report that state.
+After consent, refresh agent_profile and agent_capabilities, then reconnect the same target and verify its native identity.
+Continue only when the refreshed authority permits the requested action.
+Preserve the original target, turnId, and instruction through consent; the client may already have retried the tool.
+
 Reuse that UUID only for a retry of the identical prompt. Check get_task before
 retrying uncertain admission. A queued, accepted, working or input-required
 receipt is not completed work. Wait for retained terminal evidence; report

package/dist/src/card-output-schemas.d.ts

@@ -0,0 +1,18 @@
+export declare const cardOutputSchemas: {
+    readonly list_my_agents: {
+        type: string;
+        anyOf: object[];
+    };
+    readonly connect_my_agent: {
+        type: string;
+        anyOf: object[];
+    };
+    readonly prompt_agent: {
+        type: string;
+        anyOf: object[];
+    };
+    readonly get_task: {
+        type: string;
+        anyOf: object[];
+    };
+};

package/dist/src/card-output-schemas.js

@@ -0,0 +1,43 @@
+// Exact successful shapes from this kit's existing native tool dispatcher.
+// Errors keep their existing structuredContent envelope and are described too.
+const string = { type: 'string' };
+const integer = { type: 'integer' };
+const boolean = { type: 'boolean' };
+const target = { workspaceId: string, threadId: string };
+const environment = { type: 'object', properties: { kind: { const: 'persistent-sandbox' }, sandboxId: string,
+        sessionId: string, instanceKey: string, generation: integer, profileVersion: { type: ['string', 'null'] },
+        filesystemIncarnationId: string }, required: ['kind', 'sandboxId', 'sessionId'], additionalProperties: false };
+const file = { type: 'object', properties: { path: string, content: string, revision: string, mediaType: string,
+        sha256: string, bytes: integer }, required: ['path', 'content', 'revision', 'mediaType', 'sha256', 'bytes'], additionalProperties: false };
+const response = { type: 'object', properties: { content: string, mediaType: string, sha256: string, bytes: integer },
+    required: ['content', 'mediaType', 'sha256', 'bytes'], additionalProperties: false };
+const continuation = { type: 'object', properties: { tool: { const: 'get_task' }, arguments: { type: 'object',
+            properties: { ...target, turnId: string }, required: ['workspaceId', 'threadId', 'turnId'], additionalProperties: false },
+        resubmit: { const: false } }, required: ['tool', 'arguments', 'resubmit'], additionalProperties: false };
+const notification = { type: 'object', properties: { state: { const: 'not_subscribed' }, name: { const: 'agent.task_updated' },
+        arguments: { type: 'object', properties: { ...target, turnId: string },
+            required: ['workspaceId', 'threadId', 'turnId'], additionalProperties: false } },
+    required: ['state', 'name', 'arguments'], additionalProperties: false };
+const failure = { type: 'object', properties: { error: { type: 'object', properties: { code: string, status: integer,
+                admission: { const: 'not-started' }, recovery: { type: 'object', properties: { tool: { const: 'get_task' },
+                        arguments: { type: 'object', properties: { ...target, turnId: string },
+                            required: ['workspaceId', 'threadId', 'turnId'], additionalProperties: false }, resubmit: { const: false } },
+                    required: ['tool', 'arguments', 'resubmit'], additionalProperties: false } },
+            required: ['code', 'status'], additionalProperties: false } }, required: ['error'], additionalProperties: false };
+const tool = (success) => ({ type: 'object', anyOf: [success, failure] });
+const task = { type: 'object', properties: { ...target, turnId: string, executionId: string,
+        state: { enum: ['queued', 'working', 'input-required', 'succeeded', 'failed', 'cancelled', 'unknown'] },
+        source: string, environment, completionVerified: boolean, reason: string, completedAt: string,
+        response, outputs: { type: 'array', items: file }, continuation, notification },
+    required: ['workspaceId', 'threadId', 'turnId', 'state', 'source', 'completionVerified'], additionalProperties: false };
+export const cardOutputSchemas = {
+    list_my_agents: tool({ type: 'object', properties: { appName: string, identityId: string,
+            agents: { type: 'array', items: { type: 'object', properties: { workspaceId: string, name: string, threadId: string },
+                    required: ['workspaceId', 'name'], additionalProperties: false } } },
+        required: ['appName', 'identityId', 'agents'], additionalProperties: false }),
+    connect_my_agent: tool({ type: 'object', properties: { appName: string, identityId: string, ...target,
+            agentRef: string, contextVersion: string, continuity: { enum: ['persistent-sandbox', 'host-defined'] }, environment },
+        required: ['appName', 'identityId', 'workspaceId', 'threadId', 'agentRef', 'contextVersion', 'continuity'], additionalProperties: false }),
+    prompt_agent: tool(task),
+    get_task: tool(task),
+};

package/dist/src/cards.d.ts

@@ -0,0 +1,9 @@
+/** Optional, prebundled MCP Apps resource. No tokens or native clients belong here. */
+export interface AgentCardsResource {
+    html: string;
+    /** A dedicated HTTPS origin, required for hosted ChatGPT submissions. */
+    domain?: string;
+}
+export declare const AGENT_CARDS_URI = "ui://tangle-agents/cards.html";
+export declare const AGENT_CARDS_MIME = "text/html;profile=mcp-app";
+export declare const AGENT_CARD_TOOLS: readonly ["list_my_agents", "connect_my_agent", "prompt_agent", "get_task"];

package/dist/src/cards.js

@@ -0,0 +1,3 @@
+export const AGENT_CARDS_URI = 'ui://tangle-agents/cards.html';
+export const AGENT_CARDS_MIME = 'text/html;profile=mcp-app';
+export const AGENT_CARD_TOOLS = ['list_my_agents', 'connect_my_agent', 'prompt_agent', 'get_task'];

package/dist/src/kit.d.ts

@@ -1,3 +1,4 @@
+import { type AgentCardsResource } from './cards.ts';
 import { type AgentAppDescription } from './app-metadata.ts';
 import type { NativeBinding, NativeMcpFactory, OAuthResource, Principal } from './contracts.ts';
 import type { InspectionBinding } from './inspection.ts';
@@ -17,5 +18,7 @@ export declare function createAgentsHandler(options: {
     taskWait?: TaskWaitPolicy;
     /** Optional durable event adapter, bound to this host's native grant store and worker. */
     events?: TaskEvents;
+    /** Optional MCP Apps renderer. Omit to retain the tools-only protocol. */
+    cards?: AgentCardsResource;
     allowedOrigins?: readonly string[];
 }): (request: Request) => Promise<Response>;

package/dist/src/kit.js

@@ -1,3 +1,5 @@
+import { AGENT_CARDS_URI, AGENT_CARDS_MIME, AGENT_CARD_TOOLS } from "./cards.js";
+import { cardOutputSchemas } from "./card-output-schemas.js";
 import { agentAppDiscovery, defineAgentAppMetadata } from "./app-metadata.js";
 import { AgentFailure } from "./contracts.js";
 import { ACTION_TOOLS as names, HANDOFF_ACTIONS, describeAgentWorkflows } from "./workflows.js";
@@ -6,6 +8,12 @@ import { observeTask, taskWaitPolicy, validateNativeTask } from "./task-wait.js"
 import { describeConnection, digest, projectEnvironment } from "./connection.js";
 export { digest } from "./connection.js";
 const failureMarker = Symbol('native-tool-failure');
+/** Only kit checks completed before native admission may permit reconnect and retry. */
+class PreAdmissionFailure extends AgentFailure {
+    constructor(error) {
+        super(error instanceof AgentFailure ? error.message : 'native_operation_failed', error instanceof AgentFailure ? error.status : 503);
+    }
+}
 /** An error after entering native admission must retain its reconciliation handle. */
 class AdmissionFailure extends AgentFailure {
     recovery;
@@ -184,24 +192,29 @@ async function run(action, args, binding, revalidate, signal, policy, canReadTas
             break;
         }
         case 'delegate': {
-            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(args.turnId))
-                throw new AgentFailure('turn_id_must_be_uuid');
-            // Validate observation authorization BEFORE admitting work. A denied wait must not create a task.
-            if (Math.min(args.waitMs ?? policy.defaultMs, policy.maxMs) > 0) {
-                if (!canReadTask)
-                    throw new AgentFailure('task_read_scope_required', 403);
-                await binding.authorize(target, 'task');
-                await revalidate();
+            try {
+                if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(args.turnId))
+                    throw new AgentFailure('turn_id_must_be_uuid');
+                // Validate observation authorization BEFORE admitting work. A denied wait must not create a task.
+                if (Math.min(args.waitMs ?? policy.defaultMs, policy.maxMs) > 0) {
+                    if (!canReadTask)
+                        throw new AgentFailure('task_read_scope_required', 403);
+                    await binding.authorize(target, 'task');
+                    await revalidate();
+                }
+                if (args.contextVersion !== undefined) {
+                    if (!canConnect)
+                        throw new AgentFailure('connect_scope_required', 403);
+                    await binding.authorize(target, 'connect');
+                    await revalidate();
+                    if ((await describeConnection(await s.connect(target))).contextVersion !== args.contextVersion)
+                        throw new AgentFailure('agent_context_changed_reconnect_required', 409);
+                    await binding.authorize(target, 'delegate');
+                    await revalidate();
+                }
             }
-            if (args.contextVersion !== undefined) {
-                if (!canConnect)
-                    throw new AgentFailure('connect_scope_required', 403);
-                await binding.authorize(target, 'connect');
-                await revalidate();
-                if ((await describeConnection(await s.connect(target))).contextVersion !== args.contextVersion)
-                    throw new AgentFailure('agent_context_changed_reconnect_required', 409);
-                await binding.authorize(target, 'delegate');
-                await revalidate();
+            catch (error) {
+                throw new PreAdmissionFailure(error);
             }
             try {
                 const task = await s.startTask(target, args.turnId, args.prompt, args.contextVersion === undefined ? undefined : { contextVersion: args.contextVersion });
@@ -422,7 +435,7 @@ export function createAgentsHandler(options) {
                     || (typeof params.name === 'string' && request.headers.get('mcp-name') !== params.name))
                     return rpcResult({ error: { code: -32600, message: 'MCP routing headers do not match request' } });
                 if (parsed.method === 'server/discover')
-                    return rpcResult({ result: { resultType: 'complete', supportedVersions: ['2026-07-28'], serverInfo: { name: metadata.name, version: '0.1.0' }, capabilities: { tools: {}, ...(eventsEnabled ? { events: {} } : {}) } } });
+                    return rpcResult({ result: { resultType: 'complete', supportedVersions: ['2026-07-28'], serverInfo: { name: metadata.name, version: '0.1.0' }, capabilities: { tools: {}, ...(options.cards ? { resources: {} } : {}), ...(eventsEnabled ? { events: {} } : {}) } } });
             }
             if (parsed.method.startsWith('events/')) {
                 if (!v2 || !eventsEnabled)
@@ -436,6 +449,16 @@ export function createAgentsHandler(options) {
                 }
                 return rpcResult(result);
             }
+            if (options.cards && (parsed.method === 'resources/list' || parsed.method === 'resources/read')) {
+                const descriptor = { uri: AGENT_CARDS_URI, name: 'agent-cards', title: `${metadata.displayName} agents`, mimeType: AGENT_CARDS_MIME };
+                if (parsed.method === 'resources/list')
+                    return rpcResult({ result: { resources: [descriptor], ...(v2 ? { resultType: 'complete' } : {}) } });
+                if (!record(parsed.params) || parsed.params.uri !== AGENT_CARDS_URI)
+                    return rpcResult({ error: { code: -32002, message: 'Resource not found' } });
+                return rpcResult({ result: { contents: [{ ...descriptor, text: options.cards.html,
+                                _meta: { ui: { prefersBorder: true, csp: { connectDomains: [], resourceDomains: [] }, ...(options.cards.domain ? { domain: options.cards.domain } : {}) } },
+                            }], ...(v2 ? { resultType: 'complete' } : {}) } });
+            }
             const workflows = describeAgentWorkflows(actions);
             const handoff = workflows.some(workflow => workflow.id === 'handoff-to-agent') ? createHandoffTool(binding, revalidate) : null;
             const profileSchema = { type: 'object', properties: { id: { type: 'string', minLength: 1 }, name: { type: 'string' } }, required: ['id'], additionalProperties: false };
@@ -443,7 +466,12 @@ export function createAgentsHandler(options) {
                 { name: 'agent_profile', description: 'Stable application identity of the authenticated account.', inputSchema: { type: 'object', properties: {}, additionalProperties: false }, run: async (args) => { validate(args, {}); return { id: binding.applicationUserId, ...(binding.name ? { name: binding.name } : {}) }; } },
                 { name: 'agent_capabilities', description: 'Discover actions actually supported for this identity, app and grant now.', inputSchema: { type: 'object', properties: {}, additionalProperties: false }, run: async (args) => { validate(args, {}); return { appName: binding.appName, actions: [...actions.map(a => names[a]), ...(handoff ? [handoff.name] : [])], workflows, inspection: inspection?.tools.map(tool => tool.name) ?? [], media: ['text/plain; charset=utf-8'], compatibilityAliases: actions.includes('delegate') ? { delegate_task: names.delegate } : {}, preferredPromptTool: actions.includes('delegate') ? names.delegate : null, resultKinds: canReadOutput ? [...(binding.services.readFile ? ['files'] : []), ...(binding.services.readResponse ? ['response'] : [])] : [], execution: 'native-application', stateStore: 'native-application', taskWait: { defaultMs: waitPolicy.defaultMs, maxMs: waitPolicy.maxMs }, events: eventsEnabled ? { name: 'agent.task_updated', protocolVersion: '2026-07-28', delivery: ['webhook'], replay: false } : null }; } },
                 ...advertisedActions.map(action => ({ name: names[action], description: descriptions[action], inputSchema: { type: 'object', properties: Object.fromEntries(Object.entries(schemas[action]).map(([key, value]) => { const { optional: _optional, ...schema } = value; return [key, schema]; })), required: Object.keys(schemas[action]).filter(key => !schemas[action][key].optional), additionalProperties: false }, run: async (args) => {
-                        validate(args, schemas[action]);
+                        try {
+                            validate(args, schemas[action]);
+                        }
+                        catch (error) {
+                            throw action === 'delegate' ? new PreAdmissionFailure(error) : error;
+                        }
                         if (!actions.includes(action))
                             throw new AgentFailure('insufficient_scope', 403);
                         if (action === 'delegate' && args.contextVersion !== undefined && !actions.includes('connect'))
@@ -469,14 +497,14 @@ export function createAgentsHandler(options) {
                         return await tool.run(args, {});
                     }
                     catch (error) {
-                        return { [failureMarker]: { code: error instanceof AgentFailure ? error.message : 'native_operation_failed', status: error instanceof AgentFailure ? error.status : 503, ...(error instanceof AdmissionFailure ? { recovery: error.recovery } : {}) } };
+                        return { [failureMarker]: { code: error instanceof AgentFailure ? error.message : 'native_operation_failed', status: error instanceof AgentFailure ? error.status : 503, ...(error instanceof PreAdmissionFailure ? { admission: 'not-started' } : {}), ...(error instanceof AdmissionFailure ? { recovery: error.recovery } : {}) } };
                     } } })),
                 buildEnv: () => ({}),
-                formatResult: result => {
+                formatResult: (result, tool) => {
                     const failed = result && typeof result === 'object' && failureMarker in result ? result[failureMarker] : null;
                     return failed
                         ? { isError: true, content: [{ type: 'text', text: failed.code }], structuredContent: { error: failed } }
-                        : { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result };
+                        : { content: [{ type: 'text', text: JSON.stringify(result) }], structuredContent: result, ...(options.cards && AGENT_CARD_TOOLS.includes(tool.name) ? { _meta: { agentCards: { displayName: metadata.displayName, tools: actions.map(action => names[action]) } } } : {}) };
                 },
             });
             if (parsed.method === 'tools/call' && record(parsed.params) && parsed.params.name === 'delegate_task') {
@@ -499,7 +527,7 @@ export function createAgentsHandler(options) {
                         ? [...new Set(HANDOFF_ACTIONS.flatMap(a => binding.requiredScopes[a] ?? []))]
                         : [];
                     const securitySchemes = [{ type: 'oauth2', scopes: inspectionTool ? inspectionScopes : action ? binding.requiredScopes[action] : handoffScopes }];
-                    Object.assign(tool, { annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: readOnly, openWorldHint: action === 'delegate' || action === 'decide' || action === 'channel' }, securitySchemes, _meta: { securitySchemes, ...(tool.name === 'agent_profile' ? { 'openai/profile': true } : {}) }, ...(tool.name === 'agent_profile' ? { outputSchema: profileSchema } : {}) });
+                    Object.assign(tool, { annotations: { readOnlyHint: readOnly, destructiveHint: !readOnly, idempotentHint: readOnly, openWorldHint: action === 'delegate' || action === 'decide' || action === 'channel' }, securitySchemes, _meta: { securitySchemes, ...(tool.name === 'agent_profile' ? { 'openai/profile': true } : {}), ...(options.cards && AGENT_CARD_TOOLS.includes(String(tool.name)) ? { ui: { resourceUri: AGENT_CARDS_URI, visibility: ['model', 'app'] } } : {}) }, ...(tool.name === 'agent_profile' ? { outputSchema: profileSchema } : {}), ...(Object.hasOwn(cardOutputSchemas, String(tool.name)) ? { outputSchema: cardOutputSchemas[tool.name] } : {}) });
                 }
                 if (v2 && envelope.result) {
                     envelope.result.tools?.sort((a, b) => String(a.name).localeCompare(String(b.name)));
@@ -507,6 +535,12 @@ export function createAgentsHandler(options) {
                 }
                 return Response.json(envelope, { headers: { 'cache-control': 'no-store' } });
             }
+            if (options.cards && parsed.method === 'initialize' && response.ok) {
+                const envelope = await response.json();
+                if (envelope.result)
+                    envelope.result.capabilities = { ...envelope.result.capabilities, resources: {} };
+                return Response.json(envelope, { headers: { 'cache-control': 'no-store' } });
+            }
             if (v2 && response.ok && response.status !== 204) {
                 const envelope = await response.json();
                 if (envelope.result)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/chatgpt-agents-kit",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "repository": {
     "type": "git",
     "url": "https://github.com/tangle-network/chatgpt-plugins.git",
@@ -28,21 +28,29 @@
     "./events-node": {
       "types": "./dist/src/events-node.d.ts",
       "import": "./dist/src/events-node.js"
+    },
+    "./cards": {
+      "types": "./dist/cards/server.d.ts",
+      "import": "./dist/cards/server.js"
     }
   },
   "files": [
     "dist",
     "README.md",
-    "SETUP.md"
+    "SETUP.md",
+    "CARDS.md"
   ],
   "scripts": {
     "check": "tsc --noEmit",
-    "build": "npm run check && tsc -p tsconfig.build.json && node scripts/build-assets.mjs",
-    "test": "node --experimental-strip-types --test tests/kit.test.ts tests/workflows.test.ts tests/task-turn.test.ts tests/persistent-agent.test.ts tests/distribution.test.ts tests/setup.test.ts && npm run test:package",
+    "build": "npm run check && tsc -p tsconfig.build.json && node scripts/build-assets.mjs && node scripts/build-cards.mjs",
+    "test": "node --experimental-strip-types --test tests/kit.test.ts tests/workflows.test.ts tests/task-turn.test.ts tests/persistent-agent.test.ts tests/distribution.test.ts tests/setup.test.ts tests/cards.test.ts && npm run test:package",
     "test:package": "node --experimental-strip-types --test tests/packaged-generator.test.mjs",
     "acceptance": "node --experimental-strip-types acceptance/run.ts",
     "build:plugin": "node dist/src/cli.js",
-    "verify:turn": "npm run build && node scripts/prove-turn.mjs"
+    "verify:turn": "npm run build && node scripts/prove-turn.mjs",
+    "test:cards": "node --experimental-strip-types --test tests/cards.test.ts",
+    "proof:cards": "node cards/proof.mjs",
+    "proof:cards:lifecycle": "node cards/proof-lifecycle.mjs"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.31.0",
@@ -51,8 +59,19 @@
     "zod": "4.6.5"
   },
   "devDependencies": {
+    "@axe-core/playwright": "4.11.1",
+    "@modelcontextprotocol/ext-apps": "2.0.3",
+    "@playwright/test": "1.58.2",
     "@tangle-network/agent-app": "0.50.11",
+    "@tangle-network/brand": "1.10.0",
+    "@tangle-network/ui": "11.13.0",
     "@types/node": "22.15.30",
+    "@types/react": "19.2.14",
+    "@types/react-dom": "19.2.3",
+    "ajv": "8.18.0",
+    "esbuild": "0.27.4",
+    "react": "19.2.4",
+    "react-dom": "19.2.4",
     "typescript": "5.9.3"
   }
 }