@namzu/sdk 52.3.0 → 52.5.0

package/src/types/hitl/index.ts

@@ -1,5 +1,6 @@
 import type { CostInfo, TokenUsage } from '../common/index.js'
 import type { CheckpointId, PlanId, SessionId, TurnId } from '../ids/index.js'
+import type { Message } from '../message/index.js'
 
 export type { CheckpointId }
 
@@ -139,7 +140,28 @@ export type HITLDecisionRequest =
 			question: UserQuestionData
 	  }
 
-export type ResumeHandler = (request: HITLDecisionRequest) => Promise<HITLResumeDecision>
+/**
+ * What the turn offers a resume handler besides the request, in memory only.
+ *
+ * Kept out of {@link HITLDecisionRequest} on purpose: the request is written
+ * to the session log when a decision takes long, and a transcript does not
+ * belong there. A handler that does not need it ignores the argument; one that
+ * wraps another passes it on.
+ */
+export interface ResumeContext {
+	/**
+	 * The conversation as it stands now, the batch under review included.
+	 * Read on demand; the array is the turn's own, so a caller must not change it.
+	 */
+	readonly transcript: () => readonly Message[]
+	/** The turn's cancellation signal, when it has one. */
+	readonly signal?: AbortSignal
+}
+
+export type ResumeHandler = (
+	request: HITLDecisionRequest,
+	context?: ResumeContext,
+) => Promise<HITLResumeDecision>
 
 export interface ToolCallSummary {
 	id: string
@@ -158,6 +180,24 @@ export interface ToolCallSummary {
 		reason?: string
 		/** A matching rule requested review; read-only exemptions must not bypass it. */
 		explicitReview?: true
+		/**
+		 * A rule written to ask a person (a `review` rule), or a hook that asked
+		 * for one, requested this review. Unlike {@link explicitReview} it is not
+		 * set when an `allow` rule was demoted to review because the call reaches
+		 * past its boundary. `bypass` and `classify` keep this question for a
+		 * person; they answer the demoted kind themselves.
+		 */
+		askRule?: true
+		/**
+		 * How wide the `allow` rule that settled this call is. `tool` means the
+		 * rule names the whole tool, a category, a tier or a source, or its
+		 * pattern matches every input; `pattern` means it matches some inputs
+		 * only. Present only when `decision` is `allow` and a rule (not the
+		 * read-only allowance) decided it. The `classify` review mode reads it:
+		 * a whole-tool allow for a shell tool would let the classifier never
+		 * see a command.
+		 */
+		allowScope?: 'tool' | 'pattern'
 	}
 	/**
 	 * What this call reaches beyond the turn's ordinary boundary, as the
@@ -278,6 +318,14 @@ export interface ToolCallEscalation {
 	 * tool that declares `commandArgument`.
 	 */
 	dangerousRemoval?: string
+	/**
+	 * Why the kernel could not finish looking at this call: the check that
+	 * finds the escalations above threw, so none of them is known to be
+	 * absent. Treated as the most serious escalation there is, because the
+	 * safety checks did not run: a person is asked in every mode, `bypass`
+	 * and `classify` included, and it is refused when nobody can be asked.
+	 */
+	unfinishedCheck?: string
 }
 
 export interface ToolModification {

package/src/types/sandbox/index.ts

@@ -334,6 +334,16 @@ export interface Sandbox {
 	readonly status: SandboxStatus
 	readonly rootDir: string
 	readonly environment: SandboxEnvironment
+	/**
+	 * The network policy in force right now, when the backend can say.
+	 *
+	 * Optional, and absent does NOT mean open: a caller that needs to know
+	 * whether a host is reachable (the host process opening a connection on a
+	 * turn's behalf, outside the boundary) treats absence as "not allowed" on a
+	 * tier that isolates the network. A backend that enforces
+	 * {@link setNetworkPolicy} should report what it enforces here.
+	 */
+	readonly networkPolicy?: SandboxNetworkPolicy
 	exec(command: string, args?: string[], opts?: SandboxExecOptions): Promise<SandboxExecResult>
 
 	/**

package/src/types/tool/index.ts

@@ -105,6 +105,20 @@ export interface SkillRegistryRef {
 	names(): readonly string[]
 }
 
+/**
+ * Where a WebSocket monitor connects, already checked.
+ *
+ * `addresses` are what the caller verified are outside the host's own
+ * network; the connection is pinned to them and never resolves the name
+ * itself. A caller that did not check must not hand it a target: the registry
+ * trusts it, as it trusts a spawn it is given.
+ */
+export interface MonitorWebSocketTarget {
+	readonly url: string
+	readonly protocols?: readonly string[]
+	readonly addresses: readonly { readonly address: string; readonly family: 4 | 6 }[]
+}
+
 /**
  * The slice of the background job registry a tool is given.
  *
@@ -135,6 +149,19 @@ export interface BackgroundJobRegistryRef {
 		timeoutMs: number
 		workingDirectory?: string
 	}): { job: { id: string; status: string }; timeoutMs: number }
+	/**
+	 * Start a monitor whose source is a WebSocket connection. Separate from
+	 * {@link startMonitor} so a host that implements that one for commands is
+	 * not handed an input it was not written for; a host without this method
+	 * refuses a `ws` call with a plain message. The target's addresses are
+	 * already checked; see {@link MonitorWebSocketTarget}.
+	 */
+	startWebSocketMonitor?(params: {
+		description: string
+		timeoutMs: number
+		workingDirectory?: string
+		webSocket: MonitorWebSocketTarget
+	}): { job: { id: string; status: string }; timeoutMs: number }
 	get(id: string): {
 		id: string
 		status: string
@@ -1151,6 +1178,23 @@ export interface ToolDefinition<TInput = unknown> extends ToolPresentation<TInpu
 	 */
 	requiresApproval?(input: TInput): boolean
 
+	/**
+	 * What the auto-mode safety classifier is shown of this call.
+	 *
+	 * The classifier (`createAutoReviewClassifier`, review mode `classify`)
+	 * reads a compact transcript, not raw tool arguments: a tool knows which
+	 * part of its own input says what the call DOES. A shell tool returns the
+	 * command, a file tool the path and a short summary of the change, a fetch
+	 * the address. The string should be short and carry no content the model
+	 * could not already be trusted with; the runtime caps its length.
+	 *
+	 * Absent, the classifier is shown the input as compact JSON. A tool whose
+	 * input is large or opaque (a file body, a binary payload) should declare
+	 * this so the classifier judges the action rather than the bulk. Never
+	 * called with a tool RESULT: results are untrusted and are not shown.
+	 */
+	classifierInput?(input: TInput): string
+
 	/**
 	 * Free-form, tool-author-declared data for filtering and behaviour
 	 * customization — never a classification the runtime itself reads.