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

package/dist/src/directory.js

@@ -0,0 +1,94 @@
+import { AgentFailure } from "./contracts.js";
+const id = { type: 'string', pattern: '^[A-Za-z0-9_-]{1,256}$', minLength: 1, maxLength: 256 };
+const properties = { workspaceId: id, q: { type: 'string', maxLength: 200 },
+    cursor: { type: 'string', minLength: 1, maxLength: 1536 }, limit: { type: 'integer', minimum: 1, maximum: 100 } };
+const validId = (value) => typeof value === 'string' && /^[A-Za-z0-9_-]{1,256}$/.test(value);
+const validDate = (value) => value === undefined || (typeof value === 'string' && Number.isFinite(Date.parse(value)));
+const states = ['queued', 'working', 'input-required', 'succeeded', 'failed', 'cancelled', 'unknown'];
+export function directoryTools(binding, actions, revalidate) {
+    return ['threads', 'tasks'].flatMap(kind => {
+        const action = kind === 'threads' ? 'connect' : 'task';
+        const maxLimit = kind === 'tasks' ? 10 : 100;
+        const maxCursor = kind === 'tasks' ? 1536 : 512;
+        const service = kind === 'threads' ? binding.services.listThreads : binding.services.listTasks;
+        if (!service || !actions.includes('list') || !actions.includes(action))
+            return [];
+        return [{ name: `list_my_${kind}`, description: `Choose existing ${kind} by title in an accessible workspace. Read-only; never creates or restarts work.`,
+                inputSchema: { type: 'object', properties: { ...properties, cursor: { ...properties.cursor, maxLength: maxCursor }, limit: { ...properties.limit, maximum: maxLimit }, ...(kind === 'tasks' ? { threadId: id } : {}) }, required: kind === 'threads' ? ['workspaceId'] : [], additionalProperties: false },
+                async run(args) {
+                    const keys = [...Object.keys(properties), ...(kind === 'tasks' ? ['threadId'] : [])];
+                    if (Object.keys(args).some(key => !keys.includes(key)) || (kind === 'threads' ? !validId(args.workspaceId) : args.workspaceId !== undefined && !validId(args.workspaceId))
+                        || (args.threadId !== undefined && !validId(args.threadId))
+                        || (args.q !== undefined && (typeof args.q !== 'string' || args.q.length > 200))
+                        || (args.cursor !== undefined && (typeof args.cursor !== 'string' || !args.cursor || args.cursor.length > maxCursor))
+                        || (args.limit !== undefined && (!Number.isSafeInteger(args.limit) || Number(args.limit) < 1 || Number(args.limit) > maxLimit)))
+                        throw new AgentFailure('invalid_argument');
+                    const query = args;
+                    const native = async (read) => {
+                        try {
+                            return await read();
+                        }
+                        catch (error) {
+                            throw new AgentFailure(error instanceof AgentFailure && [401, 403, 404].includes(error.status) ? 'native_target_forbidden' : 'native_directory_unavailable', error instanceof AgentFailure && [401, 403, 404].includes(error.status) ? error.status : 503);
+                        }
+                    };
+                    const visibleWorkspaces = async () => {
+                        const workspaces = await native(() => binding.services.list());
+                        await revalidate();
+                        if (query.workspaceId && !workspaces.some(workspace => workspace.workspaceId === query.workspaceId))
+                            throw new AgentFailure('native_target_forbidden', 403);
+                        return new Set(workspaces.map(workspace => workspace.workspaceId));
+                    };
+                    const before = await visibleWorkspaces();
+                    await revalidate();
+                    const page = kind === 'threads' ? await native(() => binding.services.listThreads(query)) : await native(() => binding.services.listTasks(query));
+                    const after = await visibleWorkspaces();
+                    if (!page || typeof page !== 'object')
+                        throw new AgentFailure('native_directory_invalid', 502);
+                    const rows = kind === 'threads' ? ('threads' in page ? page.threads : undefined) : ('tasks' in page ? page.tasks : undefined);
+                    if (!Array.isArray(rows) || rows.length > (query.limit ?? maxLimit)
+                        || (page.nextCursor !== null && (typeof page.nextCursor !== 'string' || !page.nextCursor || page.nextCursor.length > maxCursor)))
+                        throw new AgentFailure('native_directory_invalid', 502);
+                    const projected = [];
+                    const targets = [];
+                    for (const value of rows) {
+                        if (!value || typeof value !== 'object' || Array.isArray(value))
+                            throw new AgentFailure('native_directory_invalid', 502);
+                        const row = value;
+                        if (!row || !validId(row.threadId) || typeof row.title !== 'string' || row.title.length > 1024 || !validDate(row.updatedAt))
+                            throw new AgentFailure('native_directory_invalid', 502);
+                        const workspaceId = kind === 'tasks' ? row.workspaceId : query.workspaceId;
+                        if (!validId(workspaceId) || !before.has(workspaceId) || !after.has(workspaceId) || (query.workspaceId && workspaceId !== query.workspaceId))
+                            throw new AgentFailure('native_target_forbidden', 403);
+                        const target = { workspaceId, threadId: row.threadId };
+                        targets.push(target);
+                        if (query.threadId && row.threadId !== query.threadId)
+                            throw new AgentFailure('native_directory_invalid', 502);
+                        await native(() => binding.authorize(target, action));
+                        await revalidate();
+                        const summary = { threadId: row.threadId, title: row.title, ...(row.updatedAt ? { updatedAt: row.updatedAt } : {}) };
+                        if (kind === 'tasks') {
+                            if (!validId(row.turnId) || (typeof row.state !== 'string' || !states.includes(row.state)) || !validDate(row.completedAt) || typeof row.completionVerified !== 'boolean')
+                                throw new AgentFailure('native_directory_invalid', 502);
+                            for (const name of [row.workspaceName, row.threadTitle])
+                                if (name !== undefined && (typeof name !== 'string' || name.length > 1024))
+                                    throw new AgentFailure('native_directory_invalid', 502);
+                            if (!validDate(row.createdAt))
+                                throw new AgentFailure('native_directory_invalid', 502);
+                            projected.push({ ...summary, ...target, turnId: row.turnId, state: row.state, completionVerified: row.completionVerified === true, ...(row.statusError ? { statusError: 'status_unavailable' } : {}), ...(row.workspaceName ? { workspaceName: row.workspaceName } : {}), ...(row.threadTitle ? { threadTitle: row.threadTitle } : {}), ...(row.createdAt ? { createdAt: row.createdAt } : {}), ...(row.completedAt ? { completedAt: row.completedAt } : {}) });
+                        }
+                        else if (kind === 'threads')
+                            projected.push(summary);
+                        else
+                            throw new AgentFailure('native_directory_invalid', 502);
+                    }
+                    // Authorization can change while later rows await native services.
+                    await visibleWorkspaces();
+                    for (const target of targets)
+                        await native(() => binding.authorize(target, action));
+                    await revalidate();
+                    return { appName: binding.appName, identityId: binding.applicationUserId, ...(query.workspaceId ? { workspaceId: query.workspaceId } : {}),
+                        ...(query.threadId ? { threadId: query.threadId } : {}), [kind]: projected, nextCursor: page.nextCursor };
+                } }];
+    });
+}

