@namzu/sdk 3.0.0 → 3.2.0

package/src/compaction/__tests__/context-reducer.test.ts

@@ -0,0 +1,239 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { AssistantMessage, Message, ToolMessage } from '../../types/message/index.js'
+import { createSlidingWindowReducer } from '../reducer.js'
+import type { ContextReduction } from '../reducer.js'
+
+/**
+ * `strategy: 'sliding-window'` was accepted by the config schema and then
+ * ignored — the runtime asked only whether the strategy was `'disabled'`, so
+ * a host who chose the cheap non-LLM path silently got the expensive LLM one,
+ * summarization calls and all. These pin the behaviour the name always
+ * claimed, and the three invariants that make a shorter history usable rather
+ * than merely shorter.
+ */
+
+const sys = (content: string): Message => ({ role: 'system', content, timestamp: 1 })
+const user = (content: string): Message => ({ role: 'user', content, timestamp: 1 })
+const asst = (content: string): Message => ({ role: 'assistant', content, timestamp: 1 })
+
+const callsTool = (id: string): AssistantMessage => ({
+	role: 'assistant',
+	content: null,
+	timestamp: 1,
+	toolCalls: [{ id, type: 'function', function: { name: 'echo', arguments: '{}' } }],
+})
+
+const toolResult = (id: string): ToolMessage => ({
+	role: 'tool',
+	content: 'ok',
+	timestamp: 1,
+	toolCallId: id,
+})
+
+function reduction(
+	messages: readonly Message[],
+	over?: Partial<ContextReduction>,
+): ContextReduction {
+	return {
+		messages,
+		reason: 'threshold',
+		estimatedTokens: 1_000,
+		contextWindowTokens: 2_000,
+		model: 'mock-model',
+		keepRecentMessages: 4,
+		...over,
+	}
+}
+
+describe('the sliding window keeps recent turns and drops the rest', () => {
+	it('keeps the configured tail', async () => {
+		const reduce = createSlidingWindowReducer()
+		const messages = [sys('prompt'), ...Array.from({ length: 10 }, (_, i) => user(`m${i}`))]
+
+		const next = await reduce(reduction(messages))
+
+		expect(next).toBeDefined()
+		expect(next?.length).toBe(5) // the system floor plus keepRecentMessages
+		expect(next?.at(-1)).toBe(messages.at(-1))
+	})
+
+	it('cuts harder when the provider already rejected the prompt', async () => {
+		const reduce = createSlidingWindowReducer()
+		const messages = [sys('prompt'), ...Array.from({ length: 10 }, (_, i) => user(`m${i}`))]
+
+		const threshold = await reduce(reduction(messages))
+		const overflow = await reduce(reduction(messages, { reason: 'overflow' }))
+
+		// An overflow means the ordinary window was ALREADY too big. Cutting to
+		// the same size would shed nothing and the caller would retry an
+		// identical prompt.
+		expect(overflow?.length).toBeLessThan(threshold?.length ?? 0)
+	})
+
+	it('summarizes nothing — every survivor is the original object', async () => {
+		const reduce = createSlidingWindowReducer()
+		const messages = [sys('prompt'), ...Array.from({ length: 8 }, (_, i) => user(`m${i}`))]
+
+		const next = await reduce(reduction(messages))
+
+		for (const message of next ?? []) expect(messages).toContain(message)
+	})
+})
+
+describe('the three invariants a shorter history has to keep', () => {
+	it('never drops the leading system floor', async () => {
+		const reduce = createSlidingWindowReducer()
+		const messages = [
+			sys('prompt'),
+			sys('working memory'),
+			...Array.from({ length: 8 }, (_, i) => user(`m${i}`)),
+		]
+
+		const next = await reduce(reduction(messages))
+
+		expect(next?.[0]).toBe(messages[0])
+		expect(next?.[1]).toBe(messages[1])
+	})
+
+	it('does not split a tool_use from its tool_result', async () => {
+		const reduce = createSlidingWindowReducer()
+		// The naive cut at length-3 lands between the assistant call and its
+		// result, which is a provider 400 on the next turn.
+		const messages = [
+			sys('prompt'),
+			user('go'),
+			asst('thinking'),
+			callsTool('c1'),
+			toolResult('c1'),
+			user('again'),
+			asst('done'),
+			user('more'),
+		]
+
+		const next = await reduce(reduction(messages, { keepRecentMessages: 5 }))
+
+		const kept = new Set(next ?? [])
+		// Cutting at 3 would keep the call and its result together; cutting at
+		// 4 would orphan the result. The pair is never split either way.
+		expect(kept.has(messages[4] as Message)).toBe(kept.has(messages[3] as Message))
+	})
+
+	it('takes a cut above the requested window when nothing below is safe', async () => {
+		const reduce = createSlidingWindowReducer()
+		// A multi-step turn: the user is silent while the agent works, so every
+		// boundary inside the recent window opens on an assistant or tool
+		// message. A backwards-only search would decline here — exactly when
+		// the history is longest.
+		const messages = [
+			sys('prompt'),
+			user('go'),
+			callsTool('c1'),
+			toolResult('c1'),
+			asst('working'),
+			callsTool('c2'),
+			toolResult('c2'),
+			// The only user turn after the opening one, and it sits ABOVE the
+			// requested cut — so every candidate below opens on an assistant or
+			// tool message and the backwards search comes back empty.
+			user('next'),
+			callsTool('c3'),
+			toolResult('c3'),
+		]
+
+		const next = await reduce(reduction(messages, { keepRecentMessages: 5 }))
+
+		expect(next).toBeDefined()
+		expect(next?.length).toBeLessThan(messages.length)
+		// It kept LESS than asked rather than declining, and what it kept opens
+		// on a user turn.
+		expect(next?.[1]?.role).toBe('user')
+	})
+
+	it('keeps a pinned turn from the middle of the conversation', async () => {
+		const reduce = createSlidingWindowReducer()
+		const pinned: Message = { ...user('the account id is X'), retain: true }
+		const messages = [
+			sys('prompt'),
+			user('m0'),
+			pinned,
+			...Array.from({ length: 8 }, (_, i) => user(`m${i + 1}`)),
+		]
+
+		const next = await reduce(reduction(messages))
+
+		// Recency is not the only thing that matters, which is what `retain`
+		// exists to say.
+		expect(next).toContain(pinned)
+		expect(next).not.toContain(messages[1])
+	})
+})
+
+describe('refusing beats a reduction that would break the next turn', () => {
+	it('declines when there is nothing but the system floor to cut', async () => {
+		const reduce = createSlidingWindowReducer()
+
+		expect(await reduce(reduction([sys('prompt'), user('go')]))).toBeUndefined()
+	})
+
+	it('declines when every candidate cut splits one assistant fan-out', async () => {
+		const reduce = createSlidingWindowReducer()
+		// Six results answering one call: no cut inside the block is safe, and
+		// the condition clears itself on the next assistant message.
+		const messages = [
+			sys('prompt'),
+			user('go'),
+			{
+				role: 'assistant',
+				content: null,
+				timestamp: 1,
+				toolCalls: Array.from({ length: 6 }, (_, i) => ({
+					id: `c${i}`,
+					type: 'function' as const,
+					function: { name: 'echo', arguments: '{}' },
+				})),
+			} as AssistantMessage,
+			...Array.from({ length: 6 }, (_, i) => toolResult(`c${i}`)),
+		]
+
+		expect(await reduce(reduction(messages, { keepRecentMessages: 2 }))).toBeUndefined()
+	})
+
+	it('declines rather than reporting a reduction that removed nothing', async () => {
+		const reduce = createSlidingWindowReducer()
+		// Every non-system message is pinned, so the survivor set is the input.
+		const messages = [
+			sys('prompt'),
+			...Array.from({ length: 8 }, (_, i) => ({ ...user(`m${i}`), retain: true })),
+		]
+
+		// Saying "reduced" here would have the overflow path retry an identical
+		// prompt and burn a model call to be told the same thing.
+		expect(await reduce(reduction(messages))).toBeUndefined()
+	})
+})
+
+describe('the knob a caller reaches for', () => {
+	it('lets an explicit window override the run config', async () => {
+		const reduce = createSlidingWindowReducer({ keepRecentMessages: 2 })
+		const messages = [sys('prompt'), ...Array.from({ length: 10 }, (_, i) => user(`m${i}`))]
+
+		const next = await reduce(reduction(messages, { keepRecentMessages: 8 }))
+
+		expect(next?.length).toBe(3)
+	})
+
+	it('is a plain function, so a host can wrap one', async () => {
+		const inner = createSlidingWindowReducer()
+		const seen = vi.fn()
+		const reduce = async (input: ContextReduction) => {
+			seen(input.reason)
+			return inner(input)
+		}
+		const messages = [sys('prompt'), ...Array.from({ length: 8 }, (_, i) => user(`m${i}`))]
+
+		await reduce(reduction(messages, { reason: 'overflow' }))
+
+		expect(seen).toHaveBeenCalledWith('overflow')
+	})
+})

