@sema-agent/core 7.43.0 → 7.45.0

package/dist/orchestration/workflow.js

@@ -19,6 +19,7 @@ import { boundInputHashOf } from "../core/canonical-json.js";
 import { boundedRedactedSummary } from "../core/untrusted-egress.js";
 import { delimitUntrusted } from "../core/untrusted-text.js";
 import { OUTPUT_TOOL_NAME } from "../core/runner/synthetic-tools.js";
+import { deniedToolNamesOf } from "../core/runner/sub-agent-deny-lists.js";
 import { compileOutputSchema } from "../core/runner/strict-output-schema.js";
 import { WorkflowBudgetExceededError, WorkflowNestingError, WorkflowAgentBlockedError, WorkflowAgentParkedError, WorkflowAgentSchemaError, WorkflowAgentStalledError, WorkflowMaxAgentsError, WORKFLOW_SPAWN_BLOCKED_ERROR_CODE } from "./workflow-types.js";
 import { WorkflowScriptError } from "./workflow-meta.js";
@@ -118,7 +119,7 @@ export function applyWorkflowAgentType(spec, agentType, registry) {
     if (out.memoryPersistenceCapable === undefined && def.memoryPersistenceCapable !== undefined)
         out.memoryPersistenceCapable = def.memoryPersistenceCapable;
     if (def.allowTools !== undefined || def.denyTools !== undefined) {
-        const perType = createAllowDenyPolicy({ ...(def.allowTools ? { allow: def.allowTools } : {}), ...(def.denyTools ? { deny: def.denyTools } : {}), scope: "narrowing" });
+        const perType = createAllowDenyPolicy({ ...(def.allowTools ? { allow: def.allowTools } : {}), ...(def.denyTools ? { deny: deniedToolNamesOf(`workflow agentType "${def.name}"`, def.denyTools) } : {}), scope: "narrowing" });
         out.toolPolicy = out.toolPolicy ? combinePolicies(out.toolPolicy, perType) : perType;
     }
     return out;
@@ -1056,9 +1057,10 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
         const parks = run.parks ?? (run.parks = []);
         const at = parks.findIndex((e) => e.callKey === rec.callKey);
         const held = at === -1 ? undefined : parks[at];
+        const holder = { parkedBy: runId, generation: held?.generation ?? 0 };
         const key = held !== undefined && held.token === paused.terminal.token && held.originUnconfirmed !== true
-            ? { callKey: rec.callKey, sessionId: paused.sessionId, token: paused.terminal.token, originRunId: held.originRunId }
-            : { callKey: rec.callKey, sessionId: paused.sessionId, token: paused.terminal.token, originRunId: runId, originUnconfirmed: true };
+            ? { callKey: rec.callKey, sessionId: paused.sessionId, token: paused.terminal.token, originRunId: held.originRunId, ...holder }
+            : { callKey: rec.callKey, sessionId: paused.sessionId, token: paused.terminal.token, originRunId: runId, originUnconfirmed: true, ...holder };
         if (at === -1)
             parks.push(key);
         else
@@ -2263,19 +2265,23 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         throw parksUnreadable("its journal yielded no entry to derive one from");
                     const candidates = new Map();
                     const keyed = (k) => k.token !== "" && k.sessionId !== "";
+                    const clash = (a, b) => a !== "" && b !== "" && a !== b;
                     const offerCandidate = (ord, key) => {
                         const recorded = candidates.get(ord);
-                        if (recorded !== undefined && (recorded.callKey !== key.callKey || (keyed(recorded) && keyed(key) && (recorded.token !== key.token || recorded.sessionId !== key.sessionId))))
+                        if (recorded !== undefined && (recorded.callKey !== key.callKey || clash(recorded.token, key.token) || clash(recorded.sessionId, key.sessionId)))
                             throw parkBindingBroken(ord, "the prior run's key caches name different tokens, sessions or calls for it");
-                        if (recorded === undefined || (!keyed(recorded) && keyed(key)))
+                        if (recorded === undefined)
                             candidates.set(ord, key);
+                        else if (!keyed(recorded) && keyed(key))
+                            candidates.set(ord, recorded.parkedBy === undefined ? key : { ...key, parkedBy: recorded.parkedBy, generation: recorded.generation });
                     };
                     for (const raw of recordParks ?? []) {
                         const e = raw;
-                        if (e === null || typeof e !== "object" || typeof e.callKey !== "string" || typeof e.sessionId !== "string" || typeof e.token !== "string" || typeof e.originRunId !== "string" || !/^\d+:/.test(e.callKey)) {
+                        const holder = e === null || typeof e !== "object" ? undefined : e.parkedBy === undefined && e.generation === undefined ? {} : typeof e.parkedBy === "string" && e.parkedBy !== "" && Number.isSafeInteger(e.generation) && e.generation >= 0 ? { parkedBy: e.parkedBy, generation: e.generation } : undefined;
+                        if (e === null || typeof e !== "object" || holder === undefined || typeof e.callKey !== "string" || typeof e.sessionId !== "string" || typeof e.token !== "string" || typeof e.originRunId !== "string" || !/^\d+:/.test(e.callKey)) {
                             throw parkBindingBroken(-1, "a recorded park entry is malformed or its call key has no ordinal");
                         }
-                        offerCandidate(callKeyOrdinal(e.callKey), { callKey: e.callKey, sessionId: e.sessionId, token: e.token, originRunId: e.originRunId, ...(e.originUnconfirmed === true ? { originUnconfirmed: true } : {}) });
+                        offerCandidate(callKeyOrdinal(e.callKey), { callKey: e.callKey, sessionId: e.sessionId, token: e.token, originRunId: e.originRunId, ...(e.originUnconfirmed === true ? { originUnconfirmed: true } : {}), ...holder });
                     }
                     for (const [ord, e] of replayByOrdinal.entries()) {
                         if (e?.parked === undefined)
@@ -2320,6 +2326,9 @@ export function startWorkflow(runner, fn, opts = {}, internals) {
                         }
                     }
                     if (!finalized) {
+                        for (const key of inherited)
+                            if (key.generation !== undefined)
+                                key.generation += 1;
                         run.parks = inherited;
                         delete run.resumeAdmissionIncomplete;
                     }

package/dist/tools/fs/removal-targets.d.ts

@@ -0,0 +1,82 @@
+import { type EstablishedPlan } from "./shell-read-establish.js";
+import type { ExecutionEnv } from "../../internal/harness-types.js";
+import type { ToolCallRequest } from "../../core/tool-policy.js";
+/** The REMOVAL programs — the reference implementation's dangerous-removal arm reads `rm` and `rmdir`, with or without a
+ *  recursive option (removing an empty home or the task root is still removing it). */
+export declare const SHELL_REMOVAL_COMMANDS: readonly ["rm", "rmdir"];
+export type ShellRemovalCommand = (typeof SHELL_REMOVAL_COMMANDS)[number];
+/** What makes a removal target dangerous, in the order a card names it. `runtime_script`: a shell's script text is built
+ *  only when the command runs, and what it may run includes a removal nobody can read before it does. */
+export type DangerousRemovalKind = "filesystem_root" | "home" | "workspace" | "top_level" | "runtime_script";
+/** The protected locations a removal is judged against. `homes`: the environment's declared home and every other spelling
+ *  of it (its canonical one); `workspace`: the task root, the working directory, the additional working directories. */
+export interface RemovalSeat {
+    readonly homes: readonly string[];
+    readonly workspace: readonly string[];
+}
+/** One dangerous removal a command makes: the program (the removal program, or the shell a runtime-built script is handed
+ *  to), the operand as written, the target as established (the script word as written, for `runtime_script`). */
+export interface DangerousRemoval {
+    readonly kind: DangerousRemovalKind;
+    readonly program: string;
+    readonly operand: string;
+    readonly target: string;
+}
+/**
+ * The ONE dangerous-removal predicate: is removing this absolute path removing a protected location? The reference
+ * implementation's set (cli 2.1.291 `dme` / `xW`) — the filesystem root (a drive root, a UNC share root), a home directory
+ * (every spelling the seat holds), a workspace directory or any of its ANCESTORS (the task root, the working directory, an
+ * additional working directory — whether the home lies inside the task root or the task root inside the home), a top-level
+ * directory (one segment below the root). `undefined` for a relative path or any other target.
+ */
+export declare function dangerousRemovalOf(path: string, seat: RemovalSeat): DangerousRemovalKind | undefined;
+/** What one removal finding asks: a protected location (`dangerous_delete`), or a target the command builds from a value
+ *  of its own that the guard cannot read (`unverifiable_delete`). */
+export type RemovalFinding = (DangerousRemoval & {
+    readonly guard: "dangerous_delete";
+}) | {
+    readonly guard: "unverifiable_delete";
+    readonly program: string;
+    readonly operand: string;
+    readonly name: string;
+};
+/**
+ * The removal findings of an established plan — ONE walk, nested plans included (a `bash -c` / `sh -c` text, a substitution
+ * body), two words. For every `rm` / `rmdir` segment, each of its OPERANDS (every write target that is not one of its
+ * option words, read off its argv with {@link REMOVAL_GRAMMAR}) as the plan established it on the WRITE face (the entry the
+ * program unlinks, and the deny-floor shadow of a home word the plan did not place) is judged by {@link dangerousRemovalOf};
+ * an operand the plan could not place that expands a name the command itself binds is judged in every spelling those
+ * bindings give it ({@link boundSpellingsOf}), and one with a binding this reading cannot read is an unverifiable target (a
+ * recursive force `rm`). A shell handed a script built only when the command runs is a dangerous removal of its own
+ * ({@link runtimeScriptOf}). The read-face copy of an operand is not judged: it follows a link the removal does not follow.
+ */
+export declare function removalFindingsOf(established: EstablishedPlan, seat: RemovalSeat): RemovalFinding[];
+/** Does any segment of this plan (nested plans included) run a removal program, or hand a shell a script built when it
+ *  runs? The guard establishes nothing for a command that does neither. */
+export declare function planRunsRemoval(plan: EstablishedPlan["plan"]): boolean;
+/** What the removal guard asks for one command: the guard word and its sentence's account — the first protected location
+ *  (the program, the location, the target), else the first bound value the guard cannot read; `undefined` when neither. */
+export interface RemovalVerdict {
+    readonly guard: RemovalFinding["guard"];
+    readonly text: string;
+}
+/**
+ * The seat the dangerous-removal arm of the removal guard (`createUnverifiableDeletePolicy`, tool-policy.ts) reads, beside the request's own `root` /
+ * `cwd` (the task root and the live working directory): the execution environment (its declared home — the `HOME` the
+ * shell child receives, the same seat the read station folds `~` / `$HOME` with — and its resolver, so a target that
+ * resolves through a link is judged where it lands), and the leg's additional working directories.
+ */
+export interface RemovalGuardSeat {
+    readonly env?: ExecutionEnv;
+    readonly additionalRoots?: () => readonly string[];
+}
+/**
+ * The dangerous-removal READING of one command — undefined when no segment of it (nested shell text included) runs a
+ * removal program, so a command that removes nothing costs the gate no suspension. Otherwise `judge` establishes the plan
+ * the read station plans (the same planner, the same write-target reading) lexically against the request's `cwd` and the
+ * seat's home, and — where an environment is seated — through its resolver too, and returns what either establishment
+ * finds ({@link removalFindingsOf}: the protected-location word first, then the unverifiable one).
+ */
+export declare function removalReadingOf(command: string, req: Pick<ToolCallRequest, "cwd" | "root">, seat: RemovalGuardSeat | undefined): {
+    judge(signal?: AbortSignal): Promise<RemovalVerdict | undefined>;
+} | undefined;

package/dist/tools/fs/removal-targets.js

@@ -0,0 +1,236 @@
+import { planShellReads } from "./shell-read-plan.js";
+import { createShellReadEstablisher, establishShellReadsLexically } from "./shell-read-establish.js";
+import { isAbsolutePathForm, isWinFormPath, normalizeAbsPathLexically } from "./safety.js";
+import { reentryText } from "./shell-reentry-text.js";
+import { bashClassifyDefaultAllow, SHELL_REENTRY_PROGRAM_RE } from "./bash-readonly-classifier.js";
+import { programArgs, readArgv } from "./shell-read-write-targets.js";
+import { inlineUntrusted } from "../../core/untrusted-text.js";
+export const SHELL_REMOVAL_COMMANDS = Object.freeze(["rm", "rmdir"]);
+const REMOVAL_COMMAND_SET = new Set(SHELL_REMOVAL_COMMANDS);
+const REMOVAL_GRAMMAR = { required: "", optional: "", longRequired: [] };
+function removalKey(path) {
+    let k = normalizeAbsPathLexically(path.normalize("NFC")).replace(/\\/g, "/").toLowerCase();
+    k = k.replace(/(?:\/+\*+)+\/*$/, "");
+    const drive = driveOf(path, k);
+    let rest = k.slice(drive.length);
+    if (rest === "")
+        rest = "/";
+    if (rest.length > 1)
+        rest = rest.replace(/\/+$/, "");
+    return drive + rest.replace(/^\/private\/(etc|var|tmp|home)(?=\/|$)/, "/$1");
+}
+function driveOf(path, key) {
+    return isWinFormPath(path) && key.length >= 2 && key[1] === ":" ? key.slice(0, 2) : "";
+}
+export function dangerousRemovalOf(path, seat) {
+    if (!isAbsolutePathForm(path))
+        return undefined;
+    const k = removalKey(path);
+    const rest = k.slice(driveOf(path, k).length);
+    if (rest === "/" || /^\/\/[^/]+\/[^/]+$/.test(k))
+        return "filesystem_root";
+    if (seat.homes.some((h) => isAbsolutePathForm(h) && removalKey(h) === k))
+        return "home";
+    const prefix = k.endsWith("/") ? k : `${k}/`;
+    if (seat.workspace.some((w) => isAbsolutePathForm(w) && (removalKey(w) === k || removalKey(w).startsWith(prefix))))
+        return "workspace";
+    if (/^\/[^/]+$/.test(rest))
+        return "top_level";
+    return undefined;
+}
+function tildeNamesAHome(spelled) {
+    const m = /^~([^/]*)(\/.*)?$/.exec(spelled);
+    if (m === null)
+        return false;
+    const key = removalKey(`/~home${m[2] ?? ""}`);
+    return key === "/~home" || !key.startsWith("/~home/");
+}
+function removalKindOf(read, seat) {
+    const floors = read.established === "unestablishable" && read.candidate.bases === "unmodelled" ? read.spellings : [];
+    for (const view of [read.target, read.origin, ...floors]) {
+        const kind = view === undefined ? undefined : dangerousRemovalOf(view, seat);
+        if (kind !== undefined)
+            return kind;
+    }
+    return read.established === "unestablishable" && tildeNamesAHome(read.candidate.spelled) ? "home" : undefined;
+}
+function literalOf(pieces) {
+    return pieces.every((q) => q.literal !== undefined) ? pieces.map((q) => q.literal).join("") : undefined;
+}
+const NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const NAME_BINDERS = new Set(["unset", "local", "declare", "typeset", "readonly", "export", "read"]);
+function bindingsOf(plan) {
+    const out = new Map();
+    const bind = (name, value) => {
+        out.set(name, [...(out.get(name) ?? []), value]);
+    };
+    for (const segment of plan.segments) {
+        for (const w of segment.argv)
+            if (w.assignment !== undefined)
+                bind(w.assignment.name, w.assignment.settlesWholeName ? literalOf(w.assignment.value.pieces) : undefined);
+        const [head, name] = segment.argv;
+        if ((head?.folded === "for" || head?.folded === "select") && name !== undefined && NAME.test(name.folded)) {
+            const at = segment.argv.findIndex((w, i) => i > 1 && w.folded === "in");
+            const words = at < 0 ? [undefined] : segment.argv.slice(at + 1).map((w) => literalOf(w.pieces));
+            for (const v of words.length > 0 ? words : [undefined])
+                bind(name.folded, v);
+        }
+        if (head !== undefined && NAME_BINDERS.has(head.folded))
+            for (const w of segment.argv.slice(1))
+                if (w.assignment === undefined && NAME.test(w.folded))
+                    bind(w.folded, undefined);
+    }
+    return out;
+}
+const BOUND_SPELLINGS_MAX = 64;
+function boundSpellingsOf(word, bindings) {
+    const named = word.pieces.filter((q) => q.literal === undefined);
+    if (named.length === 0 || !named.some((q) => q.expansion?.kind === "parameter" && q.expansion.name !== undefined && bindings.has(q.expansion.name)))
+        return undefined;
+    let spellings = [""];
+    for (const q of word.pieces) {
+        if (q.literal !== undefined) {
+            spellings = spellings.map((sp) => sp + q.literal);
+            continue;
+        }
+        const name = q.expansion?.kind === "parameter" && (q.expansion.body === undefined || q.expansion.body === q.expansion.name) ? q.expansion.name : undefined;
+        const values = name !== undefined ? bindings.get(name) : undefined;
+        if (name === undefined || values === undefined)
+            return { unreadable: q.expansion?.name ?? word.raw };
+        if (values.some((v) => v === undefined || (q.quotedBy === undefined && /\s/.test(v))))
+            return { unreadable: name };
+        spellings = spellings.flatMap((sp) => values.map((v) => sp + v));
+        if (spellings.length > BOUND_SPELLINGS_MAX)
+            return { unreadable: name };
+    }
+    return { spellings };
+}
+function recursiveForce(args) {
+    const { options } = readArgv(args, REMOVAL_GRAMMAR);
+    const has = (long, short) => options.some((o) => (o.long ? long.startsWith(o.name) : short.test(o.name)));
+    return has("recursive", /^[rR]$/) && has("force", /^f$/);
+}
+export function removalFindingsOf(established, seat) {
+    const out = [];
+    const bindings = bindingsOf(established.plan);
+    for (const segment of established.plan.segments) {
+        const program = segment.verb?.basename;
+        if (program !== undefined && REMOVAL_COMMAND_SET.has(program)) {
+            const args = programArgs(segment);
+            const operands = new Set(readArgv(args, REMOVAL_GRAMMAR).operands);
+            const options = new Set(args.filter((w) => !operands.has(w)).map((w) => w.raw));
+            for (const read of established.reads.get(segment) ?? []) {
+                if (read.candidate.face !== "write" || options.has(read.candidate.raw))
+                    continue;
+                const kind = removalKindOf(read, seat);
+                if (kind !== undefined) {
+                    out.push({ guard: "dangerous_delete", kind, program, operand: read.candidate.raw, target: read.target ?? read.candidate.floorSpelled ?? read.candidate.spelled });
+                    continue;
+                }
+                if (read.established !== "unestablishable")
+                    continue;
+                const word = segment.argv.find((w) => w.raw === read.candidate.raw);
+                const bound = word === undefined ? undefined : boundSpellingsOf(word, bindings);
+                if (bound === undefined)
+                    continue;
+                if ("unreadable" in bound) {
+                    if (program === "rm" && recursiveForce(args))
+                        out.push({ guard: "unverifiable_delete", program, operand: read.candidate.raw, name: bound.unreadable });
+                    continue;
+                }
+                const bases = segment.bases === "unmodelled" ? (read.candidate.floorBases ?? []) : segment.bases;
+                for (const spelled of bound.spellings) {
+                    const views = isAbsolutePathForm(spelled) ? [spelled] : bases.map((base) => `${base}/${spelled}`);
+                    for (const view of views) {
+                        const hit = dangerousRemovalOf(view, seat);
+                        if (hit === undefined)
+                            continue;
+                        out.push({ guard: "dangerous_delete", kind: hit, program, operand: read.candidate.raw, target: normalizeAbsPathLexically(view) });
+                        break;
+                    }
+                }
+            }
+        }
+        const script = runtimeScriptOf(segment);
+        if (script !== undefined && program !== undefined)
+            out.push({ guard: "dangerous_delete", kind: "runtime_script", program, operand: script, target: script });
+        for (const nested of segment.nested) {
+            const sub = established.nested.get(nested);
+            if (sub !== undefined)
+                out.push(...removalFindingsOf(sub, seat));
+        }
+    }
+    return out;
+}
+function runtimeScriptOf(segment) {
+    const program = segment.verb;
+    if (segment.reentry !== "shell" || program === undefined || !SHELL_REENTRY_PROGRAM_RE.test(program.basename))
+        return undefined;
+    const at = segment.argv.findIndex((w) => w.folded === program.name);
+    if (at < 0)
+        return undefined;
+    const MARK = "\u0000";
+    const words = segment.argv.slice(at + 1).map((w) => literalOf(w.pieces) ?? `${MARK}${w.raw}`);
+    const text = reentryText(program.basename, words);
+    return text === undefined || !text.includes(MARK) ? undefined : text.split(MARK).join("");
+}
+export function planRunsRemoval(plan) {
+    return plan.segments.some((s) => (s.verb !== undefined && REMOVAL_COMMAND_SET.has(s.verb.basename)) || runtimeScriptOf(s) !== undefined || s.nested.some(planRunsRemoval));
+}
+const DANGEROUS_REMOVAL_SENTENCE = {
+    filesystem_root: (p, t) => `\`${p}\` would remove the filesystem root (${t})`,
+    home: (p, t) => `\`${p}\` would remove a home directory (${t})`,
+    workspace: (p, t) => `\`${p}\` would remove a workspace directory — the task root, the working directory or an additional working directory — or one of its ancestors (${t})`,
+    top_level: (p, t) => `\`${p}\` would remove a top-level system directory (${t})`,
+    runtime_script: (p, t) => `\`${p}\` runs a script built only when the command runs (${t}), and it may remove the filesystem root, a home directory or the task's directories before anyone can read it`,
+};
+function verdictOf(findings) {
+    for (const f of findings)
+        if (f.guard === "dangerous_delete")
+            return { guard: f.guard, text: DANGEROUS_REMOVAL_SENTENCE[f.kind](f.program, inlineUntrusted(f.target, 200)) };
+    for (const f of findings)
+        if (f.guard === "unverifiable_delete")
+            return { guard: f.guard, text: `\`${f.program}\` recursive+force target ${inlineUntrusted(f.operand, 200)} takes ${f.name}'s value, which this command sets in a form the guard cannot read (an expansion, an unset or bare declaration, a \`read\`, a loop over unread words) — the deleted path cannot be verified from this command` };
+    return undefined;
+}
+const REMOVAL_RESOLVE_TIMEOUT_MS = 10_000;
+export function removalReadingOf(command, req, seat) {
+    const homeDir = seat?.env?.homeDir;
+    const cwd = req.cwd ?? req.root ?? "";
+    const roots = req.root !== undefined ? [req.root] : cwd !== "" ? [cwd] : [];
+    const boundary = { roots, ...(cwd !== "" ? { cwd } : {}), ...(homeDir !== undefined ? { homeDir } : {}) };
+    const plan = planShellReads(command, { readers: new Set(bashClassifyDefaultAllow()), cwd, roots, ...(homeDir !== undefined ? { homeDir } : {}) });
+    if (!planRunsRemoval(plan))
+        return undefined;
+    return {
+        async judge(signal) {
+            const env = seat?.env;
+            const resolved = env !== undefined && homeDir !== undefined ? await resolvedOrUndefined(env.canonicalPath(homeDir, signal), signal) : undefined;
+            const removalSeat = {
+                homes: [...(homeDir !== undefined ? [homeDir] : []), ...(resolved !== undefined && resolved.ok ? [resolved.value] : [])],
+                workspace: [...(req.root !== undefined ? [req.root] : []), ...(req.cwd !== undefined ? [req.cwd] : []), ...(seat?.additionalRoots?.() ?? [])],
+            };
+            const lexical = removalFindingsOf(establishShellReadsLexically(plan, boundary), removalSeat);
+            if (lexical.some((f) => f.guard === "dangerous_delete") || env === undefined || roots.length === 0)
+                return verdictOf(lexical);
+            const established = await resolvedOrUndefined(createShellReadEstablisher(env, roots, { rootsCanonical: true }).establish(plan, boundary, signal), signal);
+            return verdictOf(established === undefined ? lexical : [...removalFindingsOf(established, removalSeat), ...lexical]);
+        },
+    };
+}
+async function resolvedOrUndefined(leg, signal) {
+    let timer;
+    try {
+        return await Promise.race([
+            leg.catch(() => undefined),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve(undefined), REMOVAL_RESOLVE_TIMEOUT_MS);
+                signal?.addEventListener("abort", () => resolve(undefined), { once: true });
+            }),
+        ]);
+    }
+    finally {
+        if (timer !== undefined)
+            clearTimeout(timer);
+    }
+}

package/dist/tools/fs/shell-read-write-targets.d.ts

@@ -27,6 +27,32 @@ export interface ArgWord {
 }
 /** The words a segment hands its program — the argv after the program word (a launcher's own words are not the program's). */
 export declare function programArgs(segment: ShellReadSegment): ArgWord[];
+/**
+ * One program's option GRAMMAR, as its getopt reads it: the short letters taking a REQUIRED value (the rest of the word,
+ * or the next word), those taking an OPTIONAL one (the rest of the word only), and the long names taking a required value
+ * (any unambiguous prefix; `=` or the next word) — absent for a program with no long options (a `--name` word is then an
+ * error the program stops on, and names nothing here). The GNU and BSD programs of one name read the same argv
+ * differently (`sed -l` takes a value in GNU and none in BSD; `cp -S` a suffix in GNU and none in BSD), so every question
+ * below reads the argv under BOTH grammars and takes the union of what they name.
+ */
+export interface OptionGrammar {
+    readonly required: string;
+    readonly optional: string;
+    readonly longRequired?: readonly string[];
+}
+/** One option read off an argv: a short letter or a long name as written (a prefix), and its value when it has one. */
+interface OptionRead {
+    readonly name: string;
+    readonly long: boolean;
+    readonly value?: ArgWord;
+}
+/** An argv read under one grammar: its options in order, and its operands (every word after `--` included). Options are
+ *  read anywhere among the operands, as GNU getopt permutes them — for a BSD getopt, which stops at the first operand,
+ *  that is a superset of its options (the tightening direction). */
+export declare function readArgv(words: readonly ArgWord[], grammar: OptionGrammar): {
+    readonly options: readonly OptionRead[];
+    readonly operands: readonly ArgWord[];
+};
 /** What a `sed` invocation's option words say about writing, under either grammar ({@link SED_GRAMMARS}): whether it edits
  *  in place (`-i` / `-I` / `--in-place`), the backup suffixes it is given (their values; an empty value keeps no backup),
  *  and whether GNU `--follow-symlinks` is on. */
@@ -71,3 +97,4 @@ export interface JudgedCandidate {
  *  lists it among the reads), plus its WRITE targets for the write face ({@link writeTargetsOf}), plus the deny-floor
  *  shadow of every unplaced home word ({@link denyFloorShadowsOf}) on both faces. */
 export declare function judgedCandidatesOf(segment: ShellReadSegment): readonly JudgedCandidate[];
+export {};

package/dist/tools/fs/shell-read-write-targets.js

@@ -21,7 +21,7 @@ const COPY_GRAMMARS = [
     { required: "St", optional: "", longRequired: ["target-directory", "suffix", "no-preserve", "sparse"] },
     { required: "", optional: "" },
 ];
-function readArgv(words, grammar) {
+export function readArgv(words, grammar) {
     const options = [];
     const operands = [];
     let endOfOptions = false;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/core",
-  "version": "7.43.0",
+  "version": "7.45.0",
   "description": "Stateless, task-oriented AI agent core",
   "type": "module",
   "license": "BUSL-1.1",