@tangle-network/chatgpt-agents-kit 0.1.0

package/dist/src/task-events.d.ts

@@ -0,0 +1,238 @@
+import type { NativeBinding, Principal, Target } from './contracts.ts';
+export declare const TASK_EVENT = "agent.task_updated";
+export interface EventAccess {
+    principal: Principal;
+    binding: NativeBinding;
+    check(): Promise<void>;
+}
+export interface EventOwner {
+    app: string;
+    user: string;
+    nativeUser: string;
+    client: string;
+    grant: string;
+}
+export interface Subscription {
+    owner: EventOwner;
+    target: Target;
+    turnId: string;
+    url: string;
+    secret: string;
+    previousSecret?: string;
+    rotateUntil?: number;
+    verifiedUntil: number;
+    epoch: string;
+    active: boolean;
+    expires: number;
+    nextAt: number;
+    lastDigest?: string;
+    pending?: {
+        digest: string;
+        body: string;
+        eventId: string;
+    };
+    attempts: number;
+    lastError?: string;
+}
+export interface EventRow {
+    id: string;
+    revision: number;
+    data: Subscription;
+}
+/** Use the host's database/vault. CAS must be atomic across processes; secrets
+ * must be encrypted at rest. These records are delivery state, NOT agent tasks. */
+export interface EventStore {
+    get(id: string): Promise<EventRow | null>;
+    put(id: string, expectedRevision: number | null, data: Subscription): Promise<boolean>;
+    due(now: number, limit: number): Promise<EventRow[]>;
+    nextDue(): Promise<number | null>;
+}
+export interface WebhookResponse {
+    status: number;
+    body: string;
+}
+/** Must pin validated public addresses at connection time, retain TLS hostname,
+ * reject redirects, bound response bytes and enforce the supplied AbortSignal. */
+export type WebhookPost = (url: string, body: string, headers: Record<string, string>, signal: AbortSignal) => Promise<WebhookResponse>;
+export interface TaskEventsOptions {
+    store: EventStore;
+    post: WebhookPost;
+    requiredScopes: readonly string[];
+    /** Persist a native grant REFERENCE, never an access/refresh token. */
+    grant(access: EventAccess): Promise<string | null>;
+    /** Resolve the original still-active native grant with fresh identity/scopes.
+     * null means revoked; throw for an outage. Never reconstruct a privileged client. */
+    resolve(owner: EventOwner): Promise<EventAccess | null>;
+    /** Enqueue the existing host worker. That worker calls drain(), also after
+     * retained native task updates and on its existing recovery/retry cadence. */
+    wake(at: number): Promise<void>;
+    now?: () => number;
+}
+/** Standard Webhooks signing format; serializes no body and exposes no key. */
+export declare function signedEventHeaders(id: string, subscriptionId: string, body: string, secrets: readonly string[], now: number): Promise<{
+    'content-type': string;
+    'webhook-id': string;
+    'webhook-timestamp': string;
+    'webhook-signature': string;
+    'X-MCP-Subscription-Id': string;
+}>;
+export declare const TASK_EVENT_DEFINITION: {
+    name: string;
+    description: string;
+    delivery: string[];
+    inputSchema: {
+        type: string;
+        properties: {
+            workspaceId: {
+                type: string;
+                pattern: string;
+            };
+            threadId: {
+                type: string;
+                pattern: string;
+            };
+            turnId: {
+                type: string;
+                pattern: string;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+    payloadSchema: {
+        type: string;
+        properties: {
+            workspaceId: {
+                type: string;
+                pattern: string;
+            };
+            threadId: {
+                type: string;
+                pattern: string;
+            };
+            turnId: {
+                type: string;
+                pattern: string;
+            };
+            state: {
+                type: string;
+                enum: string[];
+            };
+            executionId: {
+                type: string[];
+            };
+            completionVerified: {
+                const: boolean;
+            };
+        };
+        required: string[];
+        additionalProperties: boolean;
+    };
+};
+export declare function createTaskEvents(options: TaskEventsOptions): {
+    available: (access: EventAccess) => Promise<boolean>;
+    rpc: (method: string, raw: unknown, access: EventAccess) => Promise<{
+        result: {
+            events: {
+                name: string;
+                description: string;
+                delivery: string[];
+                inputSchema: {
+                    type: string;
+                    properties: {
+                        workspaceId: {
+                            type: string;
+                            pattern: string;
+                        };
+                        threadId: {
+                            type: string;
+                            pattern: string;
+                        };
+                        turnId: {
+                            type: string;
+                            pattern: string;
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                };
+                payloadSchema: {
+                    type: string;
+                    properties: {
+                        workspaceId: {
+                            type: string;
+                            pattern: string;
+                        };
+                        threadId: {
+                            type: string;
+                            pattern: string;
+                        };
+                        turnId: {
+                            type: string;
+                            pattern: string;
+                        };
+                        state: {
+                            type: string;
+                            enum: string[];
+                        };
+                        executionId: {
+                            type: string[];
+                        };
+                        completionVerified: {
+                            const: boolean;
+                        };
+                    };
+                    required: string[];
+                    additionalProperties: boolean;
+                };
+            }[];
+            id?: undefined;
+            refreshBefore?: undefined;
+            cursor?: undefined;
+            truncated?: undefined;
+        };
+        error?: undefined;
+    } | {
+        error: {
+            code: number;
+            message: string;
+            data?: undefined;
+        };
+        result?: undefined;
+    } | {
+        result: {
+            events?: undefined;
+            id?: undefined;
+            refreshBefore?: undefined;
+            cursor?: undefined;
+            truncated?: undefined;
+        };
+        error?: undefined;
+    } | {
+        result: {
+            id: string;
+            refreshBefore: string;
+            cursor: null;
+            truncated: boolean;
+            events?: undefined;
+        };
+        error?: undefined;
+    } | {
+        error: {
+            code: number;
+            message: string;
+            data: {
+                reason: string;
+            };
+        };
+        result?: undefined;
+    }>;
+    drain: (limit?: number) => Promise<{
+        nextWakeAt: number | null;
+        examined: number;
+        accepted: number;
+        stopped: number;
+        deferred: number;
+    }>;
+};
+export type TaskEvents = ReturnType<typeof createTaskEvents>;

package/dist/src/task-events.js

@@ -0,0 +1,268 @@
+import { AgentFailure } from "./contracts.js";
+import { validateNativeTask } from "./task-wait.js";
+export const TASK_EVENT = 'agent.task_updated';
+class EventFailure extends Error {
+    code;
+    reason;
+    constructor(code, reason) { super(reason); this.code = code; this.reason = reason; }
+}
+const encoder = new TextEncoder();
+const hash = async (text) => Array.from(new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(text))), x => x.toString(16).padStart(2, '0')).join('');
+const object = (v) => !!v && typeof v === 'object' && !Array.isArray(v);
+function keys(v, allowed) {
+    if (Object.keys(v).some(k => !allowed.includes(k)))
+        throw new EventFailure(-32602, 'invalid_arguments');
+}
+function signingKey(secret) {
+    if (!/^whsec_[A-Za-z0-9+/]+={0,2}$/.test(secret))
+        throw new EventFailure(-32602, 'invalid_signing_secret');
+    let bytes;
+    try {
+        bytes = Uint8Array.from(atob(secret.slice(6)), c => c.charCodeAt(0));
+    }
+    catch {
+        throw new EventFailure(-32602, 'invalid_signing_secret');
+    }
+    if (bytes.length < 24 || bytes.length > 64 || btoa(String.fromCharCode(...bytes)) !== secret.slice(6))
+        throw new EventFailure(-32602, 'invalid_signing_secret');
+    return bytes;
+}
+/** Standard Webhooks signing format; serializes no body and exposes no key. */
+export async function signedEventHeaders(id, subscriptionId, body, secrets, now) {
+    if (encoder.encode(body).length > 262144)
+        throw new EventFailure(-32602, 'payload_too_large');
+    const timestamp = String(Math.floor(now / 1000));
+    const signatures = await Promise.all(secrets.map(async (secret) => {
+        const key = await crypto.subtle.importKey('raw', signingKey(secret), { name: 'HMAC', hash: 'SHA-256' }, false, ['sign']);
+        const bytes = new Uint8Array(await crypto.subtle.sign('HMAC', key, encoder.encode(`${id}.${timestamp}.${body}`)));
+        return `v1,${btoa(String.fromCharCode(...bytes))}`;
+    }));
+    return { 'content-type': 'application/json', 'webhook-id': id, 'webhook-timestamp': timestamp,
+        'webhook-signature': signatures.join(' '), 'X-MCP-Subscription-Id': subscriptionId };
+}
+function equalChallenge(a, b) {
+    if (typeof a !== 'string')
+        return false;
+    const left = encoder.encode(a), right = encoder.encode(b);
+    let diff = left.length ^ right.length;
+    for (let i = 0; i < right.length; i++)
+        diff |= (left[i] ?? 0) ^ right[i];
+    return diff === 0;
+}
+const idSchema = { type: 'string', pattern: '^[A-Za-z0-9_-]{1,256}$' };
+export const TASK_EVENT_DEFINITION = {
+    name: TASK_EVENT,
+    description: 'A retained Tangle task has a newly observed state. Filter one exact workspace, thread and turn. Retrieve get_task for current verified outputs; events never authorize actions.',
+    delivery: ['webhook'],
+    inputSchema: { type: 'object', properties: { workspaceId: idSchema, threadId: idSchema, turnId: idSchema }, required: ['workspaceId', 'threadId', 'turnId'], additionalProperties: false },
+    payloadSchema: { type: 'object', properties: { workspaceId: idSchema, threadId: idSchema, turnId: idSchema,
+            state: { type: 'string', enum: ['queued', 'working', 'input-required', 'succeeded', 'failed', 'cancelled', 'unknown'] },
+            executionId: { type: ['string', 'null'] }, completionVerified: { const: false } },
+        required: ['workspaceId', 'threadId', 'turnId', 'state', 'executionId', 'completionVerified'], additionalProperties: false },
+};
+export function createTaskEvents(options) {
+    if (!options.requiredScopes.length || options.requiredScopes.some(s => !/^[\x21\x23-\x5B\x5D-\x7E]{1,256}$/.test(s)))
+        throw new Error('events_scopes_required');
+    const now = options.now ?? Date.now;
+    async function available(access) {
+        const b = access.binding;
+        const taskScopes = b.requiredScopes.task, outputScopes = b.requiredScopes.output;
+        return b.platformUserId === access.principal.userId && !!b.services.getTask && (!!b.services.readFile || !!b.services.readResponse)
+            && taskScopes !== undefined && outputScopes !== undefined
+            && [...options.requiredScopes, ...taskScopes, ...outputScopes].every(s => access.principal.scopes.includes(s));
+    }
+    async function ownerOf(access) {
+        await access.check();
+        const grant = await options.grant(access);
+        const client = access.principal.clientId;
+        if (!grant || !client || grant.length > 256 || client.length > 1024)
+            throw new EventFailure(-32001, 'events_grant_unavailable');
+        return { app: access.binding.appName, user: access.principal.userId, nativeUser: access.binding.applicationUserId, client, grant };
+    }
+    async function checked(owner, target) {
+        const access = await options.resolve(owner);
+        if (!access)
+            return null;
+        if (!await available(access) || JSON.stringify(await ownerOf(access)) !== JSON.stringify(owner))
+            return null;
+        await access.binding.authorize(target, 'task');
+        await access.check();
+        return access;
+    }
+    const identity = (owner, url, target, turnId) => hash(JSON.stringify([owner.app, owner.user, owner.nativeUser, owner.client, owner.grant, url, TASK_EVENT, target.workspaceId, target.threadId, turnId]));
+    async function rpc(method, raw, access) {
+        try {
+            if (!object(raw))
+                throw new EventFailure(-32602, 'invalid_arguments');
+            if (method === 'events/list') {
+                keys(raw, ['cursor', '_meta']);
+                if (raw.cursor != null)
+                    throw new EventFailure(-32602, 'cursor_unsupported');
+                return { result: { events: await available(access) ? [TASK_EVENT_DEFINITION] : [] } };
+            }
+            if (!['events/subscribe', 'events/unsubscribe'].includes(method))
+                return { error: { code: -32601, message: 'Method not found' } };
+            keys(raw, ['name', 'arguments', 'delivery', 'cursor', 'ttlMs', '_meta']);
+            if (raw.name !== TASK_EVENT || !object(raw.arguments) || !object(raw.delivery))
+                throw new EventFailure(-32602, 'invalid_arguments');
+            keys(raw.arguments, ['workspaceId', 'threadId', 'turnId']);
+            keys(raw.delivery, method === 'events/subscribe' ? ['mode', 'url', 'secret'] : ['mode', 'url']);
+            const { workspaceId, threadId, turnId } = raw.arguments;
+            if (![workspaceId, threadId, turnId].every(v => typeof v === 'string' && /^[A-Za-z0-9_-]{1,256}$/.test(v)))
+                throw new EventFailure(-32602, 'invalid_target');
+            const target = { workspaceId: workspaceId, threadId: threadId };
+            if (raw.delivery.mode !== 'webhook' || typeof raw.delivery.url !== 'string' || raw.delivery.url.length > 2048)
+                throw new EventFailure(-32602, 'invalid_delivery');
+            const url = new URL(raw.delivery.url);
+            if (url.protocol !== 'https:' || url.username || url.password || url.hash)
+                throw new EventFailure(-32602, 'invalid_callback_url');
+            const owner = await ownerOf(access);
+            const id = `sub_${await identity(owner, url.href, target, turnId)}`;
+            const previous = await options.store.get(id);
+            if (method === 'events/unsubscribe') {
+                // An owner can stop delivery even after workspace access is removed.
+                const stopped = previous ? { ...previous.data, active: false, secret: '', previousSecret: undefined, pending: undefined, nextAt: now() }
+                    : { owner, target, turnId: turnId, url: url.href, secret: '', epoch: crypto.randomUUID(), active: false, expires: now(), verifiedUntil: 0, nextAt: now(), attempts: 0 };
+                if (!await options.store.put(id, previous?.revision ?? null, stopped))
+                    throw new EventFailure(-32000, 'subscription_conflict_retry');
+                return { result: {} };
+            }
+            if (!await available(access))
+                throw new EventFailure(-32001, 'events_not_authorized');
+            await access.binding.authorize(target, 'task');
+            await access.check();
+            if (raw.cursor != null)
+                throw new EventFailure(-32602, 'replay_unsupported');
+            if (typeof raw.delivery.secret !== 'string')
+                throw new EventFailure(-32602, 'invalid_signing_secret');
+            signingKey(raw.delivery.secret);
+            if (raw.ttlMs != null && (!Number.isSafeInteger(raw.ttlMs) || raw.ttlMs <= 0))
+                throw new EventFailure(-32602, 'invalid_ttl');
+            const time = now(), ttl = Math.min(typeof raw.ttlMs === 'number' ? raw.ttlMs : 86400000, 86400000);
+            const retained = previous?.data.active && previous.data.expires > time ? previous.data : undefined;
+            // Cache only this principal + URL + verified key, never share verification across tenants.
+            if (!retained || retained.secret !== raw.delivery.secret || retained.verifiedUntil <= time) {
+                const challenge = crypto.randomUUID(), body = JSON.stringify({ type: 'verification', challenge });
+                try {
+                    const response = await options.post(url.href, body, await signedEventHeaders(`verify_${crypto.randomUUID()}`, id, body, [raw.delivery.secret], time), AbortSignal.timeout(10000));
+                    if (response.status < 200 || response.status >= 300 || !equalChallenge(JSON.parse(response.body).challenge, challenge))
+                        throw new Error('challenge_failed');
+                }
+                catch {
+                    throw new EventFailure(-32015, 'challenge_failed');
+                }
+            }
+            await access.binding.authorize(target, 'task');
+            await access.check();
+            const data = { owner, target, turnId: turnId, url: url.href, secret: raw.delivery.secret,
+                epoch: retained?.epoch ?? crypto.randomUUID(), active: true, expires: now() + ttl, verifiedUntil: now() + 300000,
+                nextAt: now(), attempts: 0, lastDigest: retained?.lastDigest, pending: retained?.pending,
+                ...(retained && retained.secret !== raw.delivery.secret ? { previousSecret: retained.secret, rotateUntil: now() + 300000 }
+                    : retained?.previousSecret && (retained.rotateUntil ?? 0) > now() ? { previousSecret: retained.previousSecret, rotateUntil: retained.rotateUntil } : {}), };
+            if (!await options.store.put(id, previous?.revision ?? null, data))
+                throw new EventFailure(-32000, 'subscription_conflict_retry');
+            await options.wake(now());
+            return { result: { id, refreshBefore: new Date(data.expires).toISOString(), cursor: null, truncated: false } };
+        }
+        catch (error) {
+            return { error: { code: error instanceof EventFailure ? error.code : -32000,
+                    message: error instanceof EventFailure && error.code === -32015 ? 'CallbackEndpointError' : 'Event operation failed',
+                    data: { reason: error instanceof EventFailure ? error.reason : 'event_operation_failed' } } };
+        }
+    }
+    /** One bounded pass, called by the host's EXISTING worker; no timer, second
+     * scheduler or process-local task store. Reads native state to close the
+     * subscribe/completion race and reconcile restarts. No event-history replay. */
+    async function drain(limit = 32) {
+        if (!Number.isInteger(limit) || limit < 1 || limit > 128)
+            throw new Error('invalid_event_batch');
+        const summary = { examined: 0, accepted: 0, stopped: 0, deferred: 0 };
+        for (const row of await options.store.due(now(), limit)) {
+            const leased = { ...row.data, nextAt: now() + 30000 };
+            if (!await options.store.put(row.id, row.revision, leased))
+                continue;
+            const revision = row.revision + 1;
+            summary.examined++;
+            let next = { ...leased };
+            try {
+                if (!leased.active || leased.expires <= now()) {
+                    next = { ...leased, active: false, secret: '', previousSecret: undefined, pending: undefined };
+                    summary.stopped++;
+                }
+                else {
+                    const access = await checked(leased.owner, leased.target);
+                    if (!access) {
+                        next = { ...leased, active: false, secret: '', previousSecret: undefined, pending: undefined };
+                        summary.stopped++;
+                    }
+                    else {
+                        if (!next.pending) {
+                            const task = await access.binding.services.getTask(leased.target, leased.turnId);
+                            validateNativeTask(task, leased.target, leased.turnId);
+                            const data = { ...leased.target, turnId: leased.turnId, state: task.state, executionId: task.executionId ?? null, completionVerified: false };
+                            if (data.executionId !== null && (typeof data.executionId !== 'string' || data.executionId.length > 1024))
+                                throw new Error('native_task_invalid');
+                            const digest = await hash(JSON.stringify([data, task.completedAt ?? null, task.outputs ?? []]));
+                            if (digest !== leased.lastDigest) {
+                                const eventId = `evt_${await hash(`${row.id}:${leased.epoch}:${digest}`)}`;
+                                next.pending = { digest, eventId, body: JSON.stringify({ eventId, name: TASK_EVENT, timestamp: new Date(now()).toISOString(), data, cursor: null }) };
+                            }
+                        }
+                        if (next.pending) {
+                            // Persist the exact event bytes BEFORE network I/O. Crash/retry uses the same eventId.
+                            if (!await options.store.put(row.id, revision, next))
+                                continue;
+                            const accessNow = await checked(leased.owner, leased.target);
+                            const current = await options.store.get(row.id);
+                            if (!current || current.revision !== revision + 1 || !current.data.active || current.data.expires <= now())
+                                continue;
+                            if (!accessNow) {
+                                await options.store.put(row.id, current.revision, { ...next, active: false, secret: '', previousSecret: undefined, pending: undefined });
+                                summary.stopped++;
+                                continue;
+                            }
+                            const secrets = [next.secret, ...(next.previousSecret && (next.rotateUntil ?? 0) > now() ? [next.previousSecret] : [])];
+                            let status = 0;
+                            try {
+                                status = (await options.post(next.url, next.pending.body, await signedEventHeaders(next.pending.eventId, row.id, next.pending.body, secrets, now()), AbortSignal.timeout(10000))).status;
+                            }
+                            catch { /* bounded retry, no upstream diagnostics */ }
+                            if (status >= 200 && status < 300) {
+                                next = { ...next, lastDigest: next.pending.digest, pending: undefined, attempts: 0, nextAt: now() + 10000, lastError: undefined };
+                                summary.accepted++;
+                            }
+                            else if (status === 410 || status === 413 || (status >= 400 && status < 500 && status !== 408 && status !== 429) || next.attempts >= 7) {
+                                next = { ...next, active: false, secret: '', previousSecret: undefined, pending: undefined, lastError: `callback_${status || 'unavailable'}` };
+                                summary.stopped++;
+                            }
+                            else {
+                                next = { ...next, attempts: next.attempts + 1, nextAt: now() + Math.min(300000, 1000 * 2 ** next.attempts), lastError: `callback_${status || 'unavailable'}` };
+                                summary.deferred++;
+                            }
+                            await options.store.put(row.id, revision + 1, next);
+                            continue;
+                        }
+                        next.nextAt = now() + 10000;
+                    }
+                }
+            }
+            catch (error) {
+                if (error instanceof AgentFailure && [401, 403].includes(error.status)) {
+                    next = { ...next, active: false, secret: '', previousSecret: undefined, pending: undefined };
+                    summary.stopped++;
+                }
+                else {
+                    next.nextAt = now() + 30000;
+                    next.lastError = 'native_observation_unavailable';
+                    summary.deferred++;
+                }
+            }
+            await options.store.put(row.id, revision, next);
+        }
+        const nextWakeAt = await options.store.nextDue();
+        if (nextWakeAt !== null)
+            await options.wake(Math.max(now() + 10, nextWakeAt));
+        return { ...summary, nextWakeAt };
+    }
+    return { available, rpc, drain };
+}

package/dist/src/task-wait.d.ts

@@ -0,0 +1,26 @@
+import type { NativeTask, Target } from './contracts.ts';
+/** A bounded observation of an existing native task, never an execution driver. */
+export interface TaskWaitPolicy {
+    defaultMs?: number;
+    maxMs?: number;
+    intervalMs?: number;
+}
+export declare const MAX_TASK_WAIT_MS = 25000;
+export declare function taskWaitPolicy(policy?: TaskWaitPolicy): {
+    maxMs: number;
+    defaultMs: number;
+    intervalMs: number;
+};
+export declare function validateNativeTask(task: NativeTask, target: Target, turnId: string): void;
+/** Stops starting reads at the deadline. Hosts must bound their native read I/O;
+ * abandoning a Promise would leak in-flight work and is deliberately not used. */
+export declare function observeTask(options: {
+    target: Target;
+    turnId: string;
+    initial: NativeTask;
+    waitMs: number;
+    intervalMs: number;
+    signal: AbortSignal;
+    check(): Promise<void>;
+    read(): Promise<NativeTask>;
+}): Promise<NativeTask>;

package/dist/src/task-wait.js

@@ -0,0 +1,61 @@
+import { projectEnvironment } from "./connection.js";
+import { AgentFailure } from "./contracts.js";
+export const MAX_TASK_WAIT_MS = 25_000;
+export function taskWaitPolicy(policy = {}) {
+    const maxMs = policy.maxMs ?? MAX_TASK_WAIT_MS;
+    const defaultMs = policy.defaultMs ?? Math.min(15_000, maxMs);
+    const intervalMs = policy.intervalMs ?? 500;
+    if (![maxMs, defaultMs, intervalMs].every(Number.isSafeInteger) || maxMs < 0 || maxMs > MAX_TASK_WAIT_MS
+        || defaultMs < 0 || defaultMs > maxMs || intervalMs < 10 || intervalMs > 5_000)
+        throw new Error('invalid_task_wait_policy');
+    return { maxMs, defaultMs, intervalMs };
+}
+export function validateNativeTask(task, target, turnId) {
+    if (!task || task.workspaceId !== target.workspaceId || task.threadId !== target.threadId || task.turnId !== turnId
+        || typeof task.source !== 'string' || !task.source || task.source.length > 2048
+        || (task.executionId !== undefined && (typeof task.executionId !== 'string' || !task.executionId || task.executionId.length > 1024)) || !['queued', 'working', 'input-required', 'succeeded', 'failed', 'cancelled', 'unknown'].includes(task.state))
+        throw new AgentFailure('native_task_invalid', 502);
+}
+function pause(ms, signal) {
+    return new Promise((resolve, reject) => {
+        const abort = () => { clearTimeout(timer); reject(new AgentFailure('observation_cancelled', 499)); };
+        const timer = setTimeout(() => { signal.removeEventListener('abort', abort); resolve(); }, ms);
+        signal.addEventListener('abort', abort, { once: true });
+        if (signal.aborted) {
+            signal.removeEventListener('abort', abort);
+            abort();
+        }
+    });
+}
+/** Stops starting reads at the deadline. Hosts must bound their native read I/O;
+ * abandoning a Promise would leak in-flight work and is deliberately not used. */
+export async function observeTask(options) {
+    const deadline = performance.now() + options.waitMs;
+    let task = options.initial;
+    let executionId = task.executionId;
+    let environment = task.environment ? JSON.stringify(projectEnvironment(task.environment)) : undefined;
+    validateNativeTask(task, options.target, options.turnId);
+    while (['queued', 'working'].includes(task.state) && performance.now() < deadline) {
+        if (options.signal.aborted)
+            throw new AgentFailure('observation_cancelled', 499);
+        await pause(Math.min(options.intervalMs, Math.max(1, deadline - performance.now())), options.signal);
+        if (performance.now() >= deadline)
+            break;
+        await options.check();
+        if (options.signal.aborted)
+            throw new AgentFailure('observation_cancelled', 499);
+        task = await options.read();
+        validateNativeTask(task, options.target, options.turnId);
+        if (executionId && task.executionId !== executionId)
+            throw new AgentFailure('native_execution_changed', 502);
+        executionId ??= task.executionId;
+        const observedEnvironment = task.environment ? JSON.stringify(projectEnvironment(task.environment)) : undefined;
+        if (environment && observedEnvironment !== environment)
+            throw new AgentFailure('native_environment_changed', 502);
+        environment ??= observedEnvironment;
+        await options.check();
+    }
+    if (options.signal.aborted)
+        throw new AgentFailure('observation_cancelled', 499);
+    return task;
+}

package/dist/src/workflows.d.ts

@@ -0,0 +1,19 @@
+import type { Action } from './contracts.ts';
+/** One vocabulary for native tool discovery, packaging and workflow selection. */
+export declare const ACTION_TOOLS: Readonly<Record<Action, string>>;
+export interface AgentWorkflow {
+    id: string;
+    title: string;
+    prompt: string;
+    requires: readonly Action[];
+}
+export declare const HANDOFF_ACTIONS: readonly Action[];
+/** These compose existing actions. They neither register tools nor grant access. */
+export declare const AGENT_WORKFLOWS: readonly AgentWorkflow[];
+export declare function selectAgentWorkflows(actions: readonly Action[]): AgentWorkflow[];
+export declare function describeAgentWorkflows(actions: readonly Action[]): {
+    id: string;
+    title: string;
+    prompt: string;
+    requiredTools: string[];
+}[];

package/dist/src/workflows.js

@@ -0,0 +1,38 @@
+/** One vocabulary for native tool discovery, packaging and workflow selection. */
+export const ACTION_TOOLS = {
+    list: 'list_my_agents', connect: 'connect_my_agent', create: 'create_an_agent',
+    handoff: 'handoff_file', delegate: 'prompt_agent', task: 'get_task', output: 'read_output',
+    decisions: 'list_pending_decisions', decide: 'respond_to_decision', channel: 'continue_in_channel', cancel: 'cancel_agent_run',
+};
+export const HANDOFF_ACTIONS = ['connect', 'handoff', 'output', 'delegate', 'task'];
+/** 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.',
+        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.',
+        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.',
+        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.',
+        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.',
+        requires: ['connect', 'decisions', 'decide'] },
+    { id: 'continue-agent-in-channel', title: 'Continue with the same agent by message',
+        prompt: 'Continue this task through an already connected messaging channel.',
+        requires: ['connect', 'channel'] },
+];
+export function selectAgentWorkflows(actions) {
+    const available = new Set(actions);
+    return AGENT_WORKFLOWS.filter(workflow => workflow.requires.every(action => available.has(action)))
+        .map(workflow => ({ ...workflow, requires: [...workflow.requires] }));
+}
+export function describeAgentWorkflows(actions) {
+    return selectAgentWorkflows(actions).map(({ id, title, prompt, requires }) => ({
+        id, title, prompt, requiredTools: requires.map(action => ACTION_TOOLS[action]),
+    }));
+}