toolroll 0.9.57 → 0.9.59

package/dist/session-cli.js

@@ -1,19 +1,100 @@
 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' };
+import { SESSION_DESCRIPTORS, SESSION_PROMPT_BYTES, isSessionResponse, sessionCapabilities, sessionDescriptor, validateSessionRequest, } from './session-contract.js';
+import { centralProfile, UsageError } from './team-cli.js';
+import { postCli } from './remote-exec.js';
+import { TOKEN_REPLACEMENT } from './password-bearer.js';
+/** The files key the prompt travels under: the server reads no paths, only what the request carries. */
+export const SESSION_PROMPT_FILE = 'prompt';
 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' } : {}) };
+/** Before D7 the session client signed in with an operator password on every request. */
+const RETIRED_FLAGS = new Set(['url', 'as', 'token-env', 'token-file']);
+export const SESSION_TOKEN_REQUIRED = `Session commands use your saved API token. ${TOKEN_REPLACEMENT}, then save it with \`toolroll connect <origin> --as <account> --token-stdin\`.`;
+/** The flags an operation takes: on this computer (where the prompt may come from a file or stdin, and a saved
+ * profile is chosen), or on the server (where the prompt is only ever the request's own file). */
+export function sessionCliFlags(spec, side = 'client') {
+    const prompt = spec.operation === 'start' || spec.operation === 'send';
+    return { json: 'flag', help: 'flag', ...(side === 'client' ? { profile: 'value' } : {}),
+        ...Object.fromEntries(Object.keys(spec.flags).map(name => [name, 'value'])),
+        ...(prompt ? { file: 'value', ...(side === 'client' ? { 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.`;
+        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. Sessions run on the server you connected to with your API token (toolroll connect); they need instance operator access.`;
     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.`;
+    return `toolroll session ${spec.operation}${'sessionId' in spec.inputSchema.properties ? ' <session-id>' : ''}\n${spec.synopsis}.\n\n${required.length > 0 ? `Required:\n${required.map(name => `  --${name} <value>`).join('\n')}\n` : ''}${'prompt' in spec.inputSchema.properties ? '  --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(' ')}\nRuns on the saved connection (or --profile <name>) over /api/cli with your API token. Mutations are never retried automatically.`;
 }
-class UsageError extends Error {
+/** One parser for both sides of /api/cli: `<operation> [<session-id>] --flag value …`. */
+export function parseSessionArguments(argv, side) {
+    const operation = argv[0] ?? '';
+    const spec = sessionDescriptor(operation);
+    if (!spec)
+        return { problem: `Unknown session operation. Use: ${SESSION_CLI_ACTIONS.join(', ')}.` };
+    const allowed = sessionCliFlags(spec, side);
+    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 (side === 'client' && RETIRED_FLAGS.has(name))
+            return { problem: SESSION_TOKEN_REQUIRED };
+        if (!Object.hasOwn(allowed, name))
+            return { problem: `Unknown option ${argument} for session ${operation}.` };
+        if (Object.hasOwn(flags, name))
+            return { problem: `Option --${name} was repeated.` };
+        if (allowed[name] === 'flag')
+            flags[name] = true;
+        else {
+            const value = argv[++index];
+            if (!value || value.startsWith('-'))
+                return { problem: `--${name} requires a value.` };
+            flags[name] = value;
+        }
+    }
+    return { spec, flags, positionals };
+}
+/** The validated request the parsed arguments and prompt spell. */
+export function sessionRequestOf({ spec, flags, positionals }, prompt) {
+    const request = { version: 1 };
+    if ('sessionId' in spec.inputSchema.properties) {
+        if (positionals.length !== 1)
+            return { ok: false, message: 'Name exactly one session ID.' };
+        request['sessionId'] = positionals[0];
+    }
+    else if (positionals.length)
+        return { ok: false, message: 'This operation takes no positional arguments.' };
+    for (const [name, field] of Object.entries(spec.flags)) {
+        const raw = flags[name];
+        if (typeof raw !== 'string')
+            continue;
+        if (field.kind === 'integer' && !/^\d+$/.test(raw))
+            return { ok: false, message: `--${name} must be a whole number.` };
+        request[field.field] = field.kind === 'integer' ? Number(raw) : field.kind === 'nullable-id' && raw === 'none' ? null : raw;
+    }
+    if (prompt !== undefined)
+        request['prompt'] = prompt;
+    return validateSessionRequest(spec.operation, request);
+}
+/** The exact argv the server runs for a validated request: always --json, the prompt as the request's one file. */
+export function sessionArgv(spec, request) {
+    const fields = request;
+    const argv = ['session', spec.operation];
+    if (typeof fields['sessionId'] === 'string')
+        argv.push(fields['sessionId']);
+    for (const [name, field] of Object.entries(spec.flags)) {
+        const value = fields[field.field];
+        if (value !== undefined)
+            argv.push(`--${name}`, value === null ? 'none' : String(value));
+    }
+    if (typeof fields['prompt'] === 'string')
+        argv.push('--file', SESSION_PROMPT_FILE);
+    argv.push('--json');
+    return argv;
 }
 async function readBoundedFile(path, limit, label) {
     let file;
@@ -60,90 +141,6 @@ async function readStdin() {
         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',
@@ -152,42 +149,39 @@ function unconfirmed(spec, request) {
         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)
+/** One request over /api/cli, never retried. Only an answer whose identity matches the request counts as delivered. */
+async function perform(spec, request, profile, options) {
+    const files = typeof request.prompt === 'string' ? { [SESSION_PROMPT_FILE]: request.prompt } : {};
+    const outcome = await postCli(profile.origin, profile.token, { argv: sessionArgv(spec, request), files }, options);
+    if (outcome.kind === 'unconfirmed')
+        return unconfirmed(spec, request);
+    if (outcome.kind === 'refused') {
+        // /api/cli refuses before it runs anything, except a command that stopped on the server: that one may have acted.
+        if (outcome.status >= 500 && outcome.status !== 501 && outcome.status !== 503)
             return unconfirmed(spec, request);
-        return payload;
+        return { version: 1, operation: spec.operation, ok: false, status: 'rejected', delivery: 'not-sent', retry: spec.mutation ? 'never' : 'safe-read',
+            reason: /^[a-z][a-z0-9-]*$/.test(outcome.code) ? outcome.code : 'refused', message: outcome.message, nextActions: [] };
+    }
+    let payload;
+    try {
+        payload = JSON.parse(outcome.answer.stdout);
     }
     catch {
         return unconfirmed(spec, request);
     }
+    if (!isSessionResponse(payload, spec.operation))
+        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;
 }
 const terminalText = (value) => value.replace(/[\x00-\x08\x0b-\x1f\x7f]/g, '');
-function render(response) {
+/** The plain-text answer, the same on either side of the transport. */
+export function renderSessionResponse(response) {
     const result = response.result;
     const lines = response.ok && response.operation === 'show' && result?.brief ? [] : [response.message];
     for (const session of result?.sessions ?? [])
@@ -210,6 +204,8 @@ function render(response) {
         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'));
 }
+/** 0 delivered · 1 unknown (inspect first) · 3 refused. */
+export const sessionExitCode = (response) => response.ok ? 0 : response.status === 'uncertain' || response.reason === 'service-unavailable' ? 1 : 3;
 export async function runSessionCommand(argv, write, options = {}) {
     const json = argv.includes('--json');
     const stderr = options.stderr ?? (line => process.stderr.write(`${line}\n`));
@@ -236,49 +232,40 @@ export async function runSessionCommand(argv, write, options = {}) {
         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;
-        }
-    }
+    const parsed = parseSessionArguments(argv, 'client');
+    if ('problem' in parsed)
+        return fail(parsed.problem);
+    const { spec, flags } = parsed;
     if (flags['help']) {
         write(json ? envelopeJson({ ok: true, command, descriptor: spec, help: help(spec) }) : help(spec));
         return 0;
     }
-    let parsed;
+    let request;
+    let profile;
     try {
-        parsed = await parseRequest(spec, flags, positionals, options);
+        let prompt;
+        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.');
+            prompt = typeof flags['file'] === 'string' ? await readBoundedFile(flags['file'], SESSION_PROMPT_BYTES, 'The prompt file') : await (options.readStdin ?? readStdin)();
+        }
+        const validated = sessionRequestOf(parsed, prompt);
+        if (!validated.ok)
+            throw new UsageError(validated.message);
+        request = validated.request;
+        profile = centralProfile(options, typeof flags['profile'] === 'string' ? flags['profile'] : undefined);
     }
     catch (error) {
-        return fail(error instanceof UsageError ? error.message : 'The session request could not be prepared. Check the prompt and credential source.');
+        return fail(error instanceof UsageError ? error.message : 'The session request could not be prepared. Check the prompt and saved connection.');
     }
-    const response = await perform(parsed, options);
+    if (profile === null || !profile.apiToken)
+        return fail(SESSION_TOKEN_REQUIRED);
+    const response = await perform(spec, request, profile, options);
     if (json)
-        write(envelopeJson({ ...response, command, ...('key' in parsed.request ? { key: parsed.request.key } : {}) }));
+        write(envelopeJson({ ...response, command, ...('key' in request ? { key: request.key } : {}) }));
     else if (response.ok)
-        write(render(response));
+        write(renderSessionResponse(response));
     else
-        stderr(render(response));
-    return response.ok ? 0 : response.status === 'uncertain' || response.reason === 'service-unavailable' ? 1 : 3;
+        stderr(renderSessionResponse(response));
+    return sessionExitCode(response);
 }

package/dist/session-contract.js

@@ -114,8 +114,8 @@ export function isSessionResponse(value, operation) {
     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.',
+    return { version: SESSION_PROTOCOL_VERSION, transport: 'POST /api/cli with argv session <operation> (the prompt travels as the request\'s one file)', authentication: 'API token: Authorization Bearer so_… (toolroll tokens create, saved by toolroll connect)',
+        authority: 'An instance operator\'s API token without a project limit reads sessions; changing one needs an act token. Lead and 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-remote.d.ts

@@ -0,0 +1,19 @@
+import type { Store } from './store.js';
+import type { CodingWorkspace } from './coding-workspace.js';
+import { type Principal } from './operate-remote.js';
+/**
+ * The server half of `toolroll session …` over `POST /api/cli` (D7, replacing the separate /api/sessions transport and
+ * its password sign-in). /api/cli has already proved the API token and charged its budget; this binds the token's
+ * person to the existing session owner, which rechecks the account and project on every operation. Native sessions
+ * stay installation-wide operator authority: only an instance operator's act token, limited to no projects, may
+ * change one. Every request is in the action ledger like any remote command, and every answer is one session
+ * envelope: a mutation whose outcome is unknown says so, and is never retried here.
+ */
+export type SessionRunner = (principal: Principal, argv: readonly string[], files: Readonly<Record<string, string>>, write: (line: string) => void) => Promise<number>;
+export declare function createSessionRunner(options: {
+    store: Store;
+    workspace: CodingWorkspace | null;
+    projects: () => readonly string[];
+    projectAllowed: (repo: string) => boolean;
+    clock?: () => Date;
+}): SessionRunner;

package/dist/session-remote.js

@@ -0,0 +1,86 @@
+import { realpathSync } from 'node:fs';
+import { envelopeJson } from './envelope.js';
+import { REMOTE_MESSAGES, reproveRemote } from './operate-remote.js';
+import { SESSION_RESPONSE_BYTES, isSessionResponse } from './session-contract.js';
+import { parseSessionArguments, renderSessionResponse, sessionExitCode, sessionRequestOf } from './session-cli.js';
+import { SessionService } from './session-service.js';
+export function createSessionRunner(options) {
+    const { store } = options;
+    const clock = options.clock ?? (() => new Date());
+    const authorized = (actor, repo) => {
+        const account = store.accountOf(actor.name);
+        return account !== null && account.revokedAt === null && account.generation === actor.generation && store.isInstanceOperator(actor.name)
+            && (repo === undefined || (options.projectAllowed(repo) && options.projects().includes(repo)));
+    };
+    const service = options.workspace === null || store.isDemo() ? null : new SessionService({ workspace: options.workspace, authorized,
+        project: (actor, input) => {
+            const path = realpathSync(input);
+            if (!authorized(actor, path) || !options.projects().includes(path))
+                throw Error('Choose a project already admitted to this installation.');
+            return path;
+        },
+    });
+    return async (principal, argv, files, write) => {
+        const json = argv.includes('--json');
+        const parsed = parseSessionArguments(argv.slice(1), 'server');
+        const operation = 'problem' in parsed ? null : parsed.spec.operation;
+        const command = `session ${operation ?? '(unknown)'}`;
+        let tokenName = null;
+        const record = (outcome, repo, why) => {
+            store.recordAction({ at: clock().toISOString(), actor: principal.account, repo, taskId: null, runId: null, action: `remote command: ${command}`, outcome, source: 'api',
+                detail: `token ${tokenName ?? principal.tokenId}${why === null ? '' : ` · ${why}`}` });
+        };
+        const answer = (response) => {
+            write(json ? envelopeJson({ ...response, command }) : renderSessionResponse(response));
+            return sessionExitCode(response);
+        };
+        const refuse = (spec, reason, message) => {
+            record('refused', null, reason);
+            if (spec === null) {
+                write(json ? envelopeJson({ ok: false, command, reason, message }) : message);
+                return 2;
+            }
+            return answer({ version: 1, operation: spec.operation, ok: false, status: 'rejected', delivery: 'not-sent', retry: spec.mutation ? 'never' : 'safe-read', reason, message, nextActions: [] });
+        };
+        const proved = reproveRemote(store, principal, clock());
+        if (!proved.ok)
+            return refuse('problem' in parsed ? null : parsed.spec, 'unauthenticated', REMOTE_MESSAGES.stale);
+        tokenName = proved.tokenName;
+        if ('problem' in parsed)
+            return refuse(null, 'usage', parsed.problem);
+        const { spec } = parsed;
+        if (spec.mutation && proved.scope !== 'act')
+            return refuse(spec, 'read-only', REMOTE_MESSAGES.read);
+        // A session reaches every project this installation admits: a project-limited token never stands for that.
+        if (principal.projects !== null || !store.isInstanceOperator(principal.account))
+            return refuse(spec, 'all-projects', 'Native sessions need instance operator access to every project. Use a token without a project limit.');
+        const file = parsed.flags['file'];
+        if (file !== undefined && (typeof file !== 'string' || !Object.hasOwn(files, file)))
+            return refuse(spec, 'usage', REMOTE_MESSAGES.files);
+        const validated = sessionRequestOf(parsed, typeof file === 'string' ? files[file] : undefined);
+        if (!validated.ok)
+            return refuse(spec, 'invalid-request', validated.message);
+        if (service === null)
+            return refuse(spec, 'session-unavailable', 'The session owner is not ready.');
+        const repo = 'project' in validated.request && spec.operation === 'start' ? validated.request.project : null;
+        record('requested', repo, null);
+        const uncertain = (reason, message) => {
+            const sessionId = 'sessionId' in validated.request ? validated.request.sessionId : undefined;
+            return { version: 1, operation: spec.operation, ok: false, status: 'uncertain', delivery: 'unknown', retry: 'inspect-first', reason, message,
+                nextActions: [{ operation: sessionId ? 'show' : 'list', label: sessionId ? 'Inspect session' : 'Inspect saved sessions', ...(sessionId ? { sessionId } : {}) }] };
+        };
+        let reply;
+        try {
+            reply = await service.execute({ name: principal.account, generation: principal.generation }, spec.operation, validated.request);
+            if (!isSessionResponse(reply, spec.operation))
+                throw new Error('Invalid owner response');
+            if (Buffer.byteLength(JSON.stringify(reply)) > SESSION_RESPONSE_BYTES)
+                reply = uncertain('response-too-large', 'The owner response is too large to deliver. Inspect saved activity before continuing; this request was not retried.');
+        }
+        catch {
+            reply = uncertain('unconfirmed-response', 'The owner response could not be confirmed. Inspect saved activity before continuing; this request was not retried.');
+        }
+        record(reply.ok ? 'done' : reply.status === 'uncertain' ? 'failed' : 'refused', repo, reply.ok ? null : reply.reason ?? null);
+        return answer(reply);
+    };
+}