package/dist/src/gtm.d.ts

@@ -13,6 +13,8 @@ export interface GtmNativeContext {
     /** Use the persisted agent-app turn path. HTTP 200 alone is NOT admission. */
     turns?: Pick<NativeServices, 'startTask' | 'getTask'>;
     interactions?: Pick<NativeServices, 'pendingDecisions' | 'decide'>;
+    /** Native paginated discovery; absent services expose no discovery tools. */
+    directory?: Pick<NativeServices, 'listThreads' | 'listTasks'>;
     /** Only supply a live SAME-workspace application-line adapter, not createHostedAgent's legacy per-person sandbox path. */
     channels?: Pick<NativeServices, 'channelBinding' | 'sendChannel'>;
 }

package/dist/src/gtm.js

@@ -69,6 +69,7 @@ export function createGtmBinding(context) {
                 throw new AgentFailure('gtm_binary_output_unsupported', 415);
             return { content: result.file.content, revision, mediaType };
         },
+        ...context.directory,
         ...context.turns,
         ...context.interactions,
         ...context.channels,

package/dist/src/index.d.ts

@@ -1,7 +1,7 @@
 export { createAgentsHandler } from './kit.ts';
 export { createGtmBinding } from './gtm.ts';
 export { AgentFailure } from './contracts.ts';
