@namzu/sdk 43.0.0 → 44.1.0

package/dist/runtime/query/review-policy.js

@@ -1,11 +1,11 @@
 /**
- * How a run resolves calls routed to review.
+ * How a turn resolves calls routed to review.
  *
  * An authorization rule says what a tool may do. A review policy says what
  * happens to calls the rules did not cover or explicitly routed to REVIEW.
  * The two axes are separate on purpose — a rule is a durable
- * statement an operator reviewed, and a mode is a property of ONE run, the
- * difference between "we never force-push" and "this run is unattended".
+ * statement an operator reviewed, and a mode is a property of ONE turn, the
+ * difference between "we never force-push" and "this turn is unattended".
  *
  * Only calls the gate routed to review arrive here. A rule that denied one
  * already stopped it, and a rule that allowed one never asked. So a mode
@@ -34,7 +34,7 @@ export function isReviewMode(value) {
 }
 export { PLAN_MODE_REFUSAL };
 /** What the model is told when a call is refused under `strict`. */
-export const STRICT_MODE_REFUSAL = 'Refused: this run only permits tools an explicit rule allows, and no rule covers this call. Asking again will not change it — either the operator adds a rule, or this has to be done another way.';
+export const STRICT_MODE_REFUSAL = 'Refused: this turn only permits tools an explicit rule allows, and no rule covers this call. Asking again will not change it — either the operator adds a rule, or this has to be done another way.';
 /** The tools `accept-edits` approves without asking. Everything else prompts. */
 export const ACCEPT_EDITS_TOOLS = new Set(['edit', 'write']);
 /**
@@ -52,7 +52,7 @@ export const ACCEPT_EDITS_TOOLS = new Set(['edit', 'write']);
  *
  * `save_memory` is deliberately NOT here. Content saved now is retrievable
  * by `search_memory` in a later session, so a tool result that talks the
- * model into saving something reaches a future run's reasoning. A write
+ * model into saving something reaches a future turn's reasoning. A write
  * that survives the process is not read-only under any reading.
  */
 export const REVIEW_EXEMPT_WRITES = new Set([
@@ -80,10 +80,51 @@ export function isReviewExempt(registry, name, input) {
         return false;
     return isTrustedReadOnly(tool, input);
 }
-/** Review explicit requests and calls that are destructive or not exempt. */
+/**
+ * Review explicit requests, escalated calls, and calls that are destructive
+ * or not exempt.
+ *
+ * An escalated call (`ToolCallSummary.escalation`) is reviewed even when its
+ * tool only reads: a read of a file outside the working directory is exactly
+ * the read the boundary was about, and "the tool is read-only" answers a
+ * different question.
+ */
 export function batchNeedsReview(toolCalls, exempt) {
-    return toolCalls.some((tc) => tc.authorization?.explicitReview || tc.isDestructive || !exempt(tc.name, tc.input));
+    return toolCalls.some((tc) => tc.authorization?.explicitReview ||
+        tc.escalation !== undefined ||
+        tc.isDestructive ||
+        !exempt(tc.name, tc.input));
 }
+/**
+ * Whether every call in a batch only reads, so that what brought it to review
+ * can only be a path outside the roots: no explicit review from a rule,
+ * nothing destructive, no sandbox escape, and a tool exempt from review.
+ */
+function onlyReadsOutsideRoots(toolCalls, exempt) {
+    return toolCalls.every((tc) => !tc.authorization?.explicitReview &&
+        !tc.isDestructive &&
+        tc.escalation?.sandboxEscape !== true &&
+        exempt(tc.name, tc.input));
+}
+/**
+ * What the model is told when a batch asks to leave the sandbox and nobody
+ * can be asked.
+ *
+ * The whole batch is refused rather than the escape alone: the policy
+ * answers for the batch as a unit, and approving its other calls while the
+ * one that needed a person is dropped would run a plan with a hole in it.
+ */
+export const SANDBOX_ESCAPE_UNATTENDED_REFUSAL = 'Refused: a call in this batch asks to run outside the sandbox, which needs a person to confirm it each time, and nobody can be asked in this session. Nothing in this batch ran. Run the command inside the sandbox, or resend the other calls without the escape.';
+/**
+ * What the model is told when a batch reaches a path outside the turn's roots
+ * and nobody can be asked.
+ *
+ * Refused rather than approved by `auto`: the path is outside what the turn
+ * was given, and an approval of it is a person's, per call. A host with
+ * nobody to ask widens the roots up front instead (`additionalDirectories`,
+ * the CLI's `--add-dir`), where an operator wrote the directory down.
+ */
+export const OUTSIDE_ROOTS_UNATTENDED_REFUSAL = "Refused: a call in this batch reaches a path outside the working directory and the added directories, which needs a person to approve it each time, and nobody can be asked in this session. Nothing in this batch ran. Stay inside the working directory, or tell the user which directory you need so they can add it to the session (the CLI's --add-dir).";
 /** The handler behind `createReviewPolicy`, for a host that wants only the function. */
 export function createReviewHandler(options = {}) {
     const { prompt, registry } = options;
@@ -105,21 +146,84 @@ export function createReviewHandler(options = {}) {
         // through beside it would be approving something it did not show.
         if (mode === 'accept-edits' &&
             request.toolCalls.every((tc) => !tc.authorization?.explicitReview &&
+                tc.escalation === undefined &&
                 !tc.isDestructive &&
                 (ACCEPT_EDITS_TOOLS.has(tc.name) || exempt(tc.name, tc.input)))) {
             return { action: 'approve_tools' };
         }
         // Ordinary reads were approved above. Remaining calls either change
         // state or carry explicit review; plan mode does not grant that authority.
-        if (mode === 'plan')
+        // Except a batch of reads whose only reason to be here is a path outside
+        // the roots: plan mode is for reading, a read is what it tells the model
+        // to do, and the question such a path gets is the same in every mode that
+        // lets reads run. It goes on to that question below; `strict` still
+        // refuses it, since no rule can approve a path outside the roots.
+        if (mode === 'plan' && !onlyReadsOutsideRoots(request.toolCalls, exempt)) {
             return { action: 'reject_tools', feedback: PLAN_MODE_REFUSAL };
+        }
         if (mode === 'strict')
             return { action: 'reject_tools', feedback: STRICT_MODE_REFUSAL };
+        // A sandbox escape is asked about every time, in every mode that got
+        // this far — `auto` and a remembered "approve all" included, because
+        // both are answers somebody gave BEFORE this command existed. The
+        // kernel refuses an escape an approval does not name by id, so the
+        // ids below are the consent, and only a person (or an operator's
+        // explicit unattended setting) supplies them.
+        const escapes = request.toolCalls
+            .filter((tc) => tc.escalation?.sandboxEscape === true)
+            .map((tc) => tc.id);
+        if (escapes.length > 0) {
+            if (!prompt) {
+                return options.unattendedSandboxEscape === 'allow'
+                    ? { action: 'approve_tools', confirmedEscalations: escapes }
+                    : { action: 'reject_tools', feedback: SANDBOX_ESCAPE_UNATTENDED_REFUSAL };
+            }
+            const answer = await prompt({
+                sessionId: request.sessionId,
+                turnId: request.turnId,
+                toolCalls: request.toolCalls,
+            });
+            if (answer.kind === 'reject') {
+                return {
+                    action: 'reject_tools',
+                    feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+                };
+            }
+            // "Approve all" still latches for the calls that follow; it never
+            // reaches the next escape, which is asked about above regardless.
+            if (answer.kind === 'approve-all')
+                remembered.all = true;
+            return { action: 'approve_tools', confirmedEscalations: escapes };
+        }
+        // A path outside the roots is a question for a person, every time,
+        // like an escape: `auto` and a remembered "approve all" were answers
+        // given about tools, before this path was named, and neither saw it.
+        // With nobody to ask it is refused, not approved.
+        if (request.toolCalls.some((tc) => (tc.escalation?.outsidePaths?.length ?? 0) > 0)) {
+            if (!prompt)
+                return { action: 'reject_tools', feedback: OUTSIDE_ROOTS_UNATTENDED_REFUSAL };
+            const answer = await prompt({
+                sessionId: request.sessionId,
+                turnId: request.turnId,
+                toolCalls: request.toolCalls,
+            });
+            if (answer.kind === 'reject') {
+                return {
+                    action: 'reject_tools',
+                    feedback: answer.feedback ?? 'User declined to run the proposed tool(s).',
+                };
+            }
+            // Latches for the ordinary calls that follow, never for the next path.
+            if (answer.kind === 'approve-all')
+                remembered.all = true;
+            return { action: 'approve_tools' };
+        }
         if (mode === 'auto' || !prompt || remembered.all) {
             return { action: 'approve_tools' };
         }
         const answer = await prompt({
-            runId: request.runId,
+            sessionId: request.sessionId,
+            turnId: request.turnId,
             toolCalls: request.toolCalls,
         });
         switch (answer.kind) {
@@ -138,8 +242,8 @@ export function createReviewHandler(options = {}) {
 }
 /**
  * The mode as an `ApprovalPolicy`, named after itself so a durable log can
- * say which one approved a call. Swap it on a run's `RunApprovalPolicy`
- * to change mode without ending the run.
+ * say which one approved a call. Swap it on a turn's `SessionApprovalPolicy`
+ * to change mode without ending the turn.
  */
 export function createReviewPolicy(options = {}) {
     const mode = options.mode ?? (options.prompt ? 'prompt' : 'auto');

package/dist/runtime/query/review-policy.js.map

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

package/dist/runtime/query/sandbox-lifecycle.d.ts

@@ -1,5 +1,5 @@
 import type { Sandbox, SandboxCreateConfig, SandboxProvider } from '../../types/sandbox/index.js';
-/** A sandbox release gets thirty seconds before the run stops waiting for it. */
+/** A sandbox release gets thirty seconds before the turn stops waiting for it. */
 export declare const DEFAULT_SANDBOX_TEARDOWN_TIMEOUT_MS = 30000;
 export declare function resolveSandboxTeardownTimeoutMs(value: number | undefined): number;
 export type SandboxTeardownResult = {
@@ -25,16 +25,16 @@ export type SandboxAcquisitionResult = {
 /**
  * Release a sandbox under a fresh owner.
  *
- * The run signal is deliberately not an input: cleanup normally begins because
+ * The turn signal is deliberately not an input: cleanup normally begins because
  * that signal is already aborted. A private signal gives the implementation a
  * chance to stop its transport at the teardown deadline, while the independent
- * race keeps a third-party implementation that ignores it from pinning the run.
+ * race keeps a third-party implementation that ignores it from pinning the turn.
  */
 export declare function teardownSandbox(sandbox: Sandbox, timeoutMs: number): Promise<SandboxTeardownResult>;
 /**
  * Acquire a sandbox without allowing foreign setup to outlive run authority.
  *
- * Cancellation or the run timeout settles this function even when a provider
+ * Cancellation or the turn timeout settles this function even when a provider
  * ignores the signal.
  * A handle that arrives later is never published and is released exactly once.
  * This proves host/run liveness and cleanup of every handle the provider
@@ -46,7 +46,7 @@ export declare function acquireSandbox(options: {
     readonly provider: SandboxProvider;
     readonly config: Omit<SandboxCreateConfig, 'signal'>;
     readonly signal: AbortSignal;
-    /** Remaining wall-clock owned by the run, not a second sandbox budget. */
+    /** Remaining wall-clock owned by the turn, not a second sandbox budget. */
     readonly timeoutMs: number;
     readonly teardownTimeoutMs: number;
     readonly onLateTeardown?: (result: SandboxTeardownResult) => void;

package/dist/runtime/query/sandbox-lifecycle.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sandbox-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/sandbox-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAIjG,iFAAiF;AACjF,eAAO,MAAM,mCAAmC,QAAS,CAAA;AAEzD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQjF;AAED,MAAM,MAAM,qBAAqB,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAA;AAExD,MAAM,MAAM,wBAAwB,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAA;AA6BzF;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACpC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,CAAC,CA6BhC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC7C,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAA;IACpD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAA;CACjE,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAiGpC"}
+{"version":3,"file":"sandbox-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/sandbox-lifecycle.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,mBAAmB,EAAE,eAAe,EAAE,MAAM,8BAA8B,CAAA;AAIjG,kFAAkF;AAClF,eAAO,MAAM,mCAAmC,QAAS,CAAA;AAEzD,wBAAgB,+BAA+B,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAQjF;AAED,MAAM,MAAM,qBAAqB,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GAC9B;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,GACpD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAA;AAExD,MAAM,MAAM,wBAAwB,GACjC;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAA;CAAE,GAC/D;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAAC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAA;CAAE,CAAA;AA6BzF;;;;;;;GAOG;AACH,wBAAsB,eAAe,CACpC,OAAO,EAAE,OAAO,EAChB,SAAS,EAAE,MAAM,GACf,OAAO,CAAC,qBAAqB,CAAC,CA6BhC;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,cAAc,CAAC,OAAO,EAAE;IAC7C,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAA;IAClC,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,mBAAmB,EAAE,QAAQ,CAAC,CAAA;IACpD,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAA;IAC5B,2EAA2E;IAC3E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAA;IAClC,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,MAAM,EAAE,qBAAqB,KAAK,IAAI,CAAA;CACjE,GAAG,OAAO,CAAC,wBAAwB,CAAC,CAiGpC"}

package/dist/runtime/query/sandbox-lifecycle.js

@@ -1,5 +1,5 @@
 const MAX_TIMER_DELAY_MS = 2_147_483_647;
-/** A sandbox release gets thirty seconds before the run stops waiting for it. */
+/** A sandbox release gets thirty seconds before the turn stops waiting for it. */
 export const DEFAULT_SANDBOX_TEARDOWN_TIMEOUT_MS = 30_000;
 export function resolveSandboxTeardownTimeoutMs(value) {
     const resolved = value ?? DEFAULT_SANDBOX_TEARDOWN_TIMEOUT_MS;
@@ -31,10 +31,10 @@ function notifyLateTeardown(notify, result) {
 /**
  * Release a sandbox under a fresh owner.
  *
- * The run signal is deliberately not an input: cleanup normally begins because
+ * The turn signal is deliberately not an input: cleanup normally begins because
  * that signal is already aborted. A private signal gives the implementation a
  * chance to stop its transport at the teardown deadline, while the independent
- * race keeps a third-party implementation that ignores it from pinning the run.
+ * race keeps a third-party implementation that ignores it from pinning the turn.
  */
 export async function teardownSandbox(sandbox, timeoutMs) {
     const controller = new AbortController();
@@ -66,7 +66,7 @@ export async function teardownSandbox(sandbox, timeoutMs) {
 /**
  * Acquire a sandbox without allowing foreign setup to outlive run authority.
  *
- * Cancellation or the run timeout settles this function even when a provider
+ * Cancellation or the turn timeout settles this function even when a provider
  * ignores the signal.
  * A handle that arrives later is never published and is released exactly once.
  * This proves host/run liveness and cleanup of every handle the provider

package/dist/runtime/query/sandbox-lifecycle.js.map

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

package/dist/runtime/query/session-storage.d.ts

@@ -0,0 +1,75 @@
+import { type SessionLocator, SessionPaths } from '../../session/paths.js';
+import { InMemorySessionTokenBudgetStore, type SessionTokenBudgetStore } from '../../store/budget/index.js';
+import { type CheckpointLogView, InMemorySessionCheckpointStore, type SessionCheckpointStore } from '../../store/checkpoint/index.js';
+import { InMemorySessionLog, type SessionLog } from '../../store/session-log/index.js';
+import type { ChildSessionStorage } from '../../types/agent/task.js';
+import type { SessionId } from '../../types/ids/index.js';
+/** What an in-memory session keeps beside its log. */
+interface HeldState {
+    readonly checkpoints: InMemorySessionCheckpointStore;
+    readonly tokenBudgets: InMemorySessionTokenBudgetStore;
+}
+/** Where one session's log, checkpoints, ledger and child sessions go. */
+export interface SessionStorage {
+    readonly log: SessionLog;
+    /** The project layout, when the session is on disk. */
+    readonly paths: SessionPaths | undefined;
+    /** `<session-id>/`, beside the log, when the log is on disk. */
+    readonly sessionDir: string | undefined;
+    readonly checkpoints: SessionCheckpointStore;
+    /** Ledgers of root turns, keyed by (rootSessionId, rootTurnId). */
+    readonly tokenBudget: SessionTokenBudgetStore;
+    /** What a delegated child session is told; `undefined` leaves it alone. */
+    readonly children: ChildSessionStorage | undefined;
+}
+export interface SessionStorageInput {
+    readonly sessionId: SessionId;
+    /** The delegating session, for a child session's default log location. */
+    readonly parentSessionId?: SessionId;
+    readonly sessionLog?: SessionLog;
+    readonly paths?: SessionPaths;
+    readonly checkpointStore?: SessionCheckpointStore;
+    readonly tokenBudgetStore?: SessionTokenBudgetStore;
+    /** The directory the project slug is derived from when no `paths` is given. */
+    readonly workingDirectory?: string;
+}
+/**
+ * The one answer to "where does this session's state live", read by every
+ * place that opens a session log, a checkpoint store or a token ledger.
+ *
+ * - **Log.** An explicit `sessionLog` wins. Otherwise the log at `paths`
+ *   (default: `SessionPaths` under `resolveNamzuHome()` for the working
+ *   directory's project).
+ * - **Checkpoints and ledger.** An explicit store wins. Otherwise a session
+ *   whose log is an {@link InMemorySessionLog} and which names no `paths`
+ *   keeps both in memory, beside its log; every other session keeps them on
+ *   disk under `<session-id>/checkpoints/` and `<root-session-id>/budgets/`.
+ * - **Children.** An in-memory session hands that choice to its delegated
+ *   children, so a child does not fall back to a disk tree its parent never
+ *   asked for; a session on disk hands down its layout, so its children's
+ *   logs nest under its session directory.
+ */
+export declare function resolveSessionStorage(input: SessionStorageInput): Promise<SessionStorage>;
+/**
+ * The locator of a session named without its log: a root session sits at the
+ * top of the project; a child session sits under its parent, wherever the
+ * parent is. The parent's own place is found on disk, so a grandchild nests
+ * under every ancestor and not beside its parent at the top level. A parent
+ * with no log in the layout yet is taken to be a root session.
+ */
+export declare function locateSession(paths: SessionPaths, sessionId: SessionId, parentSessionId?: SessionId): Promise<SessionLocator>;
+/** `SessionPaths` for the working directory's project under `resolveNamzuHome()`. */
+export declare function defaultSessionPaths(workingDirectory?: string): Promise<SessionPaths>;
+/**
+ * @internal What an in-memory session holds beside its log right now, for
+ * tests that assert where its state went.
+ */
+export declare function heldSessionState(log: InMemorySessionLog): HeldState | undefined;
+/**
+ * The checkpoint store's view of one session log: whether a checkpoint was
+ * committed, whether the prefix it covers is intact, and which checkpoints
+ * an open decision still references.
+ */
+export declare function checkpointLogView(log: SessionLog): CheckpointLogView;
+export {};
+//# sourceMappingURL=session-storage.d.ts.map

package/dist/runtime/query/session-storage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-storage.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/session-storage.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,cAAc,EAAE,YAAY,EAAiB,MAAM,wBAAwB,CAAA;AACzF,OAAO,EAEN,+BAA+B,EAC/B,KAAK,uBAAuB,EAC5B,MAAM,6BAA6B,CAAA;AACpC,OAAO,EACN,KAAK,iBAAiB,EAGtB,8BAA8B,EAC9B,KAAK,sBAAsB,EAC3B,MAAM,iCAAiC,CAAA;AACxC,OAAO,EAGN,kBAAkB,EAClB,KAAK,UAAU,EACf,MAAM,kCAAkC,CAAA;AACzC,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAA;AACpE,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,0BAA0B,CAAA;AAGvE,sDAAsD;AACtD,UAAU,SAAS;IAClB,QAAQ,CAAC,WAAW,EAAE,8BAA8B,CAAA;IACpD,QAAQ,CAAC,YAAY,EAAE,+BAA+B,CAAA;CACtD;AAKD,0EAA0E;AAC1E,MAAM,WAAW,cAAc;IAC9B,QAAQ,CAAC,GAAG,EAAE,UAAU,CAAA;IACxB,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,YAAY,GAAG,SAAS,CAAA;IACxC,gEAAgE;IAChE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,SAAS,CAAA;IACvC,QAAQ,CAAC,WAAW,EAAE,sBAAsB,CAAA;IAC5C,mEAAmE;IACnE,QAAQ,CAAC,WAAW,EAAE,uBAAuB,CAAA;IAC7C,2EAA2E;IAC3E,QAAQ,CAAC,QAAQ,EAAE,mBAAmB,GAAG,SAAS,CAAA;CAClD;AAED,MAAM,WAAW,mBAAmB;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,0EAA0E;IAC1E,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,CAAA;IACpC,QAAQ,CAAC,UAAU,CAAC,EAAE,UAAU,CAAA;IAChC,QAAQ,CAAC,KAAK,CAAC,EAAE,YAAY,CAAA;IAC7B,QAAQ,CAAC,eAAe,CAAC,EAAE,sBAAsB,CAAA;IACjD,QAAQ,CAAC,gBAAgB,CAAC,EAAE,uBAAuB,CAAA;IACnD,+EAA+E;IAC/E,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAA;CAClC;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,qBAAqB,CAAC,KAAK,EAAE,mBAAmB,GAAG,OAAO,CAAC,cAAc,CAAC,CAqC/F;AA+CD;;;;;;GAMG;AACH,wBAAsB,aAAa,CAClC,KAAK,EAAE,YAAY,EACnB,SAAS,EAAE,SAAS,EACpB,eAAe,CAAC,EAAE,SAAS,GACzB,OAAO,CAAC,cAAc,CAAC,CAMzB;AAuDD,qFAAqF;AACrF,wBAAsB,mBAAmB,CAAC,gBAAgB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC,CAI1F;AAaD;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,kBAAkB,GAAG,SAAS,GAAG,SAAS,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,UAAU,GAAG,iBAAiB,CAqCpE"}

package/dist/runtime/query/session-storage.js

@@ -0,0 +1,236 @@
+import { readdir, realpath } from 'node:fs/promises';
+import { basename, dirname, join, resolve } from 'node:path';
+import { resolveNamzuHome } from '../../session/home.js';
+import { SessionPaths, ensureProject } from '../../session/paths.js';
+import { DiskSessionTokenBudgetStore, InMemorySessionTokenBudgetStore, } from '../../store/budget/index.js';
+import { DiskSessionCheckpointStore, InMemorySessionCheckpointStore, } from '../../store/checkpoint/index.js';
+import { DiskSessionLog, InMemorySessionLog, } from '../../store/session-log/index.js';
+import { asSessionId, isEntityId } from '../../utils/id.js';
+/** Keyed by the log's bytes, so a reopened instance of one log finds the same stores. */
+const held = new WeakMap();
+/**
+ * The one answer to "where does this session's state live", read by every
+ * place that opens a session log, a checkpoint store or a token ledger.
+ *
+ * - **Log.** An explicit `sessionLog` wins. Otherwise the log at `paths`
+ *   (default: `SessionPaths` under `resolveNamzuHome()` for the working
+ *   directory's project).
+ * - **Checkpoints and ledger.** An explicit store wins. Otherwise a session
+ *   whose log is an {@link InMemorySessionLog} and which names no `paths`
+ *   keeps both in memory, beside its log; every other session keeps them on
+ *   disk under `<session-id>/checkpoints/` and `<root-session-id>/budgets/`.
+ * - **Children.** An in-memory session hands that choice to its delegated
+ *   children, so a child does not fall back to a disk tree its parent never
+ *   asked for; a session on disk hands down its layout, so its children's
+ *   logs nest under its session directory.
+ */
+export async function resolveSessionStorage(input) {
+    const inMemory = input.sessionLog instanceof InMemorySessionLog && input.paths === undefined;
+    const paths = input.paths ?? (inMemory ? undefined : await defaultSessionPaths(input.workingDirectory));
+    // A disk log in this layout knows its place from its path. Any other log
+    // is placed like a session named without a log, under its parent wherever
+    // that is, so its checkpoints never land at the top: that includes a log
+    // kept outside the layout whose file name alone reads as a place in one.
+    const locator = paths
+        ? ((await placeInLayout(paths, input.sessionLog)) ??
+            (await locateSession(paths, input.sessionId, input.parentSessionId)))
+        : undefined;
+    const log = input.sessionLog ?? DiskSessionLog.at(paths, locator);
+    const state = inMemory ? heldState(log) : undefined;
+    const checkpoints = input.checkpointStore ??
+        state?.checkpoints ??
+        new DiskSessionCheckpointStore({
+            paths: paths,
+            log: checkpointLogView(log),
+            ...(locator ? { session: locator } : {}),
+        });
+    const tokenBudget = input.tokenBudgetStore ??
+        state?.tokenBudgets ??
+        new DiskSessionTokenBudgetStore({ paths: paths });
+    const children = inMemory
+        ? {
+            kind: 'memory',
+            ...(input.checkpointStore ? { checkpointStore: input.checkpointStore } : {}),
+        }
+        : paths
+            ? { kind: 'disk', paths }
+            : undefined;
+    const sessionDir = log instanceof DiskSessionLog ? log.sessionDir : undefined;
+    return { log, paths, sessionDir, checkpoints, tokenBudget, children };
+}
+/**
+ * Where `log` sits in `paths`'s layout, read from its path: its locator, only
+ * when that locator's log in this layout is the very file it writes.
+ * `sessionLocatorFromLogFile` reads any `<id>.jsonl` as a place, because a log
+ * does not know which project it belongs to; a file outside this project (or
+ * one named for a place it is not at) is `undefined` here.
+ */
+async function placeInLayout(paths, log) {
+    if (!(log instanceof DiskSessionLog) || !log.locator)
+        return undefined;
+    // Canonical, not lexical. `NAMZU_HOME` reached through a symlinked home
+    // (`/home/me -> /data/me`) and a log opened by its real path name the same
+    // file with two spellings; comparing them with `resolve()` read that as a
+    // log outside the layout and placed a child's checkpoints under its parent
+    // a second time, beside the ones its own log already points at.
+    const [expected, actual] = await Promise.all([
+        canonicalPath(paths.sessionLog(log.locator)),
+        canonicalPath(log.file),
+    ]);
+    return expected === actual ? log.locator : undefined;
+}
+/**
+ * `path` with every symlink in its existing prefix resolved. A log is often
+ * placed before its first append, so the file (and even its session
+ * directory) may not exist yet: the deepest ancestor that does is
+ * canonicalized and the rest appended lexically, which cannot hide a link
+ * because nothing is there to be one. Falls back to `resolve()` when nothing
+ * on the path exists at all.
+ */
+async function canonicalPath(path) {
+    let existing = resolve(path);
+    let remainder = '';
+    for (;;) {
+        const found = await realpath(existing).catch(() => undefined);
+        if (found !== undefined)
+            return remainder ? join(found, remainder) : found;
+        const parent = dirname(existing);
+        if (parent === existing)
+            return resolve(path);
+        remainder = remainder ? join(basename(existing), remainder) : basename(existing);
+        existing = parent;
+    }
+}
+/**
+ * The locator of a session named without its log: a root session sits at the
+ * top of the project; a child session sits under its parent, wherever the
+ * parent is. The parent's own place is found on disk, so a grandchild nests
+ * under every ancestor and not beside its parent at the top level. A parent
+ * with no log in the layout yet is taken to be a root session.
+ */
+export async function locateSession(paths, sessionId, parentSessionId) {
+    if (!parentSessionId)
+        return { sessionId };
+    const parent = (await findSessionLocator(paths, parentSessionId)) ?? {
+        sessionId: parentSessionId,
+    };
+    return { sessionId, ancestors: [...(parent.ancestors ?? []), parent.sessionId] };
+}
+/** Deeper than any delegation tree a project allows; a guard against a cyclic tree on disk. */
+const MAX_SEARCH_DEPTH = 64;
+/**
+ * Where `sessionId`'s log is in the project's layout: at the top level, or in
+ * some session's `subagents/`, searched breadth first. `undefined` when no log
+ * of that session exists.
+ */
+async function findSessionLocator(paths, sessionId) {
+    const target = `${sessionId}.jsonl`;
+    let frontier = [];
+    const top = await listDirectory(paths.projectDir());
+    if (top.files.has(target))
+        return { sessionId };
+    for (const name of top.directories) {
+        if (isEntityId(name, 'session'))
+            frontier.push({ sessionId: asSessionId(name) });
+    }
+    for (let depth = 0; depth < MAX_SEARCH_DEPTH && frontier.length > 0; depth++) {
+        const next = [];
+        for (const parent of frontier) {
+            const children = await listDirectory(join(paths.sessionDir(parent), 'subagents'));
+            const ancestors = [...(parent.ancestors ?? []), parent.sessionId];
+            if (children.files.has(target))
+                return { sessionId, ancestors };
+            for (const name of children.directories) {
+                if (isEntityId(name, 'session'))
+                    next.push({ sessionId: asSessionId(name), ancestors });
+            }
+        }
+        frontier = next;
+    }
+    return undefined;
+}
+async function listDirectory(directory) {
+    try {
+        const entries = await readdir(directory, { withFileTypes: true });
+        return {
+            files: new Set(entries.filter((entry) => entry.isFile()).map((entry) => entry.name)),
+            directories: entries
+                .filter((entry) => entry.isDirectory())
+                .map((entry) => entry.name)
+                .sort(),
+        };
+    }
+    catch (error) {
+        const code = error.code;
+        if (code === 'ENOENT' || code === 'ENOTDIR')
+            return { files: new Set(), directories: [] };
+        throw error;
+    }
+}
+/** `SessionPaths` for the working directory's project under `resolveNamzuHome()`. */
+export async function defaultSessionPaths(workingDirectory) {
+    const home = resolveNamzuHome();
+    const project = await ensureProject({ home, cwd: workingDirectory ?? process.cwd() });
+    return new SessionPaths({ home, slug: project.slug });
+}
+function heldState(log) {
+    const current = held.get(log.medium);
+    if (current)
+        return current;
+    const next = {
+        checkpoints: new InMemorySessionCheckpointStore({ log: checkpointLogView(log) }),
+        tokenBudgets: new InMemorySessionTokenBudgetStore(),
+    };
+    held.set(log.medium, next);
+    return next;
+}
+/**
+ * @internal What an in-memory session holds beside its log right now, for
+ * tests that assert where its state went.
+ */
+export function heldSessionState(log) {
+    return held.get(log.medium);
+}
+/**
+ * The checkpoint store's view of one session log: whether a checkpoint was
+ * committed, whether the prefix it covers is intact, and which checkpoints
+ * an open decision still references.
+ */
+export function checkpointLogView(log) {
+    const own = (scope) => {
+        if (scope.sessionId !== log.sessionId) {
+            throw new Error(`This checkpoint store answers for session ${log.sessionId}, not ${scope.sessionId}.`);
+        }
+    };
+    return {
+        async verifyThrough(scope, throughSeq, throughSha256) {
+            own(scope);
+            const read = await log.readAll({ mode: 'tolerant', throughSeq });
+            const entry = read.entries.at(-1);
+            return entry?.pointer.seq === throughSeq && entry.pointer.sha256 === throughSha256;
+        },
+        async writtenDocSha256(scope, checkpointId) {
+            own(scope);
+            let found = null;
+            for await (const { record } of log.read({ mode: 'tolerant' })) {
+                if (record.type === 'checkpoint_written' && record.checkpointId === checkpointId) {
+                    found = record.docSha256;
+                }
+            }
+            return found;
+        },
+        async openDecisionCheckpoints(scope) {
+            own(scope);
+            const open = new Map();
+            for await (const { record } of log.read({ mode: 'tolerant' })) {
+                if (record.type === 'decision_requested')
+                    open.set(record.decisionId, record.checkpointId);
+                if (record.type === 'decision_resolved' || record.type === 'decision_expired') {
+                    open.delete(record.decisionId);
+                }
+            }
+            return open.values();
+        },
+    };
+}
+//# sourceMappingURL=session-storage.js.map