@namzu/sdk 1.0.0 → 1.2.0

package/src/connector/mcp/streamable-http.ts

@@ -0,0 +1,152 @@
+import type {
+	MCPJsonRpcMessage,
+	MCPStreamableHttpTransportConfig,
+	MCPTransport,
+} from '../../types/connector/index.js'
+import { type Logger, getRootLogger } from '../../utils/logger.js'
+
+const DEFAULT_TIMEOUT_MS = 30_000
+
+export class StreamableHttpTransport implements MCPTransport {
+	private messageHandlers: Array<(message: MCPJsonRpcMessage) => void> = []
+	private closeHandlers: Array<() => void> = []
+	private errorHandlers: Array<(error: Error) => void> = []
+	private connected = false
+	private sessionId: string | null = null
+	private log: Logger
+
+	constructor(private readonly config: MCPStreamableHttpTransportConfig) {
+		this.log = getRootLogger().child({ component: 'StreamableHttpTransport' })
+	}
+
+	async connect(): Promise<void> {
+		if (this.connected) return
+		this.connected = true
+		this.log.info(`StreamableHttpTransport connected to ${this.config.url}`)
+	}
+
+	async close(): Promise<void> {
+		if (!this.connected) return
+		this.connected = false
+		for (const handler of this.closeHandlers) handler()
+	}
+
+	async send(message: MCPJsonRpcMessage): Promise<void> {
+		if (!this.connected) {
+			throw new Error('StreamableHttpTransport: not connected')
+		}
+
+		const controller = new AbortController()
+		const timeout = setTimeout(
+			() => controller.abort(),
+			this.config.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+		)
+
+		try {
+			const response = await fetch(this.config.url, {
+				method: 'POST',
+				headers: this.buildHeaders(),
+				body: JSON.stringify(message),
+				signal: controller.signal,
+			})
+
+			this.captureSessionId(response)
+
+			if (!response.ok) {
+				throw new Error(`StreamableHttpTransport: HTTP ${response.status}: ${response.statusText}`)
+			}
+
+			await this.dispatchResponseMessages(response)
+		} catch (err) {
+			const error = err instanceof Error ? err : new Error(String(err))
+			for (const handler of this.errorHandlers) handler(error)
+			throw error
+		} finally {
+			clearTimeout(timeout)
+		}
+	}
+
+	onMessage(handler: (message: MCPJsonRpcMessage) => void): void {
+		this.messageHandlers.push(handler)
+	}
+
+	onClose(handler: () => void): void {
+		this.closeHandlers.push(handler)
+	}
+
+	onError(handler: (error: Error) => void): void {
+		this.errorHandlers.push(handler)
+	}
+
+	isConnected(): boolean {
+		return this.connected
+	}
+
+	private buildHeaders(): Record<string, string> {
+		const headers: Record<string, string> = {
+			'Content-Type': 'application/json',
+			Accept: 'application/json, text/event-stream',
+			...this.config.headers,
+		}
+
+		if (this.sessionId) {
+			headers['Mcp-Session-Id'] = this.sessionId
+		}
+
+		return headers
+	}
+
+	private captureSessionId(response: Response): void {
+		const sessionId =
+			response.headers.get('mcp-session-id') ?? response.headers.get('Mcp-Session-Id')
+		if (sessionId && sessionId.length > 0) {
+			this.sessionId = sessionId
+		}
+	}
+
+	private async dispatchResponseMessages(response: Response): Promise<void> {
+		const text = await response.text()
+		if (text.trim().length === 0) return
+
+		const contentType = response.headers.get('content-type') ?? ''
+		const messages = contentType.includes('text/event-stream')
+			? parseSseMessages(text)
+			: parseJsonMessages(text)
+
+		for (const message of messages) {
+			for (const handler of this.messageHandlers) handler(message)
+		}
+	}
+}
+
+function parseJsonMessages(raw: string): MCPJsonRpcMessage[] {
+	const parsed = JSON.parse(raw) as MCPJsonRpcMessage | MCPJsonRpcMessage[]
+	return Array.isArray(parsed) ? parsed : [parsed]
+}
+
+function parseSseMessages(raw: string): MCPJsonRpcMessage[] {
+	const normalized = raw.replace(/\r\n/g, '\n')
+	const events = normalized.split(/\n\n+/)
+	const messages: MCPJsonRpcMessage[] = []
+
+	for (const event of events) {
+		const dataLines = event
+			.split('\n')
+			.filter((line) => line.startsWith('data:'))
+			.map((line) => line.slice('data:'.length).trimStart())
+
+		if (dataLines.length === 0) continue
+
+		const data = dataLines.join('\n').trim()
+		if (data.length === 0 || data === '[DONE]') continue
+
+		const parsed = JSON.parse(data) as MCPJsonRpcMessage | MCPJsonRpcMessage[]
+		if (Array.isArray(parsed)) {
+			messages.push(...parsed)
+		} else {
+			messages.push(parsed)
+		}
+	}
+
+	return messages
+}

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/persona/assembler.ts

