@namzu/sdk 1.1.0 → 1.3.0

package/dist/types/run/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/run/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,wEAAwE;AACxE,4EAA4E;AAC5E,0EAA0E;AAC1E,sBAAsB;AACtB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAQ9B,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/types/run/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAA;AAChC,cAAc,aAAa,CAAA;AAC3B,cAAc,uBAAuB,CAAA;AACrC,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,wEAAwE;AACxE,4EAA4E;AAC5E,0EAA0E;AAC1E,sBAAsB;AACtB,cAAc,aAAa,CAAA;AAC3B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,gBAAgB,CAAA;AAQ9B,OAAO,EAAE,wBAAwB,EAAE,MAAM,qBAAqB,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@namzu/sdk",
-  "version": "1.1.0",
+  "version": "1.3.0",
   "description": "Open-source AI agent SDK with a built-in runtime. Nothing between you and your agents.",
   "license": "FSL-1.1-MIT",
   "type": "module",

package/src/bridge/a2a/mapper.ts

@@ -60,6 +60,9 @@ const MAPPING: {
 			parts: [{ kind: 'text', text: e.error }],
 		}),
 
+	// Capability degradation is host-facing diagnostics, not A2A task state.
+	capability_warning: null,
+
 	iteration_started: (e, ctx) =>
 		statusEvent(e.runId, 'running', false, ctx, {
 			role: 'agent',

package/src/bridge/sse/mapper.ts

@@ -165,6 +165,11 @@ const MAPPING: {
 	run_completed: null,
 	run_failed: null,
 
+	// Not mapped to a wire event yet — hosts consume `capability_warning`
+	// from the RunEvent stream directly; promoting it to the SSE contract
+	// needs a StreamEventType addition first.
+	capability_warning: null,
+
 	agent_pending: {
 		wire: 'agent.pending',
 		transform: (e, runId) => ({

package/src/{runtime/query → constants}/continuation.ts

@@ -11,6 +11,11 @@
  * that match this constant verbatim, so the run's `result` field
  * concatenates the full multi-turn assistant output instead of only
  * surfacing the trailing continuation chunk.
+ *
+ * Lives in `constants/` (not `runtime/query/`) because both the
+ * runtime iteration loop and `manager/run/persistence.ts` consume
+ * it — a manager→runtime import for a string constant would create
+ * a manager↔runtime directory cycle.
  */
 export const AUTO_CONTINUATION_USER_MESSAGE =
 	'Continue exactly where you left off. Do not repeat content you already wrote — pick up at the next token.'

package/src/constants/index.ts

@@ -7,6 +7,7 @@ export * from './rag/index.js'
 export * from './tools/index.js'
 export * from './telemetry/index.js'
 export * from './agent/index.js'
+export * from './continuation.js'
 export * from './limits.js'
 export * from './bus/index.js'
 export * from './verification/index.js'

package/src/manager/run/persistence.ts

@@ -1,9 +1,11 @@
+import { AUTO_CONTINUATION_USER_MESSAGE } from '../../constants/continuation.js'
 import { EMPTY_TOKEN_USAGE } from '../../constants/limits.js'
-import { AUTO_CONTINUATION_USER_MESSAGE } from '../../runtime/query/continuation.js'
+import { DiskCheckpointStore } from '../../store/run/checkpoint-disk.js'
 import { RunDiskStore } from '../../store/run/disk.js'
 import { type CostInfo, type TokenUsage, accumulateTokenUsage } from '../../types/common/index.js'
 import type { RunId, SessionId, TenantId } from '../../types/ids/index.js'
 import type { Message } from '../../types/message/index.js'
+import type { CheckpointRunScope, CheckpointStore } from '../../types/run/checkpoint-store.js'
 import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { Run, RunPersistenceConfig, StopReason } from '../../types/run/index.js'
 import type { ProjectId, ThreadId } from '../../types/session/ids.js'
@@ -14,6 +16,7 @@ import type { Logger } from '../../utils/logger.js'
 export class RunPersistence {
 	private run: Run
 	private runStore: RunDiskStore
+	private checkpointStore: CheckpointStore
 	private pricing?: ModelPricing
 	private log: Logger
 	private readonly _sessionId: SessionId
@@ -34,6 +37,15 @@ export class RunPersistence {
 			logger: config.log,
 		})
 
+		// Checkpoints go through the injectable seam; the disk layout under
+		// `outputDir` (same tree the runStore writes to) stays the default.
+		this.checkpointStore =
+			config.checkpointStore ??
+			new DiskCheckpointStore({
+				baseDir: config.outputDir,
+				logger: config.log,
+			})
+
 		this.run = {
 			id: config.runId,
 			status: 'idle',
@@ -109,6 +121,27 @@ export class RunPersistence {
 		return this.runStore
 	}
 
+	/**
+	 * Checkpoint persistence for this run — the injected
+	 * {@link CheckpointStore} when the host provided one, otherwise the
+	 * disk default. Pair with {@link getRunScope} when constructing a
+	 * `CheckpointManager`.
+	 */
+	getCheckpointStore(): CheckpointStore {
+		return this.checkpointStore
+	}
+
+	/** Full five-layer scope key for this run's checkpoint operations. */
+	getRunScope(): CheckpointRunScope {
+		return {
+			tenantId: this._tenantId,
+			projectId: this._projectId,
+			sessionId: this._sessionId,
+			runId: this.run.id,
+			parentRunId: this.run.parentRunId,
+		}
+	}
+
 	getRunDir(): string | null {
 		return this.runStore.getRunDir()
 	}

package/src/provider/__tests__/registry.test.ts

@@ -1,9 +1,16 @@
 import { beforeEach, describe, expect, it } from 'vitest'
-import type { LLMProvider, ProviderCapabilities } from '../../types/provider/index.js'
+import type {
+	LLMProvider,
+	LazyProviderModule,
+	ProviderCapabilities,
+} from '../../types/provider/index.js'
+import { PERMISSIVE_PROVIDER_CAPABILITIES, resolveProviderCapabilities } from '../capabilities.js'
 import { registerMock } from '../mock-register.js'
 import { MockLLMProvider } from '../mock.js'
 import {
 	DuplicateProviderError,
+	LazyProviderLoadError,
+	LazyProviderSyncCreateError,
 	ProviderRegistry,
 	UnknownProviderError,
 	__resetProviderRegistryInternal,
@@ -16,9 +23,15 @@ interface TestProviderConfig {
 	value?: string
 }
 
+interface LazyTestProviderConfig {
+	type: 'lazytest'
+	value?: string
+}
+
 declare module '../../types/provider/config.js' {
 	interface ProviderConfigRegistry {
 		test: TestProviderConfig
+		lazytest: LazyTestProviderConfig
 	}
 }
 
@@ -52,6 +65,41 @@ const TEST_CAPS: ProviderCapabilities = {
 	supportsFunctionCalling: false,
 }
 
+class LazyTestProvider implements LLMProvider {
+	readonly id = 'lazytest'
+	readonly name = 'Lazy Test'
+	constructor(
+		public readonly config: LazyTestProviderConfig,
+		readonly capabilities?: ProviderCapabilities,
+	) {}
+	async *chatStream() {
+		yield { id: 'x', delta: { content: 'ok' } }
+	}
+}
+
+const HINT_CAPS: ProviderCapabilities = {
+	supportsTools: false,
+	supportsStreaming: false,
+	supportsFunctionCalling: false,
+}
+
+const MODULE_CAPS: ProviderCapabilities = {
+	supportsTools: true,
+	supportsStreaming: true,
+	supportsFunctionCalling: true,
+	supportsVision: false,
+}
+
+function deferred<T>() {
+	let resolve!: (value: T) => void
+	let reject!: (reason?: unknown) => void
+	const promise = new Promise<T>((res, rej) => {
+		resolve = res
+		reject = rej
+	})
+	return { promise, resolve, reject }
+}
+
 describe('ProviderRegistry', () => {
 	beforeEach(() => {
 		__resetProviderRegistryInternal()
@@ -152,4 +200,221 @@ describe('ProviderRegistry', () => {
 			expect(err.name).toBe('DuplicateProviderError')
 		})
 	})
+
+	describe('registerLazy', () => {
+		it('does not invoke the loader at registration time', () => {
+			let calls = 0
+			ProviderRegistry.registerLazy('lazytest', async () => {
+				calls++
+				return { create: (config) => new LazyTestProvider(config) }
+			})
+
+			expect(calls).toBe(0)
+			expect(ProviderRegistry.isSupported('lazytest')).toBe(true)
+			expect(ProviderRegistry.listTypes()).toContain('lazytest')
+		})
+
+		it('throws DuplicateProviderError over an existing eager registration', () => {
+			ProviderRegistry.register('test', TestProvider, TEST_CAPS)
+			expect(() =>
+				ProviderRegistry.registerLazy('test', async () => ({
+					create: (config) => new TestProvider(config),
+				})),
+			).toThrowError(DuplicateProviderError)
+		})
+
+		it('throws DuplicateProviderError over an existing lazy registration', () => {
+			const loader = async (): Promise<LazyProviderModule<LazyTestProviderConfig>> => ({
+				create: (config) => new LazyTestProvider(config),
+			})
+			ProviderRegistry.registerLazy('lazytest', loader)
+			expect(() => ProviderRegistry.registerLazy('lazytest', loader)).toThrowError(
+				DuplicateProviderError,
+			)
+		})
+
+		it('replace: true swaps between eager and lazy registrations', async () => {
+			ProviderRegistry.register('lazytest', LazyTestProvider, TEST_CAPS)
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => ({ create: (config) => new LazyTestProvider(config) }),
+				{ replace: true },
+			)
+			expect(() => ProviderRegistry.createProvider({ type: 'lazytest' })).toThrowError(
+				LazyProviderSyncCreateError,
+			)
+
+			ProviderRegistry.register('lazytest', LazyTestProvider, TEST_CAPS, { replace: true })
+			expect(ProviderRegistry.createProvider({ type: 'lazytest' })).toBeInstanceOf(LazyTestProvider)
+		})
+
+		it('sync create()/createProvider() always throws for lazy types, even after load', async () => {
+			ProviderRegistry.registerLazy('lazytest', async () => ({
+				create: (config) => new LazyTestProvider(config),
+			}))
+
+			expect(() => ProviderRegistry.create({ type: 'lazytest' })).toThrowError(
+				LazyProviderSyncCreateError,
+			)
+
+			await ProviderRegistry.createAsync({ type: 'lazytest' })
+			expect(() => ProviderRegistry.createProvider({ type: 'lazytest' })).toThrowError(
+				LazyProviderSyncCreateError,
+			)
+		})
+
+		it('unregister removes a lazy registration', () => {
+			ProviderRegistry.registerLazy('lazytest', async () => ({
+				create: (config) => new LazyTestProvider(config),
+			}))
+			expect(ProviderRegistry.unregister('lazytest')).toBe(true)
+			expect(ProviderRegistry.isSupported('lazytest')).toBe(false)
+		})
+	})
+
+	describe('createAsync', () => {
+		it('first create invokes the loader once; subsequent creates reuse the cached factory', async () => {
+			let calls = 0
+			ProviderRegistry.registerLazy('lazytest', async () => {
+				calls++
+				return { create: (config) => new LazyTestProvider(config) }
+			})
+
+			const first = await ProviderRegistry.createAsync({ type: 'lazytest', value: 'a' })
+			const second = await ProviderRegistry.createAsync({ type: 'lazytest', value: 'b' })
+
+			expect(calls).toBe(1)
+			expect(first.provider).toBeInstanceOf(LazyTestProvider)
+			expect(second.provider).toBeInstanceOf(LazyTestProvider)
+			expect((second.provider as LazyTestProvider).config.value).toBe('b')
+		})
+
+		it('concurrent first-creates share a single loader invocation', async () => {
+			let calls = 0
+			const gate = deferred<void>()
+			ProviderRegistry.registerLazy('lazytest', async () => {
+				calls++
+				await gate.promise
+				return { create: (config) => new LazyTestProvider(config) }
+			})
+
+			const a = ProviderRegistry.createAsync({ type: 'lazytest' })
+			const b = ProviderRegistry.createAsync({ type: 'lazytest' })
+			gate.resolve()
+
+			const [ra, rb] = await Promise.all([a, b])
+			expect(calls).toBe(1)
+			expect(ra.provider).toBeInstanceOf(LazyTestProvider)
+			expect(rb.provider).toBeInstanceOf(LazyTestProvider)
+		})
+
+		it('loader rejection surfaces as LazyProviderLoadError and the next create retries', async () => {
+			let calls = 0
+			ProviderRegistry.registerLazy('lazytest', async () => {
+				calls++
+				if (calls === 1) {
+					throw new Error('transient network failure')
+				}
+				return { create: (config) => new LazyTestProvider(config) }
+			})
+
+			const failure = await ProviderRegistry.createAsync({ type: 'lazytest' }).catch(
+				(err: unknown) => err,
+			)
+			expect(failure).toBeInstanceOf(LazyProviderLoadError)
+			expect((failure as LazyProviderLoadError).providerType).toBe('lazytest')
+			expect(((failure as LazyProviderLoadError).cause as Error).message).toBe(
+				'transient network failure',
+			)
+
+			const { provider } = await ProviderRegistry.createAsync({ type: 'lazytest' })
+			expect(calls).toBe(2)
+			expect(provider).toBeInstanceOf(LazyTestProvider)
+		})
+
+		it('rejects with LazyProviderLoadError when the loader resolves an invalid module shape', async () => {
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => ({}) as unknown as LazyProviderModule<LazyTestProviderConfig>,
+			)
+			await expect(ProviderRegistry.createAsync({ type: 'lazytest' })).rejects.toThrowError(
+				LazyProviderLoadError,
+			)
+		})
+
+		it('works for eagerly registered types too', async () => {
+			const { provider, capabilities } = await ProviderRegistry.createAsync({
+				type: 'mock',
+				model: 'test-model',
+			})
+			expect(provider).toBeInstanceOf(MockLLMProvider)
+			expect(capabilities.supportsStreaming).toBe(true)
+		})
+
+		it('rejects with UnknownProviderError for unregistered types', async () => {
+			await expect(
+				ProviderRegistry.createAsync({ type: 'nonexistent' } as unknown as { type: 'mock' }),
+			).rejects.toThrowError(UnknownProviderError)
+		})
+	})
+
+	describe('lazy capabilities', () => {
+		it('answers with the registration hint before load, without invoking the loader', () => {
+			let calls = 0
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => {
+					calls++
+					return { create: (config) => new LazyTestProvider(config) }
+				},
+				{ capabilities: HINT_CAPS },
+			)
+
+			expect(ProviderRegistry.getCapabilities('lazytest')).toEqual(HINT_CAPS)
+			expect(calls).toBe(0)
+		})
+
+		it('answers permissively before load when no hint was given', () => {
+			ProviderRegistry.registerLazy('lazytest', async () => ({
+				create: (config) => new LazyTestProvider(config),
+			}))
+			expect(ProviderRegistry.getCapabilities('lazytest')).toEqual(PERMISSIVE_PROVIDER_CAPABILITIES)
+		})
+
+		it('module capabilities replace the hint after load', async () => {
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => ({
+					create: (config) => new LazyTestProvider(config),
+					capabilities: MODULE_CAPS,
+				}),
+				{ capabilities: HINT_CAPS },
+			)
+
+			const { capabilities } = await ProviderRegistry.createAsync({ type: 'lazytest' })
+			expect(capabilities).toEqual(MODULE_CAPS)
+			expect(ProviderRegistry.getCapabilities('lazytest')).toEqual(MODULE_CAPS)
+		})
+
+		it('the constructed instance own capabilities win at run time over any hint', async () => {
+			const instanceCaps: ProviderCapabilities = {
+				supportsTools: true,
+				supportsStreaming: true,
+				supportsFunctionCalling: false,
+				supportsVision: false,
+			}
+			ProviderRegistry.registerLazy(
+				'lazytest',
+				async () => ({ create: (config) => new LazyTestProvider(config, instanceCaps) }),
+				{ capabilities: HINT_CAPS },
+			)
+
+			const { provider } = await ProviderRegistry.createAsync({ type: 'lazytest' })
+			// The query runtime negotiates against the instance, not the registry:
+			const resolved = resolveProviderCapabilities(provider)
+			expect(resolved.supportsTools).toBe(true)
+			expect(resolved.supportsFunctionCalling).toBe(false)
+			expect(resolved.supportsVision).toBe(false)
+		})
+	})
 })

package/src/provider/capabilities.ts

@@ -0,0 +1,47 @@
+import type { LLMProvider, ProviderCapabilities } from '../types/provider/index.js'
+
+/**
+ * Fully-resolved capability set: every flag present, no optionals left.
+ * What the query runtime branches on after applying the permissive default.
+ */
+export interface ResolvedProviderCapabilities {
+	supportsTools: boolean
+	supportsStreaming: boolean
+	supportsFunctionCalling: boolean
+	supportsVision: boolean
+	maxOutputTokens?: number
+}
+
+/**
+ * THE permissive default: a provider that declares nothing is assumed to
+ * handle everything — exactly the pre-negotiation behavior, so third-party
+ * providers written before `LLMProvider.capabilities` existed keep working
+ * without a warning storm. Shipped drivers always declare explicitly.
+ */
+export const PERMISSIVE_PROVIDER_CAPABILITIES: ResolvedProviderCapabilities = {
+	supportsTools: true,
+	supportsStreaming: true,
+	supportsFunctionCalling: true,
+	supportsVision: true,
+}
+
+/**
+ * Resolve a provider's declared capabilities against the permissive
+ * default. Absent declaration ⇒ everything `true`; a partial declaration
+ * (e.g. one missing `supportsVision`, added later) fills the gap
+ * permissively per field.
+ */
+export function resolveProviderCapabilities(
+	provider: Pick<LLMProvider, 'capabilities'>,
+): ResolvedProviderCapabilities {
+	const declared: ProviderCapabilities | undefined = provider.capabilities
+	return {
+		supportsTools: declared?.supportsTools ?? PERMISSIVE_PROVIDER_CAPABILITIES.supportsTools,
+		supportsStreaming:
+			declared?.supportsStreaming ?? PERMISSIVE_PROVIDER_CAPABILITIES.supportsStreaming,
+		supportsFunctionCalling:
+			declared?.supportsFunctionCalling ?? PERMISSIVE_PROVIDER_CAPABILITIES.supportsFunctionCalling,
+		supportsVision: declared?.supportsVision ?? PERMISSIVE_PROVIDER_CAPABILITIES.supportsVision,
+		maxOutputTokens: declared?.maxOutputTokens,
+	}
+}

package/src/provider/index.ts

@@ -1,3 +1,14 @@
-export { ProviderRegistry, UnknownProviderError, DuplicateProviderError } from './registry.js'
+export {
+	ProviderRegistry,
+	UnknownProviderError,
+	DuplicateProviderError,
+	LazyProviderLoadError,
+	LazyProviderSyncCreateError,
+} from './registry.js'
 export { MockLLMProvider } from './mock.js'
 export { registerMock, MOCK_CAPABILITIES } from './mock-register.js'
+export {
+	PERMISSIVE_PROVIDER_CAPABILITIES,
+	resolveProviderCapabilities,
+} from './capabilities.js'
+export type { ResolvedProviderCapabilities } from './capabilities.js'