toolroll 0.5.0

package/dist/session-brief.d.ts

@@ -0,0 +1,8 @@
+import type { SessionBrief, SessionResult, SessionView } from './session-contract.js';
+export type SavedSessionBrief = SessionBrief & {
+    sourceItemIds: string[];
+    partialHistory: boolean;
+};
+/** FirstMate-style bearings from saved facts, without another model call or
+ * supervisor. Agent text is explicitly a report, never verification evidence. */
+export declare function savedSessionBrief(session: SessionView, items: NonNullable<SessionResult['items']>, nextAction: string, partialHistory: boolean): SavedSessionBrief;

package/dist/session-brief.js

@@ -0,0 +1,24 @@
+const states = {
+    starting: 'Starting', ready: 'Ready to continue', working: 'Working', 'needs-input': 'Waiting for your answer',
+    stopping: 'Stopping the current turn', interrupted: 'Saved; reconnect to continue', failed: 'Stopped with an error',
+    uncertain: 'Delivery needs review', closed: 'Closed; saved work is preserved',
+};
+const excerpt = (text, limit) => {
+    const one = text.replace(/\s+/g, ' ').trim();
+    return one.length > limit ? `${one.slice(0, limit - 1)}…` : one;
+};
+/** FirstMate-style bearings from saved facts, without another model call or
+ * supervisor. Agent text is explicitly a report, never verification evidence. */
+export function savedSessionBrief(session, items, nextAction, partialHistory) {
+    const request = [...items].reverse().find(one => one.type === 'userMessage');
+    const update = [...items].reverse().find(one => one.type === 'agentMessage');
+    const lines = [`${session.title} — ${states[session.status] ?? session.status}.`];
+    if (request)
+        lines.push(`Latest saved request: ${excerpt(request.text, 280)}`);
+    if (update)
+        lines.push(`Latest saved agent report: ${excerpt(update.text, 600)}`);
+    if (session.error)
+        lines.push(excerpt(session.error, 400));
+    return { summary: lines.join('\n'), nextAction, sourceRevision: session.revision,
+        sourceItemIds: [request?.id, update?.id].filter((id) => id !== undefined), partialHistory };
+}

package/dist/session-cli.d.ts

@@ -0,0 +1,13 @@
+import { type SessionDescriptor, type SessionOperation } from './session-contract.js';
+export type SessionCliOptions = {
+    fetch?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    readStdin?: () => Promise<string>;
+    stderr?: (line: string) => void;
+};
+export declare const SESSION_CLI_ACTIONS: readonly ["capabilities", ...SessionOperation[]];
+export declare function sessionCliFlags(spec: SessionDescriptor): Record<string, 'value' | 'flag'>;
+/** Credentials are never sent to a URL with embedded authority, an API path,
+ * query, fragment or an insecure remote host. Fetch cannot follow redirects. */
+export declare function sessionServiceOrigin(raw: string): string;
+export declare function runSessionCommand(argv: readonly string[], write: (line: string) => void, options?: SessionCliOptions): Promise<number>;

package/dist/session-cli.js

