@namzu/sdk 3.1.0 → 3.2.0

package/src/compaction/reducer.ts

@@ -0,0 +1,154 @@
+import type { Message } from '../types/message/index.js'
+import { findSafeTrimIndex } from './dangling.js'
+import { findRetainedIndices } from './retention.js'
+
+/**
+ * Why the runtime is asking for a shorter history.
+ *
+ * The two cases want different behaviour and a reducer that cannot tell
+ * them apart has to guess. `'threshold'` is speculative — the estimate says
+ * the window is filling, nothing has failed, and declining costs only some
+ * headroom. `'overflow'` is the provider having already rejected the
+ * prompt: declining there ends the run.
+ */
+export type ContextReductionReason = 'threshold' | 'overflow'
+
+/** Everything a reducer needs to decide, and nothing it cannot act on. */
+export interface ContextReduction {
+	/** The live history, oldest first. Treat as read-only and return a new array. */
+	readonly messages: readonly Message[]
+	readonly reason: ContextReductionReason
+	/** Estimated size of `messages`. Derived from the provider's last prompt count when there is one, else measured. */
+	readonly estimatedTokens: number
+	/** What it has to fit in. Resolved from the model when the host did not say. */
+	readonly contextWindowTokens: number
+	/** The model this run is calling, for a reducer that varies by model. */
+	readonly model: string
+	/** The run's configured recent-window size, as a starting point. */
+	readonly keepRecentMessages: number
+}
+
+/**
+ * Replace the run's history with a shorter one.
+ *
+ * Returning `undefined` means "I could not shorten this" and is a first-class
+ * answer, not a failure — on `'threshold'` the run simply continues, and on
+ * `'overflow'` it fails with an irreducible-prompt error instead of retrying
+ * a prompt nothing changed. That is deliberate: a reducer that returned the
+ * input unchanged while reporting success would send the same rejected
+ * prompt again and burn a call to learn the same thing.
+ *
+ * A reducer OWNS reduction for the run it governs. The built-in structured
+ * pass — LLM-verified summarization, stale tool-result clearing, working
+ * state slots — does not also run, because two mechanisms editing the same
+ * history in one pass cannot both be reasoned about.
+ *
+ * Invariants a reducer is expected to keep, all three enforced by the
+ * built-in one and none of them checkable from here:
+ *
+ * 1. The leading system messages stay. They carry the system prompt and the
+ *    working-memory slot; dropping them changes who the agent is.
+ * 2. `tool_use` and its `tool_result` stay together. A split pair is a 400
+ *    from the provider, so a reducer that splits one turns a context problem
+ *    into a dead run. {@link findSafeTrimIndex} is exported for this.
+ * 3. Messages marked `retain` survive. That marker is how a caller says a
+ *    fact in the middle of the conversation outranks recency.
+ */
+export type ContextReducer = (
+	reduction: ContextReduction,
+) => readonly Message[] | undefined | Promise<readonly Message[] | undefined>
+
+export interface SlidingWindowOptions {
+	/**
+	 * How many trailing messages to keep. Defaults to the run's configured
+	 * `keepRecentMessages`, so the same knob governs both strategies.
+	 */
+	readonly keepRecentMessages?: number
+
+	/**
+	 * Fraction of the window to keep when relieving an overflow, applied to
+	 * the recent count. Defaults to 0.5.
+	 *
+	 * An overflow means the ordinary window was already too big, so cutting
+	 * to the same size again would shed nothing and the caller would retry
+	 * an identical prompt.
+	 */
+	readonly overflowFactor?: number
+}
+
+/**
+ * Keep the last N turns, drop what precedes them, summarize nothing.
+ *
+ * The honest counterpart to the structured strategy rather than a lesser
+ * version of it. Structured compaction pays a summarization call and
+ * paraphrases the agent's own reasoning to buy context; this pays nothing
+ * and admits the older history is gone. For a long-running agent whose
+ * state lives outside the transcript — a task queue, a file it keeps
+ * editing, a working-memory block the host renders each turn — that is the
+ * better trade, and the paraphrase was only ever cost.
+ *
+ * Until now `strategy: 'sliding-window'` was accepted by the config schema
+ * and then ignored: the runtime asked only whether the strategy was
+ * `'disabled'`, so choosing the cheap non-LLM path silently ran the
+ * expensive LLM one. This is the implementation that name always claimed.
+ */
+export function createSlidingWindowReducer(options: SlidingWindowOptions = {}): ContextReducer {
+	const factor = options.overflowFactor ?? 0.5
+
+	return ({ messages, reason, keepRecentMessages }) => {
+		const configured = options.keepRecentMessages ?? keepRecentMessages
+		const keep =
+			reason === 'overflow' ? Math.max(1, Math.floor(configured * factor)) : Math.max(1, configured)
+
+		let leadingSystem = 0
+		while (messages[leadingSystem]?.role === 'system') leadingSystem++
+
+		const naive = messages.length - keep
+		if (naive <= leadingSystem) return undefined
+
+		// `findSafeTrimIndex` moves a cut forward until the kept tail is a
+		// history a provider will accept — no `tool_result` without its
+		// `tool_use`, and never opening on an assistant turn, because the tail
+		// becomes the start of the wire conversation once the older half is
+		// gone. So a candidate is safe exactly when it is already its own
+		// answer.
+		//
+		// Walk BACKWARDS first: that lands on the safe cut nearest the
+		// requested window, keeping a little more than asked rather than a lot
+		// less.
+		const trimmable = [...messages]
+		let cut = -1
+		for (let candidate = naive; candidate > leadingSystem; candidate--) {
+			if (findSafeTrimIndex(trimmable, candidate) === candidate) {
+				cut = candidate
+				break
+			}
+		}
+
+		// Nothing safe below the request. Take the answer ABOVE it instead of
+		// refusing: in a multi-step turn — the agent working through tool calls
+		// with the user silent — every boundary in the recent window lands on
+		// an assistant or tool message, so a backwards-only search declines
+		// exactly when the history is longest and shedding matters most. The
+		// forward cut keeps less than asked, which is a smaller history than
+		// the caller wanted but still a correct one.
+		if (cut < 0) {
+			const forward = findSafeTrimIndex(trimmable, naive)
+			// `messages.length` means "keep nothing", which is not a history.
+			if (forward > leadingSystem && forward < messages.length) cut = forward
+		}
+		if (cut < 0) return undefined
+
+		const retained = findRetainedIndices(messages)
+		const survivors: Message[] = []
+		for (let i = 0; i < messages.length; i++) {
+			const message = messages[i]
+			if (!message) continue
+			if (i < leadingSystem || i >= cut || retained.has(i)) survivors.push(message)
+		}
+
+		// Nothing went. Reporting that as a reduction would have the overflow
+		// path retry an identical prompt.
+		return survivors.length === messages.length ? undefined : survivors
+	}
+}