@@ -48,17 +48,29 @@ export function renderSkillsSection(skills?: Skill[]): string | null {
 
 	const available = skills
 		.map((s) => {
-			const details = [`description: ${s.metadata.description.trim()}`]
-			if (s.metadata.compatibility) details.push(`compatibility: ${s.metadata.compatibility}`)
-			if (s.metadata.license) details.push(`license: ${s.metadata.license}`)
-			if (s.metadata.allowedTools) details.push(`allowed-tools: ${s.metadata.allowedTools}`)
-			return `- ${s.metadata.name} (${details.join('; ')})\n  directory: ${s.dirPath}`
+			const lines = [
+				'<skill>',
+				`<name>${s.metadata.name}</name>`,
+				`<description>${s.metadata.description.trim()}</description>`,
+				`<location>${s.dirPath}/SKILL.md</location>`,
+			]
+			if (s.metadata.compatibility) {
+				lines.push(`<compatibility>${s.metadata.compatibility}</compatibility>`)
+			}
+			if (s.metadata.license) {
+				lines.push(`<license>${s.metadata.license}</license>`)
+			}
+			if (s.metadata.allowedTools) {
+				lines.push(`<allowed_tools>${s.metadata.allowedTools}</allowed_tools>`)
+			}
+			lines.push('</skill>')
+			return lines.join('\n')
 		})
 		.join('\n')
 
 	const loadedSkills = skills.filter((s) => s.body)
 	const sections = [
-		`## Available Skills\nThese Agent Skills are available through progressive disclosure. Use a skill only when the task matches its description. If a skill is not already loaded below, activate/read its SKILL.md from the listed directory when the runtime provides filesystem or skill-loading access.\n\n${available}`,
+		`## Available Skills\nThe following block is a manifest, not the full skill content. Skill metadata is always visible; SKILL.md bodies are loaded only when the user's task matches the skill description.\n\n<available_skills>\n${available}\n</available_skills>\n\nSkill usage protocol:\n- Plain questions do not require a skill.\n- When a matching skill is already listed under Loaded Skills, apply its loaded instructions.\n- When a matching skill is not loaded and the runtime exposes filesystem or skill-loading tools, read the SKILL.md at its <location> before writing code, creating files, running shell commands for that workflow, or calling mutation tools guided by the skill.\n- Do not claim to have read a SKILL.md until its content is actually present in the prompt or returned by a tool.\n- Tool schemas and runtime permissions remain authoritative; skills provide guidance, not hidden tools.`,
 	]
 
 	if (loadedSkills.length > 0) {

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/collect.ts

@@ -1,3 +1,4 @@
+import { mergeTokenUsage } from '../types/common/index.js'
 import type { ChatCompletionResponse } from '../types/provider/chat.js'
 import type { StreamChunk } from '../types/provider/stream.js'
 
@@ -60,7 +61,9 @@ export async function collect(stream: AsyncIterable<StreamChunk>): Promise<ChatC
 		}
 
 		if (chunk.finishReason) finishReason = chunk.finishReason
-		if (chunk.usage) usage = chunk.usage
+		// Merge (per-field max), not last-write-wins: a late frame that omits
+		// input/cache tokens must not zero the counts captured earlier in the stream.
+		if (chunk.usage) usage = mergeTokenUsage(usage, chunk.usage)
 	}
 
 	const toolCalls = [...toolBuckets.entries()]

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'
 
