@namzu/sdk 27.1.0 → 28.0.0

package/dist/agents/handle.js

@@ -0,0 +1,79 @@
+import { NamzuError } from '../types/errors/index.js';
+/** A steer aimed at an agent that is not running. */
+export class AgentNotRunningError extends NamzuError {
+    constructor() {
+        super({
+            code: 'invalid_config',
+            message: 'steer() needs a run in flight — this agent is idle. Use queueForNextRun() to leave a message for the next one.',
+            details: {},
+            retryable: false,
+        });
+        this.name = 'AgentNotRunningError';
+    }
+}
+/**
+ * A host's handle on one agent.
+ *
+ * `status` is a function call rather than a stored boolean, because a
+ * stored one is only as current as whoever remembered to update it — and
+ * the whole value of this object is answering a question at the moment it
+ * is asked.
+ */
+export function createAgentHandle(options) {
+    return {
+        get status() {
+            return options.isRunning() ? 'running' : 'idle';
+        },
+        steer(text) {
+            // Refused, not rerouted. Quietly forwarding to `queueForNextRun`
+            // would be a host asking to redirect what is happening now and
+            // getting a message delivered minutes later to a different run —
+            // which is worse than an error, because nothing says it happened.
+            if (!options.isRunning())
+                throw new AgentNotRunningError();
+            options.steering.steer(text);
+        },
+        async queueForNextRun(message) {
+            if (!options.topicStateStore) {
+                throw new NamzuError({
+                    code: 'invalid_config',
+                    message: 'queueForNextRun() needs a topic state store; this handle was built without one, so there is nowhere to leave the message.',
+                    details: { topicId: options.topicId },
+                    retryable: false,
+                });
+            }
+            await appendQueuedMessage(options.topicStateStore, options.topicId, options.tenantId, message);
+        },
+    };
+}
+/**
+ * Add a message to the topic's next-run queue, under compare-and-set.
+ *
+ * Read-modify-write against the record's revision, so two hosts queueing
+ * for one conversation cannot silently drop each other's message — the
+ * loser gets the store's stale-revision error and can retry with what it
+ * now sees.
+ */
+export async function appendQueuedMessage(store, topicId, tenantId, message) {
+    const state = await store.getState(topicId, tenantId);
+    await store.setQueuedMessages(topicId, tenantId, [...(state?.queuedMessages ?? []), message], {
+        revision: state?.revision ?? 0,
+    });
+}
+/**
+ * Take whatever was queued for this topic, leaving the queue empty.
+ *
+ * Cleared as it is read, in the same compare-and-set write. A queue that
+ * was read and cleared separately would re-deliver on a crash between the
+ * two, and "start with this" arriving twice is a different instruction from
+ * the one that was left.
+ */
+export async function drainQueuedMessages(store, topicId, tenantId) {
+    const state = await store.getState(topicId, tenantId);
+    const queued = state?.queuedMessages ?? [];
+    if (queued.length === 0)
+        return [];
+    await store.setQueuedMessages(topicId, tenantId, [], { revision: state?.revision ?? 0 });
+    return queued;
+}
+//# sourceMappingURL=handle.js.map

package/dist/agents/handle.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handle.js","sourceRoot":"","sources":["../../src/agents/handle.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAgCrD,qDAAqD;AACrD,MAAM,OAAO,oBAAqB,SAAQ,UAAU;IACnD;QACC,KAAK,CAAC;YACL,IAAI,EAAE,gBAAgB;YACtB,OAAO,EACN,gHAAgH;YACjH,OAAO,EAAE,EAAE;YACX,SAAS,EAAE,KAAK;SAChB,CAAC,CAAA;QACF,IAAI,CAAC,IAAI,GAAG,sBAAsB,CAAA;IACnC,CAAC;CACD;AA0BD;;;;;;;GAOG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAA2B;IAC5D,OAAO;QACN,IAAI,MAAM;YACT,OAAO,OAAO,CAAC,SAAS,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,MAAM,CAAA;QAChD,CAAC;QAED,KAAK,CAAC,IAAY;YACjB,iEAAiE;YACjE,+DAA+D;YAC/D,iEAAiE;YACjE,kEAAkE;YAClE,IAAI,CAAC,OAAO,CAAC,SAAS,EAAE;gBAAE,MAAM,IAAI,oBAAoB,EAAE,CAAA;YAC1D,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAA;QAC7B,CAAC;QAED,KAAK,CAAC,eAAe,CAAC,OAAgB;YACrC,IAAI,CAAC,OAAO,CAAC,eAAe,EAAE,CAAC;gBAC9B,MAAM,IAAI,UAAU,CAAC;oBACpB,IAAI,EAAE,gBAAgB;oBACtB,OAAO,EACN,2HAA2H;oBAC5H,OAAO,EAAE,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE;oBACrC,SAAS,EAAE,KAAK;iBAChB,CAAC,CAAA;YACH,CAAC;YACD,MAAM,mBAAmB,CAAC,OAAO,CAAC,eAAe,EAAE,OAAO,CAAC,OAAO,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAA;QAC/F,CAAC;KACD,CAAA;AACF,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,KAAsB,EACtB,OAAgB,EAChB,QAAkB,EAClB,OAAgB;IAEhB,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IACrD,MAAM,KAAK,CAAC,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,CAAC,GAAG,CAAC,KAAK,EAAE,cAAc,IAAI,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE;QAC7F,QAAQ,EAAE,KAAK,EAAE,QAAQ,IAAI,CAAC;KAC9B,CAAC,CAAA;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CACxC,KAAsB,EACtB,OAAgB,EAChB,QAAkB;IAElB,MAAM,KAAK,GAAG,MAAM,KAAK,CAAC,QAAQ,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAA;IACrD,MAAM,MAAM,GAAG,KAAK,EAAE,cAAc,IAAI,EAAE,CAAA;IAC1C,IAAI,MAAM,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAA;IAClC,MAAM,KAAK,CAAC,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,EAAE,EAAE,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,IAAI,CAAC,EAAE,CAAC,CAAA;IACxF,OAAO,MAAM,CAAA;AACd,CAAC"}