@@ -0,0 +1,284 @@
+import { open } from 'node:fs/promises';
+import { envelopeJson } from './envelope.js';
+import { SESSION_DESCRIPTORS, SESSION_PROMPT_BYTES, SESSION_RESPONSE_BYTES, isSessionResponse, sessionCapabilities, sessionDescriptor, validateSessionRequest, } from './session-contract.js';
+const commonFlags = { url: 'value', as: 'value', 'token-env': 'value', 'token-file': 'value', json: 'flag', help: 'flag' };
+export const SESSION_CLI_ACTIONS = ['capabilities', ...SESSION_DESCRIPTORS.map(one => one.operation)];
+export function sessionCliFlags(spec) {
+    return { ...commonFlags, ...Object.fromEntries(Object.keys(spec.flags).map(name => [name, 'value'])), ...(spec.operation === 'start' || spec.operation === 'send' ? { file: 'value', stdin: 'flag' } : {}) };
+}
+function help(spec) {
+    if (!spec)
+        return `toolroll session <operation>\n\n${SESSION_DESCRIPTORS.map(one => `  ${one.operation.padEnd(12)} ${one.synopsis}`).join('\n')}\n  capabilities  Show this client's schemas and authority requirements\n\nUse session <operation> --help for required flags. Session controls require operator credentials. Chat is the separate coordinator conversation.`;
+    const fields = spec.inputSchema.required.filter(one => !['version', 'sessionId', 'prompt'].includes(one));
+    const required = fields.map(field => Object.entries(spec.flags).find(([, value]) => value.field === field)?.[0]).filter(Boolean);
+    return `toolroll session ${spec.operation}${'sessionId' in spec.inputSchema.properties ? ' <session-id>' : ''}\n${spec.synopsis}.\n\nRequired: --url <service-origin> --as <operator>\n  --token-env <variable-name> or --token-file <path>\n${required.map(name => `  --${name} <value>`).join('\n')}${'prompt' in spec.inputSchema.properties ? '\n  --file <path> or --stdin (complete prompt, up to 64 KB)' : ''}\n${'expectedRevision' in spec.inputSchema.properties ? '\nUse the revision, nativeThreadId and turnId from session show. Use none for a null thread or turn.\n' : ''}\nOptions: ${Object.keys(sessionCliFlags(spec)).map(name => `--${name}`).join(' ')}\nCredentials are sent only to the named HTTPS service or loopback HTTP. Redirects and automatic mutation retries are disabled.`;
+}
+class UsageError extends Error {
+}
+async function readBoundedFile(path, limit, label) {
+    let file;
+    try {
+        file = await open(path, 'r');
+        const stat = await file.stat();
+        if (!stat.isFile() || stat.size > limit)
+            throw new Error();
+        const buffer = Buffer.alloc(limit + 1);
+        let offset = 0;
+        while (offset <= limit) {
+            const { bytesRead } = await file.read(buffer, offset, buffer.length - offset, null);
+            if (!bytesRead)
+                break;
+            offset += bytesRead;
+        }
+        if (offset > limit)
+            throw new Error();
+        return new TextDecoder('utf-8', { fatal: true }).decode(buffer.subarray(0, offset));
+    }
+    catch {
+        throw new UsageError(`${label} must be a readable UTF-8 regular file of at most ${limit} bytes.`);
+    }
+    finally {
+        await file?.close();
+    }
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        throw new UsageError('Pipe the complete prompt into --stdin, or use --file.');
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of process.stdin) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > SESSION_PROMPT_BYTES)
+            throw new UsageError('The prompt exceeds 64 KB.');
+        chunks.push(buffer);
+    }
+    try {
+        return new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks));
+    }
+    catch {
+        throw new UsageError('The prompt must be UTF-8 text.');
+    }
+}
+/** Credentials are never sent to a URL with embedded authority, an API path,
+ * query, fragment or an insecure remote host. Fetch cannot follow redirects. */
+export function sessionServiceOrigin(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new UsageError('--url must be an HTTPS or loopback HTTP service origin.');
+    }
+    if (url.username || url.password || url.search || url.hash || url.pathname !== '/')
+        throw new UsageError('--url must contain only the service origin, with no credentials, path, query or fragment.');
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && ['127.0.0.1', '[::1]', 'localhost'].includes(url.hostname)))
+        throw new UsageError('--url requires HTTPS except for loopback HTTP.');
+    return url.origin;
+}
+async function parseRequest(spec, flags, positionals, options) {
+    const value = (name) => typeof flags[name] === 'string' ? flags[name] : '';
+    const url = sessionServiceOrigin(value('url'));
+    const account = value('as');
+    if (!account || account.length > 200 || /[\s:\x00-\x1f\x7f]/.test(account))
+        throw new UsageError('--as must name the operator account.');
+    if (Boolean(flags['token-env']) === Boolean(flags['token-file']))
+        throw new UsageError('Choose exactly one credential source: --token-env <variable-name> or --token-file <path>.');
+    let token;
+    if (flags['token-env']) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(value('token-env')))
+            throw new UsageError('--token-env must name an environment variable.');
+        token = (options.env ?? process.env)[value('token-env')] ?? '';
+    }
+    else
+        token = (await readBoundedFile(value('token-file'), 8192, 'The token file')).trim();
+    if (!token || token.length > 8192 || /[\s\x00-\x1f\x7f]/.test(token))
+        throw new UsageError('The selected credential is empty or invalid. Set the named variable or token file.');
+    const request = { version: 1 };
+    if ('sessionId' in spec.inputSchema.properties) {
+        if (positionals.length !== 1)
+            throw new UsageError('Name exactly one session ID.');
+        request['sessionId'] = positionals[0];
+    }
+    else if (positionals.length)
+        throw new UsageError('This operation takes no positional arguments.');
+    for (const [name, field] of Object.entries(spec.flags)) {
+        if (flags[name] === undefined)
+            continue;
+        const raw = value(name);
+        if (field.kind === 'integer' && !/^\d+$/.test(raw))
+            throw new UsageError(`--${name} must be a whole number.`);
+        request[field.field] = field.kind === 'integer' ? Number(raw) : field.kind === 'nullable-id' && raw === 'none' ? null : raw;
+    }
+    if ('prompt' in spec.inputSchema.properties) {
+        if (Boolean(flags['file']) === Boolean(flags['stdin']))
+            throw new UsageError('Choose exactly one prompt source: --file <path> or --stdin.');
+        request['prompt'] = flags['file'] ? await readBoundedFile(value('file'), SESSION_PROMPT_BYTES, 'The prompt file') : await (options.readStdin ?? readStdin)();
+    }
+    const validated = validateSessionRequest(spec.operation, request);
+    if (!validated.ok)
+        throw new UsageError(validated.message);
+    return { spec, request: validated.request, url, account, token };
+}
+async function readResponse(response) {
+    if (!response.body)
+        throw new Error('Missing response body');
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        while (true) {
+            const chunk = await reader.read();
+            if (chunk.done)
+                break;
+            bytes += chunk.value.byteLength;
+            if (bytes > SESSION_RESPONSE_BYTES) {
+                await reader.cancel();
+                throw new Error('Response limit');
+            }
+            chunks.push(chunk.value);
+        }
+    }
+    finally {
+        reader.releaseLock();
+    }
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(Buffer.concat(chunks)));
+}
+function unconfirmed(spec, request) {
+    const sessionId = 'sessionId' in request ? request.sessionId : undefined;
+    return { version: 1, operation: spec.operation, ok: false, status: spec.mutation ? 'uncertain' : 'rejected',
+        delivery: spec.mutation ? 'unknown' : 'not-sent', retry: spec.mutation ? 'inspect-first' : 'safe-read',
+        reason: spec.mutation ? 'delivery-unknown' : 'service-unavailable',
+        message: spec.mutation ? 'The service response could not be confirmed. Inspect the saved session before continuing; the request was not retried.' : 'The service response could not be read. Check the service address and connection.',
+        nextActions: [{ operation: sessionId ? 'show' : 'list', label: sessionId ? 'Inspect session' : 'List sessions', ...(sessionId ? { sessionId } : {}) }] };
+}
+async function perform(parsed, options) {
+    const { spec, request, url, account, token } = parsed;
+    try {
+        const response = await (options.fetch ?? fetch)(`${url}/api/sessions/${spec.operation}`, {
+            method: 'POST', redirect: 'manual', credentials: 'omit', signal: AbortSignal.timeout(60_000),
+            headers: { authorization: `Bearer ${account}:${token}`, 'content-type': 'application/json', accept: 'application/json' }, body: JSON.stringify(request),
+        });
+        if (response.status >= 300 && response.status < 400) {
+            await response.body?.cancel();
+            return unconfirmed(spec, request);
+        }
+        // This marker belongs to the owner boundary. A bare gateway 503 or 404
+        // cannot prove that an upstream mutation was never accepted.
+        if ([401, 403, 404, 503].includes(response.status) && response.headers.get('x-standing-orders-session-delivery') === 'not-sent') {
+            await response.body?.cancel();
+            const reason = response.status === 401 ? 'unauthenticated' : response.status === 403 ? 'forbidden' : response.status === 404 ? 'session-unsupported' : 'session-unavailable';
+            return { version: 1, operation: spec.operation, ok: false, status: 'rejected', delivery: 'not-sent', retry: spec.mutation ? 'never' : 'safe-read', reason,
+                message: response.status === 401 || response.status === 403 ? 'The service refused these operator credentials. Check the account and its access.' : 'This service does not currently support the requested session operation. Check its installed build and readiness.', nextActions: [] };
+        }
+        const payload = await readResponse(response);
+        if (!isSessionResponse(payload, spec.operation) || (payload.ok && !response.ok))
+            return unconfirmed(spec, request);
+        if ('sessionId' in request && payload.result?.session && payload.result.session.id !== request.sessionId)
+            return unconfirmed(spec, request);
+        if (payload.ok && 'key' in request && payload.result?.receipt?.key !== request.key)
+            return unconfirmed(spec, request);
+        if (payload.ok && 'expectedThreadId' in request && request.expectedThreadId !== null && payload.result?.session?.nativeThreadId !== request.expectedThreadId)
+            return unconfirmed(spec, request);
+        return payload;
+    }
+    catch {
+        return unconfirmed(spec, request);
+    }
+}
+const terminalText = (value) => value.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
+function render(response) {
+    const result = response.result;
+    const lines = response.ok && response.operation === 'show' && result?.brief ? [] : [response.message];
+    for (const session of result?.sessions ?? [])
+        lines.push(`${session.id}  ${session.status}  ${session.title}`);
+    if (result?.session) {
+        const session = result.session;
+        lines.push(result?.brief?.summary ?? `${session.title} · ${session.status}`, `Session: ${session.id}`, `Revision: ${session.revision} · Thread: ${session.nativeThreadId ?? 'none'} · Turn: ${session.turnId ?? 'none'}`);
+        if (session.error && !result?.brief)
+            lines.push(session.error);
+    }
+    for (const item of result?.items ?? [])
+        lines.push(`\n${item.type}: ${item.text}`);
+    for (const request of result?.requests ?? [])
+        lines.push(`\n${request.title}\n${request.detail}`);
+    if (result?.changes)
+        lines.push(result.changes.status, result.changes.diff, ...(result.changes.truncated ? ['Changes were truncated. Open the workspace for the full diff.'] : []));
+    if (result?.truncated)
+        lines.push('The response is shortened. Open the workspace for complete activity.');
+    for (const action of response.nextActions)
+        lines.push(`${action.label}: ${action.operation === 'open-ui' ? 'open the coding workspace' : `toolroll session ${action.operation}${action.sessionId ? ` ${action.sessionId}` : ''}`}`);
+    return terminalText(lines.join('\n'));
+}
+export async function runSessionCommand(argv, write, options = {}) {
+    const json = argv.includes('--json');
+    const stderr = options.stderr ?? (line => process.stderr.write(`${line}\n`));
+    const operation = argv[0];
+    const command = operation ? `session ${operation}` : 'session';
+    const fail = (message) => {
+        const payload = { ok: false, command, reason: 'usage', status: 'rejected', delivery: 'not-sent', retry: 'never', message };
+        if (json)
+            write(envelopeJson(payload));
+        else
+            stderr(message);
+        return 2;
+    };
+    if (!operation || operation === '--help' || operation === '-h') {
+        if (json)
+            write(envelopeJson({ ok: true, command: 'session', ...sessionCapabilities() }));
+        else
+            write(help());
+        return 0;
+    }
+    if (operation === 'capabilities') {
+        if (argv.slice(1).some(arg => !['--json', '--help', '-h'].includes(arg)))
+            return fail('session capabilities accepts only --json or --help.');
+        write(json ? envelopeJson({ ok: true, command, ...sessionCapabilities() }) : help());
+        return 0;
+    }
+    const spec = sessionDescriptor(operation);
+    if (!spec)
+        return fail(`Unknown session operation. Use: ${SESSION_CLI_ACTIONS.join(', ')}.`);
+    const allowed = sessionCliFlags(spec);
+    const flags = {};
+    const positionals = [];
+    for (let index = 1; index < argv.length; index++) {
+        const argument = argv[index];
+        if (!argument.startsWith('-')) {
+            positionals.push(argument);
+            continue;
+        }
+        const name = argument === '-h' ? 'help' : argument.startsWith('--') ? argument.slice(2) : '';
+        if (!Object.hasOwn(allowed, name))
+            return fail(`Unknown option ${argument} for session ${operation}.`);
+        if (Object.hasOwn(flags, name))
+            return fail(`Option --${name} was repeated.`);
+        if (allowed[name] === 'flag')
+            flags[name] = true;
+        else {
+            const value = argv[++index];
+            if (!value || value.startsWith('-'))
+                return fail(`--${name} requires a value.`);
+            flags[name] = value;
+        }
+    }
+    if (flags['help']) {
+        write(json ? envelopeJson({ ok: true, command, descriptor: spec, help: help(spec) }) : help(spec));
+        return 0;
+    }
+    let parsed;
+    try {
+        parsed = await parseRequest(spec, flags, positionals, options);
+    }
+    catch (error) {
+        return fail(error instanceof UsageError ? error.message : 'The session request could not be prepared. Check the prompt and credential source.');
+    }
+    const response = await perform(parsed, options);
+    if (json)
+        write(envelopeJson({ ...response, command, ...('key' in parsed.request ? { key: parsed.request.key } : {}) }));
+    else if (response.ok)
+        write(render(response));
+    else
+        stderr(render(response));
+    return response.ok ? 0 : response.status === 'uncertain' || response.reason === 'service-unavailable' ? 1 : 3;
+}

