@sema-agent/core 7.30.0 → 7.31.0

package/dist/tools/fs/shell-read-word.d.ts

@@ -4,7 +4,7 @@
  * (the home-directory word spelled with the declared home, as bash hands it to the program), and what the shell
  * does to the word before the program sees it.
  */
-import { type LexedToken, type LexedWord, type WordPiece } from "../../shell/lex.js";
+import { type LexedCommand, type LexedToken, type LexedWord, type WordPiece } from "../../shell/lex.js";
 /** `"glob"` = an unquoted pathname-expansion character; `"unresolvable"` = the shell rewrites the word (a brace,
  *  variable or command substitution) so its text is not the path. The read candidate's own field, spelled here. */
 export type WordExpands = false | "glob" | "unresolvable";
@@ -35,13 +35,27 @@ export declare function spelledWithHome(spelled: string, raw: string, home: stri
  *  spelling. The lexer puts the body's compound command back at command position after the head, so a definition
  *  nested in a body is dropped the same way; after a drop the token that moved up is looked at again. */
 export declare function dropDefinitionHeads(tokens: LexedToken[]): void;
+/** Why a lexed text's reads cannot all be named — the plan's `unreadable` floor, or `undefined`: the first word whose
+ *  value the text does not contain (an unresolved word), or an unquoted extended-glob opener anywhere a word, a
+ *  redirection target or a here-document delimiter stands (`pack@(age.json)`, `<<@(x)`). After `shopt -s extglob`
+ *  bash expands the pattern (or reads another delimiter) where the lexer reads a split word, so what the text opens is
+ *  not what the plan names: the whole text asks, and a deny hit anywhere still refuses. `globs: false` = the text is an
+ *  arithmetic expression (`$((2*(3+4)))`), which bash evaluates and never globs. */
+export declare function unreadableSentenceOf(lexed: LexedCommand, text: string, globs?: boolean): string | undefined;
 /** The elements of a compound array value `(e1 [k]=e2 …)`, read with the one lexer as the words bash assigns (a
  *  `[k]=` subscript prefix dropped): each is a value spelling the deny judge reads, as a scalar value is. The list is
  *  words across lines and comments, so every segment's words count, whatever else a segment carries (a word bash
  *  would reject leaves its siblings readable). None when the list does not lex — the value stays the unread list. */
 export declare function compoundArrayElements(value: {
     readonly raw: string;
-}): readonly Read[];
+}): readonly (Read & {
+    readonly denyOnly?: true;
+})[];
+/** An `$((…))` body the shell reads as ARITHMETIC: one parenthesised group spanning the whole body (`(2*(3+4))`),
+ *  its bounds read off the lexer's structure — a quoted, escaped or commented parenthesis is text, not a bound — across
+ *  the segments the lexer cuts at `&&` `||` `&` `|` and line breaks (operators arithmetic shares with the shell).
+ *  `$((cat x); :)` opens the same way but its first group closes early: a command substitution holding a subshell. */
+export declare function isArithmeticBody(body: string): boolean;
 /** What the shell does to a word (or an assignment's value) before the program sees it, read off its pieces. */
 export declare function expandsOf(w: {
     readonly pieces: readonly WordPiece[];

package/dist/tools/fs/shell-read-word.js

@@ -1,5 +1,5 @@
-import { argvOf, lexShell, literalTildeSpelling } from "../../shell/lex.js";
-import { expansionInWord, globInWord, homeExpansionOf } from "./bash-readonly-classifier.js";
+import { argvOf, lexShell, literalTildeSpelling, UNRESOLVED_SENTENCE } from "../../shell/lex.js";
+import { expansionInWord, extglobOpenerIn, globInWord, homeExpansionOf } from "./bash-readonly-classifier.js";
 export function readsOf(words, home) {
     return words.map((word) => {
         const spelled = home === undefined ? undefined : homeExpansionOf(word, home)?.spelled;
@@ -39,17 +39,52 @@ export function dropDefinitionHeads(tokens) {
             tokens.splice(k, 3);
     }
 }
+export function unreadableSentenceOf(lexed, text, globs = true) {
+    for (const segment of lexed.segments) {
+        for (const token of segment.tokens) {
+            const word = token.kind === "word" ? token : token.kind === "redirect" ? token.target : undefined;
+            if (word?.unresolved !== undefined)
+                return UNRESOLVED_SENTENCE[word.unresolved];
+        }
+    }
+    return globs && extglobOpenerIn(lexed, text) ? "an extended pattern (`?(…)` `*(…)` `+(…)` `@(…)` `!(…)`) is one this reader does not expand" : undefined;
+}
 export function compoundArrayElements(value) {
     const inner = /^\(([\s\S]*)\)$/.exec(value.raw)?.[1];
     const l = inner === undefined ? undefined : lexShell(inner);
     if (l === undefined || "parseFailure" in l)
         return [];
-    return l.segments.flatMap((sg) => argvOf(sg)).map((word) => {
-        const folded = word.folded.replace(/^\[[^\]]*\]\+?=/, "");
+    return l.segments.flatMap((sg) => argvOf(sg)).flatMap((element) => {
+        const sub = /^\[[^\]]*\]\+?=/.exec(element.raw)?.[0];
+        const value = sub === undefined ? undefined : readOfText(`V=${element.raw.slice(sub.length)}`).word.assignment?.value;
+        const word = value === undefined ? element : { ...element, raw: value.raw, folded: value.folded, pieces: value.pieces };
         const tilde = word.pieces.some((q) => q.expansion?.kind === "tilde");
-        return { word, raw: word.raw, folded: tilde ? folded : literalTildeSpelling(folded), expands: expandsOf(word) };
+        const read = { word, raw: word.raw, folded: tilde ? word.folded : literalTildeSpelling(word.folded), expands: expandsOf(word) };
+        const prefix = /^\[[^\]]*\]\+?=/.exec(element.folded)?.[0];
+        if (prefix === undefined)
+            return [read];
+        const spelled = element.pieces.some((q) => q.expansion?.kind === "tilde") ? element.folded.slice(prefix.length) : literalTildeSpelling(element.folded.slice(prefix.length));
+        return [read, { word: element, raw: element.raw, folded: spelled, expands: expandsOf(element), denyOnly: true }];
     });
 }
+export function isArithmeticBody(body) {
+    const l = body.startsWith("(") && body.endsWith(")") ? lexShell(body) : undefined;
+    if (l === undefined || "parseFailure" in l)
+        return false;
+    const tokens = l.segments.flatMap((sg) => sg.tokens);
+    if (tokens[0]?.kind !== "group" || tokens[0].op !== "(")
+        return false;
+    let depth = 0;
+    for (const [i, t] of tokens.entries()) {
+        if (t.kind !== "group")
+            continue;
+        if (t.op === "(")
+            depth++;
+        else if (--depth === 0)
+            return i === tokens.length - 1;
+    }
+    return false;
+}
 export function expandsOf(w) {
     if (expansionInWord(w) || /[`()]/.test(w.raw))
         return "unresolvable";

package/package.json

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

package/test/export-surface.snapshot.json

@@ -1,7 +1,7 @@
 {
   "_comment": "design/87 L3 — frozen public export surface of src/index.ts (name -> kind). DO NOT edit by hand to silence a red test. A removed/changed entry = a SemVer-BREAKING change; bump MAJOR and update this fixture in the SAME commit (design/87 §4.2 / §5.2). Regenerate via REGEN in test/export-surface.test.ts.",
   "_tierComment": "#435 v1 — machine-readable layering of the public surface: stable = demonstrated by README.md / src/examples; internal = an `Internal`-marked name or a runner/engine deep-subtree declaration (the model seam src/engine/llm is excluded — it is the BYOM contract, not an engine internal); advanced = a supported export the front door does not walk you through. THIS IS AN INITIAL HEURISTIC, derived mechanically and expected to be refined ticket by ticket: no human reviewed these 1700+ entries one by one, and nothing here claims otherwise. Known bias: a short or English-word export name (ok, err, Result, Usage) can match ordinary prose in README.md and land `stable` on a coincidence. Every export MUST carry a tier — a new export with no row fails the gate in export-surface.test.ts.",
-  "count": 2475,
+  "count": 2478,
   "exports": {
     "A2ATaskState": "type",
     "A2ATaskStateReversal": "type",
@@ -688,6 +688,7 @@
     "MEMORY_INSTRUCTION_TEMPLATE": "variable",
     "MEMORY_ORIGIN_CAUSES": "variable",
     "MEMORY_PREFERENCE_DISCIPLINE": "variable",
+    "MEMORY_PROJECT_KEY_ABSENT_REASONS": "variable",
     "MEMORY_READONLY_NOTICE": "variable",
     "MEMORY_RECALL_DISCIPLINE": "variable",
     "MEMORY_SAFETY": "variable",
@@ -769,6 +770,8 @@
     "MemoryNoteRecord": "interface",
     "MemoryNoteType": "type",
     "MemoryOriginCause": "type",
+    "MemoryProjectKey": "type",
+    "MemoryProjectKeyAbsentReason": "type",
     "MemoryProjectionError": "class",
     "MemoryPromptArtifactStore": "class",
     "MemoryPromptSourceStateStore": "class",
@@ -3165,6 +3168,7 @@
     "MEMORY_INSTRUCTION_TEMPLATE": "advanced",
     "MEMORY_ORIGIN_CAUSES": "advanced",
     "MEMORY_PREFERENCE_DISCIPLINE": "advanced",
+    "MEMORY_PROJECT_KEY_ABSENT_REASONS": "advanced",
     "MEMORY_READONLY_NOTICE": "advanced",
     "MEMORY_RECALL_DISCIPLINE": "advanced",
     "MEMORY_SAFETY": "advanced",
@@ -3246,6 +3250,8 @@
     "MemoryNoteRecord": "stable",
     "MemoryNoteType": "advanced",
     "MemoryOriginCause": "advanced",
+    "MemoryProjectKey": "advanced",
+    "MemoryProjectKeyAbsentReason": "advanced",
     "MemoryProjectionError": "advanced",
     "MemoryPromptArtifactStore": "advanced",
     "MemoryPromptSourceStateStore": "advanced",

package/wire-changes/core@7.30.1.json

@@ -0,0 +1,154 @@
+{
+  "repo": "core",
+  "version": "7.30.1",
+  "from": "3a100146dad04ac157def06e16d624fc8c1fe6a1",
+  "to": "v7.30.1",
+  "added": [],
+  "removed": [],
+  "changed": [],
+  "narrowed": [
+    {
+      "id": "F1",
+      "source": "behaviorFlips.summary",
+      "text": "NARROWING (#1064 ⑨, shell read boundary): an unquoted extended-glob opener (`?(` `*(` `+(` `@(` `!(`) in an argv word, a redirection target or a here-document delimiter makes the WHOLE text unestablishable — it joins the plan's `unreadable` floor, so both full-shell seats raise one MANDATED card, the read-only face and every headless face refuse, and a deny hit elsewhere in the same text still refuses outright. An `$((…))` arithmetic body keeps its reading only when the whole body is ONE complete parenthesised group, read off the lexer's structure (a quoted parenthesis is text) and followed across the segments the lexer cuts at `&&` `||` `&` `|` and line breaks; a quoted opener and a here-document body are the text they always were."
+    },
+    {
+      "id": "F2",
+      "source": "behaviorFlips.summary",
+      "text": "NARROWING (#1064 ⑬, shell read boundary; the CHANGELOG reads it as the repair of a 7.30.0 regression against 7.29.0 on the answered seats — 7.29.0 is not measured here): the declared-home spelling of an unplaced home word becomes a deny-only SHADOW candidate (`ReadCandidate.denyOnly`) established exactly as a read is — canonical target, a pattern's matches, a traversal root's tree — and judged for deny rows only; a bare `cd` / `cd --` puts the declared home on the deny floor; a `[k]=` compound element is read as the value bash assigns. The pre-spawn identity re-check compares each candidate's targets with its own re-establishment (keyed by plan position and candidate identity, deny-only reads their own class), and candidate de-duplication keys on `denyOnly`."
+    },
+    {
+      "id": "F3",
+      "source": "behaviorFlips.summary",
+      "text": "NARROWING (#1072, spawned-environment scrub): `SECRET_ENV_RE` reads `KEYS`, `TOKENS` and `PASSWORDS` as it reads their singulars, so `SERVICE_AUTH_TOKENS`, `API_KEYS`, `DB_PASSWORDS`, `GITHUB_TOKENS` no longer reach a tool's child shell; a `TOKENS` right after a count word (`TOKEN_COUNT_WORDS`: MAX OUTPUT INPUT THINKING NUM TOTAL) is a token count and is kept. The singular `TOKEN` and the exact-name exemptions keep their 7.30.0 reading."
+    },
+    {
+      "id": "F4",
+      "source": "behaviorFlips.summary",
+      "text": "NARROWING + additive option (#1073, language-server environment): `defaultLspSpawn` passes `scrubSecretEnv(process.env)` to `child_process.spawn` instead of no `env` at all, so a language server no longer inherits credential-shaped host variables; `NodeLspManagerOptions.env?` (new, optional) is the server's environment used VERBATIM by the manager's default spawn. A host-supplied `spawn` still owns its child's environment. The LSP scrub reports nothing (no findings collector)."
+    }
+  ],
+  "closedSetMembers": [],
+  "closedSetsUnreadable": [],
+  "typeKeys": [
+    {
+      "type": "NodeLspManagerOptions",
+      "at": [
+        "src/engine/lsp/node-lsp-manager.ts:76"
+      ],
+      "added": [
+        "env"
+      ],
+      "addedDetail": [
+        {
+          "key": "env",
+          "optional": true
+        }
+      ],
+      "addedRequired": [],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": true
+    },
+    {
+      "type": "ReadCandidate",
+      "at": [
+        "src/tools/fs/shell-read-plan.ts:104"
+      ],
+      "added": [
+        "denyOnly"
+      ],
+      "addedDetail": [
+        {
+          "key": "denyOnly",
+          "optional": true
+        }
+      ],
+      "addedRequired": [],
+      "removed": [],
+      "breaking": false,
+      "criteriaCovered": true
+    }
+  ],
+  "typeKeysUnreadableArms": [],
+  "typeKeysFlattenedCount": 215,
+  "declarationMoves": [],
+  "mintMoves": [],
+  "criteriaObserves": [
+    {
+      "kind": "taskEventField",
+      "name": "tool_end.gate",
+      "assertions": [
+        "G1.a",
+        "G1.b",
+        "G2.a"
+      ]
+    },
+    {
+      "kind": "taskEventField",
+      "name": "tool_end.isError",
+      "assertions": [
+        "G1.b",
+        "G3.a"
+      ]
+    },
+    {
+      "kind": "taskEventField",
+      "name": "tool_end.output",
+      "assertions": [
+        "G1.b",
+        "G2.a",
+        "G3.a",
+        "G4.a",
+        "G4.b"
+      ]
+    },
+    {
+      "kind": "taskEventField",
+      "name": "tool_end.structured",
+      "assertions": [
+        "G1.b",
+        "G2.a",
+        "G3.a"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "AskRequest.mandated",
+      "assertions": [
+        "G1.a",
+        "G2.b",
+        "G3.a"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "NodeLspManagerOptions.env",
+      "assertions": [
+        "G5.a",
+        "G5.b"
+      ]
+    },
+    {
+      "kind": "typeMember",
+      "name": "ReadCandidate.denyOnly",
+      "assertions": [
+        "G2.b",
+        "G3.b"
+      ]
+    }
+  ],
+  "consumersHint": {
+    "cli": [
+      "ReadCandidate"
+    ],
+    "server": [
+      "ReadCandidate"
+    ],
+    "sdk": [],
+    "note": "scanned cli@4e593722 server@fa3e0b9b sdk@350f64f — a name listed is MENTIONED there today, which is evidence of consumption, not proof of it. Ledger files (**/docs/core-consumption/**, **/docs/wire-consumption/**, **/*LEDGER*.json) are not evidence of use — server: 1 name(s) matched ONLY in bookkeeping files and were set aside (NodeLspManagerOptions)"
+  },
+  "breakingCount": 0,
+  "breakingItems": [],
+  "toResolvedAt": "0034a646af1de9c0cdd8ad7bd9b56234ec527c2c"
+}