@sema-agent/core 5.17.0 → 5.18.1

package/dist/core/permission-rule-store.js

@@ -0,0 +1,145 @@
+import { canonicalize } from "./canonical-json.js";
+import { isRuleLive } from "./permission-rule-model.js";
+export const PERMISSION_RULE_WRITER = "__semaPermissionRuleWriter";
+export function writerOf(store) {
+    const w = store[PERMISSION_RULE_WRITER];
+    return w !== undefined && typeof w.apply === "function" && typeof w.nextDot === "function" ? w : undefined;
+}
+export function sameScope(a, b) {
+    return a.kind === "global" ? b.kind === "global" : b.kind === "project" && a.root === b.root;
+}
+function sameDot(a, b) {
+    return a.actor === b.actor && a.counter === b.counter;
+}
+export function applyTombstones(rules, tombstones) {
+    return rules
+        .map((r) => {
+        const removed = tombstones.filter((t) => t.rule === r.rule && sameScope(t.scope, r.scope)).flatMap((t) => t.removedDots);
+        return removed.length === 0 ? r : { ...r, adds: r.adds.filter((a) => !removed.some((d) => sameDot(d, a.dot))) };
+    })
+        .filter(isRuleLive);
+}
+export function foldDelta(rules, delta) {
+    const next = rules.map((r) => ({ ...r, adds: [...r.adds] }));
+    const existing = next.find((r) => r.rule === delta.rule && sameScope(r.scope, delta.scope));
+    if (existing === undefined) {
+        next.push({ rule: delta.rule, tool: delta.tool, match: delta.match, command: delta.command, scope: delta.scope, adds: [delta.add] });
+        return next;
+    }
+    if (!existing.adds.some((a) => sameDot(a.dot, delta.add.dot)))
+        existing.adds.push(delta.add);
+    return next;
+}
+export function addDotsOf(rules) {
+    return rules.flatMap((r) => r.adds.map((a) => a.dot));
+}
+const ADD_ONLY_KEYS = ["add", "redemption", "rule", "command", "match", "tool"];
+export function assertDeleteDeltaCarriesNoAdd(delta) {
+    const smuggled = ADD_ONLY_KEYS.filter((k) => Object.hasOwn(delta, k));
+    if (smuggled.length > 0) {
+        throw new Error(`a tighten-delete may not introduce a new add (it carried: ${smuggled.join(", ")})`);
+    }
+    if (!Array.isArray(delta.tombstone?.removedDots) || delta.tombstone.removedDots.length === 0) {
+        throw new Error("a tighten-delete must carry a tombstone naming at least one observed add dot");
+    }
+}
+export async function ruleStoreChecksum(payload) {
+    const { createHash } = await import("node:crypto");
+    return `sha256:${createHash("sha256").update(canonicalize(payload), "utf8").digest("hex")}`;
+}
+const REMOVE_MAX_ATTEMPTS = 8;
+export async function removePersistedRule(opts) {
+    const store = opts.provider.forPrincipal(opts.principal);
+    const writer = writerOf(store);
+    if (writer === undefined) {
+        return { status: "failed", error: "the resolved permission-rule store has no write face — rules cannot be removed through it" };
+    }
+    let snapshot;
+    try {
+        snapshot = await store.list();
+    }
+    catch (err) {
+        return { status: "failed", error: `could not read the permission-rule store: ${errText(err)}` };
+    }
+    const live = snapshot.rules.filter((r) => r.rule === opts.rule && sameScope(r.scope, opts.scope));
+    const removedDots = live.flatMap((r) => r.adds.map((a) => a.dot));
+    if (removedDots.length === 0)
+        return { status: "no-op", rev: snapshot.rev };
+    const tombstone = { rule: opts.rule, scope: opts.scope, removedDots, deletedBy: await writer.nextDot() };
+    let expectedRev = snapshot.rev;
+    let lastError = "";
+    for (let attempt = 0; attempt < REMOVE_MAX_ATTEMPTS; attempt++) {
+        try {
+            const res = await writer.apply({ kind: "tighten-delete", tombstone }, { expectedRev });
+            if (!("conflict" in res)) {
+                let stillLive = false;
+                try {
+                    const after = await store.list();
+                    stillLive = after.rules.some((r) => r.rule === opts.rule && sameScope(r.scope, opts.scope) && isRuleLive(r));
+                }
+                catch {
+                    stillLive = false;
+                }
+                return { status: "removed", rev: res.rev, stillLive };
+            }
+            expectedRev = res.rev;
+        }
+        catch (err) {
+            lastError = errText(err);
+            break;
+        }
+    }
+    const reason = lastError !== "" ? lastError : `optimistic-concurrency retries exhausted after ${REMOVE_MAX_ATTEMPTS} attempts`;
+    try {
+        const after = await store.list();
+        const landed = after.tombstones.some((t) => t.deletedBy.actor === tombstone.deletedBy.actor && t.deletedBy.counter === tombstone.deletedBy.counter);
+        return landed
+            ? { status: "removed", rev: after.rev, stillLive: after.rules.some((r) => r.rule === opts.rule && sameScope(r.scope, opts.scope) && isRuleLive(r)) }
+            : { status: "failed", error: `${reason} (read-back confirms no tombstone was written)` };
+    }
+    catch (err) {
+        return { status: "failed", error: `${reason}; the read-back also failed (${errText(err)}) so this outcome is indeterminate — reconcile with list()` };
+    }
+}
+export function errText(err) {
+    return err instanceof Error ? err.message : String(err);
+}
+export const EMPTY_RULE_STORE = {
+    list: async () => ({ rules: [], tombstones: [], rev: 0 }),
+    durability: "process-local",
+};
+export class InMemoryPermissionRuleStore {
+    actor;
+    durability = "process-local";
+    fidelity = "structured-clone";
+    rules = [];
+    tombstones = [];
+    rev = 0;
+    counter = 0;
+    constructor(actor = `mem-${Math.random().toString(36).slice(2, 10)}`) {
+        this.actor = actor;
+    }
+    async list() {
+        return {
+            rules: applyTombstones(this.rules, this.tombstones).map((r) => ({ ...r, adds: r.adds.map((a) => ({ ...a })) })),
+            tombstones: this.tombstones.map((t) => ({ ...t })),
+            rev: this.rev,
+        };
+    }
+    [PERMISSION_RULE_WRITER] = {
+        nextDot: async () => ({ actor: this.actor, counter: ++this.counter }),
+        apply: async (delta, opts) => {
+            if (opts.expectedRev !== this.rev)
+                return { conflict: true, rev: this.rev };
+            if (delta.kind === "redemption-add") {
+                this.rules = foldDelta(this.rules, delta);
+            }
+            else {
+                assertDeleteDeltaCarriesNoAdd(delta);
+                this.tombstones = [...this.tombstones, delta.tombstone];
+            }
+            this.rev += 1;
+            return { rev: this.rev };
+        },
+    };
+}

