@namzu/sdk 43.0.0 → 44.1.0

package/dist/types/session/checkpoint.d.ts

@@ -0,0 +1,325 @@
+import { z } from 'zod';
+import type { WorkingStateSnapshot } from '../../compaction/wire.js';
+import type { SerializedSpanContext } from '../../telemetry/attributes.js';
+import type { CostInfo, TokenUsage } from '../common/index.js';
+import type { CheckpointId, MessageId, SessionId, TurnId } from '../ids/index.js';
+import type { TurnBudgetBinding } from './turn.js';
+/** Version of the checkpoint document. An older or unknown version is refused, never migrated. */
+export declare const CHECKPOINT_DOCUMENT_VERSION: 1;
+/**
+ * A checkpoint of one turn, stored at `<session-id>/checkpoints/<id>.json`.
+ *
+ * It holds NO messages. The context it restores is the fold of the session
+ * log from seq 1 through `throughSeq`, which equals the session's context at
+ * that seq because no other turn can interleave. `throughSha256` is the hash
+ * of the record at `throughSeq`, and the `checkpoint_written` record carries
+ * the document's own hash (`docSha256`): a restore refuses the checkpoint when
+ * either does not match.
+ */
+export interface Checkpoint {
+    readonly v: typeof CHECKPOINT_DOCUMENT_VERSION;
+    readonly kind: 'checkpoint';
+    readonly checkpointId: CheckpointId;
+    readonly sessionId: SessionId;
+    readonly turnId: TurnId;
+    readonly iteration: number;
+    readonly throughSeq: number;
+    readonly throughSha256: string;
+    readonly tokenUsage: TokenUsage;
+    readonly costInfo: CostInfo;
+    /** The ledger reference; the ledger itself stays authoritative. */
+    readonly budget?: {
+        readonly binding?: TurnBudgetBinding;
+        /** Present for non-durable accounts too; those need the live authority on resume. */
+        readonly accountId: string;
+    };
+    readonly guards: {
+        readonly iteration: number;
+        readonly elapsedMs: number;
+    };
+    /**
+     * Review corrections already consumed at this checkpoint, independent of
+     * compactable history: host structured-output review, prose-answer review
+     * and native structured-output correction.
+     */
+    readonly review: {
+        readonly structuredAttempts: number;
+        readonly answerAttempts: number;
+        readonly nativeStructuredAttempts: number;
+    };
+    /** The turn's current operator/goal/steering message, independent of compaction. */
+    readonly latestUserMessageId?: MessageId;
+    /** Compaction's accumulated working state, when compaction is enabled. */
+    readonly workingState?: WorkingStateSnapshot;
+    /** The trace the checkpoint was taken inside, so a resume continues it. */
+    readonly trace?: SerializedSpanContext;
+    /** When the turn was attributed (ISO-8601). Identical on every checkpoint of the turn. */
+    readonly turnCreatedAt: string;
+    /** When this checkpoint was written (ISO-8601). */
+    readonly createdAt: string;
+}
+export declare const TokenUsageSchema: z.ZodObject<{
+    promptTokens: z.ZodNumber;
+    completionTokens: z.ZodNumber;
+    totalTokens: z.ZodNumber;
+    cachedTokens: z.ZodNumber;
+    cacheWriteTokens: z.ZodNumber;
+    reasoningTokens: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens?: number | undefined;
+}, {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cachedTokens: number;
+    cacheWriteTokens: number;
+    reasoningTokens?: number | undefined;
+}>;
+export declare const CostInfoSchema: z.ZodObject<{
+    inputCostPer1M: z.ZodOptional<z.ZodNumber>;
+    outputCostPer1M: z.ZodOptional<z.ZodNumber>;
+    totalCost: z.ZodNumber;
+    cacheDiscount: z.ZodNumber;
+    unpricedTokens: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    totalCost: number;
+    cacheDiscount: number;
+    unpricedTokens: number;
+    inputCostPer1M?: number | undefined;
+    outputCostPer1M?: number | undefined;
+}, {
+    totalCost: number;
+    cacheDiscount: number;
+    unpricedTokens: number;
+    inputCostPer1M?: number | undefined;
+    outputCostPer1M?: number | undefined;
+}>;
+export declare const TurnBudgetBindingSchema: z.ZodObject<{
+    rootSessionId: z.ZodType<SessionId, z.ZodTypeDef, unknown>;
+    rootTurnId: z.ZodType<TurnId, z.ZodTypeDef, unknown>;
+    accountId: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    rootSessionId: string & import("../ids/brand.js").IdBrand<"SessionId">;
+    rootTurnId: string & import("../ids/brand.js").IdBrand<"TurnId">;
+    accountId: string;
+}, {
+    accountId: string;
+    rootSessionId?: unknown;
+    rootTurnId?: unknown;
+}>;
+export declare const CheckpointSchema: z.ZodObject<{
+    v: z.ZodLiteral<1>;
+    kind: z.ZodLiteral<"checkpoint">;
+    checkpointId: z.ZodType<CheckpointId, z.ZodTypeDef, unknown>;
+    sessionId: z.ZodType<SessionId, z.ZodTypeDef, unknown>;
+    turnId: z.ZodType<TurnId, z.ZodTypeDef, unknown>;
+    iteration: z.ZodNumber;
+    throughSeq: z.ZodNumber;
+    throughSha256: z.ZodString;
+    tokenUsage: z.ZodObject<{
+        promptTokens: z.ZodNumber;
+        completionTokens: z.ZodNumber;
+        totalTokens: z.ZodNumber;
+        cachedTokens: z.ZodNumber;
+        cacheWriteTokens: z.ZodNumber;
+        reasoningTokens: z.ZodOptional<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedTokens: number;
+        cacheWriteTokens: number;
+        reasoningTokens?: number | undefined;
+    }, {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedTokens: number;
+        cacheWriteTokens: number;
+        reasoningTokens?: number | undefined;
+    }>;
+    costInfo: z.ZodObject<{
+        inputCostPer1M: z.ZodOptional<z.ZodNumber>;
+        outputCostPer1M: z.ZodOptional<z.ZodNumber>;
+        totalCost: z.ZodNumber;
+        cacheDiscount: z.ZodNumber;
+        unpricedTokens: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        totalCost: number;
+        cacheDiscount: number;
+        unpricedTokens: number;
+        inputCostPer1M?: number | undefined;
+        outputCostPer1M?: number | undefined;
+    }, {
+        totalCost: number;
+        cacheDiscount: number;
+        unpricedTokens: number;
+        inputCostPer1M?: number | undefined;
+        outputCostPer1M?: number | undefined;
+    }>;
+    budget: z.ZodOptional<z.ZodObject<{
+        binding: z.ZodOptional<z.ZodObject<{
+            rootSessionId: z.ZodType<SessionId, z.ZodTypeDef, unknown>;
+            rootTurnId: z.ZodType<TurnId, z.ZodTypeDef, unknown>;
+            accountId: z.ZodString;
+        }, "strict", z.ZodTypeAny, {
+            rootSessionId: string & import("../ids/brand.js").IdBrand<"SessionId">;
+            rootTurnId: string & import("../ids/brand.js").IdBrand<"TurnId">;
+            accountId: string;
+        }, {
+            accountId: string;
+            rootSessionId?: unknown;
+            rootTurnId?: unknown;
+        }>>;
+        accountId: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        accountId: string;
+        binding?: {
+            rootSessionId: string & import("../ids/brand.js").IdBrand<"SessionId">;
+            rootTurnId: string & import("../ids/brand.js").IdBrand<"TurnId">;
+            accountId: string;
+        } | undefined;
+    }, {
+        accountId: string;
+        binding?: {
+            accountId: string;
+            rootSessionId?: unknown;
+            rootTurnId?: unknown;
+        } | undefined;
+    }>>;
+    guards: z.ZodObject<{
+        iteration: z.ZodNumber;
+        elapsedMs: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        iteration: number;
+        elapsedMs: number;
+    }, {
+        iteration: number;
+        elapsedMs: number;
+    }>;
+    review: z.ZodObject<{
+        structuredAttempts: z.ZodNumber;
+        answerAttempts: z.ZodNumber;
+        nativeStructuredAttempts: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        structuredAttempts: number;
+        answerAttempts: number;
+        nativeStructuredAttempts: number;
+    }, {
+        structuredAttempts: number;
+        answerAttempts: number;
+        nativeStructuredAttempts: number;
+    }>;
+    latestUserMessageId: z.ZodOptional<z.ZodType<MessageId, z.ZodTypeDef, unknown>>;
+    workingState: z.ZodOptional<z.ZodType<WorkingStateSnapshot, z.ZodTypeDef, WorkingStateSnapshot>>;
+    trace: z.ZodOptional<z.ZodType<SerializedSpanContext, z.ZodTypeDef, SerializedSpanContext>>;
+    turnCreatedAt: z.ZodString;
+    createdAt: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    kind: "checkpoint";
+    v: 1;
+    sessionId: string & import("../ids/brand.js").IdBrand<"SessionId">;
+    turnId: string & import("../ids/brand.js").IdBrand<"TurnId">;
+    review: {
+        structuredAttempts: number;
+        answerAttempts: number;
+        nativeStructuredAttempts: number;
+    };
+    checkpointId: string & import("../ids/brand.js").IdBrand<"CheckpointId">;
+    iteration: number;
+    throughSeq: number;
+    throughSha256: string;
+    tokenUsage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedTokens: number;
+        cacheWriteTokens: number;
+        reasoningTokens?: number | undefined;
+    };
+    costInfo: {
+        totalCost: number;
+        cacheDiscount: number;
+        unpricedTokens: number;
+        inputCostPer1M?: number | undefined;
+        outputCostPer1M?: number | undefined;
+    };
+    guards: {
+        iteration: number;
+        elapsedMs: number;
+    };
+    turnCreatedAt: string;
+    createdAt: string;
+    budget?: {
+        accountId: string;
+        binding?: {
+            rootSessionId: string & import("../ids/brand.js").IdBrand<"SessionId">;
+            rootTurnId: string & import("../ids/brand.js").IdBrand<"TurnId">;
+            accountId: string;
+        } | undefined;
+    } | undefined;
+    latestUserMessageId?: MessageId | undefined;
+    workingState?: WorkingStateSnapshot | undefined;
+    trace?: SerializedSpanContext | undefined;
+}, {
+    kind: "checkpoint";
+    v: 1;
+    review: {
+        structuredAttempts: number;
+        answerAttempts: number;
+        nativeStructuredAttempts: number;
+    };
+    iteration: number;
+    throughSeq: number;
+    throughSha256: string;
+    tokenUsage: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+        cachedTokens: number;
+        cacheWriteTokens: number;
+        reasoningTokens?: number | undefined;
+    };
+    costInfo: {
+        totalCost: number;
+        cacheDiscount: number;
+        unpricedTokens: number;
+        inputCostPer1M?: number | undefined;
+        outputCostPer1M?: number | undefined;
+    };
+    guards: {
+        iteration: number;
+        elapsedMs: number;
+    };
+    turnCreatedAt: string;
+    createdAt: string;
+    sessionId?: unknown;
+    turnId?: unknown;
+    checkpointId?: unknown;
+    budget?: {
+        accountId: string;
+        binding?: {
+            accountId: string;
+            rootSessionId?: unknown;
+            rootTurnId?: unknown;
+        } | undefined;
+    } | undefined;
+    latestUserMessageId?: unknown;
+    workingState?: WorkingStateSnapshot | undefined;
+    trace?: SerializedSpanContext | undefined;
+}>;
+/** Raised for a checkpoint document written by another version or another shape. */
+export declare class CheckpointDocumentError extends Error {
+    readonly name = "CheckpointDocumentError";
+}
+/**
+ * Parse a checkpoint document. A document from the run-era layout
+ * (`kind: 'run-checkpoint'`) or any other version is refused by name.
+ */
+export declare function parseCheckpoint(value: unknown): Checkpoint;
+//# sourceMappingURL=checkpoint.d.ts.map

