@tangle-network/chatgpt-agents-kit 0.1.0

package/dist/src/package.js

@@ -0,0 +1,259 @@
+import { lstat, mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
+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";
+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))))
+        throw new Error('A credential-free HTTPS MCP endpoint is required');
+    return url;
+}
+export function validateMetadata(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Metadata must be an object');
+    const m = value;
+    const keys = ['name', 'displayName', 'description', 'applicationOrigin', 'actions', 'inspection'];
+    if (Object.keys(m).some(k => !keys.includes(k)))
+        throw new Error('Unknown metadata field; credentials and auth headers are never package metadata');
+    if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(m.name) || m.name.length > 64)
+        throw new Error('Invalid plugin name');
+    for (const value of [m.displayName, m.description])
+        if (typeof value !== 'string' || !value.trim() || value.length > 300 || /[\r\n\x00]/.test(value))
+            throw new Error('Invalid display metadata');
+    const origin = endpointUrl(m.applicationOrigin, true);
+    if (origin.pathname !== '/')
+        throw new Error('applicationOrigin must be an origin');
+    const actions = Object.keys(ACTION_TOOLS);
+    if (!Array.isArray(m.actions) || !m.actions.length || m.actions.some(a => !actions.includes(a)) || new Set(m.actions).size !== m.actions.length)
+        throw new Error('Invalid action restriction');
+    if (m.inspection !== undefined && typeof m.inspection !== 'boolean')
+        throw new Error('Invalid inspection flag');
+    return m;
+}
+/** Anonymous, read-only readiness check. Does not register an OAuth client or deploy anything. */
+export async function probeOAuth(endpoint, request = fetch) {
+    const resource = endpointUrl(endpoint, true);
+    const res = await request(resource, { method: 'POST', redirect: 'error', headers: { 'content-type': 'application/json', accept: 'application/json, text/event-stream' }, body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'initialize', params: { protocolVersion: '2025-06-18', capabilities: {}, clientInfo: { name: 'tangle-agents-preflight', version: '0.1.0' } } }), signal: AbortSignal.timeout(10000) });
+    if (res.status !== 401)
+        throw new Error(`MCP must challenge unauthenticated requests; observed HTTP ${res.status}`);
+    const metadataUrl = /resource_metadata="([^"]+)"/.exec(res.headers.get('www-authenticate') ?? '')?.[1];
+    const expected = `${resource.origin}/.well-known/oauth-protected-resource${resource.pathname}`;
+    if (metadataUrl !== expected)
+        throw new Error('Missing or unexpected protected-resource discovery URL');
+    const metadataResponse = await request(metadataUrl, { redirect: 'error', signal: AbortSignal.timeout(10000) });
+    if (!metadataResponse.ok)
+        throw new Error('Protected-resource metadata unavailable');
+    const metadata = await readDiscovery(metadataResponse);
+    if (metadata.resource !== resource.href || !Array.isArray(metadata.authorization_servers) || !metadata.authorization_servers.length)
+        throw new Error('Resource audience or authorization server missing');
+    // Do not follow an arbitrary issuer supplied by a discovery document. This
+    // report is discovery-only; the operator must verify the configured issuer,
+    // S256 support and authorization-code flow before connecting ChatGPT.
+    for (const issuer of metadata.authorization_servers) {
+        if (typeof issuer !== 'string')
+            throw new Error('Invalid authorization server');
+        endpointUrl(issuer, true);
+    }
+    return { anonymousStatus: res.status, resource: resource.href, protectedResourceMetadata: metadataUrl, authorizationServers: metadata.authorization_servers, oauthLogin: 'not-executed', capabilities: 'not-discovered',
+        ...(metadata[AGENT_APP_METADATA_KEY] !== undefined ? { app: metadata[AGENT_APP_METADATA_KEY] } : {}) };
+}
+/** A registered connection is a developer input, never OAuth or login proof. */
+function registeredConnectionId(value) {
+    if (value === undefined)
+        return undefined;
+    if (!/^(?:(?:plugin_)?asdk_app_|connector_|templated_apps_)[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value)) {
+        throw new Error('Expected a registered ChatGPT connection ID (plugin_asdk_app_..., asdk_app_..., connector_... or templated_apps_...). Copy the real ID after registering this endpoint; not an OAuth client ID, token or URL');
+    }
+    // ChatGPT's browser URL uses the plugin ID; .app.json uses the app ID.
+    return value.replace(/^plugin_(?=asdk_app_)/, '');
+}
+export async function buildPackage(metadata, endpoint, out, offline = false, connectionId) {
+    const registered = registeredConnectionId(connectionId);
+    const m = validateMetadata(metadata);
+    const url = endpointUrl(endpoint, true);
+    const readiness = offline ? { oauthLogin: 'not-executed', discovery: 'not-executed', capabilities: 'not-discovered' } : await probeOAuth(url.href);
+    return writePackage(m, url, out, readiness, registered);
+}
+/** Read the selected endpoint's exact discovery document; no second app.json. */
+export async function buildPackageFromEndpoint(endpoint, out, request = fetch, connectionId) {
+    const registered = registeredConnectionId(connectionId);
+    const { metadata, url, readiness } = await inspectEndpoint(endpoint, request);
+    return writePackage(metadata, url, out, readiness, registered);
+}
+/** One discovery/metadata path for generation and read-only setup diagnostics. */
+async function inspectEndpoint(endpoint, request = fetch) {
+    const { app, ...readiness } = await probeOAuth(endpoint, request);
+    if (!app || typeof app !== 'object' || Array.isArray(app))
+        throw new Error('This endpoint does not publish Agent App metadata; use --config with its reviewed app configuration');
+    const { formatVersion, ...description } = app;
+    if (formatVersion !== 1)
+        throw new Error('Unsupported Agent App metadata version');
+    const metadata = validateMetadata(description);
+    const url = endpointUrl(endpoint, true);
+    if (metadata.applicationOrigin !== url.origin)
+        throw new Error('Discovered application origin does not match the selected endpoint');
+    return { metadata, url, readiness };
+}
+async function readDiscovery(response) {
+    const reader = response.body?.getReader();
+    if (!reader)
+        throw new Error('Protected-resource metadata unavailable');
+    const chunks = [];
+    let size = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            size += value.byteLength;
+            if (size > 65536)
+                throw new Error('Protected-resource metadata is too large');
+            chunks.push(value);
+        }
+    }
+    finally {
+        await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+    const bytes = new Uint8Array(size);
+    let offset = 0;
+    for (const chunk of chunks) {
+        bytes.set(chunk, offset);
+        offset += chunk.byteLength;
+    }
+    const parsed = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes));
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+        throw new Error('Invalid protected-resource metadata');
+    return parsed;
+}
+function outputExists(destination) {
+    return new Error(`Output already exists at ${destination}; choose a new --out directory. Existing files were not changed`);
+}
+async function requireNewOutput(destination) {
+    try {
+        await lstat(destination);
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return;
+        throw error;
+    }
+    throw outputExists(destination);
+}
+async function writePackage(m, url, out, discovered, connectionId) {
+    const { app: _displayOnly, ...readiness } = discovered;
+    if (connectionId)
+        readiness.chatgptConnection = { id: connectionId, status: 'developer-supplied-unverified' };
+    const workflows = selectAgentWorkflows(m.actions);
+    const destination = resolve(out);
+    await requireNewOutput(destination);
+    const temporary = `${destination}.building-${crypto.randomUUID()}`;
+    // build-assets.mjs mirrors these module-relative assets into dist. Never
+    // resolve against the adopter's cwd or fall back to a source checkout.
+    const skill = await readFile(new URL('../skills/operate-existing-agent/SKILL.md', import.meta.url), 'utf8');
+    await mkdir(dirname(destination), { recursive: true });
+    await mkdir(temporary);
+    try {
+        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)] } } },
+        }, null, 2) + '\n');
+        if (connectionId)
+            await writeFile(join(temporary, '.app.json'), JSON.stringify({ apps: { agents: { id: connectionId } } }, null, 2) + '\n');
+        await writeFile(join(temporary, 'mcp.json'), JSON.stringify({ $schema: 'https://agent-plugins.org/schemas/1.0.0/mcp.schema.json', mcpServers: { agents: { type: 'streamable-http', url: url.href } } }, null, 2) + '\n');
+        await writeFile(join(temporary, 'skills/operate-existing-agent/SKILL.md'), skill);
+        for (const workflow of workflows) {
+            const path = `skills/${workflow.id}/SKILL.md`;
+            await mkdir(join(temporary, 'skills', workflow.id));
+            await writeFile(join(temporary, path), await readFile(new URL(`../${path}`, import.meta.url)));
+        }
+        await writeFile(join(temporary, 'agent-workflows.json'), JSON.stringify({
+            formatVersion: 1, authority: 'packaging-restrictions-only',
+            runtimeDiscoveryRequired: true, workflows: describeAgentWorkflows(m.actions),
+        }, null, 2) + '\n');
+        if (m.inspection) {
+            await mkdir(join(temporary, 'skills/tangle-agent-run-inspection'));
+            await writeFile(join(temporary, 'skills/tangle-agent-run-inspection/SKILL.md'), await readFile(new URL('../inspection/skills/tangle-agent-run-inspection/SKILL.md', import.meta.url)));
+        }
+        await writeFile(join(temporary, 'README.md'), [
+            '# Connect this Agent App', '',
+            'Your agent, tasks, files and billing stay in the original Tangle app.', '',
+            '1. In ChatGPT, enable developer mode and add an MCP connection.',
+            `2. Use this server URL: ${url.href}`,
+            '3. Sign in to the app and review its requested permissions.',
+            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.', '',
+            '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.', '',
+            'Generation does not install ChatGPT, register OAuth or run a task.', '',
+            '## Recovery', '',
+            'Run tangle-agents-plugin --check --endpoint with the exact server URL above for read-only discovery diagnostics.',
+            'A successful check is not OAuth login, tool dispatch, task completion, output retrieval, reconnect or customer-isolation proof.',
+            'For changed metadata, skills or connection IDs, generate to a new --out directory; existing packages are never edited in place.',
+            'Refresh hosted tool metadata separately from reinstalling changed package skills. Reconnect with the original native IDs; do not create a replacement agent.',
+            'Do not use --offline to bypass a failed online check. Keep the app owner responsible for OAuth and native admission.',
+            'The installed kit includes SETUP.md with the complete app-neutral setup, example and recovery flow.', '',
+        ].join('\n'));
+        await writeFile(join(temporary, 'readiness.json'), JSON.stringify({ formatVersion: 1, ...readiness, hostedTask: 'not-executed', chatgptInstall: 'not-executed' }, null, 2) + '\n');
+        // rename does not replace a nonempty existing package; no in-place mutation.
+        await rename(temporary, destination);
+    }
+    catch (error) {
+        await rm(temporary, { recursive: true, force: true });
+        if (['EEXIST', 'ENOTEMPTY'].includes(error.code ?? ''))
+            throw outputExists(destination);
+        throw error;
+    }
+    return { directory: destination, readiness };
+}
+/** Shared by the installed compiled bin and the existing source entry point. */
+export async function runPackageCli(args = process.argv.slice(2)) {
+    const usage = [
+        'Usage: tangle-agents-plugin [--config app.json] --endpoint https://APP/mcp [--out ./chatgpt-plugin] [--offline] [--connection-id ID]',
+        '       tangle-agents-plugin --check --endpoint https://APP/mcp',
+        '--check validates anonymous discovery and app metadata without writing a package or calling native tools.',
+        '--connection-id uses the real registered ChatGPT ID; it does not register or verify that connection.',
+        'Use a new --out directory on reruns. See node_modules/@tangle-network/chatgpt-agents-kit/SETUP.md.',
+    ].join('\n');
+    try {
+        const { values } = parseArgs({ args, options: { config: { type: 'string' }, endpoint: { type: 'string' }, out: { type: 'string' }, offline: { type: 'boolean', default: false }, check: { type: 'boolean', default: false }, 'connection-id': { type: 'string' }, help: { type: 'boolean', short: 'h' } } });
+        if (values.help) {
+            console.log(usage);
+            return;
+        }
+        if (!values.endpoint)
+            throw new Error(usage);
+        if (values.check) {
+            if (values.config !== undefined || values.out !== undefined || values.offline || values['connection-id'] !== undefined)
+                throw new Error('--check takes only --endpoint; it does not generate or bind a package');
+            const { metadata, url, readiness } = await inspectEndpoint(values.endpoint);
+            console.log(JSON.stringify({ endpoint: url.href, metadata,
+                readiness: { ...readiness, hostedTask: 'not-executed', chatgptInstall: 'not-executed' },
+                packageGeneration: 'not-executed',
+                nextStep: 'Register or verify this exact endpoint in ChatGPT, then generate with --connection-id and a new --out directory.',
+            }, null, 2));
+            return;
+        }
+        if (values.offline && !values.config)
+            throw new Error('--offline requires --config; endpoint metadata was not discovered');
+        const out = values.out ?? './chatgpt-plugin';
+        const result = values.config
+            ? await buildPackage(JSON.parse(await readFile(values.config, 'utf8')), values.endpoint, out, values.offline, values['connection-id'])
+            : await buildPackageFromEndpoint(values.endpoint, out, fetch, values['connection-id']);
+        console.log(JSON.stringify(result, null, 2));
+    }
+    catch (error) {
+        console.error(error instanceof Error ? error.message : 'Package generation failed');
+        process.exitCode = 1;
+    }
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(resolve(process.argv[1])).href) {
+    await runPackageCli();
+}