package/dist/agents/runAgent.d.ts

@@ -1,11 +1,11 @@
-import type { ProjectId, SessionId, TenantId, ThreadId } from '../types/ids/index.js';
+import type { AuthorizationGateConfig } from '../types/authorization/index.js';
+import type { ProjectId, SessionId, TenantId, TopicId } from '../types/ids/index.js';
 import type { Message } from '../types/message/index.js';
 import type { LLMProvider, ReasoningEffort, ThinkingConfig } from '../types/provider/index.js';
 import type { Run, RunEventListener } from '../types/run/index.js';
 import type { Skill } from '../types/skills/index.js';
 import type { StructuredOutputConfig } from '../types/structured-output/index.js';
 import type { ToolRegistryContract } from '../types/tool/index.js';
-import type { VerificationGateConfig } from '../types/verification/index.js';
 /**
  * The session a run belongs to.
  *
@@ -26,7 +26,7 @@ import type { VerificationGateConfig } from '../types/verification/index.js';
  */
 export interface AgentIdentity {
     sessionId?: SessionId;
-    threadId?: ThreadId;
+    topicId?: TopicId;
     projectId?: ProjectId;
     tenantId?: TenantId;
 }
@@ -63,11 +63,16 @@ export interface RunAgentOptions extends AgentIdentity {
      *
      * Absent means every tool runs unreviewed, which is the right default for a
      * library front door and the wrong one for a host that hands this an agent
-     * directory it did not write. The kernel builds a `VerificationGate` from
+     * directory it did not write. The kernel builds a `AuthorizationGate` from
      * this and consults it on every call; without it there is nothing to
      * consult, so a front-door run is strictly less mediated than a kernel one.
      */
-    verificationGate?: VerificationGateConfig;
+    /**
+     * @deprecated Renamed to `authorizationGate`. Removed in the next major.
+     * Setting both to different configs throws.
+     */
+    verificationGate?: AuthorizationGateConfig;
+    authorizationGate?: AuthorizationGateConfig;
     /** Defaults to the current working directory. */
     workingDirectory?: string;
     maxIterations?: number;

package/dist/agents/runAgent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"runAgent.d.ts","sourceRoot":"","sources":["../../src/agents/runAgent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,uBAAuB,CAAA;AACrF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC9F,OAAO,KAAK,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAA;AACjF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAClE,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gCAAgC,CAAA;AAQ5E;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAA;IACnB,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACnB;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACrD,gEAAgE;IAChE,QAAQ,EAAE,WAAW,CAAA;IAErB,kEAAkE;IAClE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAAA;IAE1B,yBAAyB;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb,KAAK,CAAC,EAAE,oBAAoB,CAAA;IAE5B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,KAAK,EAAE,CAAA;IAEhB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAA;IAEzC,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAA;IAEzC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,MAAM,CAAC,EAAE,eAAe,CAAA;IAExB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAEnC;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAEnC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IAEjB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAA;CAC1C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAA;AACxC,eAAO,MAAM,oBAAoB,SAAU,CAAA;AAC3C,eAAO,MAAM,kBAAkB,SAAU,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA8ChF"}
+{"version":3,"file":"runAgent.d.ts","sourceRoot":"","sources":["../../src/agents/runAgent.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AAC9E,OAAO,KAAK,EAAE,SAAS,EAAE,SAAS,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,uBAAuB,CAAA;AACpF,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,2BAA2B,CAAA;AACxD,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,4BAA4B,CAAA;AAC9F,OAAO,KAAK,EAAE,GAAG,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAA;AAClE,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,0BAA0B,CAAA;AACrD,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,qCAAqC,CAAA;AACjF,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,wBAAwB,CAAA;AAQlE;;;;;;;;;;;;;;;;;GAiBG;AACH,MAAM,WAAW,aAAa;IAC7B,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB,SAAS,CAAC,EAAE,SAAS,CAAA;IACrB,QAAQ,CAAC,EAAE,QAAQ,CAAA;CACnB;AAED,MAAM,WAAW,eAAgB,SAAQ,aAAa;IACrD,gEAAgE;IAChE,QAAQ,EAAE,WAAW,CAAA;IAErB,kEAAkE;IAClE,MAAM,EAAE,MAAM,GAAG,OAAO,EAAE,CAAA;IAE1B,yBAAyB;IACzB,YAAY,CAAC,EAAE,MAAM,CAAA;IAErB;;;;;;;;OAQG;IACH,KAAK,EAAE,MAAM,CAAA;IAEb,KAAK,CAAC,EAAE,oBAAoB,CAAA;IAE5B;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,KAAK,EAAE,CAAA;IAEhB;;;;;;;;OAQG;IACH;;;OAGG;IACH,gBAAgB,CAAC,EAAE,uBAAuB,CAAA;IAE1C,iBAAiB,CAAC,EAAE,uBAAuB,CAAA;IAE3C,iDAAiD;IACjD,gBAAgB,CAAC,EAAE,MAAM,CAAA;IAEzB,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,WAAW,CAAC,EAAE,MAAM,CAAA;IAEpB;;;;;;;;OAQG;IACH,gBAAgB,CAAC,EAAE,sBAAsB,CAAA;IAEzC;;;;;;;;;;;;;;;OAeG;IACH,QAAQ,CAAC,EAAE,cAAc,CAAA;IACzB,MAAM,CAAC,EAAE,eAAe,CAAA;IAExB,iEAAiE;IACjE,IAAI,CAAC,EAAE,MAAM,CAAA;IAEb,MAAM,CAAC,EAAE,WAAW,CAAA;IACpB,QAAQ,CAAC,EAAE,gBAAgB,CAAA;CAC3B;AAED,MAAM,WAAW,cAAc;IAC9B,kEAAkE;IAClE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;IAEnC;;;;;;;OAOG;IACH,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAEnC,qEAAqE;IACrE,QAAQ,CAAC,GAAG,EAAE,GAAG,CAAA;IAEjB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC,aAAa,CAAC,CAAA;CAC1C;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,sBAAsB,KAAK,CAAA;AACxC,eAAO,MAAM,oBAAoB,SAAU,CAAA;AAC3C,eAAO,MAAM,kBAAkB,SAAU,CAAA;AAEzC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAsB,QAAQ,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CA+ChF"}

package/dist/agents/runAgent.js

@@ -1,6 +1,6 @@
 import { ToolRegistry } from '../registry/tool/execute.js';
 import { drainQuery } from '../runtime/query/index.js';
-import { generateProjectId, generateSessionId, generateTenantId, generateThreadId, } from '../utils/id.js';
+import { generateProjectId, generateSessionId, generateTenantId, generateTopicId, } from '../utils/id.js';
 /**
  * Defaults chosen to be safe rather than generous.
  *
@@ -57,7 +57,7 @@ export const DEFAULT_TIMEOUT_MS = 300_000;
 export async function runAgent(options) {
     const identity = {
         sessionId: options.sessionId ?? generateSessionId(),
-        threadId: options.threadId ?? generateThreadId(),
+        topicId: options.topicId ?? generateTopicId(),
         projectId: options.projectId ?? generateProjectId(),
         tenantId: options.tenantId ?? generateTenantId(),
     };
@@ -89,6 +89,7 @@ export async function runAgent(options) {
         ...(options.signal ? { signal: options.signal } : {}),
         ...(options.skills ? { skills: options.skills } : {}),
         ...(options.verificationGate ? { verificationGate: options.verificationGate } : {}),
+        ...(options.authorizationGate ? { authorizationGate: options.authorizationGate } : {}),
         ...(options.structuredOutput ? { structuredOutput: options.structuredOutput } : {}),
         ...identity,
     }, options.listener);

package/dist/agents/runAgent.js.map

@@ -1 +1 @@
-{"version":3,"file":"runAgent.js","sourceRoot":"","sources":["../../src/agents/runAgent.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"runAgent.js","sourceRoot":"","sources":["../../src/agents/runAgent.ts"],"names":[],"mappings":"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"}

package/dist/{verification → authorization}/gate.d.ts

@@ -1,5 +1,5 @@
+import type { AuthorizationGateConfig, AuthorizationRule, GateEvaluationResult } from '../types/authorization/index.js';
 import type { ToolDefinition } from '../types/tool/index.js';
-import type { GateEvaluationResult, VerificationGateConfig, VerificationRule } from '../types/verification/index.js';
 import type { Logger } from '../utils/logger.js';
 export interface ToolCallContext {
     readonly toolName: string;
@@ -21,15 +21,15 @@ export interface ToolCallContext {
  * cannot be reasoned about produces thrashing; one that can produces a route
  * around it.
  */
-export declare function describeRule(rule: VerificationRule): string;
-export declare class VerificationGate {
+export declare function describeRule(rule: AuthorizationRule): string;
+export declare class AuthorizationGate {
     private readonly rules;
     private readonly compiledPatterns;
     private readonly nameSets;
     private readonly log;
     private readonly logDecisions;
     private readonly enabled;
-    constructor(config: VerificationGateConfig, log: Logger);
+    constructor(config: AuthorizationGateConfig, log: Logger);
     evaluate(ctx: ToolCallContext): GateEvaluationResult;
 }
 //# sourceMappingURL=gate.d.ts.map

package/dist/authorization/gate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.d.ts","sourceRoot":"","sources":["../../src/authorization/gate.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACX,uBAAuB,EACvB,iBAAiB,EACjB,oBAAoB,EACpB,MAAM,iCAAiC,CAAA;AAExC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,wBAAwB,CAAA;AAE5D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAA;AAGhD,MAAM,WAAW,eAAe;IAC/B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;IACzB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAA;IAC3B,QAAQ,CAAC,OAAO,EAAE,cAAc,GAAG,SAAS,CAAA;CAC5C;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CAgC5D;AAED,qBAAa,iBAAiB;IAC7B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAqB;IAC3C,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAqB;IACtD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA0B;IACnD,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAQ;IAC5B,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;gBAErB,MAAM,EAAE,uBAAuB,EAAE,GAAG,EAAE,MAAM;IAiHxD,QAAQ,CAAC,GAAG,EAAE,eAAe,GAAG,oBAAoB;CAwDpD"}

package/dist/{verification → authorization}/gate.js

@@ -1,5 +1,7 @@
-import { MAX_CUSTOM_PATTERN_LENGTH } from '../constants/verification/index.js';
-import { VerificationGateConfigSchema } from '../types/verification/index.js';
+import { MAX_CUSTOM_PATTERN_LENGTH } from '../constants/authorization/index.js';
+import { GENAI } from '../constants/telemetry/index.js';
+import { AuthorizationGateConfigSchema } from '../types/authorization/index.js';
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js';
 import { evaluateRule } from './rules.js';
 /**
  * What the rule actually said, in words a model can act on.
@@ -48,7 +50,7 @@ export function describeRule(rule) {
         }
     }
 }
-export class VerificationGate {
+export class AuthorizationGate {
     rules;
     compiledPatterns;
     nameSets;
@@ -56,8 +58,8 @@ export class VerificationGate {
     logDecisions;
     enabled;
     constructor(config, log) {
-        const parsed = VerificationGateConfigSchema.parse(config);
-        this.log = log.child({ component: 'VerificationGate' });
+        const parsed = AuthorizationGateConfigSchema.parse(config);
+        this.log = log.child({ [SCOPE_ATTRIBUTE]: 'authorization/gate' });
         this.logDecisions = parsed.logDecisions;
         this.enabled = parsed.enabled;
         const expandedRules = [];
@@ -82,7 +84,12 @@ export class VerificationGate {
         }
         expandedRules.push(...parsed.rules);
         if (parsed.allowReadOnlyTools) {
-            expandedRules.push({ type: 'allow_read_only' });
+            expandedRules.push({
+                type: 'allow_read_only',
+                ...(parsed.allowReadOnlyExcludeCategories
+                    ? { excludeCategories: parsed.allowReadOnlyExcludeCategories }
+                    : {}),
+            });
         }
         this.rules = expandedRules;
         this.compiledPatterns = new Map();
@@ -94,9 +101,9 @@ export class VerificationGate {
             if (rule.type === 'custom_pattern') {
                 if (rule.pattern.length > MAX_CUSTOM_PATTERN_LENGTH) {
                     this.log.warn('Custom pattern exceeds max length, skipping', {
-                        index: i,
-                        length: rule.pattern.length,
-                        maxLength: MAX_CUSTOM_PATTERN_LENGTH,
+                        'namzu.authorization.index': i,
+                        'namzu.authorization.length': rule.pattern.length,
+                        'namzu.authorization.max_length': MAX_CUSTOM_PATTERN_LENGTH,
                     });
                     continue;
                 }
@@ -105,9 +112,9 @@ export class VerificationGate {
                 }
                 catch (err) {
                     this.log.warn('Invalid custom pattern regex, skipping', {
-                        index: i,
-                        pattern: rule.pattern,
-                        error: err instanceof Error ? err.message : String(err),
+                        'namzu.authorization.index': i,
+                        'namzu.authorization.pattern': rule.pattern,
+                        'exception.message': err instanceof Error ? err.message : String(err),
                     });
                 }
             }
@@ -129,9 +136,9 @@ export class VerificationGate {
                 // it.
                 if (rule.pattern.length > MAX_CUSTOM_PATTERN_LENGTH) {
                     this.log.warn('Argument pattern exceeds max length, skipping', {
-                        index: i,
-                        length: rule.pattern.length,
-                        maxLength: MAX_CUSTOM_PATTERN_LENGTH,
+                        'namzu.authorization.index': i,
+                        'namzu.authorization.length': rule.pattern.length,
+                        'namzu.authorization.max_length': MAX_CUSTOM_PATTERN_LENGTH,
                     });
                     continue;
                 }
@@ -142,9 +149,9 @@ export class VerificationGate {
                 }
                 catch (err) {
                     this.log.warn('Invalid argument pattern regex, skipping', {
-                        index: i,
-                        pattern: rule.pattern,
-                        error: err instanceof Error ? err.message : String(err),
+                        'namzu.authorization.index': i,
+                        'namzu.authorization.pattern': rule.pattern,
+                        'exception.message': err instanceof Error ? err.message : String(err),
                     });
                 }
             }
@@ -177,10 +184,10 @@ export class VerificationGate {
                 };
                 if (this.logDecisions) {
                     this.log.debug('Gate decision', {
-                        toolName: ctx.toolName,
-                        decision,
-                        ruleType: rule.type,
-                        ruleIndex: i,
+                        [GENAI.TOOL_NAME]: ctx.toolName,
+                        'namzu.authorization.decision': decision,
+                        'namzu.authorization.rule_type': rule.type,
+                        'namzu.authorization.rule_index': i,
                     });
                 }
                 return result;
@@ -193,8 +200,8 @@ export class VerificationGate {
         };
         if (this.logDecisions) {
             this.log.debug('Gate decision (default)', {
-                toolName: ctx.toolName,
-                decision: 'review',
+                [GENAI.TOOL_NAME]: ctx.toolName,
+                'namzu.authorization.decision': 'review',
             });
         }
         return result;

package/dist/authorization/gate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gate.js","sourceRoot":"","sources":["../../src/authorization/gate.ts"],"names":[],"mappings":"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"}

package/dist/authorization/index.d.ts

@@ -0,0 +1,6 @@
+export { AuthorizationGate, describeRule, type ToolCallContext } from './gate.js';
+export { defaultSandboxedGateConfig, defaultSandboxedShellGateConfig } from './presets.js';
+export { evaluateRule } from './rules.js';
+export { PERMISSION_PRESETS, SANDBOXED_PRESET, SANDBOXED_SHELL_PRESET, SUPERVISED_PRESET, UNATTENDED_PRESET, UnsupportedPermissionPresetError, availablePermissionPresets, permissionPreset, resolvePermissionPreset, } from './permission-presets.js';
+export type { PermissionPreset } from './permission-presets.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/authorization/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/authorization/index.ts"],"names":[],"mappings":"AAOA,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,KAAK,eAAe,EAAE,MAAM,WAAW,CAAA;AACjF,OAAO,EAAE,0BAA0B,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAA;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAKzC,OAAO,EACN,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,gCAAgC,EAChC,0BAA0B,EAC1B,gBAAgB,EAChB,uBAAuB,GACvB,MAAM,yBAAyB,CAAA;AAChC,YAAY,EAAE,gBAAgB,EAAE,MAAM,yBAAyB,CAAA"}

package/dist/authorization/index.js

@@ -0,0 +1,14 @@
+// This barrel is authorization: a rule engine that decides, BEFORE a tool
+// runs, whether the call is permitted. It is not verification, and the
+// module-invariant registry that used to sit beside it here moved to
+// `src/invariants/` for that reason — see the note on the move in that
+// file. Keeping the two in one directory is what let "verification" mean
+// two unrelated things in one tree.
+export { AuthorizationGate, describeRule } from './gate.js';
+export { defaultSandboxedGateConfig, defaultSandboxedShellGateConfig } from './presets.js';
+export { evaluateRule } from './rules.js';
+// A named permission stance: what the gate allows, what the sandbox must
+// actually enforce for that to be safe, and who answers the rest. The three
+// were configured independently and had to agree by hand.
+export { PERMISSION_PRESETS, SANDBOXED_PRESET, SANDBOXED_SHELL_PRESET, SUPERVISED_PRESET, UNATTENDED_PRESET, UnsupportedPermissionPresetError, availablePermissionPresets, permissionPreset, resolvePermissionPreset, } from './permission-presets.js';
+//# sourceMappingURL=index.js.map

package/dist/authorization/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/authorization/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,uEAAuE;AACvE,qEAAqE;AACrE,uEAAuE;AACvE,yEAAyE;AACzE,oCAAoC;AAEpC,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAwB,MAAM,WAAW,CAAA;AACjF,OAAO,EAAE,0BAA0B,EAAE,+BAA+B,EAAE,MAAM,cAAc,CAAA;AAC1F,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAEzC,yEAAyE;AACzE,4EAA4E;AAC5E,0DAA0D;AAC1D,OAAO,EACN,kBAAkB,EAClB,gBAAgB,EAChB,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,gCAAgC,EAChC,0BAA0B,EAC1B,gBAAgB,EAChB,uBAAuB,GACvB,MAAM,yBAAyB,CAAA"}

package/dist/authorization/permission-presets.d.ts

@@ -0,0 +1,119 @@
+import type { AuthorizationGateConfig } from '../types/authorization/index.js';
+import type { SandboxIsolationControl, SandboxIsolationReport } from '../types/sandbox/index.js';
+/**
+ * A named permission stance: what the gate allows, what the sandbox must
+ * actually enforce for that to be safe, and who answers the rest.
+ *
+ * The three were configured independently and had to agree by hand.
+ * `defaultSandboxedGateConfig` auto-approves in-sandbox file mutation, and
+ * its own docstring says why: "the FS boundary is enforced by the sandbox
+ * layer, not by per-call review". That is a claim about a DIFFERENT
+ * subsystem — one nothing checked. Hand that config a `basic` tier, where
+ * the spawned process can read and write the whole host filesystem, and the
+ * gate keeps auto-approving writes on the grounds of a boundary that is not
+ * there.
+ *
+ * So a preset states its requirement and {@link resolvePermissionPreset}
+ * refuses when the host cannot meet it. Refusing is the point: a preset
+ * that silently fell back to asking about everything would be safe and
+ * unusable, and one that silently kept auto-approving would be neither.
+ */
+export interface PermissionPreset {
+    /** Stable, and written into the run's log. */
+    readonly name: string;
+    /** One sentence an operator reads when choosing between them. */
+    readonly description: string;
+    readonly gate: AuthorizationGateConfig;
+    /**
+     * The controls the sandbox must actually enforce for `gate` to mean what
+     * it says.
+     *
+     * Controls, not a tier name. `SandboxEnvironment` names an
+     * implementation — one tier denies the network outright while another
+     * leaves the host filesystem visible — and a preset depends on the
+     * property, not on which implementation happens to supply it.
+     */
+    readonly requiresIsolation: readonly SandboxIsolationControl[];
+    /**
+     * The approval policy name this stance expects to be running under.
+     *
+     * Advisory rather than enforced: this package cannot install a handler,
+     * and a preset that pretended to would be claiming an authority it does
+     * not have. It is here so a host can compare it against the run's actual
+     * policy and so the pairing is written down in one place instead of
+     * living in whoever wired it.
+     */
+    readonly expectsApprovalPolicy: string;
+}
+/** A preset whose isolation requirement the host cannot meet. */
+export declare class UnsupportedPermissionPresetError extends Error {
+    readonly details: {
+        preset: string;
+        required: readonly SandboxIsolationControl[];
+        missing: readonly SandboxIsolationControl[];
+    };
+    constructor(details: {
+        preset: string;
+        required: readonly SandboxIsolationControl[];
+        missing: readonly SandboxIsolationControl[];
+    });
+}
+/**
+ * Ask a human about everything, and rely on nothing.
+ *
+ * The only preset with no isolation requirement, because it makes no
+ * assumption a sandbox could fail to back: every call goes to review.
+ * Correct on a bare host, and the one to reach for when the sandbox tier
+ * is unknown.
+ */
+export declare const SUPERVISED_PRESET: PermissionPreset;
+/**
+ * Trust the sandbox for the filesystem; ask about shell and network.
+ *
+ * `filesystem` only, and the omissions are deliberate. This preset does not
+ * auto-approve shell or network calls, so it does not depend on those
+ * controls being enforced — requiring them would refuse hosts that could
+ * safely run this.
+ */
+export declare const SANDBOXED_PRESET: PermissionPreset;
+/**
+ * Trust the sandbox for shell too.
+ *
+ * Requires `process` as well: a shell that auto-approves inside a tier
+ * which cannot stop it seeing or signalling host processes is a shell with
+ * the run of the machine, and the gate would be approving on the strength
+ * of a boundary that does not exist.
+ */
+export declare const SANDBOXED_SHELL_PRESET: PermissionPreset;
+/**
+ * Nobody is watching, so the sandbox has to be.
+ *
+ * All three controls, because with an auto-approving policy the sandbox is
+ * the ONLY boundary left. This is the preset an unattended run wants, and
+ * the one whose requirement must not be waived: the whole reason it can
+ * approve everything is that the host said nothing can escape.
+ */
+export declare const UNATTENDED_PRESET: PermissionPreset;
+export declare const PERMISSION_PRESETS: Readonly<Record<string, PermissionPreset>>;
+/** The preset by name, or `undefined` — the reverse lookup a host needs. */
+export declare function permissionPreset(name: string): PermissionPreset | undefined;
+/**
+ * The gate config for a preset, or a refusal naming what is missing.
+ *
+ * The check is the reason this function exists rather than a property
+ * lookup. A host reaching for `unattended` on a `basic` tier is asking for
+ * a run that approves everything with nothing enforcing the boundary it is
+ * approving on the strength of; the answer is no, with the missing controls
+ * named so the host can fix the sandbox rather than guess.
+ */
+export declare function resolvePermissionPreset(preset: PermissionPreset, isolation: SandboxIsolationReport): AuthorizationGateConfig;
+/**
+ * Every preset this host can actually honour, strongest first.
+ *
+ * For an operator picking one, and for a host that wants a default it can
+ * defend. Ordered by how much they rely on the sandbox rather than
+ * alphabetically, so the first entry is always the loosest stance this host
+ * can back up and the last is always `supervised`, which needs nothing.
+ */
+export declare function availablePermissionPresets(isolation: SandboxIsolationReport): readonly PermissionPreset[];
+//# sourceMappingURL=permission-presets.d.ts.map

package/dist/authorization/permission-presets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permission-presets.d.ts","sourceRoot":"","sources":["../../src/authorization/permission-presets.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,iCAAiC,CAAA;AAC9E,OAAO,KAAK,EAAE,uBAAuB,EAAE,sBAAsB,EAAE,MAAM,2BAA2B,CAAA;AAGhG;;;;;;;;;;;;;;;;;GAiBG;AAEH,MAAM,WAAW,gBAAgB;IAChC,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,iEAAiE;IACjE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,IAAI,EAAE,uBAAuB,CAAA;IACtC;;;;;;;;OAQG;IACH,QAAQ,CAAC,iBAAiB,EAAE,SAAS,uBAAuB,EAAE,CAAA;IAC9D;;;;;;;;OAQG;IACH,QAAQ,CAAC,qBAAqB,EAAE,MAAM,CAAA;CACtC;AAED,iEAAiE;AACjE,qBAAa,gCAAiC,SAAQ,KAAK;IAC1D,QAAQ,CAAC,OAAO,EAAE;QACjB,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAA;QAC5C,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAA;KAC3C,CAAA;gBAEW,OAAO,EAAE;QACpB,MAAM,EAAE,MAAM,CAAA;QACd,QAAQ,EAAE,SAAS,uBAAuB,EAAE,CAAA;QAC5C,OAAO,EAAE,SAAS,uBAAuB,EAAE,CAAA;KAC3C;CAOD;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,gBAiB/B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,gBAO9B,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,sBAAsB,EAAE,gBAOpC,CAAA;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB,EAAE,gBAoB/B,CAAA;AAED,eAAO,MAAM,kBAAkB,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAKzE,CAAA;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,gBAAgB,GAAG,SAAS,CAE3E;AAED;;;;;;;;GAQG;AACH,wBAAgB,uBAAuB,CACtC,MAAM,EAAE,gBAAgB,EACxB,SAAS,EAAE,sBAAsB,GAC/B,uBAAuB,CAUzB;AAED;;;;;;;GAOG;AACH,wBAAgB,0BAA0B,CACzC,SAAS,EAAE,sBAAsB,GAC/B,SAAS,gBAAgB,EAAE,CAI7B"}

package/dist/authorization/permission-presets.js

@@ -0,0 +1,137 @@
+import { AUTO_APPROVE_POLICY_NAME } from '../runtime/query/approval-policy.js';
+import { defaultSandboxedGateConfig, defaultSandboxedShellGateConfig } from './presets.js';
+/** A preset whose isolation requirement the host cannot meet. */
+export class UnsupportedPermissionPresetError extends Error {
+    details;
+    constructor(details) {
+        super(`The "${details.preset}" preset requires ${details.required.join(', ')} isolation; this sandbox does not enforce ${details.missing.join(', ')}.`);
+        this.name = 'UnsupportedPermissionPresetError';
+        this.details = details;
+    }
+}
+/**
+ * Ask a human about everything, and rely on nothing.
+ *
+ * The only preset with no isolation requirement, because it makes no
+ * assumption a sandbox could fail to back: every call goes to review.
+ * Correct on a bare host, and the one to reach for when the sandbox tier
+ * is unknown.
+ */
+export const SUPERVISED_PRESET = {
+    name: 'supervised',
+    description: 'Every tool call goes to a human. Assumes nothing about the sandbox.',
+    gate: {
+        enabled: true,
+        // `false`, and that is the whole preset. Read-only auto-approval is
+        // the one allowance whose safety does not depend on the sandbox — it
+        // depends on a tool telling the truth about itself, which is the
+        // claim `isTrustedReadOnly` exists because it cannot always take at
+        // face value.
+        allowReadOnlyTools: false,
+        denyDangerousPatterns: true,
+        logDecisions: false,
+        rules: [{ type: 'deny_dangerous_patterns' }],
+    },
+    requiresIsolation: [],
+    expectsApprovalPolicy: 'host',
+};
+/**
+ * Trust the sandbox for the filesystem; ask about shell and network.
+ *
+ * `filesystem` only, and the omissions are deliberate. This preset does not
+ * auto-approve shell or network calls, so it does not depend on those
+ * controls being enforced — requiring them would refuse hosts that could
+ * safely run this.
+ */
+export const SANDBOXED_PRESET = {
+    name: 'sandboxed',
+    description: 'In-sandbox file mutation auto-approves; shell and network calls go to a human. Requires a sandbox that confines the filesystem.',
+    gate: defaultSandboxedGateConfig(),
+    requiresIsolation: ['filesystem'],
+    expectsApprovalPolicy: 'host',
+};
+/**
+ * Trust the sandbox for shell too.
+ *
+ * Requires `process` as well: a shell that auto-approves inside a tier
+ * which cannot stop it seeing or signalling host processes is a shell with
+ * the run of the machine, and the gate would be approving on the strength
+ * of a boundary that does not exist.
+ */
+export const SANDBOXED_SHELL_PRESET = {
+    name: 'sandboxed-shell',
+    description: 'Shell as well as file mutation auto-approves inside the sandbox; network calls go to a human. Requires filesystem and process isolation.',
+    gate: defaultSandboxedShellGateConfig(),
+    requiresIsolation: ['filesystem', 'process'],
+    expectsApprovalPolicy: 'host',
+};
+/**
+ * Nobody is watching, so the sandbox has to be.
+ *
+ * All three controls, because with an auto-approving policy the sandbox is
+ * the ONLY boundary left. This is the preset an unattended run wants, and
+ * the one whose requirement must not be waived: the whole reason it can
+ * approve everything is that the host said nothing can escape.
+ */
+export const UNATTENDED_PRESET = {
+    name: 'unattended',
+    description: 'Everything auto-approves. The sandbox is the only boundary, so it must enforce all three controls.',
+    gate: {
+        ...defaultSandboxedShellGateConfig(),
+        allowReadOnlyTools: true,
+        // Network too, which is exactly what the `network` isolation
+        // requirement below is paying for. The sandboxed presets leave
+        // network to a human precisely because they do not require that
+        // control; this one requires it, so it can spend it.
+        rules: [
+            {
+                type: 'allow_by_category',
+                categories: ['filesystem', 'shell', 'analysis', 'custom', 'network'],
+            },
+        ],
+    },
+    requiresIsolation: ['filesystem', 'network', 'process'],
+    expectsApprovalPolicy: AUTO_APPROVE_POLICY_NAME,
+};
+export const PERMISSION_PRESETS = {
+    [SUPERVISED_PRESET.name]: SUPERVISED_PRESET,
+    [SANDBOXED_PRESET.name]: SANDBOXED_PRESET,
+    [SANDBOXED_SHELL_PRESET.name]: SANDBOXED_SHELL_PRESET,
+    [UNATTENDED_PRESET.name]: UNATTENDED_PRESET,
+};
+/** The preset by name, or `undefined` — the reverse lookup a host needs. */
+export function permissionPreset(name) {
+    return PERMISSION_PRESETS[name];
+}
+/**
+ * The gate config for a preset, or a refusal naming what is missing.
+ *
+ * The check is the reason this function exists rather than a property
+ * lookup. A host reaching for `unattended` on a `basic` tier is asking for
+ * a run that approves everything with nothing enforcing the boundary it is
+ * approving on the strength of; the answer is no, with the missing controls
+ * named so the host can fix the sandbox rather than guess.
+ */
+export function resolvePermissionPreset(preset, isolation) {
+    const missing = preset.requiresIsolation.filter((control) => !isolation[control]);
+    if (missing.length > 0) {
+        throw new UnsupportedPermissionPresetError({
+            preset: preset.name,
+            required: preset.requiresIsolation,
+            missing,
+        });
+    }
+    return preset.gate;
+}
+/**
+ * Every preset this host can actually honour, strongest first.
+ *
+ * For an operator picking one, and for a host that wants a default it can
+ * defend. Ordered by how much they rely on the sandbox rather than
+ * alphabetically, so the first entry is always the loosest stance this host
+ * can back up and the last is always `supervised`, which needs nothing.
+ */
+export function availablePermissionPresets(isolation) {
+    return [UNATTENDED_PRESET, SANDBOXED_SHELL_PRESET, SANDBOXED_PRESET, SUPERVISED_PRESET].filter((preset) => preset.requiresIsolation.every((control) => isolation[control]));
+}
+//# sourceMappingURL=permission-presets.js.map