package/dist/types/session/checkpoint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"checkpoint.d.ts","sourceRoot":"","sources":["../../../src/types/session/checkpoint.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAA;AACpE,OAAO,KAAK,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAA;AAE1E,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,oBAAoB,CAAA;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AACjF,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAA;AAElD,kGAAkG;AAClG,eAAO,MAAM,2BAA2B,EAAG,CAAU,CAAA;AAErD;;;;;;;;;GASG;AACH,MAAM,WAAW,UAAU;IAC1B,QAAQ,CAAC,CAAC,EAAE,OAAO,2BAA2B,CAAA;IAC9C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAA;IAC3B,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAA;IACnC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAA;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAA;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAA;IAC/B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAA;IAC3B,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE;QACjB,QAAQ,CAAC,OAAO,CAAC,EAAE,iBAAiB,CAAA;QACpC,qFAAqF;QACrF,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAC1B,CAAA;IACD,QAAQ,CAAC,MAAM,EAAE;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAA;IAC3E;;;;OAIG;IACH,QAAQ,CAAC,MAAM,EAAE;QAChB,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAA;QACnC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAA;QAC/B,QAAQ,CAAC,wBAAwB,EAAE,MAAM,CAAA;KACzC,CAAA;IACD,oFAAoF;IACpF,QAAQ,CAAC,mBAAmB,CAAC,EAAE,SAAS,CAAA;IACxC,0EAA0E;IAC1E,QAAQ,CAAC,YAAY,CAAC,EAAE,oBAAoB,CAAA;IAC5C,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,CAAC,EAAE,qBAAqB,CAAA;IACtC,0FAA0F;IAC1F,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,mDAAmD;IACnD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAC1B;AAYD,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;EASnB,CAAA;AAEV,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;EAQjB,CAAA;AAEV,eAAO,MAAM,uBAAuB;;;;;;;;;;;;EAM1B,CAAA;AAEV,eAAO,MAAM,gBAAgB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAgCnB,CAAA;AAMV,oFAAoF;AACpF,qBAAa,uBAAwB,SAAQ,KAAK;IACjD,SAAkB,IAAI,6BAA4B;CAClD;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,UAAU,CAmB1D"}

