@namzu/sdk 1.0.0 → 1.2.0

package/src/types/run/checkpoint-store.ts

@@ -0,0 +1,72 @@
+/**
+ * CheckpointStore — persistence contract for iteration checkpoints.
+ *
+ * Mirrors the {@link import('../session/store.js').SessionStore} precedent:
+ * a narrow interface the kernel consumes, with the built-in disk layout as
+ * the default implementation and host-injected backends (e.g. Postgres) as
+ * drop-in replacements. Every accessor takes an explicit
+ * {@link CheckpointRunScope} so a shared backend can key rows by the full
+ * five-layer attribution (Convention #17) instead of a filesystem path.
+ */
+
+import type { CheckpointId, IterationCheckpoint } from '../hitl/index.js'
+import type { RunId, SessionId, TenantId } from '../ids/index.js'
+import type { ProjectId } from '../session/ids.js'
+
+/**
+ * Identifies the run whose checkpoints are being addressed.
+ *
+ * The full Tenant → Project → Session → Run scope is required so shared
+ * backends can enforce isolation; the built-in
+ * {@link import('../../store/run/checkpoint-disk.js').DiskCheckpointStore}
+ * is path-addressed (its `baseDir` already encodes project/session) and
+ * only consults `runId`/`parentRunId` for directory layout.
+ */
+export interface CheckpointRunScope {
+	/** Isolation boundary (Convention #17). */
+	tenantId: TenantId
+	/** Long-lived goal scope the run belongs to. */
+	projectId: ProjectId
+	/** Session the run is attributed to. */
+	sessionId: SessionId
+	/** Run whose checkpoints are addressed. */
+	runId: RunId
+	/**
+	 * Present for sub-runs. Hierarchical stores may use it for layout (the
+	 * disk store nests sub-run directories under
+	 * `<parentRunId>/children/<runId>`); flat stores can ignore it.
+	 */
+	parentRunId?: RunId
+}
+
+/**
+ * Persistence contract consumed by
+ * {@link import('../../runtime/query/checkpoint.js').CheckpointManager} and
+ * the replay entry points (`listCheckpoints` / `prepareReplayState`).
+ *
+ * Read accessors return `null` / an empty array when nothing exists for the
+ * supplied scope — callers branch on missing explicitly, never on a thrown
+ * not-found error. `deleteCheckpoint` is idempotent: deleting an absent
+ * checkpoint succeeds as a no-op (mirrors the disk store's ENOENT
+ * swallowing).
+ */
+export interface CheckpointStore {
+	/** Persist one checkpoint. Overwrites an existing checkpoint with the same id. */
+	writeCheckpoint(scope: CheckpointRunScope, checkpoint: IterationCheckpoint): Promise<void>
+
+	/** Load a single checkpoint by id. Returns `null` when it does not exist. */
+	readCheckpoint(
+		scope: CheckpointRunScope,
+		checkpointId: CheckpointId,
+	): Promise<IterationCheckpoint | null>
+
+	/**
+	 * All checkpoints for the run, sorted by `createdAt` ascending (the
+	 * ordering the disk store guarantees and `CheckpointManager.prune`
+	 * relies on for oldest-first deletion).
+	 */
+	listCheckpoints(scope: CheckpointRunScope): Promise<IterationCheckpoint[]>
+
+	/** Delete a checkpoint by id. Absent checkpoints succeed as a no-op. */
+	deleteCheckpoint(scope: CheckpointRunScope, checkpointId: CheckpointId): Promise<void>
+}

package/src/types/run/config.ts

@@ -3,6 +3,7 @@ import type { Logger } from '../../utils/logger.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { PermissionMode } from '../permission/index.js'
 import type { ProjectId, ThreadId } from '../session/ids.js'
