toolroll 0.9.43 → 0.9.44

package/dist/operate-remote-arguments.js

@@ -0,0 +1,185 @@
+const args = (positionals = '', values = '', references = {}) => ({
+    positionals: positionals.split(' ').filter(Boolean).map(word => {
+        const [name = '', type = 'value'] = word.split(':');
+        return { name: name.replace(/[?*]$/, ''), kind: type, optional: name.endsWith('?'), rest: name.endsWith('*') };
+    }),
+    flags: new Map([...['json', 'help', 'repo', ...values.split(' ').filter(Boolean)].map(name => [name, 'value']), ...Object.entries(references)]),
+});
+/** All remotely allowed rows, including those with no resource references. Credentials and file-output
+ * flags are refused by the outer boundary. `source` on memory is provenance text; on revise it is a scope
+ * digest. Neither dereferences a conversation, task or proposal. Creation IDs are never looked up. */
+export const REMOTE_ARGUMENTS = new Map([
+    ...['status', 'ready', 'grants', 'gaps', 'sync', 'runner list', 'coordinator list', 'incident list',
+        'routine list', 'intake show', 'intake run', 'template list', 'webhook status', 'webhook test', 'review show',
+        'chat-approval show', 'chat-approval off'].map(row => [row, args()]),
+    ['integrations', args('', 'saved')],
+    ['outbox list', args('', 'all')],
+    ['task add', args('title*', 'key report checks', { id: 'refused', replaces: 'task' })],
+    ['task ask', args('id:task', 'person why')],
+    ['task checks', args('task:task', 'level')],
+    ['task add-tests', args('task:task')],
+    ['task list', args('', 'state view limit cursor')],
+    ['task show', args('id:task')],
+    ['task wait', args('id:task', 'timeout')],
+    ['task complete', args('task:task', 'digest', { run: 'run', 'pull-request': 'refused' })],
+    ['task revise', args('task:task', 'feedback source key', { run: 'run' })],
+    ['task state', args('id:task state', 'key reason', { 'replaced-by': 'task' })],
+    ['task block', args('id:task', 'key', { on: 'task' })],
+    ['task unblock', args('id:task', 'key', { on: 'task' })],
+    ['task next', args('id:task', 'key undo')],
+    ['task steer', args('id:task', 'note')],
+    ['task assign', args('id:task', 'key runner anyone')],
+    ['task scope', args('id:task', 'key goal not touches budget-usd risk acceptance candidate compare model provider race race-count race-per-usd race-total-usd repair-model')],
+    ['task plan', args('id:task', 'key provider model')],
+    ['task hold', args('id:task', 'key reason until')],
+    ['task unhold', args('id:task', 'key')],
+    ['task require', args('id:task', 'key cap require')],
+    ['task requeue', args('id:task')],
+    ['task review', args('id:review', 'brief all', { run: 'run' })],
+    ['task repair', args('run:run', '', { yes: 'step-up' })],
+    ['task route', args('id:task', 'risk phase provider model clear-phase digest size risky')],
+    ['task reopen', args('id:task')],
+    ['task stop', args('id:task', '', { run: 'run' })],
+    ['task resume', args('id:task', '', { run: 'run' })],
+    ['check-progress', args('run:run')],
+    ['cap list', args()], ['cap add', args('name', 'kind probe expires')],
+    // These objects are installation-scoped at the outer boundary; only an all-project principal reaches them.
+    ['incident resolve', args('incident')],
+    ['routine show', args('id')],
+    ['routine add', args('name', 'goal schedule acceptance ceiling budget-usd not touches require')],
+    ...['refresh', 'pause', 'resume', 'run-now'].map(action => [`routine ${action}`, args('name')]),
+    ['config show', args('phase?')], ['verify show', args()],
+    ['intake preview', args()], ['intake pr-comments', args('', 'limit')],
+    ['template show', args('name')],
+    ['contest show', args('id')], ['contest exclude', args('contest ordinal')],
+    ...['search', 'impact'].map(action => [`knowledge ${action}`, args('query', 'base')]),
+    ['knowledge refresh', args('', 'base')],
+    // Decision reads and supersession are already project-bound in project-memory.ts. Proposal IDs are
+    // accepted only by memory apply (step-up), never by the listing commands below.
+    ...['search', 'decisions', 'show', 'decide', 'retire', 'review', 'status'].map(action => [`memory ${action}`,
+        args(['search', 'decide'].includes(action) ? 'query*' : ['show', 'retire'].includes(action) ? 'query' : '', 'why reason supersedes source all decision sessions no-local')]),
+    ['flows list', args()],
+    ['flows show', args('flow:flow')], ['flows export', args('flow:flow')],
+    ['flows create', args('', 'yes name template', { steps: 'steps' })],
+    ['flows edit', args('flow:flow', 'yes name', { steps: 'steps' })],
+    ['flows trigger add', args('flow:flow trigger:trigger-json', 'yes')],
+    ...['pause', 'resume', 'remove'].map(action => [`flows trigger ${action}`, args('flow:flow trigger:trigger')]),
+    ['flows card add', args('flow:flow', 'title description zone')],
+    ['flows archive', args('flow:flow', 'yes')],
+    ['models status', args('', 'provider')], ['models list', args('', 'provider')],
+]);
+export const REMOTE_NOT_FOUND = { ok: false, reason: 'not-found', message: 'Not found.' };
+const positiveId = (value) => /^[1-9][0-9]*$/.test(value) && Number.isSafeInteger(Number(value));
+const object = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+/** Read-only authorization of every supplied reference, before the handler can disclose or mutate it. */
+export function remoteArgumentsOf(store, allows, invocation, positional, flags, named, files) {
+    const audit = REMOTE_ARGUMENTS.get(invocation);
+    if (audit === undefined)
+        return REMOTE_NOT_FOUND;
+    const values = positional.slice(invocation.split(' ').length - 1);
+    const resolved = [];
+    const admit = (repo) => typeof repo === 'string' && allows(repo) && (named === null || named === repo);
+    const input = (value) => {
+        const raw = value.trim().startsWith('{') || value.trim().startsWith('[') ? value
+            : Object.prototype.hasOwnProperty.call(files, value) ? files[value] : undefined;
+        if (raw === undefined)
+            return undefined;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    const check = (kind, value) => {
+        if (kind === 'value')
+            return true;
+        if (kind === 'review')
+            return check(flags.has('brief') ? 'task' : 'run', value);
+        if (kind === 'task' || kind === 'run') {
+            if (kind === 'task' && (!value || value.length > 64 || /[\x00-\x1f\x7f]/.test(value)))
+                return false;
+            if (kind === 'run' && !positiveId(value))
+                return false;
+            const run = kind === 'run' ? store.getRun(Number(value)) : null;
+            const ref = kind === 'run' ? run === null ? null : store.refById(run.taskRef) : store.lookupRef(value);
+            if (ref === null || !admit(ref.repo) || store.lookupRef(ref.externalId)?.id !== ref.id || store.getTask(ref.externalId) === null)
+                return false;
+            resolved.push({ repo: ref.repo, taskId: ref.externalId, taskRef: ref.id, kind });
+            return true;
+        }
+        if (kind === 'flow' || kind === 'trigger') {
+            if (!positiveId(value) || value.length > 10)
+                return false;
+            const trigger = kind === 'trigger' ? store.getFlowTrigger(Number(value)) : null;
+            const flow = kind === 'flow' ? store.getFlow(Number(value)) : trigger === null ? null : store.getFlow(trigger.flow);
+            if (flow === null || flow.state !== 'active' || !admit(flow.repo) || trigger?.state === 'removed')
+                return false;
+            resolved.push({ repo: flow.repo, taskId: null, ...(kind === 'flow' ? { flow: flow.id } : { parentFlow: trigger.flow }), kind });
+            return true;
+        }
+        if (kind === 'trigger-json') {
+            const config = input(value);
+            // Invalid/unavailable input cannot reach a resource lookup; the handler reports its existing file/JSON error.
+            if (!object(config))
+                return true;
+            return config['kind'] !== 'flow' || (typeof config['flow'] === 'number' && check('flow', String(config['flow'])));
+        }
+        if (kind === 'steps') {
+            const config = input(value), steps = object(config) ? config['steps'] : config;
+            if (!Array.isArray(steps))
+                return true;
+            // Build steps can name another project. Check the token ceiling as well as the owner's account grants.
+            return steps.every(step => !object(step) || step['repo'] === undefined ||
+                typeof step['repo'] === 'string' && store.knownRepos().includes(step['repo']) && allows(step['repo']));
+        }
+        return false;
+    };
+    for (const [name, value] of flags) {
+        const kind = audit.flags.get(name);
+        if (kind === 'step-up')
+            return { ok: false, reason: 'step-up', message: 'approve in the console or chat' };
+        if (kind === 'refused')
+            return { ok: false, reason: 'not-remote', message: 'That option is not available remotely.' };
+        if (kind === undefined)
+            return { ok: false, reason: 'usage', message: 'That option is not available for this remote command.' };
+        // Resolve positionals first below so the primary ledger target is stable regardless of flag order.
+        if (kind !== 'value' && typeof value !== 'string')
+            return REMOTE_NOT_FOUND;
+    }
+    for (let i = 0; i < audit.positionals.length; i++) {
+        const arg = audit.positionals[i];
+        const value = values[i];
+        if (value === undefined) {
+            if (arg.optional)
+                continue;
+            return REMOTE_NOT_FOUND;
+        }
+        if (!check(arg.kind, value))
+            return REMOTE_NOT_FOUND;
+    }
+    if (values.length > audit.positionals.length && !audit.positionals.at(-1)?.rest)
+        return REMOTE_NOT_FOUND;
+    for (const [name, value] of flags)
+        if (!check(audit.flags.get(name), String(value)))
+            return REMOTE_NOT_FOUND;
+    const task = resolved.find(ref => ref.kind === 'task');
+    for (const ref of resolved) {
+        if (ref.kind === 'run' && task !== undefined && ref.taskRef !== task.taskRef) {
+            // Review/revise accept a saved result from the same revision family. Stop/resume name an exact attempt.
+            const runFamily = store.taskFamilyOf(ref.taskId, [ref.repo], false);
+            const taskFamily = store.taskFamilyOf(task.taskId, [task.repo], false);
+            if (!['task review', 'task revise'].includes(invocation) || ref.repo !== task.repo || runFamily === null || taskFamily === null ||
+                runFamily.root.id !== taskFamily.root.id)
+                return REMOTE_NOT_FOUND;
+        }
+        if (ref.parentFlow !== undefined && ref.parentFlow !== resolved.find(one => one.kind === 'flow')?.flow)
+            return REMOTE_NOT_FOUND;
+    }
+    if (invocation === 'task repair') {
+        const draft = store.repairChainFor(Number(values[0]))?.draftTask;
+        if (draft != null && (!check('task', draft) || resolved.at(-1)?.repo !== resolved[0]?.repo))
+            return REMOTE_NOT_FOUND;
+    }
+    return { ok: true, repo: resolved[0]?.repo ?? named, taskId: resolved[0]?.taskId ?? null };
+}

package/dist/operate-remote.d.ts

@@ -0,0 +1,86 @@
+import type { Store } from "./store.js";
+import type { LedgerSource } from "./action-ledger.js";
+import { type CommandRow } from "./surface.js";
+/** Who a remote call is, as the transport proved it from an `so_` token. */
+export type Principal = {
+    kind: "person";
+    account: string;
+    /** The account's credential generation when the token was checked. */
+    generation: number;
+    scope: "read" | "act";
+    tokenId: string;
+    /** The projects the person may use (null: all of them). */
+    projects: string[] | null;
+};
+export type RemoteSource = Extract<LedgerSource, "api" | "mcp">;
+export { activeRemote, withRemote, type RemoteRun } from "./remote-run.js";
+/** Thrown where a remote run reaches something only this machine's owner may use; the command ends refused. */
+export declare class RemoteRefusal extends Error {
+    readonly reason: string;
+    constructor(reason: string, message: string);
+}
+export declare const REMOTE_MESSAGES: {
+    readonly "step-up": "Approvals, people and policy changes aren't taken from a token: approve in the console or chat.";
+    readonly no: "That command only runs on the server's own machine, not for a remote caller.";
+    readonly unknown: "That isn't a command a remote caller can run.";
+    readonly read: "Your token reads only. Use an act token for this command.";
+    readonly stale: "Your sign-in changed since this token was checked. Sign in again.";
+    readonly credential: "Remote commands run as your token's person: leave out --as, --token, --db and other credential or file flags.";
+    readonly project: "Name a project you have access to with --repo (its path on the server).";
+    readonly installation: "This command covers every project; it needs access to all projects.";
+    readonly files: "Send that file with the request; the server reads no paths of its own for you.";
+};
+/**
+ * How a "yes" command finds the project it touches, before it runs. Any --repo given is checked too.
+ *  installation — reads or acts across every project: only for someone with access to all of them.
+ *  repo — needs --repo, naming a project the server knows and the person may use.
+ *  references — the audited arguments resolve every resource to its stored project before dispatch.
+ *  self — the command already narrows to the person's own projects (their access is passed in).
+ *  global — touches no project's data.
+ */
+export type RemoteScope = {
+    kind: "installation";
+} | {
+    kind: "repo";
+} | {
+    kind: "references";
+} | {
+    kind: "self";
+} | {
+    kind: "global";
+};
+/** Every "yes" row's scope. The remote test holds this to the guide's "yes" rows exactly. */
+export declare const REMOTE_SCOPES: ReadonlyMap<string, RemoteScope>;
+/** Flags a remote caller never passes: who they are comes from the token, and the server reads and writes no paths for them. */
+export declare const REMOTE_REFUSED_FLAGS: ReadonlySet<string>;
+/**
+ * The guide row an argv is: the longest invocation its command and leading positionals spell. A command with no
+ * row of its own runs nowhere remotely (backup, restore, storage, ledger, policy and the rest).
+ */
+export declare function remoteRowOf(command: string, positional: readonly string[]): CommandRow | null;
+/**
+ * Re-prove the principal now, against the store: the account still stands at the same generation, the token is
+ * the person's, unrevoked and unexpired, and the scope is no wider than the token's or the person's role.
+ */
+export declare function reproveRemote(store: Store, principal: Principal, now: Date): {
+    ok: true;
+    scope: "read" | "act";
+    tokenName: string;
+} | {
+    ok: false;
+};
+/** Whether the person may use `repo`: inside their token's projects and their account's current access. Null is "every project". */
+export declare function remoteAllows(store: Store, principal: Principal, repo: string | null): boolean;
+/** The project a command touches, or why it may not run: --repo must be a project the server knows, by its exact path. */
+export declare function remoteProjectOf(store: Store, run: {
+    allows: (repo: string | null) => boolean;
+}, scope: RemoteScope, positional: readonly string[], repos: readonly string[], invocation: string, flags: ReadonlyMap<string, string | true>, files: Readonly<Record<string, string>>): {
+    ok: true;
+    repo: string | null;
+    taskId: string | null;
+} | {
+    ok: false;
+    reason: string;
+    message: string;
+};
+export declare function remoteSecret(): string;

package/dist/operate-remote.js

@@ -0,0 +1,125 @@
+/**
+ * Running a command on a central server for a person who signed in with their own API token
+ * (`runOperateAs` in operate.ts). The machine contract is the allowlist: every row states `remote`
+ * (src/surface.ts), and only "yes" rows run. This module holds what that boundary decides before any
+ * command code runs — which row an argv is, whether the person and token still stand, and which
+ * project the command touches — and the per-run state the credential paths in operate.ts consult so
+ * a remote run is always the person and never this machine's owner.
+ */
+import { randomBytes } from "node:crypto";
+import { isAbsolute } from "node:path";
+import { COMMAND_GUIDE } from "./surface.js";
+import { remoteArgumentsOf, REMOTE_NOT_FOUND } from "./operate-remote-arguments.js";
+export { activeRemote, withRemote } from "./remote-run.js";
+/** Thrown where a remote run reaches something only this machine's owner may use; the command ends refused. */
+export class RemoteRefusal extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+export const REMOTE_MESSAGES = {
+    "step-up": "Approvals, people and policy changes aren't taken from a token: approve in the console or chat.",
+    no: "That command only runs on the server's own machine, not for a remote caller.",
+    unknown: "That isn't a command a remote caller can run.",
+    read: "Your token reads only. Use an act token for this command.",
+    stale: "Your sign-in changed since this token was checked. Sign in again.",
+    credential: "Remote commands run as your token's person: leave out --as, --token, --db and other credential or file flags.",
+    project: "Name a project you have access to with --repo (its path on the server).",
+    installation: "This command covers every project; it needs access to all projects.",
+    files: "Send that file with the request; the server reads no paths of its own for you.",
+};
+const installation = { kind: "installation" }, repo = { kind: "repo" }, self = { kind: "self" }, global = { kind: "global" };
+const references = { kind: "references" };
+/** Every "yes" row's scope. The remote test holds this to the guide's "yes" rows exactly. */
+export const REMOTE_SCOPES = new Map([
+    ["status", installation], ["integrations", installation], ["ready", installation], ["grants", installation], ["sync", installation],
+    ["gaps", repo], ["task add", repo],
+    ...["ask", "checks", "add-tests", "show", "wait", "complete", "revise", "state", "block", "unblock", "next", "steer", "assign", "scope", "plan", "hold",
+        "unhold", "require", "requeue", "review", "repair", "route", "reopen", "stop", "resume"].map(action => [`task ${action}`, references]),
+    ["check-progress", references],
+    ["task list", installation],
+    ["runner list", installation], ["coordinator list", installation], ["outbox list", installation], ["incident list", installation], ["incident resolve", installation],
+    ["cap list", repo], ["cap add", repo],
+    ...["list", "show", "add", "refresh", "pause", "resume", "run-now"].map(action => [`routine ${action}`, installation]),
+    ["config show", installation], ["verify show", repo], ["intake show", installation], ["intake run", installation], ["intake preview", installation],
+    ["intake pr-comments", installation], ["template list", installation], ["template show", installation], ["contest show", installation],
+    ["contest exclude", installation], ["webhook status", installation], ["webhook test", installation], ["review show", installation],
+    ["chat-approval show", self], ["chat-approval off", self],
+    ["knowledge search", repo], ["knowledge impact", repo], ["knowledge refresh", repo],
+    ...["search", "decisions", "show", "decide", "retire", "review", "status"].map(action => [`memory ${action}`, self]),
+    ...["list", "show", "export", "create", "edit", "trigger add", "trigger pause", "trigger resume", "trigger remove", "card add", "archive"]
+        .map(action => [`flows ${action}`, self]),
+    ["models status", global], ["models list", global],
+]);
+/** Flags a remote caller never passes: who they are comes from the token, and the server reads and writes no paths for them. */
+export const REMOTE_REFUSED_FLAGS = new Set([
+    "db", "as", "token", "token-file", "token-env", "password", "key-file", "credentials", "containment", "out", "project-root", "bin", "port", "host",
+]);
+/**
+ * The guide row an argv is: the longest invocation its command and leading positionals spell. A command with no
+ * row of its own runs nowhere remotely (backup, restore, storage, ledger, policy and the rest).
+ */
+export function remoteRowOf(command, positional) {
+    for (let words = Math.min(positional.length, 2); words >= 0; words -= 1) {
+        const invocation = [command, ...positional.slice(0, words)].join(" ");
+        const row = COMMAND_GUIDE.find(one => one.invocation === invocation && one.invocation !== "");
+        if (row !== undefined)
+            return row;
+    }
+    return null;
+}
+/**
+ * Re-prove the principal now, against the store: the account still stands at the same generation, the token is
+ * the person's, unrevoked and unexpired, and the scope is no wider than the token's or the person's role.
+ */
+export function reproveRemote(store, principal, now) {
+    if (principal === null || typeof principal !== "object" || principal.kind !== "person" || typeof principal.account !== "string" || typeof principal.tokenId !== "string")
+        return { ok: false };
+    const account = store.accountOf(principal.account);
+    if (account === null || account.revokedAt !== null || account.generation !== principal.generation)
+        return { ok: false };
+    const token = store.apiTokenSecret(principal.tokenId)?.row ?? null;
+    if (token === null || token.account !== principal.account || token.revokedAt !== null || Date.parse(token.expiresAt) <= now.getTime())
+        return { ok: false };
+    const scope = principal.scope === "act" && token.access === "act" && account.role === "approver" ? "act" : "read";
+    return { ok: true, scope, tokenName: token.name };
+}
+/** Whether the person may use `repo`: inside their token's projects and their account's current access. Null is "every project". */
+export function remoteAllows(store, principal, repo) {
+    if (principal.projects !== null && (repo === null || !principal.projects.includes(repo)))
+        return false;
+    return store.accountCanAccess(principal.account, repo);
+}
+/** The project a command touches, or why it may not run: --repo must be a project the server knows, by its exact path. */
+export function remoteProjectOf(store, run, scope, positional, repos, invocation, flags, files) {
+    const known = store.knownRepos();
+    // The local parser keeps the last raw --repo as well as a split repoList. Require those identities
+    // to agree: comma lists and repeated project flags cannot authorize one path and dispatch another.
+    const rawRepo = flags.get("repo");
+    if (rawRepo !== undefined && (repos.length !== 1 || rawRepo !== repos[0]))
+        return { ok: false, reason: "unknown-project", message: REMOTE_MESSAGES.project };
+    for (const given of repos) {
+        if (!isAbsolute(given) || !known.includes(given) || !run.allows(given))
+            return { ok: false, reason: "unknown-project", message: REMOTE_MESSAGES.project };
+    }
+    const named = repos[0] ?? null;
+    const checked = remoteArgumentsOf(store, run.allows, invocation, positional, flags, named, files);
+    if (!checked.ok)
+        return checked;
+    switch (scope.kind) {
+        case "global":
+        case "self":
+            return checked;
+        case "installation":
+            return run.allows(null) ? { ok: true, repo: named, taskId: null } : { ok: false, reason: "all-projects", message: REMOTE_MESSAGES.installation };
+        case "repo":
+            return named === null ? { ok: false, reason: "unknown-project", message: REMOTE_MESSAGES.project } : checked;
+        case "references":
+            return checked.repo === null ? REMOTE_NOT_FOUND : checked;
+    }
+}
+export function remoteSecret() {
+    return `remote:${randomBytes(24).toString("base64url")}`;
+}

package/dist/operate.d.ts

@@ -8,6 +8,7 @@ import { type Store } from "./store.js";
 import { type DispatchAdapter } from "./sync.js";
 import { type TelegramTransport } from "./telegram.js";
 import { type MateCliSeams } from "./mate-cli.js";
+import { type Principal, type RemoteSource } from "./operate-remote.js";
 import { type PublishExec } from "./publish.js";
 import { type Runner as CommandRunner } from "./builder.js";
 import { type ReleaseIo } from "./releases.js";
@@ -123,6 +124,26 @@ export declare function parseOperateArgs(argv: readonly string[], ownValues?: Re
 };
 /** Route an `operate` command. Returns the process exit code. */
 export declare function runOperate(command: string, argv: readonly string[], write: Write, options?: OperateOptions): Promise<number>;
+export type { Principal };
+/**
+ * Run one command on this server for a person who signed in with their own API token (the transport and MCP
+ * gateway prove the `so_` token and refuse browser origins; this is everything after). The command's row in the
+ * machine contract decides first: "no" and "step-up" rows, and commands with no row, are refused before any
+ * command code runs. The principal is re-proved against the store, a read token runs only reads, and the project
+ * the command touches must be one the person may use, named by --repo where a local run would use the working
+ * directory. The command then runs as that person: every credential check resolves to them, nothing prompts, and
+ * this machine's saved login and lead token are never read. Files are only those sent in `files`, keyed by the
+ * argument that names them. Every call is in the action history as the person, from source `api` (or `mcp`),
+ * with the token's name. The store is the caller's and stays open.
+ */
+export declare function runOperateAs(argv: string[], opts: {
+    principal: Principal;
+    store: Store;
+    write: (s: string) => void;
+    files?: Record<string, string>;
+    source?: RemoteSource;
+    options?: OperateOptions;
+}): Promise<number>;
 /** Durably create the login file BEFORE the bootstrap commits (arc 2
  * finding 27): exclusive, 0600, fsynced — file and directory both — so the
  * row only ever follows a durable secret. Throws on any failure. */
@@ -142,4 +163,3 @@ export declare function readUpConsoleUrl(dir: string): string | null;
  * missing credentials stay a usage refusal, exactly as before.
  */
 export declare const PROPOSALS_ACTIONS: readonly ["list", "confirm", "dismiss"];
-export {};