-export type { Action, Metadata, NativeBinding, NativeChannel, NativeFile, NativeMcpFactory, NativeServices, NativeTask, NativeResponse, NativeConnection, NativeEnvironment, OAuthResource, Principal, Target, } from './contracts.ts';
+export type { Action, Metadata, NativeBinding, NativeChannel, NativeFile, NativeMcpFactory, NativeServices, NativeTask, NativeResponse, NativeConnection, NativeEnvironment, OAuthResource, Principal, Target, NativeDirectoryQuery, NativeTaskQuery, NativeThreadSummary, NativeTaskSummary, } from './contracts.ts';
 export type { GtmNativeContext } from './gtm.ts';
 export type { InspectionBinding, InspectionExposure } from './inspection.ts';
 export { createTaskEvents, TASK_EVENT } from './task-events.ts';

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,6 @@
+import { AGENT_CARDS_URI, AGENT_CARDS_MIME, AGENT_CARD_TOOLS } from "./cards.js";
+import { directoryTools } from "./directory.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 +9,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;
@@ -98,7 +107,8 @@ async function output(binding, target, path) {
 async function taskReceipt(binding, target, task, expectedTurn, canReadOutput, checkOutput) {
     validateNativeTask(task, target, expectedTurn);
     const base = { ...target, turnId: task.turnId, executionId: task.executionId, state: task.state, source: task.source, ...(task.environment ? { environment: projectEnvironment(task.environment) } : {}) };
-    if (task.state !== 'succeeded')
+    const settledResponse = ['failed', 'input-required'].includes(task.state) && task.response && task.completedAt;
+    if (task.state !== 'succeeded' && !settledResponse)
         return { ...base, completionVerified: false };
     if (!task.executionId || !task.completedAt || !Number.isFinite(Date.parse(task.completedAt)) || (!task.outputs?.length && !task.response))
         return { ...base, completionVerified: false, reason: 'execution_output_provenance_missing' };
@@ -125,18 +135,24 @@ async function taskReceipt(binding, target, task, expectedTurn, canReadOutput, c
         if (bytes > 262144)
             throw new AgentFailure('output_too_large', 413);
         outcome = value.outcome ?? 'completed';
+        if (task.state !== 'succeeded' && outcome !== task.state)
+            throw new AgentFailure('native_response_outcome_mismatch', 502);
         // Explicit projection: do not expose arbitrary host/provider fields.
         response = { content: value.content, mediaType: value.mediaType, sha256: await digest(value.content), bytes };
     }
-    if (task.outputs?.length && !binding.services.readFile)
-        return { ...base, completionVerified: false, reason: 'output_reader_unavailable' };
+    const unavailableOutput = (reason) => ({ ...base, completionVerified: false, reason,
+        ...(outcome !== 'completed' && response ? { state: outcome, response, completedAt: task.completedAt, outputs: [] } : {}) });
+    if (task.outputs?.length && !binding.services.readFile) {
+        await checkOutput();
+        return unavailableOutput('output_reader_unavailable');
+    }
     const outputs = [];
     for (const ref of task.outputs ?? []) {
         await checkOutput();
         const file = await output(binding, target, ref.path);
         await checkOutput();
         if (!ref.revision || file.revision !== ref.revision)
-            return { ...base, completionVerified: false, reason: 'output_revision_changed' };
+            return unavailableOutput('output_revision_changed');
         outputs.push(file);
     }
     return { ...base, ...(outcome !== 'completed' ? { state: outcome, reason: 'native_result_not_completed' } : {}),
@@ -184,24 +200,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 +443,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,14 +457,31 @@ 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 directory = directoryTools(binding, actions, revalidate);
+            const executableTools = [...actions.map(action => names[action]), ...directory.map(tool => tool.name)];
             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 };
             const tools = [
                 { 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 }; } },
+                { 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: [...executableTools, ...(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'))
@@ -453,6 +491,7 @@ export function createAgentsHandler(options) {
                             ? { ...result, notification: { state: 'not_subscribed', name: 'agent.task_updated', arguments: { workspaceId: args.workspaceId, threadId: args.threadId, turnId: args.turnId } } }
                             : result;
                     } })),
+                ...directory,
                 ...(handoff ? [handoff] : []),
                 ...(inspection?.tools ?? []),
             ];
