@namzu/sdk 27.1.0 → 28.0.0

package/src/agents/runAgent.ts

@@ -1,18 +1,18 @@
 import { ToolRegistry } from '../registry/tool/execute.js'
 import { drainQuery } from '../runtime/query/index.js'
-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'
 import {
 	generateProjectId,
 	generateSessionId,
 	generateTenantId,
-	generateThreadId,
+	generateTopicId,
 } from '../utils/id.js'
 
 /**
@@ -35,7 +35,7 @@ import {
  */
 export interface AgentIdentity {
 	sessionId?: SessionId
-	threadId?: ThreadId
+	topicId?: TopicId
 	projectId?: ProjectId
 	tenantId?: TenantId
 }
@@ -79,11 +79,17 @@ 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
@@ -212,7 +218,7 @@ export const DEFAULT_TIMEOUT_MS = 300_000
 export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult> {
 	const identity: Required<AgentIdentity> = {
 		sessionId: options.sessionId ?? generateSessionId(),
-		threadId: options.threadId ?? generateThreadId(),
+		topicId: options.topicId ?? generateTopicId(),
 		projectId: options.projectId ?? generateProjectId(),
 		tenantId: options.tenantId ?? generateTenantId(),
 	}
@@ -248,6 +254,7 @@ export async function runAgent(options: RunAgentOptions): Promise<RunAgentResult
 			...(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,
 		},

package/src/{verification → authorization}/gate.ts

@@ -1,11 +1,13 @@
-import { MAX_CUSTOM_PATTERN_LENGTH } from '../constants/verification/index.js'
-import type { ToolDefinition } from '../types/tool/index.js'
+import { MAX_CUSTOM_PATTERN_LENGTH } from '../constants/authorization/index.js'
+import { GENAI } from '../constants/telemetry/index.js'
 import type {
+	AuthorizationGateConfig,
+	AuthorizationRule,
 	GateEvaluationResult,
-	VerificationGateConfig,
-	VerificationRule,
-} from '../types/verification/index.js'
-import { VerificationGateConfigSchema } from '../types/verification/index.js'
+} from '../types/authorization/index.js'
+import { AuthorizationGateConfigSchema } from '../types/authorization/index.js'
+import type { ToolDefinition } from '../types/tool/index.js'
+import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import type { Logger } from '../utils/logger.js'
 import { evaluateRule } from './rules.js'
 
@@ -30,7 +32,7 @@ export interface ToolCallContext {
  * cannot be reasoned about produces thrashing; one that can produces a route
  * around it.
  */
-export function describeRule(rule: VerificationRule): string {
+export function describeRule(rule: AuthorizationRule): string {
 	switch (rule.type) {
 		case 'deny_dangerous_patterns':
 			return 'this matches a pattern the operator refuses outright; rewording it will not help'
@@ -64,21 +66,21 @@ export function describeRule(rule: VerificationRule): string {
 	}
 }
 
-export class VerificationGate {
-	private readonly rules: VerificationRule[]
+export class AuthorizationGate {
+	private readonly rules: AuthorizationRule[]
 	private readonly compiledPatterns: Map<number, RegExp>
 	private readonly nameSets: Map<number, Set<string>>
 	private readonly log: Logger
 	private readonly logDecisions: boolean
 	private readonly enabled: boolean
 
-	constructor(config: VerificationGateConfig, log: Logger) {
-		const parsed = VerificationGateConfigSchema.parse(config)
-		this.log = log.child({ component: 'VerificationGate' })
+	constructor(config: AuthorizationGateConfig, log: Logger) {
+		const parsed = AuthorizationGateConfigSchema.parse(config)
+		this.log = log.child({ [SCOPE_ATTRIBUTE]: 'authorization/gate' })
 		this.logDecisions = parsed.logDecisions
 		this.enabled = parsed.enabled
 
-		const expandedRules: VerificationRule[] = []
+		const expandedRules: AuthorizationRule[] = []
 
 		// Order is the whole meaning of this list, because the first rule to
 		// match decides and nothing after it is consulted.
@@ -103,7 +105,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
 
@@ -117,9 +124,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
 				}
@@ -127,9 +134,9 @@ export class VerificationGate {
 					this.compiledPatterns.set(i, new RegExp(rule.pattern))
 				} 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),
 					})
 				}
 			}
@@ -152,9 +159,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
 				}
@@ -164,9 +171,9 @@ export class VerificationGate {
 					this.nameSets.set(i, new Set(rule.toolNames))
 				} 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),
 					})
 				}
 			}
@@ -210,10 +217,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,
 					})
 				}
 
@@ -229,8 +236,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',
 			})
 		}
 

package/src/authorization/index.ts

@@ -0,0 +1,26 @@
+// 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, type ToolCallContext } 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'
+export type { PermissionPreset } from './permission-presets.js'

package/src/authorization/permission-presets.ts