package/src/connector/builtins/__tests__/oauth2-auth.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+
+import type { AuthConfig } from '../../../types/connector/index.js'
+import { HttpConnector } from '../http.js'
+
+/**
+ * `'oauth2'` was grouped with `'none'` and `'custom'`, returning no headers.
+ *
+ * So a connector configured for OAuth2 sent an UNAUTHENTICATED request.
+ * Every other auth type throws on a missing credential; this one quietly
+ * did not, and the upstream's 401 reads as a bad token rather than as no
+ * token at all — which sends whoever is debugging to look at the token.
+ */
+
+function headersFor(auth: AuthConfig): Record<string, string> {
+	const connector = new HttpConnector()
+	// The resolver is private by design; reaching it directly is what keeps
+	// this test about the header decision rather than about fetch.
+	return (
+		connector as unknown as { resolveAuthHeaders(a: AuthConfig): Record<string, string> }
+	).resolveAuthHeaders(auth)
+}
+
+describe('an oauth2 connector does not send an unauthenticated request', () => {
+	it('sends the access token it was given', () => {
+		const headers = headersFor({
+			type: 'oauth2',
+			credentials: { accessToken: 'tok_abc' },
+		} as AuthConfig)
+
+		expect(headers.Authorization).toBe('Bearer tok_abc')
+	})
+
+	it('accepts the token under either name', () => {
+		const headers = headersFor({ type: 'oauth2', credentials: { token: 'tok_xyz' } } as AuthConfig)
+
+		expect(headers.Authorization).toBe('Bearer tok_xyz')
+	})
+
+	it('refuses when there is no token, rather than sending nothing', () => {
+		// The whole defect: an empty header set went out and the request
+		// reached the upstream with no credential at all.
+		expect(() => headersFor({ type: 'oauth2', credentials: {} } as AuthConfig)).toThrow(
+			/accessToken/,
+		)
+	})
+
+	it('refuses when credentials are absent entirely', () => {
+		expect(() => headersFor({ type: 'oauth2' } as AuthConfig)).toThrow(/unauthenticated/)
+	})
+})
+
+describe('the other schemes are unchanged', () => {
+	it("still sends nothing for 'none'", () => {
+		expect(headersFor({ type: 'none' } as AuthConfig)).toEqual({})
+	})
+
+	it("still sends nothing for 'custom', which is the host's job", () => {
+		// Deliberately empty, unlike oauth2: `custom` means the host attaches
+		// its own headers, so there is nothing to omit and nothing to refuse.
+		expect(headersFor({ type: 'custom' } as AuthConfig)).toEqual({})
+	})
+
+	it('still sends a bearer token', () => {
+		expect(
+			headersFor({ type: 'bearer', credentials: { token: 't' } } as AuthConfig).Authorization,
+		).toBe('Bearer t')
+	})
+
+	it('still refuses a bearer with no token', () => {
+		expect(() => headersFor({ type: 'bearer', credentials: {} } as AuthConfig)).toThrow(/token/)
+	})
+})

