@namzu/sdk 39.0.0 → 40.0.0

package/src/types/tool/index.ts

@@ -113,6 +113,33 @@ export interface BackgroundJobRegistryRef {
 	}
 	kill(id: string): Promise<{ id: string; status: string }>
 	list(): readonly { id: string; command: string; status: string }[]
+	/**
+	 * Await this job's exit instead of reading it in a loop; resolves at
+	 * once for a job that has already stopped. Optional, and added after
+	 * the rest of this surface: a host implementing this interface directly
+	 * rather than through `bindOwner` may not have it yet, so `wait_for_job`
+	 * checks for it and says so rather than assuming every host can wait.
+	 */
+	waitForExit?(
+		id: string,
+		opts?: { signal?: AbortSignal },
+	): Promise<{
+		id: string
+		status: string
+		exitCode?: number
+	}>
+	/**
+	 * Say that the model is waiting on this job, so the run stays open for it
+	 * when the model stops calling tools.
+	 *
+	 * Called by `wait_for_job` and nothing else. The kernel holds a finishing
+	 * run open — bounded, and for no model tokens — only for a job marked
+	 * here; a job nobody marked never delays a run, which is what a dev server
+	 * or a watcher needs. Optional for the reason `waitForExit` is: a host
+	 * implementing this interface directly may have nowhere to record the
+	 * intent, and then there is simply no hold.
+	 */
+	markAwaited?(id: string): void
 }
 
 /**
@@ -138,6 +165,83 @@ export interface FileReadTracker {
 	 * preserves it; different or unknown content clears it. Never infer from a name.
 	 */
 	writeCallId?(key: string): string | undefined
+	/**
+	 * Optional chain of calls whose bodies compose the current content: the
+	 * full-body write that started it, then the successful edits applied on
+	 * top of it, in order.
+	 *
+	 * Defined only while at least one edit sits on a witnessed write — exactly
+	 * when `writeCallId` is not. An edited file's body is no longer the write
+	 * call's body, and a consumer that knows only `writeCallId` has to keep
+	 * seeing nothing there rather than a claim that has quietly stopped being
+	 * true. The chain names INPUTS: reconstructing the body means replaying
+	 * those calls' visible arguments and checking the result against
+	 * `fingerprint(key)`, never asserting it.
+	 */
+	editChain?(key: string): { rootWriteCallId: string; editCallIds: readonly string[] } | undefined
+	/**
+	 * Optional record of a successful edit's resulting content, with the call
+	 * that produced it.
+	 *
+	 * Does everything `recordRead(key, content)` does, and additionally extends
+	 * the chain when this edit ran against content the ledger already had a
+	 * fingerprint for and a witnessed write underneath it — the two facts that
+	 * make the replay reproducible. Missing either, it is an ordinary
+	 * observation of a body nobody can replay: the fingerprint advances and the
+	 * chain is cleared. Pass ToolContext.toolUseId only after the edit succeeded.
+	 */
+	recordEdit?(key: string, content: string, callId: string): void
+	/**
+	 * Optional witness of a read that returned the file WHOLE, with the
+	 * fingerprint of the rendering it returned.
+	 *
+	 * Does everything `recordRead(key, content)` does, and additionally records
+	 * that the body is visible in `callId`'s receipt — not as text this ledger
+	 * holds, but as the exact rendering `callId` emitted, so a consumer can
+	 * check the receipt it can see against `renderedFingerprint` before
+	 * referencing it. A partial read never calls this: a window proves nothing
+	 * about the rest of the file. Pass `ToolContext.toolUseId` and the
+	 * fingerprint of the tool's own output string.
+	 *
+	 * The witness is recorded only where no write witness or chain survives the
+	 * observation, because a write-rooted body is one the model composed and
+	 * can be replayed through. It is cleared by exactly what clears a write
+	 * witness — different or unknown content — and additionally by any
+	 * `recordEdit`, because a read roots no chain: the body it witnesses exists
+	 * only as a rendering, and nothing may be replayed on top of it.
+	 */
+	recordFullRead?(key: string, content: string, callId: string, renderedFingerprint: string): void
+	/**
+	 * Optional witness of the full read above: the call whose receipt holds the
+	 * body, and the fingerprint of what that call emitted.
+	 *
+	 * `renderedFingerprint` is deliberately not the body's fingerprint —
+	 * `fingerprint(key)` is that. It describes the RECEIPT, so a consumer
+	 * admits the reference only while the receipt it can see is byte-for-byte
+	 * what the tool returned; an elided, spilled or cleared one is not.
+	 *
+	 * The derived work context asks a tracker for `writeCallId` and
+	 * `fingerprint` before it reads any witness at all — a name alone does not
+	 * say the ledger is the one execution wrote — so a tracker implementing
+	 * this pair and neither of those still establishes nothing.
+	 */
+	readWitness?(key: string): { callId: string; renderedFingerprint: string } | undefined
+	/**
+	 * Optional note that a built-in mutation has just refused this path because
+	 * the body on disk differs from the fingerprint above.
+	 *
+	 * Not an observation. The refusing tool read the disk, but all it reports
+	 * here is the disagreement — recording the body it found would re-baseline
+	 * the drift check and admit the very mutation that was refused. An
+	 * implementation must therefore leave `fingerprint`, `hasRead`,
+	 * `writeCallId`, `editChain` and `readWitness` exactly as they were, and any
+	 * later content observation clears the flag. It exists so a consumer that
+	 * cannot read the filesystem — the derived work context — can stop
+	 * referencing a body it has been told is stale, without a check of its own.
+	 */
+	recordDriftObserved?(key: string): void
+	/** Whether a refused mutation has reported this path stale since the last observation. */
+	driftObserved?(key: string): boolean
 	/**
 	 * Fingerprint of the body captured at the last read, when one was.
 	 *

package/src/utils/env.ts

@@ -0,0 +1,23 @@
+/**
+ * A positive whole number of milliseconds from the environment, or the
+ * caller's own default.
+ *
+ * Every bound that can be tuned wants the same three answers, and the third
+ * is the one worth sharing: a variable set to `soon`, to `-1` or to nothing
+ * at all falls back rather than parsing, because a run must not wait, hold or
+ * time out for `NaN`.
+ *
+ * `process.env` is read on every call, so where it is called decides when the
+ * value is sampled — `wait_for_job` fixes its bounds at module load and names
+ * them in a tool schema, and the kernel's hold ceiling asks per hold. That
+ * choice is why this lives here rather than being imported from the tool: the
+ * kernel reaching into `wait_for_job` for the parse would pull the tool's
+ * module-load sampling into the runtime's own graph, and move when the
+ * `NAMZU_JOB_WAIT_*` bounds are read.
+ */
+export function readPositiveIntEnv(key: string, fallback: number): number {
+	const value = process.env[key]?.trim()
+	if (!value) return fallback
+	const parsed = Number(value)
+	return Number.isSafeInteger(parsed) && parsed > 0 ? parsed : fallback
+}