@@ -194,6 +197,7 @@ export {
 	RemoteExecutionContext,
 	ScopedConnectorRegistry,
 	StdioTransport,
+	StreamableHttpTransport,
 	TenantConnectorManager,
 	toolDefinitionToMCPTool,
 	toolResultToMCPToolResult,
@@ -247,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/registry/tool/execute.test.ts

@@ -20,18 +20,21 @@
  *     reports true iff at least one tool is suspended.
  *   - `getAvailability(name)` returns 'active' as a default even for
  *     unknown names (this is non-obvious but is the current behavior).
- *   - `searchDeferred(q)` filters DEFERRED tools: a useful whole query
- *     matches name OR description (case-insensitive); a batched multi-term
- *     query matches meaningful tokens against the NAME only. Generic/short
- *     tokens (`clawtool`, `tool`, …) are ignored so they can't over-activate.
+ *   - `searchDeferred(q)` is a RANKED weighted search over DEFERRED tools:
+ *     per meaningful term (≥3 chars, not a stop token) the score is
+ *     exact-name 12 / name-substring 8 / description 5 / argument-name 3;
+ *     results sort score-descending with name ties broken alphabetically.
+ *     Generic/short tokens (`clawtool`, `tool`, CRUD verbs like `list`,
+ *     `read`, …) are stopped so they can't over-activate the catalog.
  *   - `assignTiers(mapping)` mutates `tool.tier` on existing tools;
  *     throws via `getOrThrow` on unknown name; throws if the tier id
  *     is not in `tierConfig.tiers`.
  *   - `toTierGuidance` returns null without a guidanceTemplate; calls
  *     the template with every defined tier otherwise.
  *   - `toPromptSection`: returns '' when no active or deferred tools;
- *     otherwise produces `<available_tools>` + `<deferred_tools>`
- *     fragments.
+ *     otherwise produces `<available_tools>` (name-only — descriptions
+ *     already ride the runtime tools param) + `<deferred_tools>` (name +
+ *     first-sentence hint ≤100 chars) fragments.
  *   - `toLLMTools`: converts active + suspended tools (filtered by
  *     `toolNames` if provided) into LLM tool schemas via
  *     `zodToJsonSchema`. When `tierConfig.labelInDescription` is true,
@@ -198,15 +201,59 @@ describe('ToolRegistry — searchDeferred', () => {
 		r.register([makeTool('clawtool_PeerRegister')], 'deferred')
 		r.register([makeTool('clawtool_PeerList')], 'deferred')
 		r.register([makeTool('clawtool_Unrelated')], 'deferred')
-		// A whole-phrase substring match would find none of these.
+		// A whole-phrase substring match would find none of these. Equal
+		// scores tie-break alphabetically by name (deterministic ranking).
 		expect(r.searchDeferred('A2aCard PeerRegister PeerList').map((t) => t.name)).toEqual([
 			'clawtool_A2aCard',
-			'clawtool_PeerRegister',
 			'clawtool_PeerList',
+			'clawtool_PeerRegister',
 		])
 		expect(r.searchDeferred('   ')).toEqual([])
 	})
 
+	it('ranks exact name above name substring above description-only matches', () => {
+		const r = new ToolRegistry()
+		r.register([makeTool('release_notes', { description: 'Write deploy notes.' })], 'deferred')
+		r.register([makeTool('deploy_preview', { description: 'Stage a preview build.' })], 'deferred')
+		r.register([makeTool('deploy', { description: 'Ship the current build.' })], 'deferred')
+		expect(r.searchDeferred('deploy').map((t) => t.name)).toEqual([
+			'deploy', // exact name → 12
+			'deploy_preview', // name substring → 8
+			'release_notes', // description only → 5
+		])
+	})
+
+	it('indexes argument names so a parameter term can locate a tool', () => {
+		const r = new ToolRegistry()
+		r.register(
+			[
+				makeTool('send_invoice', {
+					inputSchema: z.object({ customerEmail: z.string(), amount: z.number() }),
+				}),
+			],
+			'deferred',
+		)
+		r.register([makeTool('send_reminder')], 'deferred')
+		expect(r.searchDeferred('customerEmail').map((t) => t.name)).toEqual(['send_invoice'])
+	})
+
+	it('stops generic CRUD verbs so they cannot activate catalog slices', () => {
+		const r = new ToolRegistry()
+		r.register(
+			[makeTool('list_deals', { description: 'List the deals in an account.' })],
+			'deferred',
+		)
+		r.register([makeTool('list_workflows', { description: 'List workflows.' })], 'deferred')
+		r.register([makeTool('read_document', { description: 'Read a document body.' })], 'deferred')
+		// Bare CRUD verbs identify nothing.
+		expect(r.searchDeferred('list')).toEqual([])
+		expect(r.searchDeferred('read')).toEqual([])
+		expect(r.searchDeferred('create update delete')).toEqual([])
+		// The non-generic remainder carries the query.
+		expect(r.searchDeferred('list deals').map((t) => t.name)).toEqual(['list_deals'])
+		expect(r.searchDeferred('read document').map((t) => t.name)).toEqual(['read_document'])
+	})
+
 	it('does not over-activate on generic/shared tokens', () => {
 		const r = new ToolRegistry()
 		r.register([makeTool('clawtool_A2aCard', { description: 'peer card' })], 'deferred')
@@ -270,10 +317,38 @@ describe('ToolRegistry — toPromptSection + toLLMTools', () => {
 		expect(s).toContain('<tool_runtime_contract>')
 		expect(s).toContain('runtime tools parameter')
 		expect(s).toContain('<available_tools>')
-		expect(s).toContain('- a: a tool')
+		// Active entries are NAME-ONLY: the description already rides the
+		// runtime tools param every request — repeating it double-bills.
+		expect(s).toContain('- a\n')
+		expect(s).not.toContain('- a: a tool')
 		expect(s).toContain('<deferred_tools>')
 		expect(s).toContain('Deferred tools are discoverable')
-		expect(s).toContain('- b')
+		// Deferred entries carry a one-line hint — their schema is off the
+		// wire, so the hint is the model's only capability signal.
+		expect(s).toContain('- b: b tool')
+	})
+
+	it('toPromptSection truncates deferred hints to the first sentence, capped at 100 chars', () => {
+		const r = new ToolRegistry()
+		r.register(
+			[
+				makeTool('two_sentences', {
+					description: 'Reads the document. Second sentence that must not appear.',
+				}),
+				makeTool('long_sentence', {
+					description: `${'x'.repeat(150)} end`,
+				}),
+			],
+			'deferred',
+		)
+		const s = r.toPromptSection()
+		expect(s).toContain('- two_sentences: Reads the document.')
+		expect(s).not.toContain('Second sentence')
+		const longLine = s.split('\n').find((line) => line.startsWith('- long_sentence:'))
+		expect(longLine).toBeDefined()
+		const hint = (longLine ?? '').replace('- long_sentence: ', '')
+		expect(hint.length).toBeLessThanOrEqual(100)
+		expect(hint.endsWith('…')).toBe(true)
 	})
 
 	it('toPromptSection references search_tools only when it is active', () => {