package/src/connector/builtins/http.test.ts

@@ -140,8 +140,12 @@ describe('HttpConnector', () => {
 			expect(headers.Authorization).toBe(`Basic ${btoa('alice:pw')}`)
 		})
 
-		it('none / oauth2 / custom add no auth headers', async () => {
-			for (const type of ['none', 'oauth2', 'custom'] as const) {
+		it('none / custom add no auth headers', async () => {
+			// `oauth2` was in this list, and that is what the defect was: it
+			// meant a connector configured for OAuth2 reached the upstream with
+			// no credential at all. `none` and `custom` belong here — the first
+			// asks for no auth, the second says the host attaches its own.
+			for (const type of ['none', 'custom'] as const) {
 				const c = new HttpConnector()
 				await c.connect({ baseUrl: 'https://api.example.com' }, { type, credentials: {} })
 				fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: {} }))
@@ -152,6 +156,28 @@ describe('HttpConnector', () => {
 			}
 		})
 
+		it('oauth2 refuses rather than reaching the upstream unauthenticated', async () => {
+			const c = new HttpConnector()
+
+			await expect(
+				c.connect({ baseUrl: 'https://api.example.com' }, { type: 'oauth2', credentials: {} }),
+			).rejects.toThrow(/accessToken/)
+		})
+
+		it('oauth2 sends the access token it was given', async () => {
+			const c = new HttpConnector()
+			await c.connect(
+				{ baseUrl: 'https://api.example.com' },
+				{ type: 'oauth2', credentials: { accessToken: 'tok_1' } },
+			)
+			fetchMock.mockResolvedValueOnce(makeResponse({ status: 200, body: {} }))
+
+			await c.execute('request', { method: 'GET', path: 'x' })
+
+			const headers = fetchMock.mock.calls.at(-1)?.[1].headers as Record<string, string>
+			expect(headers.Authorization).toBe('Bearer tok_1')
+		})
+
 		it('api_key throws when apiKey is missing', async () => {
 			const c = new HttpConnector()
 			await expect(

package/src/connector/builtins/http.ts

@@ -188,9 +188,33 @@ export class HttpConnector extends BaseConnector<HttpConnectorConfig> {
 				const encoded = btoa(`${username}:${password}`)
 				return { Authorization: `Basic ${encoded}` }
 			}
-			case 'none':
-			case 'oauth2':
+			case 'oauth2': {
+				// Grouped with `none` until now, so a connector configured for
+				// OAuth2 sent an UNAUTHENTICATED request — every other auth type
+				// throws on a missing credential, and this one quietly did not.
+				// The upstream answers 401 and the failure reads as a bad token
+				// rather than as no token at all.
+				//
+				// The token exchange itself is not implemented here: a client
+				// credentials or authorization-code flow needs a token endpoint,
+				// refresh handling and a place to keep the result, none of which
+				// belong in a request-header helper. What is supported is an
+				// access token the host already holds, which is the case a
+				// connector config can actually express today.
+				const token = creds.accessToken ?? creds.token
+				if (!token) {
+					throw new Error(
+						'AuthConfig oauth2: missing required credential "accessToken". This connector holds no token endpoint, so an access token obtained elsewhere has to be supplied — sending the request without one would reach the upstream unauthenticated.',
+					)
+				}
+				return { Authorization: `Bearer ${token}` }
+			}
 			case 'custom':
+				// Deliberately empty, unlike `oauth2` above: `custom` means the
+				// host attaches its own headers, so there is nothing here to
+				// omit and nothing to refuse.
+				return {}
+			case 'none':
 				return {}
 			default: {
 				const _exhaustive: never = auth.type

package/src/connector/index.ts

@@ -51,5 +51,9 @@ export { MCPToolDiscovery } from './mcp/discovery.js'
 
 export { MCPConnectorBridge } from '../bridge/mcp/connector/adapter.js'
 
-export { MCPServer } from './mcp/server.js'
-export type { MCPServerToolProvider, MCPServerResourceProvider } from './mcp/server.js'
+export { MCPServer, MCPMethodNotFound } from './mcp/server.js'
+export type {
+	MCPServerToolProvider,
+	MCPServerResourceProvider,
+	MCPServerPromptProvider,
+} from './mcp/server.js'

package/src/connector/mcp/__tests__/prompts-and-lifecycle.test.ts

@@ -0,0 +1,286 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { JSON_RPC_METHOD_NOT_FOUND } from '../../../constants/mcp/index.js'
+import type {
+	MCPJsonRpcMessage,
+	MCPPromptDefinition,
+	MCPPromptMessage,
+	MCPTransport,
+} from '../../../types/connector/index.js'
+import { MCPClient } from '../client.js'
+import { MCPServer } from '../server.js'
+import type { MCPServerPromptProvider, MCPServerToolProvider } from '../server.js'
+
+/**
+ * The half of MCP that is not tools.
+ *
+ * `MCPPromptDefinition` and `MCPPromptArgument` were declared when the types
+ * were written; no client method ever asked for a prompt and no server branch
+ * ever served one. `MCPLifecycleEvent` and `MCPEventListener` were declared
+ * beside them and nothing ever emitted one, so a host could learn that a
+ * server had died only by noticing calls had started failing.
+ */
+
+function fakeTransport(): {
+	transport: MCPTransport
+	sent: MCPJsonRpcMessage[]
+	deliver: (m: MCPJsonRpcMessage) => void
+} {
+	const sent: MCPJsonRpcMessage[] = []
+	let onMessage: ((m: MCPJsonRpcMessage) => void) | undefined
+	const transport: MCPTransport = {
+		connect: async () => undefined,
+		close: async () => undefined,
+		send: async (m: MCPJsonRpcMessage) => {
+			sent.push(m)
+		},
+		onMessage: (h: (m: MCPJsonRpcMessage) => void) => {
+			onMessage = h
+		},
+		onClose: () => undefined,
+		onError: () => undefined,
+	} as unknown as MCPTransport
+	return { transport, sent, deliver: (m) => onMessage?.(m) }
+}
+
+const toolProvider: MCPServerToolProvider = {
+	listTools: () => [],
+	callTool: async () => ({ content: [{ type: 'text', text: 'ok' }] }),
+}
+
+function promptProvider(over: Partial<MCPServerPromptProvider> = {}): MCPServerPromptProvider {
+	const prompts: MCPPromptDefinition[] = [
+		{
+			name: 'summarize',
+			description: 'Summarize a file',
+			arguments: [
+				{ name: 'path', required: true },
+				{ name: 'style', required: false },
+			],
+		},
+	]
+	const messages: MCPPromptMessage[] = [
+		{ role: 'user', content: { type: 'text', text: 'summarize it' } },
+	]
+	return {
+		listPrompts: () => prompts,
+		getPrompt: async () => ({ description: 'Summarize a file', messages }),
+		...over,
+	}
+}
+
+async function ask(
+	t: ReturnType<typeof fakeTransport>,
+	method: string,
+	params: Record<string, unknown> = {},
+) {
+	t.deliver({ jsonrpc: '2.0', id: 1, method, params } as MCPJsonRpcMessage)
+	await new Promise((r) => setTimeout(r, 0))
+	return t.sent.at(-1) as MCPJsonRpcMessage & {
+		result?: unknown
+		error?: { code: number; message: string }
+	}
+}
+
+describe('a server serves the prompts it publishes', () => {
+	it('lists them', async () => {
+		const t = fakeTransport()
+		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
+		await server.start(t.transport)
+
+		const reply = await ask(t, 'prompts/list')
+
+		expect((reply.result as { prompts: MCPPromptDefinition[] }).prompts[0]?.name).toBe('summarize')
+	})
+
+	it('returns the messages the server composed', async () => {
+		const t = fakeTransport()
+		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
+		await server.start(t.transport)
+
+		const reply = await ask(t, 'prompts/get', {
+			name: 'summarize',
+			arguments: { path: 'a.ts' },
+		})
+
+		expect((reply.result as { messages: MCPPromptMessage[] }).messages[0]?.content).toEqual({
+			type: 'text',
+			text: 'summarize it',
+		})
+	})
+
+	it('advertises the capability only when something is behind it', async () => {
+		const withPrompts = fakeTransport()
+		const without = fakeTransport()
+		const a = new MCPServer({ name: 'a' }, toolProvider, undefined, promptProvider())
+		const b = new MCPServer({ name: 'b' }, toolProvider)
+		await a.start(withPrompts.transport)
+		await b.start(without.transport)
+
+		const withCap = await ask(withPrompts, 'initialize')
+		const withoutCap = await ask(without, 'initialize')
+
+		// A capability advertised without a provider is a promise the next
+		// call breaks.
+		expect(
+			(withCap.result as { capabilities: Record<string, unknown> }).capabilities.prompts,
+		).toBeDefined()
+		expect(
+			(withoutCap.result as { capabilities: Record<string, unknown> }).capabilities.prompts,
+		).toBeUndefined()
+	})
+
+	it('refuses a required argument the caller omitted', async () => {
+		const t = fakeTransport()
+		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
+		await server.start(t.transport)
+
+		const reply = await ask(t, 'prompts/get', { name: 'summarize', arguments: {} })
+
+		// Checked from the declaration, so every provider does not have to
+		// re-implement it or forget to.
+		expect(reply.error?.message).toContain('path')
+	})
+
+	it('accepts an optional argument being absent', async () => {
+		const t = fakeTransport()
+		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
+		await server.start(t.transport)
+
+		const reply = await ask(t, 'prompts/get', {
+			name: 'summarize',
+			arguments: { path: 'a.ts' },
+		})
+
+		expect(reply.error).toBeUndefined()
+	})
+
+	it('refuses a prompt it does not publish', async () => {
+		const t = fakeTransport()
+		const server = new MCPServer({ name: 'srv' }, toolProvider, undefined, promptProvider())
+		await server.start(t.transport)
+
+		const reply = await ask(t, 'prompts/get', { name: 'nonexistent' })
+
+		expect(reply.error?.message).toContain('nonexistent')
+	})
+})
+
+describe('"none" and "not here" are different answers', () => {
+	it('says method-not-found for prompts when there is no provider', async () => {
+		const t = fakeTransport()
+		const server = new MCPServer({ name: 'srv' }, toolProvider)
+		await server.start(t.transport)
+
+		const reply = await ask(t, 'prompts/list')
+
+		expect(reply.error?.code).toBe(JSON_RPC_METHOD_NOT_FOUND)
+	})
+
+	it('says method-not-found for resources when there is no provider', async () => {
+		const t = fakeTransport()
+		const server = new MCPServer({ name: 'srv' }, toolProvider)
+		await server.start(t.transport)
+
+		const reply = await ask(t, 'resources/list')
+
+		// This used to answer `{ resources: [] }` for a capability
+		// `initialize` never advertised — telling a client "none" where the
+		// truth is "not here". The two send a client in opposite directions.
+		expect(reply.error?.code).toBe(JSON_RPC_METHOD_NOT_FOUND)
+	})
+
+	it('uses the protocol code for an unknown method, not a generic failure', async () => {
+		const t = fakeTransport()
+		const server = new MCPServer({ name: 'srv' }, toolProvider)
+		await server.start(t.transport)
+
+		const reply = await ask(t, 'completely/unknown')
+
+		expect(reply.error?.code).toBe(JSON_RPC_METHOD_NOT_FOUND)
+	})
+
+	it('still reports a provider failure as an internal error', async () => {
+		const t = fakeTransport()
+		const server = new MCPServer(
+			{ name: 'srv' },
+			toolProvider,
+			undefined,
+			promptProvider({
+				listPrompts: () => {
+					throw new Error('provider exploded')
+				},
+			}),
+		)
+		await server.start(t.transport)
+
+		const reply = await ask(t, 'prompts/list')
+
+		// A broken provider is not the same as an unimplemented method, and
+		// collapsing the two would tell a client to stop asking for something
+		// that works tomorrow.
+		expect(reply.error?.code).toBe(-32603)
+	})
+})
+
+describe('a client says out loud what it already knew', () => {
+	function failingClient() {
+		// `connect` failing is the simplest path that actually emits. A
+		// never-connected client's `disconnect` returns early and emits
+		// nothing — an easy way to write a test that proves nothing, which is
+		// what the first version of these did.
+		return new MCPClient({
+			serverName: 'srv',
+			transport: { type: 'stdio', command: 'definitely-not-a-real-binary-xyz', args: [] },
+		})
+	}
+
+	/**
+	 * Covered here: the transport-error emitter. `connect`'s own catch emits
+	 * the same event and is NOT pinned — a spawn failure surfaces through the
+	 * transport first, so the catch is the second line of defence rather than
+	 * the path this reaches. Reaching it needs a connection that opens and
+	 * then fails negotiation, which this fake cannot stage; said rather than
+	 * left for a mutation run to discover.
+	 */
+	it('reports a failure to whoever is listening', async () => {
+		const client = failingClient()
+		const seen: string[] = []
+		client.onLifecycle((e) => seen.push(e.type))
+
+		await client.connect().catch(() => undefined)
+
+		expect(seen).toContain('mcp_client_error')
+	})
+
+	it('stops reporting once the listener unsubscribes', async () => {
+		const client = failingClient()
+		const seen = vi.fn()
+
+		const off = client.onLifecycle(seen)
+		off()
+		await client.connect().catch(() => undefined)
+
+		// `onNotification` returns nothing, so a listener registered there
+		// cannot be removed and keeps a disposed host object alive for as
+		// long as the client. This is that bug not repeated.
+		expect(seen).not.toHaveBeenCalled()
+	})
+
+	it('leaves other listeners working when one throws', async () => {
+		const client = failingClient()
+		const survivor = vi.fn()
+		client.onLifecycle(() => {
+			throw new Error('observer bug')
+		})
+		client.onLifecycle(survivor)
+
+		await client.connect().catch(() => undefined)
+
+		// These fire from inside transport callbacks and from `connect`'s
+		// failure path, so an escaping exception would surface as a connection
+		// error — blaming the server for a bug in the host's own observer, and
+		// silencing every listener registered after the broken one.
+		expect(survivor).toHaveBeenCalled()
+	})
+})