@namzu/sdk 1.0.0 → 1.1.0

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

@@ -0,0 +1,169 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+
+import type { MCPJsonRpcMessage } from '../../types/connector/index.js'
+import { MCPClient } from './client.js'
+
+afterEach(() => {
+	vi.unstubAllGlobals()
+})
+
+describe('Streamable HTTP MCP transport', () => {
+	it('connects through MCPClient, preserves session headers, and parses SSE responses', async () => {
+		const fetchMock = vi.fn<typeof fetch>()
+		fetchMock
+			.mockResolvedValueOnce(
+				jsonResponse(
+					{
+						jsonrpc: '2.0',
+						id: 1,
+						result: {
+							protocolVersion: '2024-11-05',
+							capabilities: { tools: { listChanged: true } },
+							serverInfo: { name: 'github' },
+						},
+					},
+					{ 'mcp-session-id': 'sid_123' },
+				),
+			)
+			.mockResolvedValueOnce(new Response('', { status: 202 }))
+			.mockResolvedValueOnce(
+				sseResponse([
+					{ jsonrpc: '2.0', method: 'notifications/progress', params: { pct: 50 } },
+					{
+						jsonrpc: '2.0',
+						id: 2,
+						result: {
+							tools: [
+								{
+									name: 'search_repositories',
+									description: 'Search repositories',
+									inputSchema: { type: 'object' },
+								},
+							],
+						},
+					},
+				]),
+			)
+		vi.stubGlobal('fetch', fetchMock)
+
+		const client = new MCPClient({
+			serverName: 'github',
+			transport: {
+				type: 'streamable_http',
+				url: 'https://mcp.example.test/mcp',
+				headers: { Authorization: 'Bearer token' },
+			},
+		})
+		const notifications: string[] = []
+		client.onNotification((method) => notifications.push(method))
+
+		await client.connect()
+		const tools = await client.listTools()
+
+		expect(tools.map((tool) => tool.name)).toEqual(['search_repositories'])
+		expect(notifications).toEqual(['notifications/progress'])
+		expect(fetchMock).toHaveBeenCalledTimes(3)
+
+		const initialize = requestAt(fetchMock, 0)
+		expect(initialize.input).toBe('https://mcp.example.test/mcp')
+		expect(initialize.body.method).toBe('initialize')
+		expect(initialize.headers.Authorization).toBe('Bearer token')
+		expect(initialize.headers.Accept).toBe('application/json, text/event-stream')
+
+		const initialized = requestAt(fetchMock, 1)
+		expect(initialized.body.method).toBe('notifications/initialized')
+		expect(initialized.headers['Mcp-Session-Id']).toBe('sid_123')
+
+		const listTools = requestAt(fetchMock, 2)
+		expect(listTools.body.method).toBe('tools/list')
+		expect(listTools.headers['Mcp-Session-Id']).toBe('sid_123')
+	})
+
+	it('supports the streamable-http alias without non-standard hint headers', async () => {
+		const fetchMock = vi.fn<typeof fetch>()
+		fetchMock
+			.mockResolvedValueOnce(
+				jsonResponse(
+					{
+						jsonrpc: '2.0',
+						id: 1,
+						result: {
+							protocolVersion: '2024-11-05',
+							capabilities: { tools: {} },
+							serverInfo: { name: 'linear' },
+						},
+					},
+					{ 'Mcp-Session-Id': 'sid_alias' },
+				),
+			)
+			.mockResolvedValueOnce(new Response(null, { status: 204 }))
+			.mockResolvedValueOnce(
+				jsonResponse({
+					jsonrpc: '2.0',
+					id: 2,
+					result: { content: [{ type: 'text', text: 'ok' }] },
+				}),
+			)
+		vi.stubGlobal('fetch', fetchMock)
+
+		const client = new MCPClient({
+			serverName: 'linear',
+			transport: {
+				type: 'streamable-http',
+				url: 'https://mcp.example.test/linear',
+			},
+		})
+
+		await client.connect()
+		const result = await client.callTool('create_issue', { title: 'Bug' })
+
+		expect(result.content).toEqual([{ type: 'text', text: 'ok' }])
+		const callTool = requestAt(fetchMock, 2)
+		expect(callTool.body.method).toBe('tools/call')
+		expect(callTool.headers).toEqual({
+			'Content-Type': 'application/json',
+			Accept: 'application/json, text/event-stream',
+			'Mcp-Session-Id': 'sid_alias',
+		})
+	})
+})
+
+function jsonResponse(body: MCPJsonRpcMessage, headers?: Record<string, string>): Response {
+	return new Response(JSON.stringify(body), {
+		status: 200,
+		headers: {
+			'content-type': 'application/json',
+			...headers,
+		},
+	})
+}
+
+function sseResponse(messages: MCPJsonRpcMessage[]): Response {
+	return new Response(messages.map((message) => `data: ${JSON.stringify(message)}\n\n`).join(''), {
+		status: 200,
+		headers: {
+			'content-type': 'text/event-stream',
+		},
+	})
+}
+
+function requestAt(
+	fetchMock: ReturnType<typeof vi.fn<typeof fetch>>,
+	index: number,
+): {
+	input: Parameters<typeof fetch>[0]
+	headers: Record<string, string>
+	body: MCPJsonRpcMessage
+} {
+	const call = fetchMock.mock.calls[index]
+	if (!call) {
+		throw new Error(`No fetch call at index ${index}`)
+	}
+	const [input, init] = call
+	if (!init) {
+		throw new Error(`Fetch call at index ${index} had no init`)
+	}
+	const headers = init.headers as Record<string, string>
+	const body = JSON.parse(String(init.body)) as MCPJsonRpcMessage
+	return { input, headers, body }
+}

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/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/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/public-runtime.ts

@@ -194,6 +194,7 @@ export {
 	RemoteExecutionContext,
 	ScopedConnectorRegistry,
 	StdioTransport,
+	StreamableHttpTransport,
 	TenantConnectorManager,
 	toolDefinitionToMCPTool,
 	toolResultToMCPToolResult,

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', () => {