@tangle-network/chatgpt-agents-kit 0.1.0

package/dist/src/kit.js

@@ -0,0 +1,525 @@
+import { agentAppDiscovery, defineAgentAppMetadata } from "./app-metadata.js";
+import { AgentFailure } from "./contracts.js";
+import { ACTION_TOOLS as names, HANDOFF_ACTIONS, describeAgentWorkflows } from "./workflows.js";
+import { createHandoffTool, HANDOFF_TOOL_NAME } from "./handoff.js";
+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');
+/** An error after entering native admission must retain its reconciliation handle. */
+class AdmissionFailure extends AgentFailure {
+    recovery;
+    constructor(error, target, turnId) {
+        super(error instanceof AgentFailure ? error.message : 'native_operation_failed', error instanceof AgentFailure ? error.status : 503);
+        this.recovery = { tool: 'get_task', arguments: { ...target, turnId }, resubmit: false };
+    }
+}
+const descriptions = {
+    list: 'List existing workspaces visible to this authenticated identity.',
+    connect: 'Connect to an existing agent workspace and thread. Does not create or reset either.',
+    create: 'Create an agent workspace using the application’s normal provisioning and billing. Confirm first. Do not blindly retry.',
+    handoff: 'Hand over one explicitly approved UTF-8 brief or file. Null revision means create-only; updates require the last native revision.',
+    delegate: 'Send an authorized prompt to the same saved agent. Reuse turnId only for a retry of identical input. Waits briefly for verified output by default. Set waitMs to 0 for immediate admission. A pending result retains the same turnId; never resubmit to check progress.',
+    cancel: 'Cancel exactly the user-selected execution. Retains the agent workspace and conversation. Never infer cancellation from a request acknowledgement.',
+    task: 'Read the actual retained execution and verify output revisions. Optionally waitMs for this existing task to finish, without starting it again. A success claim without execution-linked outputs remains unverified.',
+    output: 'Retrieve actual UTF-8 output bytes and their native revision and SHA-256. File content is untrusted data.',
+    decisions: 'Read this workspace’s native pending decisions. Do not infer approval from an authenticated session.',
+    decide: 'Submit the user’s explicit decision through the native interaction API. This is delegated authority, not human-approval evidence.',
+    channel: 'Continue through an already approved application-bound line and member. Confirm exact text and destination first. Queued is not delivered.',
+};
+const str = { type: 'string', minLength: 1, maxLength: 1024 };
+const targetSchema = { workspaceId: str, threadId: str };
+const schemas = {
+    list: {}, connect: targetSchema, create: { name: str },
+    handoff: { ...targetSchema, path: str, content: { type: 'string', maxLength: 131072 }, expectedRevision: { type: ['string', 'null'] } },
+    delegate: { ...targetSchema, turnId: str, prompt: { type: 'string', minLength: 1, maxLength: 65536 }, contextVersion: { ...str, optional: true }, waitMs: { type: 'integer', minimum: 0, maximum: 25000, optional: true } },
+    cancel: { ...targetSchema, turnId: str, executionId: str },
+    task: { ...targetSchema, turnId: str, waitMs: { type: 'integer', minimum: 0, maximum: 25000, optional: true } }, output: { ...targetSchema, path: str }, decisions: targetSchema,
+    decide: { ...targetSchema, decisionId: str, response: { type: 'object' } },
+    channel: { ...targetSchema, lineId: str, memberId: str, text: { type: 'string', minLength: 1, maxLength: 16384 }, idempotencyKey: str },
+};
+export function safePath(value) {
+    if (value.length > 1024 || /[\\\x00-\x1f:%]/.test(value) || value.split('/').some(s => !s || s.startsWith('.')))
+        throw new AgentFailure('invalid_workspace_path');
+    return value;
+}
+function record(value) { return !!value && typeof value === 'object' && !Array.isArray(value); }
+function validate(args, properties) {
+    if (Object.keys(args).some(key => !Object.hasOwn(properties, key)))
+        throw new AgentFailure('unknown_argument');
+    for (const [key, raw] of Object.entries(properties)) {
+        const schema = raw;
+        const value = args[key];
+        if (schema.optional && value === undefined)
+            continue;
+        if (schema.type === 'integer') {
+            if (!Number.isSafeInteger(value) || value < (schema.minimum ?? 0) || value > (schema.maximum ?? Infinity))
+                throw new AgentFailure('invalid_argument');
+            continue;
+        }
+        if (Array.isArray(schema.type) && value === null)
+            continue;
+        if (schema.type === 'object' ? !record(value) : typeof value !== 'string')
+            throw new AgentFailure('invalid_argument');
+        if (typeof value === 'string' && (value.length < (schema.minLength ?? 0) || value.length > (schema.maxLength ?? 131072)))
+            throw new AgentFailure('invalid_argument');
+    }
+}
+function supported(binding, action) {
+    const s = binding.services;
+    switch (action) {
+        case 'list': return typeof s.list === 'function';
+        case 'connect': return typeof s.connect === 'function';
+        case 'create': return !!s.create;
+        case 'handoff': return !!s.putFile;
+        case 'delegate': return !!s.startTask && !!s.getTask;
+        case 'task': return !!s.getTask;
+        case 'cancel': return !!s.cancelTask && !!s.getTask;
+        case 'output': return !!s.readFile;
+        case 'decisions': return !!s.pendingDecisions;
+        case 'decide': return !!s.pendingDecisions && !!s.decide;
+        case 'channel': return !!s.channelBinding && !!s.sendChannel;
+    }
+}
+function targetOf(args) {
+    const target = { workspaceId: args.workspaceId, threadId: args.threadId };
+    if (Object.values(target).some(v => !/^[A-Za-z0-9_-]{1,256}$/.test(v)))
+        throw new AgentFailure('invalid_target');
+    return target;
+}
+async function output(binding, target, path) {
+    const file = await binding.services.readFile(target, safePath(path));
+    if (!file || typeof file.content !== 'string' || !file.revision || typeof file.mediaType !== 'string')
+        throw new AgentFailure('native_output_invalid', 502);
+    if (new TextEncoder().encode(file.content).byteLength > 262144)
+        throw new AgentFailure('output_too_large', 413);
+    return { path, ...file, sha256: await digest(file.content), bytes: new TextEncoder().encode(file.content).byteLength };
+}
+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')
+        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' };
+    if ((task.outputs?.length ?? 0) > 32)
+        throw new AgentFailure('too_many_outputs', 413);
+    if (!canReadOutput)
+        return { ...base, completionVerified: false, reason: 'output_scope_required' };
+    let response;
+    let outcome = 'completed';
+    if (task.response) {
+        if (!binding.services.readResponse)
+            return { ...base, completionVerified: false, reason: 'response_reader_unavailable' };
+        await checkOutput();
+        const value = await binding.services.readResponse(target, expectedTurn);
+        await checkOutput();
+        if (!value)
+            return { ...base, completionVerified: false, reason: 'retained_response_unavailable' };
+        if (value.workspaceId !== target.workspaceId || value.threadId !== target.threadId
+            || value.turnId !== expectedTurn || value.executionId !== task.executionId || value.completedAt !== task.completedAt
+            || typeof value.content !== 'string' || typeof value.mediaType !== 'string'
+            || (value.outcome !== undefined && !['completed', 'input-required', 'failed'].includes(value.outcome)))
+            throw new AgentFailure('native_response_invalid', 502);
+        const bytes = new TextEncoder().encode(value.content).byteLength;
+        if (bytes > 262144)
+            throw new AgentFailure('output_too_large', 413);
+        outcome = value.outcome ?? 'completed';
+        // 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 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' };
+        outputs.push(file);
+    }
+    return { ...base, ...(outcome !== 'completed' ? { state: outcome, reason: 'native_result_not_completed' } : {}),
+        completedAt: task.completedAt, completionVerified: outcome === 'completed', ...(response ? { response } : {}), outputs };
+}
+async function run(action, args, binding, revalidate, signal, policy, canReadTask, canReadOutput, canConnect) {
+    const s = binding.services;
+    const identity = { appName: binding.appName, identityId: binding.applicationUserId };
+    if (action === 'list') {
+        const agents = await s.list();
+        await revalidate();
+        return { ...identity, agents };
+    }
+    if (action === 'create') {
+        const created = await s.create(args.name);
+        await revalidate();
+        return { ...identity, ...created };
+    }
+    const target = targetOf(args);
+    await binding.authorize(target, action);
+    await revalidate();
+    if (signal.aborted)
+        throw new AgentFailure('observation_cancelled', 499);
+    const checkOutput = async () => { await binding.authorize(target, 'output'); await revalidate(); };
+    const observe = async (initial, defaultMs) => {
+        const waitMs = Math.min(args.waitMs ?? defaultMs, policy.maxMs);
+        if (!canReadTask && waitMs > 0)
+            throw new AgentFailure('task_read_scope_required', 403);
+        return observeTask({ target, turnId: args.turnId, initial, waitMs, intervalMs: policy.intervalMs, signal,
+            check: async () => { await binding.authorize(target, 'task'); await revalidate(); },
+            read: () => s.getTask(target, args.turnId),
+        });
+    };
+    let result;
+    switch (action) {
+        case 'connect':
+            result = { ...identity, ...target, ...await describeConnection(await s.connect(target)) };
+            break;
+        case 'handoff': {
+            const path = safePath(args.path);
+            const saved = await s.putFile(target, path, args.content, args.expectedRevision);
+            if (!saved.revision)
+                throw new AgentFailure('native_revision_missing', 502);
+            result = { ...target, path, revision: saved.revision, inputSha256: await digest(args.content), storedBytesVerified: false, authorization: 'delegated-tool-call' };
+            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();
+            }
+            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();
+            }
+            try {
+                const task = await s.startTask(target, args.turnId, args.prompt, args.contextVersion === undefined ? undefined : { contextVersion: args.contextVersion });
+                result = await taskReceipt(binding, target, await observe(task, policy.defaultMs), args.turnId, canReadOutput, checkOutput);
+                break;
+            }
+            catch (error) {
+                throw new AdmissionFailure(error, target, args.turnId);
+            }
+        }
+        case 'cancel': {
+            // Read authorization and exact execution identity are prerequisites to a cancellation.
+            if (!canReadTask)
+                throw new AgentFailure('task_read_scope_required', 403);
+            await binding.authorize(target, 'task');
+            await revalidate();
+            const before = await s.getTask(target, args.turnId);
+            validateNativeTask(before, target, args.turnId);
+            if (!before.executionId || before.executionId !== args.executionId)
+                throw new AgentFailure('native_execution_changed', 409);
+            await binding.authorize(target, 'cancel');
+            await revalidate();
+            const after = await s.cancelTask(target, args.turnId, args.executionId);
+            validateNativeTask(after, target, args.turnId);
+            if (after.executionId !== before.executionId)
+                throw new AgentFailure('native_execution_changed', 502);
+            result = { ...target, turnId: after.turnId, executionId: after.executionId, state: after.state,
+                cancellationVerified: after.state === 'cancelled', workspaceDeleted: false };
+            break;
+        }
+        case 'task':
+            result = await taskReceipt(binding, target, await observe(await s.getTask(target, args.turnId), 0), args.turnId, canReadOutput, checkOutput);
+            break;
+        case 'output':
+            result = { ...target, ...await output(binding, target, args.path) };
+            break;
+        case 'decisions':
+            result = { ...target, decisions: await s.pendingDecisions(target) };
+            break;
+        case 'decide':
+            result = { ...target, authorization: 'delegated-tool-call', result: await s.decide(target, args.decisionId, args.response) };
+            break;
+        case 'channel': {
+            const bound = await s.channelBinding(target, args.lineId, args.memberId);
+            if (bound.applicationUserId !== binding.applicationUserId || bound.target.workspaceId !== target.workspaceId || bound.target.threadId !== target.threadId || bound.lineId !== args.lineId || bound.memberId !== args.memberId || bound.consent !== 'enabled' || !bound.binding)
+                throw new AgentFailure('channel_binding_or_consent_mismatch', 403);
+            // sendChannel MUST recheck native live attachment/consent atomically with send.
+            await revalidate();
+            const receipt = await s.sendChannel(bound, { memberId: bound.memberId, text: args.text, idempotencyKey: args.idempotencyKey });
+            if (!receipt.message?.id || !receipt.message.status)
+                throw new AgentFailure('native_message_receipt_missing', 502);
+            result = { ...identity, ...target, lineId: bound.lineId, memberId: bound.memberId, binding: bound.binding, messageId: receipt.message.id, status: receipt.message.status, deliveryVerified: false };
+            break;
+        }
+    }
+    await binding.authorize(target, action);
+    await revalidate();
+    if ((action === 'delegate' || action === 'task') && canReadTask && record(result) && ['queued', 'working', 'unknown'].includes(String(result.state)) && !result.completionVerified)
+        return { ...result, continuation: { tool: names.task, arguments: { ...target, turnId: args.turnId }, resubmit: false } };
+    return result;
+}
+async function boundedBody(request) {
+    const reader = request.body?.getReader();
+    if (!reader)
+        throw new AgentFailure('json_required');
+    const parts = [];
+    let length = 0;
+    try {
+        while (true) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            length += value.byteLength;
+            if (length > 524288) {
+                await reader.cancel();
+                throw new AgentFailure('request_too_large', 413);
+            }
+            parts.push(value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    const all = new Uint8Array(length);
+    let offset = 0;
+    for (const part of parts) {
+        all.set(part, offset);
+        offset += part.byteLength;
+    }
+    return new TextDecoder('utf-8', { fatal: true }).decode(all);
+}
+export function createAgentsHandler(options) {
+    const metadata = defineAgentAppMetadata(options.metadata, options.oauth.resource);
+    const waitPolicy = taskWaitPolicy(options.taskWait);
+    const resource = new URL(options.oauth.resource);
+    if (resource.username || resource.password || resource.search || resource.hash || (resource.protocol !== 'https:' && !(resource.protocol === 'http:' && ['localhost', '127.0.0.1', '[::1]'].includes(resource.hostname))))
+        throw new Error('invalid_oauth_resource');
+    const metadataUrl = `${resource.origin}/.well-known/oauth-protected-resource${resource.pathname}`;
+    const failure = (status, code) => Response.json({ error: code }, { status, headers: { 'cache-control': 'no-store', ...(status === 401 ? { 'www-authenticate': `Bearer resource_metadata="${metadataUrl}"` } : {}) } });
+    return async (request) => {
+        const url = new URL(request.url);
+        if (url.href === metadataUrl && request.method === 'GET') {
+            try {
+                const resourceMetadata = await options.oauth.protectedResourceMetadata();
+                if (resourceMetadata.resource !== resource.href || !resourceMetadata.authorization_servers?.length)
+                    return failure(503, 'oauth_metadata_unavailable');
+                return Response.json({ ...resourceMetadata, ...agentAppDiscovery(metadata) }, { headers: { 'cache-control': 'no-store' } });
+            }
+            catch {
+                return failure(503, 'oauth_metadata_unavailable');
+            }
+        }
+        if (url.origin !== resource.origin || url.pathname !== resource.pathname || url.search)
+            return failure(404, 'not_found');
+        const origin = request.headers.get('origin');
+        if (origin && !(options.allowedOrigins ?? [resource.origin]).includes(origin))
+            return failure(403, 'origin_not_allowed');
+        const token = /^Bearer ([^\s]+)$/i.exec(request.headers.get('authorization') ?? '')?.[1];
+        if (!token || /^(sk-|gak_|svc_)/.test(token))
+            return failure(401, 'oauth_required');
+        let principal;
+        let initialPrincipal;
+        let binding;
+        try {
+            principal = await options.oauth.verifyAccessToken(token);
+            if (!principal?.userId)
+                return failure(401, 'invalid_oauth_token');
+            // Snapshot before host callbacks or body I/O; a verifier may reuse a mutable object.
+            initialPrincipal = { userId: principal.userId, clientId: principal.clientId, scopes: [...principal.scopes] };
+            binding = await options.bind(principal);
+            if (binding.platformUserId !== principal.userId || !binding.applicationUserId || binding.appName !== metadata.name)
+                return failure(403, 'identity_binding_mismatch');
+        }
+        catch {
+            return failure(503, 'identity_unavailable');
+        }
+        if (request.method !== 'POST')
+            return failure(405, 'post_required');
+        if (request.headers.get('content-type')?.split(';')[0]?.trim().toLowerCase() !== 'application/json')
+            return failure(415, 'json_required');
+        let body;
+        let parsed;
+        try {
+            body = await boundedBody(request);
+            const value = JSON.parse(body);
+            if (!record(value) || value.jsonrpc !== '2.0' || typeof value.method !== 'string' || ('id' in value && value.id !== null && typeof value.id !== 'string' && typeof value.id !== 'number'))
+                return failure(400, 'invalid_rpc');
+            parsed = value;
+        }
+        catch (error) {
+            return failure(error instanceof AgentFailure ? error.status : 400, error instanceof AgentFailure ? error.message : 'invalid_json');
+        }
+        // The body, inspection setup, and dispatcher may all wait on external work.
+        // Keep the initial grant fixed and use the app's live verifier at each boundary.
+        const revalidate = async () => {
+            let current;
+            try {
+                current = await options.oauth.verifyAccessToken(token);
+            }
+            catch {
+                throw new AgentFailure('identity_unavailable', 503);
+            }
+            if (!current?.userId)
+                throw new AgentFailure('invalid_oauth_token', 401);
+            const initialScopes = new Set(initialPrincipal.scopes);
+            const currentScopes = new Set(current.scopes);
+            if (current.userId !== initialPrincipal.userId || current.clientId !== initialPrincipal.clientId
+                || currentScopes.size !== initialScopes.size || [...currentScopes].some(scope => !initialScopes.has(scope)))
+                throw new AgentFailure('oauth_principal_changed', 401);
+            return { userId: current.userId, clientId: current.clientId, scopes: [...currentScopes] };
+        };
+        try {
+            principal = await revalidate();
+        }
+        catch (error) {
+            return failure(error instanceof AgentFailure ? error.status : 503, error instanceof AgentFailure ? error.message : 'identity_unavailable');
+        }
+        let inspection;
+        let inspectionScopes = [];
+        try {
+            const configured = options.inspection ? await options.inspection(principal, binding) : null;
+            if (configured && (!configured.requiredScopes.length || configured.requiredScopes.some(scope => !/^[\x21\x23-\x5B\x5D-\x7E]{1,256}$/.test(scope))))
+                return failure(503, 'inspection_scope_invalid');
+            inspectionScopes = configured?.requiredScopes ?? [];
+            // Inspection remains optional; do not initialize its SDKs for an app that
+            // does not expose it to this grant. No replacement inspection path.
+            inspection = configured && inspectionScopes.every(scope => principal.scopes.includes(scope))
+                ? await (await import("./inspection.js")).createInspectionBridge(configured.exposure)
+                : null;
+        }
+        catch {
+            return failure(503, 'inspection_unavailable');
+        }
+        try {
+            try {
+                await revalidate();
+            }
+            catch (error) {
+                return failure(error instanceof AgentFailure ? error.status : 503, error instanceof AgentFailure ? error.message : 'identity_unavailable');
+            }
+            const actions = metadata.actions.filter(action => supported(binding, action) && binding.requiredScopes[action] !== undefined && binding.requiredScopes[action].every(scope => principal.scopes.includes(scope)));
+            // A read grant can discover the prompt scope before the user grants run.
+            // Keep it out of executable capabilities until the live grant includes every scope.
+            const upgradeableDelegate = !actions.includes('delegate') && metadata.actions.includes('delegate')
+                && supported(binding, 'delegate') && !!binding.requiredScopes.delegate?.length
+                && actions.some(action => ['list', 'connect', 'task', 'output', 'decisions'].includes(action));
+            const advertisedActions = upgradeableDelegate ? [...actions, 'delegate'] : actions;
+            const eventAccess = { principal: initialPrincipal, binding, check: async () => { await revalidate(); } };
+            const canReadOutput = metadata.actions.includes('output') && binding.requiredScopes.output !== undefined
+                && binding.requiredScopes.output.every(scope => principal.scopes.includes(scope))
+                && (!!binding.services.readFile || !!binding.services.readResponse);
+            const eventsEnabled = actions.includes('task') && canReadOutput && !!options.events && await options.events.available(eventAccess);
+            const v2 = request.headers.get('mcp-protocol-version') === '2026-07-28';
+            const rpcResult = (envelope) => Response.json({ jsonrpc: '2.0', id: parsed.id ?? null, ...envelope }, { headers: { 'cache-control': 'no-store' } });
+            if (v2) {
+                const params = record(parsed.params) ? parsed.params : {};
+                if (request.headers.get('mcp-method') !== parsed.method
+                    || (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: {} } : {}) } } });
+            }
+            if (parsed.method.startsWith('events/')) {
+                if (!v2 || !eventsEnabled)
+                    return rpcResult({ error: { code: -32601, message: 'Events unavailable for this protocol or grant' } });
+                const result = await options.events.rpc(parsed.method, parsed.params ?? {}, eventAccess);
+                try {
+                    await revalidate();
+                }
+                catch (error) {
+                    return failure(error instanceof AgentFailure ? error.status : 503, error instanceof AgentFailure ? error.message : 'identity_unavailable');
+                }
+                return rpcResult(result);
+            }
+            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 }; } },
+                ...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]);
+                        if (!actions.includes(action))
+                            throw new AgentFailure('insufficient_scope', 403);
+                        if (action === 'delegate' && args.contextVersion !== undefined && !actions.includes('connect'))
+                            throw new AgentFailure('connect_scope_required', 403);
+                        const result = await run(action, args, binding, revalidate, request.signal, waitPolicy, actions.includes('task'), canReadOutput, actions.includes('connect'));
+                        return record(result) && result.continuation && eventsEnabled
+                            ? { ...result, notification: { state: 'not_subscribed', name: 'agent.task_updated', arguments: { workspaceId: args.workspaceId, threadId: args.threadId, turnId: args.turnId } } }
+                            : result;
+                    } })),
+                ...(handoff ? [handoff] : []),
+                ...(inspection?.tools ?? []),
+            ];
+            if (upgradeableDelegate && parsed.method === 'tools/call' && record(parsed.params)
+                && [names.delegate, 'delegate_task'].includes(String(parsed.params.name))) {
+                const challenge = `Bearer resource_metadata="${metadataUrl}", error="insufficient_scope", error_description="Additional permission is required to run this agent", scope="${binding.requiredScopes.delegate.join(' ')}"`;
+                return rpcResult({ result: { isError: true, content: [{ type: 'text', text: 'insufficient_scope' }],
+                        _meta: { 'mcp/www_authenticate': [challenge] }, ...(v2 ? { resultType: 'complete' } : {}) } });
+            }
+            const handler = options.nativeMcp({
+                serverInfo: { name: metadata.name, version: '0.1.0' },
+                tools: tools.map(tool => ({ ...tool, run: async (args) => { try {
+                        await revalidate();
+                        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 } : {}) } };
+                    } } })),
+                buildEnv: () => ({}),
+                formatResult: result => {
+                    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 };
+                },
+            });
+            if (parsed.method === 'tools/call' && record(parsed.params) && parsed.params.name === 'delegate_task') {
+                const args = parsed.params.arguments;
+                if (!record(args) || Object.hasOwn(args, 'prompt'))
+                    return rpcResult({ error: { code: -32602, message: 'invalid_legacy_prompt_arguments' } });
+                const { brief, ...rest } = args;
+                body = JSON.stringify({ ...parsed, params: { ...parsed.params, name: names.delegate, arguments: { ...rest, prompt: brief } } });
+            }
+            const response = await handler(new Request(resource, { method: 'POST', headers: { 'content-type': 'application/json' }, body }));
+            // The maintained tools-only envelope intentionally omits host metadata. Add
+            // OAuth/profile/approval annotations without replacing its RPC dispatcher.
+            if (parsed.method === 'tools/list' && response.ok) {
+                const envelope = await response.json();
+                for (const tool of envelope.result?.tools ?? []) {
+                    const action = advertisedActions.find(a => names[a] === tool.name);
+                    const readOnly = !action || ['list', 'connect', 'task', 'output', 'decisions'].includes(action);
+                    const inspectionTool = inspection?.tools.some(item => item.name === tool.name);
+                    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 } : {}) });
+                }
+                if (v2 && envelope.result) {
+                    envelope.result.tools?.sort((a, b) => String(a.name).localeCompare(String(b.name)));
+                    Object.assign(envelope.result, { resultType: 'complete', ttlMs: 0, cacheScope: 'private' });
+                }
+                return Response.json(envelope, { headers: { 'cache-control': 'no-store' } });
+            }
+            if (v2 && response.ok && response.status !== 204) {
+                const envelope = await response.json();
+                if (envelope.result)
+                    envelope.result.resultType = 'complete';
+                return Response.json(envelope, { headers: { 'cache-control': 'no-store' } });
+            }
+            const headers = new Headers(response.headers);
+            headers.set('cache-control', 'no-store');
+            return new Response(response.body, { status: response.status, headers });
+        }
+        finally {
+            if (inspection)
+                await inspection.close();
+        }
+    };
+}