package/dist/session-contract.d.ts

@@ -0,0 +1,183 @@
+/** The session transport is a client of the running owner, never a catalog owner.
+ * These descriptors drive request validation, CLI parsing, help and discovery. */
+export declare const SESSION_PROTOCOL_VERSION = 1;
+export declare const SESSION_PROMPT_BYTES = 64000;
+export declare const SESSION_REQUEST_BYTES = 128000;
+export declare const SESSION_RESPONSE_BYTES = 4000000;
+export type SessionOperation = 'list' | 'show' | 'changes' | 'start' | 'send' | 'stop' | 'resume' | 'recover';
+export type SessionExpected = {
+    sessionId: string;
+    key: string;
+    expectedRevision: number;
+    expectedThreadId: string | null;
+    expectedTurnId: string | null;
+};
+export type SessionRequests = {
+    list: {
+        version: 1;
+        project?: string;
+        limit?: number;
+    };
+    show: {
+        version: 1;
+        sessionId: string;
+        view?: 'brief' | 'activity';
+    };
+    changes: {
+        version: 1;
+        sessionId: string;
+    };
+    start: {
+        version: 1;
+        project: string;
+        title: string;
+        prompt: string;
+        model?: string;
+        key: string;
+    };
+    send: {
+        version: 1;
+        prompt: string;
+    } & SessionExpected;
+    stop: {
+        version: 1;
+    } & SessionExpected;
+    resume: {
+        version: 1;
+    } & SessionExpected;
+    recover: {
+        version: 1;
+    } & SessionExpected;
+};
+export type SessionRequest = SessionRequests[SessionOperation];
+export type SessionView = {
+    id: string;
+    repo: string;
+    title: string;
+    status: string;
+    nativeThreadId: string | null;
+    turnId: string | null;
+    revision: number;
+    branch?: string;
+    base?: string;
+    error?: string | null;
+    deliveryReviewRequired?: boolean;
+    updatedAt?: string;
+};
+export type SessionBrief = {
+    summary: string;
+    nextAction: string;
+    sourceRevision: number;
+    sourceItemIds?: string[];
+    partialHistory?: boolean;
+};
+export type SessionResult = {
+    session?: SessionView;
+    sessions?: SessionView[];
+    items?: {
+        id: string;
+        type: string;
+        text: string;
+        status: string | null;
+        clientId?: string;
+    }[];
+    requests?: {
+        id: string;
+        kind: string;
+        title: string;
+        detail: string;
+    }[];
+    changes?: {
+        head: string;
+        status: string;
+        diff: string;
+        truncated: boolean;
+    };
+    receipt?: {
+        key: string;
+        status: string;
+    };
+    brief?: SessionBrief;
+    truncated?: boolean;
+};
+export type SessionNextAction = {
+    operation: SessionOperation | 'open-ui';
+    label: string;
+    sessionId?: string;
+};
+export type SessionResponse = {
+    version: 1;
+    operation: SessionOperation;
+    ok: boolean;
+    status: 'succeeded' | 'pending' | 'rejected' | 'uncertain';
+    delivery: 'confirmed' | 'not-sent' | 'unknown';
+    retry: 'safe-read' | 'inspect-first' | 'never';
+    message: string;
+    nextActions: SessionNextAction[];
+    reason?: string;
+    result?: SessionResult;
+};
+type Field = {
+    type: 'string' | 'integer' | readonly ['string', 'null'];
+    minLength?: number;
+    maxLength?: number;
+    pattern?: string;
+    minimum?: number;
+    maximum?: number;
+    maxBytes?: number;
+    nonblank?: boolean;
+    const?: number;
+};
+export type SessionDescriptor = {
+    operation: SessionOperation;
+    synopsis: string;
+    mutation: boolean;
+    audience: 'operator';
+    agentMayInvoke: false;
+    retry: 'safe-read' | 'inspect-first';
+    inputSchema: {
+        type: 'object';
+        additionalProperties: false;
+        required: readonly string[];
+        properties: Record<string, Field>;
+    };
+    flags: Readonly<Record<string, {
+        field: string;
+        kind: 'string' | 'integer' | 'nullable-id';
+    }>>;
+};
+export declare const SESSION_DESCRIPTORS: readonly SessionDescriptor[];
+export declare const SESSION_OPERATIONS: SessionOperation[];
+export declare function sessionDescriptor(operation: string): SessionDescriptor | undefined;
+export type SessionValidation = {
+    ok: true;
+    request: SessionRequest;
+} | {
+    ok: false;
+    message: string;
+};
+export declare function validateSessionRequest(operation: string, value: unknown): SessionValidation;
+/** Validate before claiming success. A broken response to a mutation is unknown
+ * delivery, not proof that the owner rejected it. Additional fields are allowed. */
+export declare function isSessionResponse(value: unknown, operation: SessionOperation): value is SessionResponse;
+export declare function sessionCapabilities(): {
+    version: number;
+    transport: string;
+    authentication: string;
+    authority: string;
+    operations: readonly SessionDescriptor[];
+    brief: {
+        supported: boolean;
+        operation: string;
+        defaultView: string;
+        source: string;
+    };
+    unsupported: string[];
+    limits: {
+        promptBytes: number;
+        requestBytes: number;
+        responseBytes: number;
+    };
+    retry: string;
+};
+export {};