package/dist/types/session/checkpoint.js

@@ -0,0 +1,100 @@
+import { z } from 'zod';
+import { isEntityId } from '../../utils/id.js';
+/** Version of the checkpoint document. An older or unknown version is refused, never migrated. */
+export const CHECKPOINT_DOCUMENT_VERSION = 1;
+const count = z.number().int().nonnegative().safe();
+const sha256 = z.string().regex(/^[a-f0-9]{64}$/);
+const iso = z.string().datetime({ offset: false });
+/** Annotated with the id's own alias, so declarations name it rather than expanding its brand. */
+function id(kind) {
+    return z.custom((value) => isEntityId(value, kind), {
+        message: `expected a ${kind} id (UUID)`,
+    });
+}
+export const TokenUsageSchema = z
+    .object({
+    promptTokens: count,
+    completionTokens: count,
+    totalTokens: count,
+    cachedTokens: count,
+    cacheWriteTokens: count,
+    reasoningTokens: count.optional(),
+})
+    .strict();
+export const CostInfoSchema = z
+    .object({
+    inputCostPer1M: z.number().nonnegative().optional(),
+    outputCostPer1M: z.number().nonnegative().optional(),
+    totalCost: z.number().nonnegative(),
+    cacheDiscount: z.number(),
+    unpricedTokens: count,
+})
+    .strict();
+export const TurnBudgetBindingSchema = z
+    .object({
+    rootSessionId: id('session'),
+    rootTurnId: id('turn'),
+    accountId: z.string().min(1),
+})
+    .strict();
+export const CheckpointSchema = z
+    .object({
+    v: z.literal(CHECKPOINT_DOCUMENT_VERSION),
+    kind: z.literal('checkpoint'),
+    checkpointId: id('checkpoint'),
+    sessionId: id('session'),
+    turnId: id('turn'),
+    iteration: count,
+    throughSeq: count.positive(),
+    throughSha256: sha256,
+    tokenUsage: TokenUsageSchema,
+    costInfo: CostInfoSchema,
+    budget: z
+        .object({ binding: TurnBudgetBindingSchema.optional(), accountId: z.string().min(1) })
+        .strict()
+        .optional(),
+    guards: z.object({ iteration: count, elapsedMs: count }).strict(),
+    review: z
+        .object({
+        structuredAttempts: count,
+        answerAttempts: count,
+        nativeStructuredAttempts: count,
+    })
+        .strict(),
+    latestUserMessageId: id('message').optional(),
+    // Each has its own validator where it is restored; the document only
+    // requires an object.
+    workingState: z.custom(isPlainObject).optional(),
+    trace: z.custom(isPlainObject).optional(),
+    turnCreatedAt: iso,
+    createdAt: iso,
+})
+    .strict();
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** Raised for a checkpoint document written by another version or another shape. */
+export class CheckpointDocumentError extends Error {
+    name = 'CheckpointDocumentError';
+}
+/**
+ * Parse a checkpoint document. A document from the run-era layout
+ * (`kind: 'run-checkpoint'`) or any other version is refused by name.
+ */
+export function parseCheckpoint(value) {
+    if (isPlainObject(value)) {
+        const record = value;
+        if (record.kind !== undefined && record.kind !== 'checkpoint') {
+            throw new CheckpointDocumentError(`Not a session checkpoint: kind ${JSON.stringify(record.kind)}. Checkpoints from earlier releases are not read.`);
+        }
+        if (record.v !== CHECKPOINT_DOCUMENT_VERSION) {
+            throw new CheckpointDocumentError(`Unsupported checkpoint version ${JSON.stringify(record.v)}; this release reads version ${CHECKPOINT_DOCUMENT_VERSION}.`);
+        }
+    }
+    const parsed = CheckpointSchema.safeParse(value);
+    if (!parsed.success) {
+        throw new CheckpointDocumentError(`Invalid checkpoint document: ${parsed.error.message}`);
+    }
+    return parsed.data;
+}
+//# sourceMappingURL=checkpoint.js.map