package/dist/core/permission-rules.d.ts

@@ -11,7 +11,7 @@ export interface ParsedPermissionRule {
 }
 export interface PermissionRuleIssue {
     rule: string;
-    code: "invalid.empty_tool" | "invalid.paren" | "invalid.param_split" | "invalid.allow_param_rule" | "invalid.primary_field" | "invalid.cap_exceeded" | "unsupported.bash_prefix" | "unsupported.file_glob" | "unsupported.mcp_paren" | "unsupported.unknown_param";
+    code: "invalid.empty_tool" | "invalid.paren" | "invalid.param_split" | "invalid.allow_param_rule" | "invalid.primary_field" | "invalid.cap_exceeded" | "unsupported.bash_prefix" | "unsupported.bash_prefix_rules_store" | "unsupported.file_glob" | "unsupported.mcp_paren" | "unsupported.unknown_param";
     message: string;
 }
 export interface PermissionRuleCaps {
@@ -26,10 +26,11 @@ export interface PermissionRulePolicyOptions {
     onIssue?: (issue: PermissionRuleIssue) => void;
     defaultAction?: "allow" | "ask" | "deny";
     primaryFieldGeneric?: "reject" | "allow-lexical";
+    bashPrefixLane?: "reject" | "rules-store";
     caps?: Partial<PermissionRuleCaps>;
 }
 export declare function parsePermissionRule(rule: string): ParsedPermissionRule;
 export declare function wildcardMatch(pattern: string, value: string): boolean;
 export declare const fileToolParamVocabulary: (canonicalTool: string) => ReadonlySet<string> | undefined;
-export declare function validatePermissionRules(rules: PermissionRule[], opts?: Pick<PermissionRulePolicyOptions, "primaryFieldGeneric" | "caps">): PermissionRuleIssue[];
+export declare function validatePermissionRules(rules: PermissionRule[], opts?: Pick<PermissionRulePolicyOptions, "primaryFieldGeneric" | "caps" | "bashPrefixLane">): PermissionRuleIssue[];
 export declare function createPermissionRulePolicy(rules: PermissionRule[], opts?: PermissionRulePolicyOptions): NamedToolPolicy;

package/dist/core/permission-rules.js

@@ -109,7 +109,7 @@ function countStars(s) {
             n++;
     return n;
 }
-function compile(rules, caps, primaryFieldGeneric) {
+function compile(rules, caps, primaryFieldGeneric, bashPrefixLane = "reject") {
     const byTool = new Map();
     const issues = [];
     const bad = (rule, code, message) => {
@@ -159,7 +159,12 @@ function compile(rules, caps, primaryFieldGeneric) {
             const paramPart = colon > 0 ? content.slice(0, colon).trim() : "";
             const looksLikeParamRule = colon > 0 && /^[A-Za-z_][A-Za-z0-9_]*$/.test(paramPart) && BASH_GENERIC_PARAMS.has(paramPart);
             if (!looksLikeParamRule || content.endsWith(":*")) {
-                bad(text, "unsupported.bash_prefix", "Bash prefix/legacy rules (`Bash(npm run:*)`, `Bash(git *)`) are the tool-specific lane — not supported by the generic param DSL (use createCoarseCommandNamePolicy or a dedicated batch)");
+                if (bashPrefixLane === "rules-store") {
+                    bad(text, "unsupported.bash_prefix_rules_store", "Bash prefix rules (`Bash(npm run:*)`, `Bash(git *)`) belong to the persisted allow-rule lane this deployment declared — not to the generic param DSL; the rule is not compiled here");
+                }
+                else {
+                    bad(text, "unsupported.bash_prefix", "Bash prefix/legacy rules (`Bash(npm run:*)`, `Bash(git *)`) are the tool-specific lane — not supported by the generic param DSL (use createCoarseCommandNamePolicy or a dedicated batch)");
+                }
                 continue;
             }
         }
@@ -205,7 +210,7 @@ function compile(rules, caps, primaryFieldGeneric) {
 }
 export function validatePermissionRules(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
-    return compile(rules, caps, opts?.primaryFieldGeneric ?? "reject").issues;
+    return compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject").issues;
 }
 function isPlainObjectArgs(args) {
     return typeof args === "object" && args !== null && !Array.isArray(args);
@@ -235,7 +240,7 @@ function ruleMessage(kind, ruleText, source) {
 }
 export function createPermissionRulePolicy(rules, opts) {
     const caps = { ...DEFAULT_CAPS, ...opts?.caps };
-    const { byTool, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject");
+    const { byTool, issues } = compile(rules, caps, opts?.primaryFieldGeneric ?? "reject", opts?.bashPrefixLane ?? "reject");
     const setLevelCap = issues.some((i) => i.code === "invalid.cap_exceeded" && i.rule === "");
     if (issues.length > 0 && ((opts?.onInvalidRule ?? "throw") === "throw" || setLevelCap)) {
         const e = new Error(`createPermissionRulePolicy: ${issues.length} invalid/unsupported rule(s):\n` +

package/dist/core/runner/prepare-memory.d.ts

@@ -1,4 +1,4 @@
-import type { BeforeWriteHook, RunnerDeps, TaskSpec } from "../types.js";
+import type { BeforeWriteHook, RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
 import type { Prepared } from "./prepare-task.js";
 export interface PrepareMemoryInput {
     spec: TaskSpec;
@@ -9,6 +9,7 @@ export interface PrepareMemoryInput {
         current?: BeforeWriteHook;
     };
     writeToolsMounted: boolean;
+    memorySearchToolsPlanned: boolean;
     admissionCtx: {
         orgMemoryDenied: boolean;
         complianceDegraded: boolean;
@@ -20,6 +21,7 @@ export interface PrepareMemoryInput {
 export interface PrepareMemoryResult {
     memoryEngineSession: Prepared["memoryEngineSession"];
     memoryBlock: string | undefined;
+    memoryTools?: ToolSpec[];
     seedFiles?: ReadonlyArray<{
         path: string;
         content: string;

package/dist/core/runner/prepare-memory.js

@@ -2,7 +2,8 @@ import { admitMemoryScopes } from "../memory-admission.js";
 import { adoptLegacyRepoDirs, deriveRepoControlPlaneDir, deriveProjectControlDir, deriveProjectMemoryDir, deriveRepoMemoryDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, lookupProjectIdHint, recordProjectIdHint, resolveMemoryEngineRoot } from "../memory-engine/layout.js";
 import { classifyScopePlanes, derivePersonalControlDir, derivePersonalMemoryDir, mergeHarvestReports, mergeInjections, needsDualRoots, parsedProjectPlane } from "../memory-engine/dual-root.js";
 import { normalizeMemorySpec } from "../memory.js";
-import { MemoryEngine } from "../memory-engine/engine.js";
+import { MEMORY_RECALL_DISCIPLINE, MemoryEngine } from "../memory-engine/engine.js";
+import { createMemoryEngineTools } from "../memory-engine/tools.js";
 import { assertScopeContractPlacement, parseScopeKey, resolveProjectId } from "../memory-engine/scope-contract.js";
 import { FileMemoryEngineBackend } from "../memory-engine/file-backend.js";
 export async function prepareMemory(input) {
@@ -35,6 +36,7 @@ export async function prepareMemory(input) {
     }
     const useMemoryEngine = Boolean(memorySpec && memorySpec.enabled && deps.memoryBackend);
     let memoryEngineSession;
+    let memoryTools;
     if (useMemoryEngine && memorySpec) {
         try {
             const backend = deps.memoryBackend;
@@ -111,24 +113,36 @@ export async function prepareMemory(input) {
             }
             const personalMemoryDir = derivePersonalMemoryDir(engineRoot);
             const personalControlDir = derivePersonalControlDir(engineRoot);
-            const createPersonalEngine = () => new MemoryEngine({
-                backend: typeof pinned === "string" && pinned
+            const createPersonalEngine = () => {
+                const personalBackend = typeof pinned === "string" && pinned
                     ? new FileMemoryEngineBackend(personalMemoryDir, { controlDir: personalControlDir })
-                    : backend,
-                memoryDir: personalMemoryDir,
-                controlDir: personalControlDir,
-            });
+                    : backend;
+                return {
+                    engine: new MemoryEngine({ backend: personalBackend, memoryDir: personalMemoryDir, controlDir: personalControlDir, onIncident: onEngineIncident }),
+                    backend: personalBackend,
+                };
+            };
+            const onEngineIncident = (err) => deps.onError?.(err, { phase: "memory", sessionId });
+            const retrievalBackend = (b) => b.retrievalView?.() ?? b;
+            const planeScopes = (scopes, write) => [...new Set([...scopes, ...(write !== null ? [write] : [])])];
+            const pollutedOpts = (engine) => {
+                const rec = engine.sessionPollution(sessionId);
+                return rec !== undefined ? { polluted: { reason: rec.reason } } : {};
+            };
             let writeEngine;
             let writeHandle;
             let injectFn;
             let harvestBoth;
+            let toolPlanes;
             if (dual) {
                 const projectEngine = new MemoryEngine({
                     backend,
                     memoryDir,
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
+                    onIncident: onEngineIncident,
                 });
-                const personalEngine = createPersonalEngine();
+                const personal = createPersonalEngine();
+                const personalEngine = personal.engine;
                 const p = planes;
                 const projectHandle = await projectEngine.materialize(p.project, p.writePlane === "project" ? memorySpec.writeScope : null);
                 const personalHandle = await personalEngine.materialize(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null);
@@ -136,10 +150,14 @@ export async function prepareMemory(input) {
                 writeEngine = writeIsPersonal ? personalEngine : projectEngine;
                 writeHandle = writeIsPersonal ? personalHandle : projectHandle;
                 injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: input.writeToolsMounted }), personalEngine.inject(personalHandle, { writeToolMounted: input.writeToolsMounted }));
+                toolPlanes = [
+                    { backend: retrievalBackend(backend), scopes: planeScopes(p.project, p.writePlane === "project" ? memorySpec.writeScope : null), recordRetrieved: (ids) => projectEngine.recordRetrieved(ids) },
+                    { backend: retrievalBackend(personal.backend), scopes: planeScopes(p.personal, p.writePlane === "personal" ? memorySpec.writeScope : null), recordRetrieved: (ids) => personalEngine.recordRetrieved(ids) },
+                ];
                 harvestBoth = async () => {
                     const writeFirst = writeIsPersonal ? [personalEngine, personalHandle] : [projectEngine, projectHandle];
                     const readOther = writeIsPersonal ? [projectEngine, projectHandle] : [personalEngine, personalHandle];
-                    const writeReport = await writeFirst[0].harvest(writeFirst[1]);
+                    const writeReport = await writeFirst[0].harvest(writeFirst[1], pollutedOpts(writeFirst[0]));
                     let readReport;
                     let readFailure;
                     try {
@@ -155,24 +173,28 @@ export async function prepareMemory(input) {
                 };
             }
             else if (personalOnly) {
-                const personalEngine = createPersonalEngine();
+                const personal = createPersonalEngine();
+                const personalEngine = personal.engine;
                 const handle = await personalEngine.materialize(memorySpec.scopes, memorySpec.writeScope);
                 writeEngine = personalEngine;
                 writeHandle = handle;
                 injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted });
-                harvestBoth = () => personalEngine.harvest(handle);
+                harvestBoth = () => personalEngine.harvest(handle, pollutedOpts(personalEngine));
+                toolPlanes = [{ backend: retrievalBackend(personal.backend), scopes: planeScopes(memorySpec.scopes, memorySpec.writeScope), recordRetrieved: (ids) => personalEngine.recordRetrieved(ids) }];
             }
             else {
                 const engine = new MemoryEngine({
                     backend,
                     memoryDir,
                     controlDir: identityKey !== undefined ? deriveProjectControlDir(engineRoot, identityKey) : deriveRepoControlPlaneDir(engineRoot, repoRoot),
+                    onIncident: onEngineIncident,
                 });
                 const handle = await engine.materialize(memorySpec.scopes, memorySpec.writeScope);
                 writeEngine = engine;
                 writeHandle = handle;
                 injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted });
-                harvestBoth = () => engine.harvest(handle);
+                harvestBoth = () => engine.harvest(handle, pollutedOpts(engine));
+                toolPlanes = [{ backend: retrievalBackend(backend), scopes: planeScopes(memorySpec.scopes, memorySpec.writeScope), recordRetrieved: (ids) => engine.recordRetrieved(ids) }];
             }
             memoryWriteGateRef.current = (w) => writeEngine.gateWrite(writeHandle, w.key, w.content);
             const harvestSafe = async (phase = "terminal") => {
@@ -197,7 +219,22 @@ export async function prepareMemory(input) {
                     return undefined;
                 }
             };
-            memoryEngineSession = { engine: writeEngine, handle: writeHandle, inject: injectFn, harvest: harvestSafe };
+            memoryEngineSession = {
+                engine: writeEngine,
+                handle: writeHandle,
+                inject: injectFn,
+                harvest: harvestSafe,
+                pollution: {
+                    polluted: () => writeEngine.sessionPollution(sessionId),
+                    markPolluted: (reason) => writeEngine.markSessionPolluted(sessionId, reason),
+                },
+                contentSafety: {
+                    trustedTools: new Set(memorySpec.trustedTools ?? []),
+                    execIsExternalContent: memorySpec.execIsExternalContent === true,
+                },
+            };
+            if (input.memorySearchToolsPlanned)
+                memoryTools = createMemoryEngineTools({ planes: toolPlanes });
         }
         catch (err) {
             if (typeof err.code === "string" && (err.code.startsWith("config.memory_scope") || err.code.startsWith("config.memory_project"))) {
@@ -216,8 +253,11 @@ export async function prepareMemory(input) {
         const injection = memoryEngineSession.inject();
         if (injection.block.trim())
             memoryBlock = injection.block;
+        if (memoryTools !== undefined) {
+            memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_RECALL_DISCIPLINE}` : MEMORY_RECALL_DISCIPLINE;
+        }
         if (memoryBlock !== undefined && injection.indexSeed !== undefined)
             seedFiles = [injection.indexSeed];
     }
-    return { memoryEngineSession, memoryBlock, admittedOrgScopes, ownOrgVerdict, ...(seedFiles !== undefined ? { seedFiles } : {}) };
+    return { memoryEngineSession, memoryBlock, admittedOrgScopes, ownOrgVerdict, ...(memoryTools !== undefined ? { memoryTools } : {}), ...(seedFiles !== undefined ? { seedFiles } : {}) };
 }

package/dist/core/runner/prepare-task.d.ts

@@ -64,6 +64,7 @@ export interface Prepared {
         hit: boolean;
     };
     blockedToolCalls: Set<string>;
+    approvalSettledBy: Map<string, import("../tool-policy.js").ApprovalSettledBy>;
     nestedStats: NestedUsageAccum;
     rewindNotes?: NonNullable<TaskResult["rewindNotes"]>;
     cwdRef?: CwdRef;
@@ -134,6 +135,17 @@ export interface Prepared {
         handle: MemorySessionHandle;
         inject: () => import("../memory-engine/engine.js").MemoryInjection;
         harvest: (phase?: "checkpoint" | "terminal") => Promise<HarvestReport | undefined>;
+        pollution: {
+            polluted: () => {
+                at: number;
+                reason: string;
+            } | undefined;
+            markPolluted: (reason: string) => void;
+        };
+        contentSafety: {
+            trustedTools: ReadonlySet<string>;
+            execIsExternalContent: boolean;
+        };
     };
     ownedEnv?: ExecutionEnv;
     suspendRef: {