package/dist/src/sandbox-agent.d.ts

@@ -0,0 +1,35 @@
+import type { Sandbox } from '@tangle-network/sandbox/core';
+import type { NativeBinding, NativeServices, Target } from './contracts.ts';
+/** The application's EXISTING enrollment. Never derive sandbox/session ids from model input.
+ * Keep an existing thread pinned to this incarnation; replacing it requires an explicit
+ * application migration/new thread, not an automatic ensure() during a prompt. */
+export interface SandboxAgentTarget extends Target {
+    agentRef: string;
+    sandboxId: string;
+    sessionId: string;
+    filesystemIncarnationId: string;
+    instance?: {
+        key: string;
+        generation: number;
+    };
+    profileVersion?: string | null;
+}
+export interface SandboxAgentContext {
+    platformUserId: string;
+    applicationUserId: string;
+    appName: string;
+    name?: string;
+    /** User-scoped SDK, supplied by the native host. No shared privileged client. */
+    client: Pick<Sandbox, 'get' | 'instances'>;
+    requiredScopes: NativeBinding['requiredScopes'];
+    /** Recheck the original grant and the application's current target permissions. */
+    authorize: NativeBinding['authorize'];
+    list: NativeServices['list'];
+    resolve(target: Target): Promise<SandboxAgentTarget>;
+}
+/** Concrete SDK binding for an already-provisioned generic Sandbox agent.
+ * NOT a replacement for GTM/Creative's application-owned preparation/billing/approval path.
+ * The native session message lane owns durable admission, execution and retention.
+ * There is no plugin task database, ensure/create, worker loop, or request-owned execution.
+ */
+export declare function createSandboxAgentBinding(context: SandboxAgentContext): NativeBinding;