package/dist/session-contract.js

@@ -0,0 +1,122 @@
+/** The session transport is a client of the running owner, never a catalog owner.
+ * These descriptors drive request validation, CLI parsing, help and discovery. */
+export const SESSION_PROTOCOL_VERSION = 1;
+export const SESSION_PROMPT_BYTES = 64_000;
+export const SESSION_REQUEST_BYTES = 128_000;
+export const SESSION_RESPONSE_BYTES = 4_000_000;
+const text = (maxLength) => ({ type: 'string', minLength: 1, maxLength, nonblank: true });
+const identity = { ...text(200), pattern: '^[A-Za-z0-9_.:-]+$' };
+const nullableIdentity = { ...identity, type: ['string', 'null'] };
+const key = { type: 'string', pattern: '^[A-Za-z0-9_-]{16,100}$', minLength: 16, maxLength: 100 };
+const prompt = { ...text(SESSION_PROMPT_BYTES), maxBytes: SESSION_PROMPT_BYTES };
+const model = { ...text(128), pattern: '^[A-Za-z0-9][A-Za-z0-9._:/-]{0,127}$' };
+const expected = { sessionId: identity, key, expectedRevision: { type: 'integer', minimum: 0 }, expectedThreadId: nullableIdentity, expectedTurnId: nullableIdentity };
+const expectedFlags = {
+    key: { field: 'key', kind: 'string' }, revision: { field: 'expectedRevision', kind: 'integer' },
+    thread: { field: 'expectedThreadId', kind: 'nullable-id' }, turn: { field: 'expectedTurnId', kind: 'nullable-id' },
+};
+function descriptor(operation, synopsis, mutation, fields, required, flags) {
+    return { operation, synopsis, mutation, audience: 'operator', agentMayInvoke: false, retry: mutation ? 'inspect-first' : 'safe-read',
+        inputSchema: { type: 'object', additionalProperties: false, required: ['version', ...required], properties: { version: { type: 'integer', const: 1 }, ...fields } }, flags };
+}
+export const SESSION_DESCRIPTORS = [
+    descriptor('list', 'List your native coding sessions', false, { project: text(4096), limit: { type: 'integer', minimum: 1, maximum: 100 } }, [], { project: { field: 'project', kind: 'string' }, limit: { field: 'limit', kind: 'integer' } }),
+    descriptor('show', 'Inspect the saved brief and exact identity; request activity when needed', false, { sessionId: identity, view: { type: 'string', pattern: '^(brief|activity)$' } }, ['sessionId'], { view: { field: 'view', kind: 'string' } }),
+    descriptor('changes', 'Read changes from the saved session checkout', false, { sessionId: identity }, ['sessionId'], {}),
+    descriptor('start', 'Start a native coding session in a project', true, { project: text(4096), title: text(160), prompt, model, key }, ['project', 'title', 'prompt', 'key'], { project: { field: 'project', kind: 'string' }, title: { field: 'title', kind: 'string' }, model: { field: 'model', kind: 'string' }, key: { field: 'key', kind: 'string' } }),
+    descriptor('send', 'Send a message to the exact saved session and turn', true, { ...expected, prompt }, [...Object.keys(expected), 'prompt'], expectedFlags),
+    descriptor('stop', 'Stop the exact running turn', true, expected, Object.keys(expected), expectedFlags),
+    descriptor('resume', 'Reconnect the saved conversation', true, expected, Object.keys(expected), expectedFlags),
+    descriptor('recover', 'Check process exit and reconcile saved delivery receipts', true, expected, Object.keys(expected), expectedFlags),
+];
+export const SESSION_OPERATIONS = SESSION_DESCRIPTORS.map(one => one.operation);
+export function sessionDescriptor(operation) { return SESSION_DESCRIPTORS.find(one => one.operation === operation); }
+const record = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+export function validateSessionRequest(operation, value) {
+    const spec = sessionDescriptor(operation);
+    const bad = (message) => ({ ok: false, message });
+    if (!spec)
+        return bad('Choose a supported session operation.');
+    if (!record(value))
+        return bad('The session request must be a JSON object.');
+    for (const field of Object.keys(value))
+        if (!Object.hasOwn(spec.inputSchema.properties, field))
+            return bad(`Unknown session field: ${field}.`);
+    for (const field of spec.inputSchema.required)
+        if (!Object.hasOwn(value, field))
+            return bad(`Missing session field: ${field}.`);
+    for (const [name, valueAtField] of Object.entries(value)) {
+        const field = spec.inputSchema.properties[name];
+        if (Array.isArray(field.type) && valueAtField === null)
+            continue;
+        if (field.type === 'integer') {
+            if (!Number.isSafeInteger(valueAtField) || typeof valueAtField !== 'number' || (field.minimum !== undefined && valueAtField < field.minimum) || (field.maximum !== undefined && valueAtField > field.maximum) || (field.const !== undefined && valueAtField !== field.const))
+                return bad(`Invalid ${name}.`);
+        }
+        else {
+            if (typeof valueAtField !== 'string' || (field.nonblank && !valueAtField.trim()) || (field.minLength !== undefined && valueAtField.length < field.minLength) || (field.maxLength !== undefined && valueAtField.length > field.maxLength) || (field.maxBytes !== undefined && Buffer.byteLength(valueAtField) > field.maxBytes) || (field.pattern !== undefined && !new RegExp(field.pattern).test(valueAtField)))
+                return bad(`Invalid ${name}.`);
+        }
+    }
+    if (Buffer.byteLength(JSON.stringify(value)) > SESSION_REQUEST_BYTES)
+        return bad('The session request is too large.');
+    return { ok: true, request: value };
+}
+/** Validate before claiming success. A broken response to a mutation is unknown
+ * delivery, not proof that the owner rejected it. Additional fields are allowed. */
+export function isSessionResponse(value, operation) {
+    if (!record(value) || value['version'] !== 1 || value['operation'] !== operation || typeof value['ok'] !== 'boolean' || typeof value['message'] !== 'string' || !Array.isArray(value['nextActions']))
+        return false;
+    if (!['succeeded', 'pending', 'rejected', 'uncertain'].includes(String(value['status'])) || !['confirmed', 'not-sent', 'unknown'].includes(String(value['delivery'])) || !['safe-read', 'inspect-first', 'never'].includes(String(value['retry'])))
+        return false;
+    if ((value['ok'] === true) !== ['succeeded', 'pending'].includes(String(value['status'])))
+        return false;
+    if (value['status'] === 'uncertain' && (value['delivery'] !== 'unknown' || value['retry'] !== 'inspect-first'))
+        return false;
+    if (value['status'] === 'rejected' && value['delivery'] !== 'not-sent')
+        return false;
+    if (value['ok'] === true && value['delivery'] !== 'confirmed')
+        return false;
+    if (value['reason'] !== undefined && (typeof value['reason'] !== 'string' || !/^[a-z][a-z0-9-]*$/.test(value['reason'])))
+        return false;
+    for (const action of value['nextActions'])
+        if (!record(action) || typeof action['label'] !== 'string' || ![...SESSION_OPERATIONS, 'open-ui'].includes(String(action['operation'])) || (action['sessionId'] !== undefined && typeof action['sessionId'] !== 'string'))
+            return false;
+    if (value['result'] === undefined)
+        return value['ok'] === false;
+    const result = value['result'];
+    if (!record(result))
+        return false;
+    const session = (item) => record(item) && ['id', 'repo', 'title', 'status'].every(key => typeof item[key] === 'string') && (typeof item['nativeThreadId'] === 'string' || item['nativeThreadId'] === null) && (typeof item['turnId'] === 'string' || item['turnId'] === null) && Number.isSafeInteger(item['revision']) && Number(item['revision']) >= 0;
+    if (result['session'] !== undefined && !session(result['session']))
+        return false;
+    if (result['sessions'] !== undefined && (!Array.isArray(result['sessions']) || !result['sessions'].every(session)))
+        return false;
+    if (value['ok'] === true && (operation === 'list' ? !Array.isArray(result['sessions']) : !session(result['session'])))
+        return false;
+    if (result['changes'] !== undefined) {
+        const changes = result['changes'];
+        if (!record(changes) || !['head', 'status', 'diff'].every(key => typeof changes[key] === 'string') || typeof changes['truncated'] !== 'boolean')
+            return false;
+    }
+    if (value['ok'] === true && operation === 'changes' && result['changes'] === undefined)
+        return false;
+    if (result['items'] !== undefined && (!Array.isArray(result['items']) || !result['items'].every(item => record(item) && ['id', 'type', 'text'].every(key => typeof item[key] === 'string') && (item['status'] === null || typeof item['status'] === 'string'))))
+        return false;
+    if (result['requests'] !== undefined && (!Array.isArray(result['requests']) || !result['requests'].every(item => record(item) && ['id', 'kind', 'title', 'detail'].every(key => typeof item[key] === 'string'))))
+        return false;
+    if (result['receipt'] !== undefined && (!record(result['receipt']) || typeof result['receipt']['key'] !== 'string' || typeof result['receipt']['status'] !== 'string'))
+        return false;
+    if (result['truncated'] !== undefined && typeof result['truncated'] !== 'boolean')
+        return false;
+    if (result['brief'] !== undefined && (!record(result['brief']) || typeof result['brief']['summary'] !== 'string' || typeof result['brief']['nextAction'] !== 'string' || !Number.isSafeInteger(result['brief']['sourceRevision'])))
+        return false;
+    return true;
+}
+export function sessionCapabilities() {
+    return { version: SESSION_PROTOCOL_VERSION, transport: 'POST /api/sessions/<operation>', authentication: 'operator account: Authorization Bearer name:token',
+        authority: 'Operator credentials are required for session reads and controls. External coordinator credentials have no session access.',
+        operations: SESSION_DESCRIPTORS, brief: { supported: true, operation: 'show', defaultView: 'brief', source: 'Saved state and labeled agent reports, pinned to a revision; no additional model call.' },
+        unsupported: ['events', 'review', 'continue'], limits: { promptBytes: SESSION_PROMPT_BYTES, requestBytes: SESSION_REQUEST_BYTES, responseBytes: SESSION_RESPONSE_BYTES },
+        retry: 'Never automatically retry a mutation. Inspect saved state after a lost response; keep the original key.' };
+}

package/dist/session-http.d.ts

@@ -0,0 +1,19 @@
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { type SessionOperation, type SessionRequests, type SessionResponse } from './session-contract.js';
+export type SessionHttpActor = {
+    name: string;
+    generation: number;
+};
+export type SessionHttpExecute = <O extends SessionOperation>(actor: SessionHttpActor, operation: O, request: SessionRequests[O]) => Promise<SessionResponse>;
+export type SessionHttpOptions = {
+    /** Verify the bearer against the current account and installation-wide
+     * operator role. Derive both fields here, never from the JSON request.
+     * Host, TLS and other server admission checks remain with the caller. */
+    authenticate: (request: IncomingMessage) => SessionHttpActor | null | Promise<SessionHttpActor | null>;
+    /** The existing live owner's operation. Null means no owner is ready.
+     * The service rechecks actor generation and project access at execution. */
+    execute: SessionHttpExecute | null;
+};
+/** Handle this API family before the browser's form parser or login redirects.
+ * This adapter dispatches at most once. It owns no catalog, database or provider. */
+export declare function handleSessionHttp(request: IncomingMessage, response: ServerResponse, options: SessionHttpOptions): Promise<boolean>;