@@ -0,0 +1,215 @@
+import { AUTO_APPROVE_POLICY_NAME } from '../runtime/query/approval-policy.js'
+import type { AuthorizationGateConfig } from '../types/authorization/index.js'
+import type { SandboxIsolationControl, SandboxIsolationReport } from '../types/sandbox/index.js'
+import { defaultSandboxedGateConfig, defaultSandboxedShellGateConfig } from './presets.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 class UnsupportedPermissionPresetError extends Error {
+	readonly details: {
+		preset: string
+		required: readonly SandboxIsolationControl[]
+		missing: readonly SandboxIsolationControl[]
+	}
+
+	constructor(details: {
+		preset: string
+		required: readonly SandboxIsolationControl[]
+		missing: readonly SandboxIsolationControl[]
+	}) {
+		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: PermissionPreset = {
+	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: PermissionPreset = {
+	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: PermissionPreset = {
+	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: PermissionPreset = {
+	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: Readonly<Record<string, PermissionPreset>> = {
+	[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: string): PermissionPreset | undefined {
+	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: PermissionPreset,
+	isolation: SandboxIsolationReport,
+): AuthorizationGateConfig {
+	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: SandboxIsolationReport,
+): readonly PermissionPreset[] {
+	return [UNATTENDED_PRESET, SANDBOXED_SHELL_PRESET, SANDBOXED_PRESET, SUPERVISED_PRESET].filter(
+		(preset) => preset.requiresIsolation.every((control) => isolation[control]),
+	)
+}

package/src/{verification → authorization}/presets.ts

@@ -1,4 +1,4 @@
-import type { VerificationGateConfig } from '../types/verification/index.js'
+import type { AuthorizationGateConfig } from '../types/authorization/index.js'
 
 /**
  * Sensible defaults for an agent that runs inside a host-provided
@@ -34,10 +34,14 @@ import type { VerificationGateConfig } from '../types/verification/index.js'
  *
  * Hosts override individual fields by spreading: `{ ...defaultSandboxedGateConfig(), logDecisions: false }`.
  */
-export function defaultSandboxedGateConfig(): VerificationGateConfig {
+export function defaultSandboxedGateConfig(): AuthorizationGateConfig {
 	return {
 		enabled: true,
 		allowReadOnlyTools: true,
+		// See the shell preset below for what this closes: the read-only
+		// allowance asks whether a claim is trustworthy, never what channel
+		// the call travels over.
+		allowReadOnlyExcludeCategories: ['network'],
 		denyDangerousPatterns: true,
 		logDecisions: false,
 		rules: [{ type: 'allow_by_category', categories: ['filesystem', 'analysis', 'custom'] }],
@@ -62,10 +66,18 @@ export function defaultSandboxedGateConfig(): VerificationGateConfig {
  * other tenants, or when the working directory is the user's
  * actual home/repo without an extra isolation layer.
  */
-export function defaultSandboxedShellGateConfig(): VerificationGateConfig {
+export function defaultSandboxedShellGateConfig(): AuthorizationGateConfig {
 	return {
 		enabled: true,
 		allowReadOnlyTools: true,
+		// The docblock above says a `network` tool goes to review, and without
+		// this it did not: `allow_read_only` is appended last as a default for
+		// tools nobody wrote a rule about, and it resolved purely through
+		// `isTrustedReadOnly` — which asks whether the read-only CLAIM is
+		// trustworthy and never what the tool reaches. A read-only network
+		// call matched the default and was approved without review, in the
+		// preset whose own documentation said it would not be.
+		allowReadOnlyExcludeCategories: ['network'],
 		denyDangerousPatterns: true,
 		logDecisions: false,
 		rules: [

package/src/{verification → authorization}/rules.ts

@@ -1,10 +1,10 @@
 import { DANGEROUS_PATTERNS } from '../constants/tools/index.js'
 import { isTrustedReadOnly } from '../tools/trusted-read-only.js'
+import type { AuthorizationRule, GateDecision } from '../types/authorization/index.js'
 import type { ToolDefinition } from '../types/tool/index.js'
-import type { GateDecision, VerificationRule } from '../types/verification/index.js'
 
 export function evaluateRule(
-	rule: VerificationRule,
+	rule: AuthorizationRule,
 	toolName: string,
 	toolInput: unknown,
 	toolDef: ToolDefinition | undefined,
@@ -16,7 +16,20 @@ export function evaluateRule(
 			// A server's own claim about its own tool cannot settle this. See
 			// `isTrustedReadOnly`: a self-declaration may raise the requirement
 			// and never lower it.
-			return isTrustedReadOnly(toolDef, toolInput) ? 'allow' : null
+			if (!isTrustedReadOnly(toolDef, toolInput)) return null
+
+			// Read-only is a claim about the DATA a call returns, not about the
+			// CHANNEL it travels over. A tool can be `readOnlyHint: true` AND
+			// `provenance.readOnlyHintTrusted: true` — a claim this rule would
+			// otherwise take at face value — and still cross the one boundary
+			// the gate exists to police, because `isTrustedReadOnly` only ever
+			// asks whether the CLAIM is trustworthy. `excludeCategories` lets a
+			// rule say "not this channel, however trusted the claim", falling
+			// through exactly as if nothing had matched.
+			const category = toolDef?.category
+			if (category && rule.excludeCategories?.includes(category)) return null
+
+			return 'allow'
 		}
 
 		case 'deny_dangerous_patterns': {