@namzu/sdk 1.1.0 → 1.2.0

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/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,8 @@
 export { ProviderRegistry, UnknownProviderError, DuplicateProviderError } 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'

package/src/public-runtime.ts

@@ -99,6 +99,7 @@ export {
 
 export {
 	ActivityStore,
+	DiskCheckpointStore,
 	DiskMemoryStore,
 	DiskTaskStore,
 	InMemoryMemoryIndex,
@@ -146,8 +147,10 @@ export {
 	DuplicateProviderError,
 	MOCK_CAPABILITIES,
 	MockLLMProvider,
+	PERMISSIVE_PROVIDER_CAPABILITIES,
 	ProviderRegistry,
 	registerMock,
+	resolveProviderCapabilities,
 	UnknownProviderError,
 } from './provider/index.js'
 
@@ -248,6 +251,7 @@ export {
 
 export { wrapProviderWithProbes } from './provider/instrumentation.js'
 export type { ProviderInstrumentationOptions } from './provider/instrumentation.js'
+export type { ResolvedProviderCapabilities } from './provider/capabilities.js'
 export { collect } from './provider/collect.js'
 
 export { wrapVaultWithProbes } from './vault/instrumentation.js'

package/src/run/reporter.ts

@@ -225,6 +225,15 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'capability_warning':
+				log.warn('Provider capability mismatch', {
+					runId: event.runId,
+					capability: event.capability,
+					providerId: event.providerId,
+					message: event.message,
+				})
+				break
+
 			default: {
 				const _exhaustive: never = event
 				throw new Error(`Unhandled run event type: ${(_exhaustive as RunEvent).type}`)

package/src/runtime/query/__tests__/capability-negotiation.test.ts

@@ -0,0 +1,248 @@
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { z } from 'zod'
+
+import {
+	PERMISSIVE_PROVIDER_CAPABILITIES,
+	resolveProviderCapabilities,
+} from '../../../provider/capabilities.js'
+import { ToolRegistry } from '../../../registry/tool/execute.js'
+import type { SessionId, TenantId } from '../../../types/ids/index.js'
+import { createUserMessage } from '../../../types/message/index.js'
+import type {
+	ChatCompletionParams,
+	LLMProvider,
+	ProviderCapabilities,
+	StreamChunk,
+} from '../../../types/provider/index.js'
+import type { RunEvent } from '../../../types/run/index.js'
+import type { ProjectId, ThreadId } from '../../../types/session/ids.js'
+import { drainQuery } from '../index.js'
+
+const ZERO_USAGE = {
+	promptTokens: 0,
+	completionTokens: 0,
+	totalTokens: 0,
+	cachedTokens: 0,
+	cacheWriteTokens: 0,
+}
+
+class CapturingProvider implements LLMProvider {
+	readonly id = 'capturing'
+	readonly name = 'Capturing Provider'
+	readonly capabilities?: ProviderCapabilities
+	lastParams?: ChatCompletionParams
+
+	constructor(capabilities?: ProviderCapabilities) {
+		this.capabilities = capabilities
+	}
+
+	async *chatStream(params: ChatCompletionParams): AsyncIterable<StreamChunk> {
+		this.lastParams = params
+		yield { id: 'msg_1', delta: { content: 'done' } }
+		yield { id: 'msg_1', delta: {}, finishReason: 'stop', usage: ZERO_USAGE }
+	}
+}
+
+const NO_TOOLS_CAPABILITIES: ProviderCapabilities = {
+	supportsTools: false,
+	supportsStreaming: true,
+	supportsFunctionCalling: false,
+	supportsVision: true,
+}
+
+const NO_VISION_CAPABILITIES: ProviderCapabilities = {
+	supportsTools: true,
+	supportsStreaming: true,
+	supportsFunctionCalling: true,
+	supportsVision: false,
+}
+
+function registerEchoTool(tools: ToolRegistry): void {
+	tools.register({
+		name: 'echo',
+		description: 'Echo the text back.',
+		inputSchema: z.object({ text: z.string() }),
+		execute: async () => ({ success: true, output: 'ok' }),
+	})
+}
+
+function baseParams(provider: LLMProvider, tools: ToolRegistry, workingDirectory: string) {
+	return {
+		provider,
+		tools,
+		runConfig: {
+			model: 'mock-model',
+			timeoutMs: 5_000,
+			tokenBudget: 100_000,
+			maxIterations: 1,
+			maxResponseTokens: 256,
+		},
+		agentId: 'agent_test',
+		agentName: 'Test Agent',
+		workingDirectory,
+		sessionId: 'ses_capability' as SessionId,
+		threadId: 'thd_capability' as ThreadId,
+		projectId: 'prj_capability' as ProjectId,
+		tenantId: 'tnt_capability' as TenantId,
+	}
+}
+
+describe('resolveProviderCapabilities', () => {
+	it('resolves an undeclared provider to the permissive default', () => {
+		expect(resolveProviderCapabilities(new CapturingProvider())).toEqual(
+			PERMISSIVE_PROVIDER_CAPABILITIES,
+		)
+	})
+
+	it('fills a partial declaration (missing supportsVision) permissively per field', () => {
+		const resolved = resolveProviderCapabilities({
+			capabilities: {
+				supportsTools: false,
+				supportsStreaming: true,
+				supportsFunctionCalling: false,
+			},
+		})
+		expect(resolved.supportsTools).toBe(false)
+		expect(resolved.supportsVision).toBe(true)
+	})
+})
+
+describe('query() capability negotiation', () => {
+	let workdirs: string[] = []
+
+	afterEach(async () => {
+		await Promise.all(workdirs.map((dir) => rm(dir, { recursive: true, force: true })))
+		workdirs = []
+	})
+
+	async function mkWorkdir(): Promise<string> {
+		const dir = await mkdtemp(join(tmpdir(), 'namzu-capability-'))
+		workdirs.push(dir)
+		return dir
+	}
+
+	it('strips tool surfaces and emits a capability_warning for a no-tools provider', async () => {
+		const provider = new CapturingProvider(NO_TOOLS_CAPABILITIES)
+		const tools = new ToolRegistry()
+		registerEchoTool(tools)
+		const events: RunEvent[] = []
+
+		const run = await drainQuery(
+			{
+				...baseParams(provider, tools, await mkWorkdir()),
+				messages: [createUserMessage('hello')],
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		expect(run.status).toBe('completed')
+
+		// The model was never told about tools: no tools param on the wire…
+		expect(provider.lastParams?.tools).toBeUndefined()
+		// …and no tool section in the system prompt.
+		const systemPrompt = (provider.lastParams?.messages ?? [])
+			.filter((m) => m.role === 'system')
+			.map((m) => m.content)
+			.join('\n')
+		expect(systemPrompt).not.toContain('<available_tools>')
+		expect(systemPrompt).not.toContain('echo')
+
+		// The host got the machine-readable warning.
+		const warning = events.find(
+			(e): e is Extract<RunEvent, { type: 'capability_warning' }> =>
+				e.type === 'capability_warning',
+		)
+		expect(warning?.capability).toBe('tools')
+		expect(warning?.providerId).toBe('capturing')
+		expect(warning?.message).toContain('stripped')
+	})
+
+	it('keeps tool surfaces intact for an undeclared (permissive-default) provider', async () => {
+		const provider = new CapturingProvider()
+		const tools = new ToolRegistry()
+		registerEchoTool(tools)
+
+		const run = await drainQuery({
+			...baseParams(provider, tools, await mkWorkdir()),
+			messages: [createUserMessage('hello')],
+		})
+
+		expect(run.status).toBe('completed')
+		expect(provider.lastParams?.tools?.map((t) => t.function.name)).toContain('echo')
+	})
+
+	it('emits a vision capability_warning when attachments hit a no-vision provider', async () => {
+		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
+		const events: RunEvent[] = []
+
+		const run = await drainQuery(
+			{
+				...baseParams(provider, new ToolRegistry(), await mkWorkdir()),
+				messages: [
+					createUserMessage('what is in this image?', [
+						{ data: 'aGVsbG8=', mediaType: 'image/png' },
+					]),
+				],
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		expect(run.status).toBe('completed')
+		const warning = events.find(
+			(e): e is Extract<RunEvent, { type: 'capability_warning' }> =>
+				e.type === 'capability_warning',
+		)
+		expect(warning?.capability).toBe('vision')
+		expect(warning?.providerId).toBe('capturing')
+	})
+
+	it('does not warn when no attachments are present on a no-vision provider', async () => {
+		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
+		const events: RunEvent[] = []
+
+		await drainQuery(
+			{
+				...baseParams(provider, new ToolRegistry(), await mkWorkdir()),
+				messages: [createUserMessage('plain text')],
+			},
+			(event) => {
+				events.push(event)
+			},
+		)
+
+		expect(events.some((e) => e.type === 'capability_warning')).toBe(false)
+	})
+
+	it('strictCapabilities: true throws on a tools mismatch instead of degrading', async () => {
+		const provider = new CapturingProvider(NO_TOOLS_CAPABILITIES)
+		const tools = new ToolRegistry()
+		registerEchoTool(tools)
+
+		await expect(
+			drainQuery({
+				...baseParams(provider, tools, await mkWorkdir()),
+				messages: [createUserMessage('hello')],
+				strictCapabilities: true,
+			}),
+		).rejects.toThrow(/supportsTools: false/)
+	})
+
+	it('strictCapabilities: true throws on a vision mismatch instead of degrading', async () => {
+		const provider = new CapturingProvider(NO_VISION_CAPABILITIES)
+
+		await expect(
+			drainQuery({
+				...baseParams(provider, new ToolRegistry(), await mkWorkdir()),
+				messages: [createUserMessage('describe', [{ data: 'aGVsbG8=', mediaType: 'image/png' }])],
+				strictCapabilities: true,
+			}),
+		).rejects.toThrow(/supportsVision: false/)
+	})
+})