@namzu/sdk 1.1.0 → 1.3.0

package/src/types/provider/config.ts

@@ -35,10 +35,28 @@ export interface MockProviderConfig {
 	responseDelayMs?: number
 }
 
+/**
+ * What a provider DRIVER actually does with the request — not what the
+ * vendor API could theoretically support. A driver that never reads
+ * `params.tools` declares `supportsTools: false` even if the backing
+ * service has a tools endpoint; a driver that drops `attachments`
+ * declares `supportsVision: false` even for a multimodal model.
+ *
+ * The query runtime consults these before each run (see
+ * `resolveProviderCapabilities` in `provider/capabilities.ts`) so
+ * degradation is loud instead of silent.
+ */
 export interface ProviderCapabilities {
 	supportsTools: boolean
 	supportsStreaming: boolean
 	supportsFunctionCalling: boolean
+	/**
+	 * Whether the driver maps user-message image `attachments` into the
+	 * provider request. Optional for compatibility with pre-existing
+	 * declarations: absent ⇒ treated as vision-capable (permissive
+	 * default — the runtime only warns when a driver explicitly says no).
+	 */
+	supportsVision?: boolean
 	maxOutputTokens?: number
 }
 
@@ -52,4 +70,40 @@ export interface RegisterOptions {
 	replace?: boolean
 }
 
+/**
+ * What a lazy loader must resolve to: a factory that constructs the
+ * provider, plus (optionally) the provider package's authoritative
+ * capability declaration resolved at load time.
+ *
+ * Designed so a host can map a dynamic import in one line:
+ *
+ * ```ts
+ * ProviderRegistry.registerLazy('anthropic', async () => {
+ *   const m = await import('@namzu/anthropic')
+ *   return { create: (c) => new m.AnthropicProvider(c), capabilities: m.ANTHROPIC_CAPABILITIES }
+ * })
+ * ```
+ */
+export interface LazyProviderModule<C = unknown> {
+	create: (config: C) => LLMProvider
+	/**
+	 * Authoritative type-level capabilities shipped by the loaded module.
+	 * When present, replaces any registration-time hint in the registry.
+	 */
+	capabilities?: ProviderCapabilities
+}
+
+export type LazyProviderLoader<C = unknown> = () => Promise<LazyProviderModule<C>>
+
+export interface RegisterLazyOptions extends RegisterOptions {
+	/**
+	 * Pre-load capability HINT so `ProviderRegistry.getCapabilities(type)`
+	 * can answer without triggering the loader. Precedence (weakest first):
+	 * this hint → the loaded module's `capabilities` → the constructed
+	 * instance's own `LLMProvider.capabilities` (what the query runtime
+	 * resolves via `resolveProviderCapabilities` and actually respects).
+	 */
+	capabilities?: ProviderCapabilities
+}
+
 export type LLMProviderConstructor<C = unknown> = new (config: C) => LLMProvider

package/src/types/provider/index.ts

@@ -16,5 +16,8 @@ export type {
 	ProviderCapabilities,
 	ProviderFactoryResult,
 	RegisterOptions,
+	LazyProviderModule,
+	LazyProviderLoader,
+	RegisterLazyOptions,
 	LLMProviderConstructor,
 } from './config.js'

package/src/types/provider/interface.ts

@@ -1,6 +1,7 @@
 import type { DoctorCheckResult } from '../doctor/index.js'
 
 import type { ChatCompletionParams } from './chat.js'
+import type { ProviderCapabilities } from './config.js'
 import type { ModelInfo } from './model.js'
 import type { StreamChunk } from './stream.js'
 
@@ -8,6 +9,16 @@ export interface LLMProvider {
 	readonly id: string
 	readonly name: string
 
+	/**
+	 * Honest declaration of what this DRIVER does with the request
+	 * (tools passed through? attachments mapped?) — not what the vendor
+	 * API supports. Optional so third-party providers that predate the
+	 * field keep working: the runtime resolves an absent declaration to
+	 * {@link import('../../provider/capabilities.js').PERMISSIVE_PROVIDER_CAPABILITIES},
+	 * i.e. today's behavior (assume everything works, never warn).
+	 */
+	readonly capabilities?: ProviderCapabilities
+
 	/**
 	 * The single LLM entry point. Returns an async iterable of
 	 * {@link StreamChunk} carrying text deltas, tool-call argument

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/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"}