package/src/compaction/factory.ts

@@ -20,6 +20,13 @@ import type { CompactionStrategy } from './types.js'
  * const trimmed = manager.applyManagement(messages)
  * ```
  */
+/**
+ * @deprecated Nothing calls this. Select a strategy with
+ * `compactionConfig.strategy`, or pass a `contextReducer` to `query()`.
+ *
+ * The factory produced managers the runtime had no seam to drive, so its
+ * return value was always dropped on the floor. See {@link ConversationManager}.
+ */
 export function createConversationManager(
 	strategy: CompactionStrategy,
 	config: CompactionConfig,

package/src/compaction/index.ts

@@ -11,6 +11,14 @@ export type { DanglingResult } from './dangling.js'
 
 export type { ConversationManager } from './interface.js'
 
+export { createSlidingWindowReducer } from './reducer.js'
+export type {
+	ContextReducer,
+	ContextReduction,
+	ContextReductionReason,
+	SlidingWindowOptions,
+} from './reducer.js'
+
 export { WorkingStateManager } from './manager.js'
 
 export { serializeState } from './serializer.js'

package/src/compaction/interface.ts

@@ -7,6 +7,19 @@ import type { Message } from '../types/message/index.js'
  * A manager applies two strategies:
  * 1. **Routine management** (applyManagement): Called after each iteration to proactively optimize context.
  * 2. **Overflow reduction** (reduceContext): Called when the LLM reports context window exceeded.
+ *
+ * @deprecated Use {@link ContextReducer}, which the runtime actually drives.
+ *
+ * This interface cannot be implemented correctly. `reduceContext` is
+ * documented as reducing the history, but it takes `Message[]` and returns
+ * `boolean` — the only way to honour the contract is to mutate the argument
+ * in place, and neither shipped implementation does. Both build a shorter
+ * array locally, discard it, and return `true`. Nothing in the runtime ever
+ * called any of it, which is why an unfulfillable contract survived.
+ *
+ * `ContextReducer` returns the new history, may be async so a reducer can
+ * call a model, and is told whether it was asked speculatively or after the
+ * provider rejected the prompt. Kept exported until the next major.
  */
 export interface ConversationManager {
 	/** Unique name for this manager (e.g., 'structured', 'sliding-window', 'disabled') */

package/src/compaction/managers/null.ts

@@ -5,6 +5,9 @@ import type { ConversationManager } from '../interface.js'
  * No-op conversation manager implementation.
  * Never modifies messages, useful for testing or when context management is disabled.
  */
+/**
+ * @deprecated Use `strategy: 'disabled'`, which the runtime reads.
+ */
 export class NullManager implements ConversationManager {
 	readonly name = 'null'
 

package/src/compaction/managers/slidingWindow.ts

@@ -20,6 +20,12 @@ export interface SlidingWindowManagerConfig {
  * 2. Use findSafeTrimIndex to ensure tool call/result pairs remain atomic
  * 3. applyManagement runs proactively each iteration; reduceContext on overflow
  */
+/**
+ * @deprecated Use `createSlidingWindowReducer()`, or `strategy: 'sliding-window'`.
+ *
+ * Never reachable through the runtime, and `reduceContext` here computes a
+ * trim index and returns a boolean without trimming anything.
+ */
 export class SlidingWindowManager implements ConversationManager {
 	readonly name = 'sliding-window'
 	private readonly keepRecentMessages: number

package/src/compaction/managers/structured.ts

@@ -22,6 +22,16 @@ import { serializeState } from '../serializer.js'
  *
  * Provides maximum context preservation but more computational overhead.
  */
+/**
+ * @deprecated Not the structured strategy. `strategy: 'structured'` runs the
+ * live path in `runtime/query/iteration/phases/compaction.ts`, which this
+ * class predates and does not share code with.
+ *
+ * What is here is a weaker parallel copy: no LLM-verified summary, no stale
+ * tool-result clearing, no retention pins, no events — and a `reduceContext`
+ * that builds a shorter history into a local array and then returns a
+ * boolean, discarding it.
+ */
 export class StructuredCompactionManager implements ConversationManager {
 	readonly name = 'structured'
 	private readonly config: CompactionConfig

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'