+import type { CheckpointStore } from './checkpoint-store.js'
 
 export interface AgentRunConfig {
 	model: string
@@ -19,6 +20,27 @@ export interface AgentRunConfig {
 		memoryLimitMb?: number
 		maxProcesses?: number
 	}
+
+	/**
+	 * 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 run's checkpoint
+	 * set down to the newest N (oldest-first deletion across ALL of the
+	 * run's checkpoints, including tool-review/plan ones). Default
+	 * `undefined` — never prune, today's behavior. Each checkpoint copies
+	 * the full message array, so long tool-heavy runs grow O(iterations ×
+	 * history) without this.
+	 */
+	pruneKeepLast?: number
 }
 
 /**
@@ -45,6 +67,14 @@ export interface RunPersistenceConfig {
 	parentRunId?: RunId
 
 	depth?: number
+
+	/**
+	 * Optional checkpoint persistence override. Defaults to the disk
+	 * layout under `outputDir` (a
+	 * {@link import('../../store/run/checkpoint-disk.js').DiskCheckpointStore});
+	 * hosts inject a scope-keyed backend (e.g. Postgres) here.
+	 */
+	checkpointStore?: CheckpointStore
 }
 
 export interface RunStoreConfig {

package/src/types/run/events.ts

@@ -99,6 +99,19 @@ type CoreRunEvent =
 	  }
 	| { type: 'run_completed'; runId: RunId; result: string }
 	| { type: 'run_failed'; runId: RunId; error: string }
+	// Additive 2026-07 (provider capability negotiation): emitted once per
+	// run when the request asks for something the provider DRIVER declared
+	// it cannot do — tools registered against a no-tools driver (tool
+	// surfaces stripped so the model is never told about uncallable
+	// tools), or image attachments against a no-vision driver (attachments
+	// dropped). Hosts surface these so degradation is visible, not silent.
+	| {
+			type: 'capability_warning'
+			runId: RunId
+			capability: 'tools' | 'vision'
+			providerId: string
+			message: string
+	  }
 	| {
 			type: 'token_usage_updated'
 			runId: RunId

package/src/types/run/index.ts

@@ -1,5 +1,6 @@
 export * from './stop-reason.js'
 export * from './config.js'
+export * from './checkpoint-store.js'
 export * from './entity.js'
 export * from './replay.js'
 // Domain `RunStatus` (session-hierarchy.md §4.6 state machine). Safe to

package/src/version.ts

@@ -1,6 +1,28 @@
-import { createRequire } from 'node:module'
+import { readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
 
-const require = createRequire(import.meta.url)
-const pkg = require('../package.json') as { version: string }
+/**
+ * The SDK's package version, read from package.json relative to this module.
+ *
+ * Wrapped in try/catch (mirroring the CLI's readPackageVersion): a bundler
+ * like esbuild collapses the whole dist tree into a single file, so at runtime
+ * `../package.json` no longer resolves next to the bundle. Without the guard,
+ * this module's top-level read throws at import time and takes the entire
+ * process down — which is exactly what broke the bundled desktop runtime
+ * (`Cannot find module '../package.json'` on any code path that touches the
+ * SDK runtime). The version string is cosmetic, so a placeholder is fine.
+ */
+function readVersion(): string {
+	try {
+		const here = dirname(fileURLToPath(import.meta.url))
+		const pkg = JSON.parse(readFileSync(join(here, '..', 'package.json'), 'utf8')) as {
+			version?: unknown
+		}
+		return typeof pkg.version === 'string' ? pkg.version : '0.0.0'
+	} catch {
+		return '0.0.0'
+	}
+}
 
-export const VERSION: string = pkg.version
+export const VERSION: string = readVersion()

package/dist/runtime/query/continuation.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"continuation.d.ts","sourceRoot":"","sources":["../../../src/runtime/query/continuation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,8BAA8B,mHACiE,CAAA"}

package/dist/runtime/query/continuation.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"continuation.js","sourceRoot":"","sources":["../../../src/runtime/query/continuation.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,8BAA8B,GAC1C,2GAA2G,CAAA"}