package/dist/src/sandbox-agent.js

@@ -0,0 +1,178 @@
+import { describeConnection } from "./connection.js";
+import { AgentFailure } from "./contracts.js";
+const id = (value) => typeof value === 'string' && /^[A-Za-z0-9_-]{1,256}$/.test(value);
+function environment(enrollment, box) {
+    return { kind: 'persistent-sandbox', sandboxId: enrollment.sandboxId, sessionId: enrollment.sessionId,
+        ...(box.filesystemIncarnationId ? { filesystemIncarnationId: box.filesystemIncarnationId } : {}),
+        ...(enrollment.instance ? { instanceKey: enrollment.instance.key, generation: enrollment.instance.generation } : {}),
+        ...(enrollment.profileVersion !== undefined ? { profileVersion: enrollment.profileVersion } : {}) };
+}
+/** Concrete SDK binding for an already-provisioned generic Sandbox agent.
+ * NOT a replacement for GTM/Creative's application-owned preparation/billing/approval path.
+ * The native session message lane owns durable admission, execution and retention.
+ * There is no plugin task database, ensure/create, worker loop, or request-owned execution.
+ */
+export function createSandboxAgentBinding(context) {
+    async function locate(target, action) {
+        await context.authorize(target, action);
+        const resolved = await context.resolve(target);
+        // Snapshot the enrollment before any I/O; host caches may reuse mutable objects.
+        const enrollment = resolved && { ...resolved, ...(resolved.instance ? { instance: { ...resolved.instance } } : {}) };
+        if (!enrollment || enrollment.workspaceId !== target.workspaceId || enrollment.threadId !== target.threadId
+            || !id(enrollment.sandboxId) || !id(enrollment.sessionId) || !enrollment.agentRef || typeof enrollment.filesystemIncarnationId !== 'string' || !enrollment.filesystemIncarnationId
+            || (enrollment.instance && !/^[A-Za-z0-9][A-Za-z0-9._:@-]{0,199}$/.test(enrollment.instance.key))
+            || (enrollment.instance && enrollment.profileVersion === undefined)
+            || (enrollment.instance && (!Number.isSafeInteger(enrollment.instance.generation) || enrollment.instance.generation < 0)))
+            throw new AgentFailure('agent_enrollment_invalid', 502);
+        if (enrollment.instance) {
+            const instance = await context.client.instances.get(enrollment.instance.key);
+            if (!instance || instance.sandboxId !== enrollment.sandboxId || instance.generation !== enrollment.instance.generation
+                || instance.profileVersion !== enrollment.profileVersion)
+                throw new AgentFailure('agent_environment_changed_reconnect_required', 409);
+        }
+        const box = await context.client.get(enrollment.sandboxId);
+        if (!box || box.id !== enrollment.sandboxId)
+            throw new AgentFailure('agent_environment_unavailable', 409);
+        if (enrollment.filesystemIncarnationId && box.filesystemIncarnationId !== enrollment.filesystemIncarnationId)
+            throw new AgentFailure('agent_filesystem_changed_reconnect_required', 409);
+        // Validate metadata before a prompt can cause any effect.
+        await describeConnection({ agentRef: enrollment.agentRef, environment: environment(enrollment, box) });
+        await context.authorize(target, action);
+        return { box, enrollment };
+    }
+    async function requireSession(box, sessionId) {
+        const info = await box.session(sessionId).status();
+        if (!info || info.id !== sessionId)
+            throw new AgentFailure('agent_session_missing_restore_required', 409);
+    }
+    async function retained(box, enrollment, turnId) {
+        if (box.status !== 'running')
+            throw new AgentFailure('agent_environment_sleeping_resume_required', 409);
+        const session = box.session(enrollment.sessionId);
+        const admission = await session.admission(turnId);
+        if (!admission)
+            throw new AgentFailure('native_turn_not_admitted', 404);
+        if (admission.sessionId !== enrollment.sessionId || admission.turnId !== turnId || !admission.executionId)
+            throw new AgentFailure('native_admission_invalid', 502);
+        const base = { workspaceId: enrollment.workspaceId, threadId: enrollment.threadId,
+            turnId: admission.turnId, executionId: admission.executionId,
+            environment: environment(enrollment, box), source: 'sandbox-session-admission' };
+        if (admission.status === 'unavailable')
+            return { ...base, state: 'unknown' };
+        const runs = await session.runs();
+        const matches = runs.filter(run => run.executionId === admission.executionId);
+        if (matches.length > 1 || (matches[0] && matches[0].sessionId !== enrollment.sessionId))
+            throw new AgentFailure('native_execution_invalid', 502);
+        const run = matches[0];
+        // Expired/missing replay does not mean failure, completion, or permission to rerun.
+        if (!run)
+            return { ...base, state: 'unknown' };
+        if (run.status === 'active') {
+            const requests = await session.interactions();
+            return { ...base, state: requests.some(request => request.binding.executionId === admission.executionId) ? 'input-required' : 'working' };
+        }
+        if (run.status === 'failed' || run.status === 'cancelled')
+            return { ...base, state: run.status };
+        if (run.status !== 'completed')
+            throw new AgentFailure('native_execution_invalid', 502);
+        return { ...base, state: 'succeeded', response: true,
+            ...(Number.isFinite(run.completedAt) ? { completedAt: new Date(run.completedAt).toISOString() } : {}) };
+    }
+    const services = {
+        list: context.list,
+        async connect(target) {
+            const { box, enrollment } = await locate(target, 'connect');
+            // A read does not wake or recreate the environment. The enrollment is retained
+            // while asleep; a prompt may resume that exact sandbox under its run grant.
+            if (box.status === 'running')
+                await requireSession(box, enrollment.sessionId);
+            return { agentRef: enrollment.agentRef, environment: environment(enrollment, box) };
+        },
+        async startTask(target, turnId, prompt, options) {
+            const { box, enrollment } = await locate(target, 'delegate');
+            if (['stopped', 'suspended'].includes(box.status)) {
+                await context.authorize(target, 'delegate');
+                await box.resume(); // Exact existing box. Never replace it on resume failure.
+            }
+            if (box.filesystemIncarnationId !== enrollment.filesystemIncarnationId)
+                throw new AgentFailure('agent_filesystem_changed_reconnect_required', 409);
+            await requireSession(box, enrollment.sessionId);
+            await context.authorize(target, 'delegate');
+            if (options?.contextVersion && options.contextVersion !== (await describeConnection({ agentRef: enrollment.agentRef, environment: environment(enrollment, box) })).contextVersion)
+                throw new AgentFailure('agent_context_changed_reconnect_required', 409);
+            // A named instance or host enrollment can move during the awaited session
+            // checks. The host must serialize migration with dispatch after this check.
+            const current = await context.resolve(target);
+            if (!current || current.workspaceId !== enrollment.workspaceId || current.threadId !== enrollment.threadId
+                || current.sandboxId !== enrollment.sandboxId || current.sessionId !== enrollment.sessionId
+                || current.agentRef !== enrollment.agentRef || current.filesystemIncarnationId !== enrollment.filesystemIncarnationId
+                || current.profileVersion !== enrollment.profileVersion || current.instance?.key !== enrollment.instance?.key
+                || current.instance?.generation !== enrollment.instance?.generation)
+                throw new AgentFailure('agent_environment_changed_reconnect_required', 409);
+            if (enrollment.instance) {
+                const instance = await context.client.instances.get(enrollment.instance.key);
+                if (!instance || instance.sandboxId !== enrollment.sandboxId || instance.generation !== enrollment.instance.generation
+                    || instance.profileVersion !== enrollment.profileVersion)
+                    throw new AgentFailure('agent_environment_changed_reconnect_required', 409);
+            }
+            await context.authorize(target, 'delegate');
+            // Use the maintained message lane directly: the native route owns input-bound
+            // replay and serialized admission. Unlike driveConversationTurn, this cannot
+            // create a missing session or read a cached answer under only a run grant.
+            const receipt = await box.session(enrollment.sessionId).sendMessage({
+                turnId, parts: [{ type: 'text', text: prompt }],
+            });
+            if (!receipt.info?.id || receipt.processing !== true)
+                throw new AgentFailure('native_admission_invalid', 502);
+            const task = await retained(box, enrollment, turnId);
+            if (task.executionId !== receipt.info.id)
+                throw new AgentFailure('native_execution_changed', 502);
+            return task;
+        },
+        async getTask(target, turnId) {
+            const { box, enrollment } = await locate(target, 'task');
+            // Read-only admission lookup. Never call driveConversationTurn with a dummy
+            // prompt: that path validates input and may admit work when misconfigured.
+            return retained(box, enrollment, turnId);
+        },
+        async readResponse(target, turnId) {
+            const { box, enrollment } = await locate(target, 'output');
+            const task = await retained(box, enrollment, turnId);
+            if (task.state !== 'succeeded' || !task.executionId || !task.completedAt)
+                return null;
+            const cached = await box.findCompletedTurn(turnId, { sessionId: enrollment.sessionId });
+            if (!cached)
+                return null;
+            if (cached.turnId !== turnId || cached.sessionId !== enrollment.sessionId
+                || cached.result.executionId !== task.executionId || !Number.isFinite(Date.parse(cached.completedAt)))
+                throw new AgentFailure('native_response_invalid', 502);
+            const content = cached.result.text ?? cached.result.response;
+            if (typeof content !== 'string')
+                throw new AgentFailure('native_response_invalid', 502);
+            const { deriveAgentResultOutcome } = await import('@tangle-network/sandbox');
+            const outcome = deriveAgentResultOutcome(cached.result);
+            await context.authorize(target, 'output');
+            return { workspaceId: enrollment.workspaceId, threadId: enrollment.threadId,
+                turnId: task.turnId, executionId: task.executionId, completedAt: task.completedAt,
+                content, mediaType: 'text/plain; charset=utf-8',
+                outcome: outcome.success ? 'completed' : outcome.status === 'failed' ? 'failed' : 'input-required' };
+        },
+        async cancelTask(target, turnId, executionId) {
+            const { box, enrollment } = await locate(target, 'cancel');
+            const before = await retained(box, enrollment, turnId);
+            if (before.executionId !== executionId)
+                throw new AgentFailure('native_execution_changed', 409);
+            if (['succeeded', 'failed', 'cancelled'].includes(before.state))
+                return before;
+            if (before.state === 'unknown')
+                throw new AgentFailure('native_execution_unavailable', 409);
+            await context.authorize(target, 'cancel');
+            await box.session(enrollment.sessionId).interrupt({ executionId });
+            // Acknowledgement alone is not proof that cancellation completed.
+            return retained(box, enrollment, turnId);
+        },
+    };
+    return { platformUserId: context.platformUserId, applicationUserId: context.applicationUserId,
+        appName: context.appName, ...(context.name ? { name: context.name } : {}), requiredScopes: context.requiredScopes,
+        authorize: context.authorize, services };
+}