package/dist/src/package.d.ts

@@ -0,0 +1,28 @@
+import type { Metadata } from './contracts.ts';
+export declare function endpointUrl(value: string, allowLoopback?: boolean): URL;
+export declare function validateMetadata(value: unknown): Metadata;
+/** Anonymous, read-only readiness check. Does not register an OAuth client or deploy anything. */
+export declare function probeOAuth(endpoint: string, request?: typeof fetch): Promise<{
+    app?: {} | null | undefined;
+    anonymousStatus: number;
+    resource: string;
+    protectedResourceMetadata: string;
+    authorizationServers: string[];
+    oauthLogin: string;
+    capabilities: string;
+}>;
+export declare function buildPackage(metadata: Metadata, endpoint: string, out: string, offline?: boolean, connectionId?: string): Promise<{
+    directory: string;
+    readiness: {
+        [x: string]: unknown;
+    };
+}>;
+/** Read the selected endpoint's exact discovery document; no second app.json. */
+export declare function buildPackageFromEndpoint(endpoint: string, out: string, request?: typeof fetch, connectionId?: string): Promise<{
+    directory: string;
+    readiness: {
+        [x: string]: unknown;
+    };
+}>;
+/** Shared by the installed compiled bin and the existing source entry point. */
+export declare function runPackageCli(args?: string[]): Promise<void>;