package/dist/types/session/checkpoint.js.map

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

package/dist/types/session/config.d.ts

@@ -0,0 +1,199 @@
+import type { SessionTokenBudget } from '../../store/budget/index.js';
+import type { SessionCheckpointStore } from '../../store/checkpoint/index.js';
+import type { SessionLog } from '../../store/session-log/index.js';
+import type { ModelPricing } from '../../utils/cost.js';
+import type { Logger } from '../../utils/logger.js';
+import type { SessionId, TenantId, TurnId } from '../ids/index.js';
+import type { PermissionMode } from '../permission/index.js';
+import type { ProjectId, TopicId } from './ids.js';
+/** The configuration one turn runs with. */
+export interface TurnConfig {
+    model: string;
+    /** Total turn duration in milliseconds; 0 disables the turn deadline. */
+    timeoutMs: number;
+    /**
+     * Maximum silence between provider stream chunks, in milliseconds.
+     *
+     * Defaults to five minutes at the `query()` boundary. This is distinct
+     * from `timeoutMs`, which is checked between agent iterations and cannot
+     * settle a provider iterator whose pending `next()` never returns. Set
+     * `0` to retain unbounded stream silence. Positive values must be integer
+     * milliseconds accepted by the platform timer.
+     */
+    streamIdleTimeoutMs?: number;
+    /**
+     * Maximum accumulated inline image/document payload on one provider request.
+     *
+     * Defaults to 24 MiB. The budget is shared by user attachments and rich
+     * tool-result blocks. When history exceeds it, the provider-bound projection
+     * replaces the oldest values with model-visible omission markers; the turn's
+     * canonical messages and durable evidence remain unchanged. Set `0` to keep
+     * the prior unbounded behaviour.
+     */
+    maxRequestRichContentBytes?: number;
+    maxResponseTokens?: number;
+    /**
+     * Extended-thinking request, forwarded on every model call in the turn.
+     *
+     * Drivers that do not support it ignore the field. Note that a provider
+     * rejects temperature/top_p/top_k while thinking is enabled, so the
+     * driver omits them rather than sending a request it knows will 400.
+     */
+    thinking?: import('../provider/index.js').ThinkingConfig;
+    /**
+     * How much work the model should spend on each call in the turn.
+     *
+     * A SIBLING of {@link TurnConfig.thinking}, not a field inside it.
+     * On some models the two are independent controls that apply together —
+     * effort shapes the answer while a budget sets thinking depth — so
+     * nesting one inside the other would make that combination unsayable.
+     *
+     * The failure this closes is the one this codebase keeps finding: the
+     * field existed on the provider params, a driver already read it and
+     * wrote it to the wire, and nothing in the kernel ever set it. So a
+     * caller could not reach it at all, and the symptom — every request
+     * going out at the model's default — reads as "this model ignores
+     * effort" rather than "nobody plumbed it through".
+     *
+     * Turn-level rather than per-step, deliberately. It is a property of what
+     * the turn is FOR, and a value that moves between steps buys a different
+     * answer shape at the cost of the prompt-cache prefix on every step that
+     * changes it.
+     *
+     * A driver that cannot honour it REFUSES rather than dropping it, on the
+     * same reasoning as `thinking`: paying for a turn you believe was
+     * high-effort and silently was not is worse than a startup error.
+     */
+    effort?: import('../provider/index.js').ReasoningEffort;
+    /** Provider-hosted search for this turn. Explicit opt-in; no local network permission. */
+    webSearch?: import('../provider/index.js').ChatCompletionParams['webSearch'];
+    /** Cumulative parent-and-descendant tokens; 0 is unlimited with usage accounting. */
+    tokenBudget: number;
+    costLimitUsd?: number;
+    /** Main-loop iterations; 0 disables this guard. Omitted defaults depend on the entry point. */
+    maxIterations?: number;
+    temperature?: number;
+    env?: Record<string, string>;
+    permissionMode?: PermissionMode;
+    sandbox?: {
+        timeoutMs?: number;
+        memoryLimitMb?: number;
+        maxProcesses?: number;
+        /**
+         * What the sandbox is rooted at — see `SandboxConfigSchema.workspace`.
+         * Absent means `'ephemeral'`: a fresh temp directory, which is the
+         * behaviour every sandboxed turn had before this existed.
+         */
+        workspace?: 'ephemeral' | 'working-directory';
+    };
+    /**
+     * Iteration-checkpoint cadence: create a checkpoint on every Nth
+     * tool-call iteration (iterations 1, 1+N, 1+2N, …). Default `1` —
+     * a checkpoint per iteration, today's behavior. Values < 1 are
+     * treated as 1. Off-cadence iterations also skip the HITL
+     * `iteration_checkpoint` park (there is no checkpoint id to park on).
+     * Tool-review and plan-approval checkpoints are unaffected — those
+     * exist to anchor a pending HITL decision, not for growth control.
+     */
+    checkpointEvery?: number;
+    /**
+     * After creating an iteration checkpoint, prune the turn's checkpoint
+     * set down to the newest N. Default `undefined` — never prune. A
+     * checkpoint holds no inline messages (its context is the fold of the
+     * session log through `throughSeq`), so it costs its own bookkeeping
+     * rather than a copy of the conversation, but the COUNT only ever grows
+     * unless a host bounds it here. The CLI does.
+     *
+     * Oldest-first by `createdAt`, across all of the turn's checkpoints — but
+     * a checkpoint an open decision references is never collected, whatever
+     * its age. Those rows are what `SessionIndex.listPendingDecisions` serves
+     * to an approval queue and what a sweep enumerates, so pruning
+     * briefly holds more than N while a park is outstanding; the next prune
+     * after the park resolves — by `unpark`, or by `expire` for one that ran
+     * out of time — collects them. A host that needs the bound to hold
+     * regardless should sweep expired parks itself.
+     */
+    pruneKeepLast?: number;
+    /**
+     * How long a human-in-the-loop park stays worth serving, in ms.
+     *
+     * Written onto the park as an ABSOLUTE deadline, so it survives the
+     * process that set it. Every timer in the SDK is an in-process
+     * `setTimeout` and the park-record delay is deliberately `unref`'d, so
+     * nothing in memory can outlive a redeploy: without this a turn parks for
+     * approval, the worker is replaced, nobody answers, and the checkpoint
+     * stays outstanding forever — every approval-queue reader keeps serving
+     * it and its workspace is never reclaimed.
+     *
+     * The turn timeout does not cover this. It is only checked between
+     * iterations and a park suspends mid-iteration, so a long-lived process
+     * hard-stops the turn immediately *after* the human finally approves,
+     * while across a restart the restored elapsed clock excludes parked time
+     * entirely — the same configuration producing two opposite outcomes.
+     *
+     * Expiry is enforced on READ (`findPendingCheckpoint` skips an expired
+     * park) and by a host sweep (`listExpiredParks` + `CheckpointManager
+     * .expire`). An out-of-process timer stays a host concern, consistent
+     * with the same decision made for retention.
+     *
+     * Default `undefined` — no deadline, today's behaviour.
+     */
+    hitlParkTtlMs?: number;
+    /**
+     * Override the logger a turn's log lines derive from.
+     *
+     * This is an override of the SOURCE, not a substitute for correlation:
+     * `TurnContextFactory.buildLogger` always calls `.child()` on whichever
+     * logger this resolves to, so a host-supplied logger still gains
+     * `namzu.turn.id`, `sessionId`, `threadId`, `projectId` and `tenantId` —
+     * the same binding the process default gets. A host that wants its own
+     * sink, format or destination threaded through every record a turn
+     * produces sets this once; a host that wants the process default
+     * (`getRootLogger()`) sets nothing, which is what absent has always
+     * meant.
+     */
+    logger?: Logger;
+}
+/**
+ * Config for {@link import('../../manager/session/turn-recorder.js').TurnRecorder}.
+ *
+ * `sessionId`, `topicId`, `tenantId` and `projectId` are required: every
+ * turn is attributed across the full scope (Tenant → Project → Topic →
+ * Session → Turn). The recorder appends records to `sessionLog` under the
+ * session lease; it writes no `run.json`, `messages.json` or `report.md`.
+ */
+export interface TurnRecorderConfig {
+    /** The ledger this turn and its child sessions spend from, keyed by (rootSessionId, rootTurnId). */
+    budget?: SessionTokenBudget;
+    sessionId: SessionId;
+    turnId: TurnId;
+    agentId: string;
+    agentName: string;
+    turnConfig: TurnConfig;
+    providerId: string;
+    pricing?: ModelPricing;
+    log: Logger;
+    topicId: TopicId;
+    tenantId: TenantId;
+    projectId: ProjectId;
+    /** Present on a child session's turn: the parent session that delegated it. */
+    parentSessionId?: SessionId;
+    /** Present on a child session's turn: the parent turn whose tool call spawned the child. */
+    parentTurnId?: TurnId;
+    depth?: number;
+    /** The session log the turn's records are appended to. */
+    sessionLog: SessionLog;
+    /**
+     * Optional checkpoint persistence override. Defaults to the disk layout
+     * under `<session-id>/checkpoints/`; hosts inject a scope-keyed backend here.
+     */
+    checkpointStore?: SessionCheckpointStore;
+}
+export interface LimitCheckerConfig {
+    tokenBudget: number;
+    timeoutMs: number;
+    costLimitUsd?: number;
+    maxIterations: number;
+    budgetWarningThreshold: number;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/types/session/config.d.ts.map

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

package/dist/types/session/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../../../src/types/session/config.ts"],"names":[],"mappings":""}

package/dist/types/session/derive-status.d.ts

@@ -0,0 +1,28 @@
+import type { PendingDecision } from '../hitl/index.js';
+import type { TurnExecutionStatus, TurnStatus } from './turn.js';
+/**
+ * Project what the SDK records about a turn onto the session-layer
+ * {@link TurnStatus}.
+ *
+ * `Turn.status` is a {@link TurnExecutionStatus} — six values, none of which can
+ * say "a human owes this turn an answer". `TurnStatus` has the vocabulary for
+ * that and is consumed by session-status derivation and by handoff gating,
+ * but nothing in the repo ever produced it: a host implementing a resolver
+ * had to invent the projection, and the two `awaiting_hitl*` variants in
+ * particular had no producer at all. `awaiting_hitl_resolution` documented
+ * a "persisted wait after a HITL timeout" for a timeout nothing could
+ * raise.
+ *
+ * The park record is the missing input. It is durable, it is what an
+ * approval queue already reads, and it carries the deadline that separates
+ * "waiting" from "waited too long".
+ */
+export declare function deriveTurnStatus(input: {
+    /** What the turn itself recorded. */
+    readonly status: TurnExecutionStatus;
+    /** The turn's outstanding park, if it has one. */
+    readonly park?: PendingDecision;
+    /** Injectable for tests; defaults to now. */
+    readonly now?: number;
+}): TurnStatus;
+//# sourceMappingURL=derive-status.d.ts.map