@@ -469,14 +508,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, applicationOrigin: metadata.applicationOrigin, tools: executableTools } } } : {}) };
                 },
             });
             if (parsed.method === 'tools/call' && record(parsed.params) && parsed.params.name === 'delegate_task') {
@@ -498,8 +537,9 @@ export function createAgentsHandler(options) {
                     const handoffScopes = tool.name === HANDOFF_TOOL_NAME
                         ? [...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 } : {}) });
+                    const directoryScopes = directory.some(item => item.name === tool.name) ? [...new Set([...(binding.requiredScopes.list ?? []), ...(binding.requiredScopes[tool.name === 'list_my_threads' ? 'connect' : 'task'] ?? [])])] : null;
+                    const securitySchemes = [{ type: 'oauth2', scopes: directoryScopes ?? (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 } : {}), ...(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 +547,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/dist/src/package.js

@@ -3,7 +3,7 @@ import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
 import { parseArgs } from 'node:util';
 import { AGENT_APP_METADATA_KEY } from "./app-metadata.js";
-import { ACTION_TOOLS, selectAgentWorkflows, describeAgentWorkflows } from "./workflows.js";
+import { ACTION_TOOLS, selectAgentWorkflows, describeAgentWorkflows, selectAgentStarterPrompts } from "./workflows.js";
 export function endpointUrl(value, allowLoopback = false) {
     const url = new URL(value);
     if (url.username || url.password || url.search || url.hash || (url.protocol !== 'https:' && !(allowLoopback && url.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(url.hostname))))
@@ -159,7 +159,7 @@ async function writePackage(m, url, out, discovered, connectionId) {
         await mkdir(join(temporary, 'skills/operate-existing-agent'), { recursive: true });
         await writeFile(join(temporary, 'plugin.json'), JSON.stringify({
             $schema: 'https://agent-plugins.org/schemas/1.0.0/plugin.schema.json', name: m.name, version: '0.1.0', description: m.description,
-            extensions: { 'com.openai': { ...(connectionId ? { apps: './.app.json' } : {}), interface: { displayName: m.displayName, shortDescription: m.description, developerName: 'Tangle', category: 'Productivity', websiteURL: m.applicationOrigin, defaultPrompt: ['Connect my agent', ...workflows.slice(0, 2).map(workflow => workflow.prompt)] } } },
+            extensions: { 'com.openai': { ...(connectionId ? { apps: './.app.json' } : {}), interface: { displayName: m.displayName, shortDescription: m.description, developerName: 'Tangle', category: 'Productivity', websiteURL: m.applicationOrigin, defaultPrompt: selectAgentStarterPrompts(m.actions) } } },
         }, null, 2) + '\n');
         if (connectionId)
             await writeFile(join(temporary, '.app.json'), JSON.stringify({ apps: { agents: { id: connectionId } } }, null, 2) + '\n');
@@ -188,7 +188,10 @@ async function writePackage(m, url, out, discovered, connectionId) {
                 ? `4. Verify that .app.json maps this endpoint's registered connection: ${connectionId}. This mapping is developer-supplied, not verified by the generator.`
                 : '4. Copy the real registered connection ID from ChatGPT. Rerun the installed generator with --connection-id and a new --out directory to add its .app.json mapping.',
             '5. Import/install that generated package using the current ChatGPT plugin instructions; test in a new chat.',
-            '6. Ask: Connect my agent. Select the SAME existing agent, workspace and conversation used in the app.', '',
+            '6. Ask for the agent or project by name. Choose the existing conversation when several matches appear.', '',
+            'Describe the result you want, review it here, then ask for a specific change in the same conversation.',
+            'Return later by asking for that work by name. Available discovery tools determine which work ChatGPT can find.', '',
+            '## Developer acceptance', '',
             'Prompt the selected agent; use get_task to observe the same turn.',
             'Reopen results with read_output and the returned native references.',
             'A queued receipt is not completion. Missing capabilities stay unavailable.', '',

package/dist/src/workflows.d.ts

@@ -17,3 +17,5 @@ export declare function describeAgentWorkflows(actions: readonly Action[]): {
     prompt: string;
     requiredTools: string[];
 }[];
+/** Starters describe only packaged actions; live discovery still decides what can run. */
+export declare function selectAgentStarterPrompts(actions: readonly Action[]): string[];

package/dist/src/workflows.js

@@ -8,16 +8,16 @@ export const HANDOFF_ACTIONS = ['connect', 'handoff', 'output', 'delegate', 'tas
 /** These compose existing actions. They neither register tools nor grant access. */
 export const AGENT_WORKFLOWS = [
     { id: 'handoff-to-agent', title: 'Hand this work to my agent',
-        prompt: 'Prepare a reviewed handoff of this work to my existing agent.',
+        prompt: 'Help my agent finish this work using the context we have chosen.',
         requires: HANDOFF_ACTIONS },
     { id: 'review-agent-deliverables', title: 'Review and improve my agent’s work',
-        prompt: 'Retrieve my agent’s actual deliverables and help me review and revise them.',
+        prompt: 'Review my agent’s latest result and help me improve it.',
         requires: ['connect', 'task', 'delegate'] },
     { id: 'save-agent-playbook', title: 'Save this workflow for my agent',
-        prompt: 'Turn this successful workflow into a reusable playbook for my agent to review.',
+        prompt: 'Save how we did this as a playbook for my agent.',
         requires: ['connect', 'handoff', 'output'] },
     { id: 'resume-agent-work', title: 'Pick up where my agent left off',
-        prompt: 'Reconnect to the same agent and task, and show verified results and remaining work.',
+        prompt: 'Pick up my recent work and show what needs my attention.',
         requires: ['connect', 'task'] },
     { id: 'resolve-agent-decisions', title: 'Resolve my agent’s pending decisions',
         prompt: 'Show the pending decisions for my selected agent so I can review them.',
@@ -36,3 +36,21 @@ export function describeAgentWorkflows(actions) {
         id, title, prompt, requiredTools: requires.map(action => ACTION_TOOLS[action]),
     }));
 }
+/** Starters describe only packaged actions; live discovery still decides what can run. */
+export function selectAgentStarterPrompts(actions) {
+    const available = new Set(actions);
+    const prompts = [];
+    if (available.has('list'))
+        prompts.push('Show my agents and help me choose what to work on.');
+    if (available.has('connect') && available.has('delegate')) {
+        prompts.push('Help my agent finish a task in its existing workspace.');
+    }
+    const workflows = selectAgentWorkflows(actions);
+    const resume = workflows.find(workflow => workflow.id === 'resume-agent-work');
+    if (resume)
+        prompts.push(resume.prompt);
+    for (const workflow of workflows)
+        if (!prompts.includes(workflow.prompt))
+            prompts.push(workflow.prompt);
+    return prompts.length ? prompts.slice(0, 3) : ['Show what this agent connection can do.'];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/chatgpt-agents-kit",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "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"
   }
 }