@namzu/sdk 2.0.0 → 3.0.0

package/src/manager/run/persistence.ts

@@ -8,7 +8,7 @@ import type { Message } from '../../types/message/index.js'
 import type { ProviderErrorInfo } from '../../types/provider/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 { Run, RunPersistenceConfig, StepResult, StopReason } from '../../types/run/index.js'
 import type { ProjectId, ThreadId } from '../../types/session/ids.js'
 import { type ModelPricing, ZERO_COST, accumulateCost } from '../../utils/cost.js'
 import { generateEmergencySaveId } from '../../utils/id.js'
@@ -19,6 +19,11 @@ export class RunPersistence {
 	private runStore: RunDiskStore
 	private checkpointStore: CheckpointStore
 	private pricing?: ModelPricing
+
+	/** See {@link recordTurnUsage}. */
+	private _lastPromptTokens?: number
+	/** See {@link lastPromptMessageCount}. */
+	private _lastPromptMessageCount?: number
 	private log: Logger
 	private readonly _sessionId: SessionId
 	private readonly _threadId: ThreadId
@@ -204,7 +209,133 @@ export class RunPersistence {
 		}
 	}
 
+	/**
+	 * Accumulate usage from a MAIN-LOOP turn, and remember its prompt size.
+	 *
+	 * `tokenUsage.promptTokens` is cumulative across turns, so it says
+	 * nothing about how full the context currently is. The last turn's
+	 * prompt count does: it is the provider's own measurement of the
+	 * context it just received. Compaction needs that number and nothing
+	 * else gives it — a char/4 heuristic is the alternative.
+	 *
+	 * Side-channel calls (advisory, the compaction verifier, routing) use
+	 * plain {@link accumulateUsage} instead: their prompts are not the
+	 * run's context, and letting them write here would corrupt the signal.
+	 */
+	recordTurnUsage(usage: TokenUsage): void {
+		this.accumulateUsage(usage)
+		this._lastPromptTokens = usage.promptTokens
+		// How much of the history that number covers. The loop pushes the
+		// assistant message and its tool results AFTER this call, so without
+		// the watermark a reader cannot tell which messages the provider
+		// actually weighed — and every one appended since is invisible to it.
+		this._lastPromptMessageCount = this.run.messages.length
+	}
+
+	/**
+	 * Forget the last prompt measurement. Called after compaction: the
+	 * reading described the context that was just replaced, so leaving it
+	 * in place would re-trigger compaction against a window that no longer
+	 * exists.
+	 */
+	/**
+	 * Attach the loop's per-iteration record to the run so a host that
+	 * persists the returned `Run` keeps per-step attribution instead of
+	 * having to reconstruct it from raw events.
+	 */
+	/** Record the validated structured output on the run. */
+	/**
+	 * Override the assembled result.
+	 *
+	 * Used by the output-guardrail rewrite path: the run produced text, a
+	 * policy corrected it, and the corrected text is what `run_completed`
+	 * and `Run.result` must carry.
+	 */
+	/**
+	 * Override the run's final text.
+	 *
+	 * The override is sticky: `resolveResult` re-derives the result from the
+	 * message tail, and it runs again when the run settles, so without this
+	 * flag a guardrail's redaction was silently re-expanded back to the raw
+	 * model output at `markCompleted`. The previous code only survived that
+	 * by settling the run EARLY — which is what made configuring a guardrail
+	 * rewrite a cancelled run's status.
+	 */
+	setResult(result: string): void {
+		this.run.result = result
+		this.resultOverridden = true
+	}
+
+	setStructuredOutput(value: unknown): void {
+		this.run.structuredOutput = value
+	}
+
+	setSteps(steps: readonly StepResult[]): void {
+		this.run.steps = steps
+	}
+
+	clearLastPromptTokens(): void {
+		this._lastPromptTokens = undefined
+		this._lastPromptMessageCount = undefined
+	}
+
+	/**
+	 * Provider-reported size of the most recent main-loop prompt, or
+	 * `undefined` before the first turn completes.
+	 */
+	get lastPromptTokens(): number | undefined {
+		return this._lastPromptTokens
+	}
+
+	/**
+	 * How many messages {@link lastPromptTokens} covers. Anything at or
+	 * after this index was appended once the measurement was already taken
+	 * and has to be accounted for separately.
+	 */
+	get lastPromptMessageCount(): number | undefined {
+		return this._lastPromptMessageCount
+	}
+
+	/**
+	 * Seed the spend counters from a checkpoint so a resumed run continues
+	 * its budget instead of starting a fresh one.
+	 *
+	 * Without this, a run checkpointed at $4.80 of a $5 cap came back with a
+	 * brand-new $5: a task that parked five times spent 5x its cap while
+	 * every invocation truthfully reported itself in budget. The checkpoint
+	 * already persisted all three values — they were written and discarded
+	 * on the way back in.
+	 *
+	 * Restore, not accumulate: the caller holds a checkpoint's absolute
+	 * totals, and adding them to a freshly-zeroed run would be the same
+	 * arithmetic only by accident.
+	 */
+	restoreUsage(tokenUsage: TokenUsage, costInfo: CostInfo, currentIteration: number): void {
+		this.run.tokenUsage = { ...tokenUsage }
+		this.run.costInfo = { ...costInfo }
+		this.run.currentIteration = currentIteration
+	}
+
+	/**
+	 * Assemble the final assistant output WITHOUT settling the run.
+	 *
+	 * An output guardrail has to read what the run produced before it can
+	 * judge it, and the only way to materialize that used to be
+	 * `markCompleted()` — which force-marked a cancelled or paused run as
+	 * `completed` merely because a guardrail was configured. Reading and
+	 * settling are different operations; this is the read.
+	 */
+	materializeResult(): string {
+		this.resolveResult()
+		return this.run.result ?? ''
+	}
+
+	/** Set once a caller has explicitly supplied the final text. */
+	private resultOverridden = false
+
 	private resolveResult(): void {
+		if (this.resultOverridden) return
+
 		// Walk the tail of the message log to assemble the final
 		// assistant output. The iteration loop's auto-continuation
 		// path (see `runtime/query/iteration/index.ts`) inserts a

package/src/plugin/__tests__/enable-contributions.test.ts

@@ -192,8 +192,8 @@ describe('PluginLifecycleManager enable() contribution types', () => {
 			expect(mockConnect).toHaveBeenCalledOnce()
 			expect(mockListTools).toHaveBeenCalledOnce()
 			expect(toolRegistry.listNames()).toEqual([
-				'fs-plugin:mcp__fs__read_file',
-				'fs-plugin:mcp__fs__write_file',
+				'fs-plugin__mcp__fs__read_file',
+				'fs-plugin__mcp__fs__write_file',
 			])
 		})
 
@@ -217,7 +217,7 @@ describe('PluginLifecycleManager enable() contribution types', () => {
 			})
 
 			await mgr.enable(pluginId)
-			expect(toolRegistry.listNames()).toContain('net:mcp__srv__ping')
+			expect(toolRegistry.listNames()).toContain('net__mcp__srv__ping')
 
 			await mgr.disable(pluginId)
 			expect(mockDisconnect).toHaveBeenCalledOnce()

package/src/plugin/__tests__/hook-ordering.test.ts

@@ -0,0 +1,252 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import type { PluginId, RunId } from '../../types/ids/index.js'
+import type { PluginHookResult } from '../../types/plugin/index.js'
+import { PluginLifecycleManager } from '../lifecycle.js'
+
+/**
+ * Hook order was install order — neither declared nor stable, since it
+ * depends on when each plugin happened to be installed. That is fine for a
+ * hook that only observes and wrong for one that decides: `executeHooks`
+ * SHORT-CIRCUITS on `skip` and `error`, so a hook that denies a dangerous
+ * command only gets to deny it if it runs before whatever else stops the
+ * chain. A guard whose firing depends on installation history is not a
+ * guard.
+ */
+
+const RUN_ID = 'run_x' as RunId
+
+function makeLogger(): never {
+	const logger = {
+		info: vi.fn(),
+		warn: vi.fn(),
+		error: vi.fn(),
+		debug: vi.fn(),
+		child: () => logger,
+	}
+	return logger as never
+}
+
+function makeManager(hookTimeoutMs?: number) {
+	return new PluginLifecycleManager({
+		pluginRegistry: {} as never,
+		toolRegistry: {} as never,
+		log: makeLogger(),
+		...(hookTimeoutMs !== undefined ? { hookTimeoutMs } : {}),
+	})
+}
+
+const record = (order: string[], name: string, result?: PluginHookResult) => async () => {
+	order.push(name)
+	return result ?? ({ action: 'continue' } as PluginHookResult)
+}
+
+describe('priority', () => {
+	it('runs a lower priority first, whatever order it was registered in', async () => {
+		const order: string[] = []
+		const manager = makeManager()
+		manager.registerHook('p_late' as PluginId, {
+			event: 'pre_tool_use',
+			priority: 900,
+			handler: record(order, 'observer'),
+		})
+		manager.registerHook('p_guard' as PluginId, {
+			event: 'pre_tool_use',
+			priority: 10,
+			handler: record(order, 'guard'),
+		})
+
+		await manager.executeHooks('pre_tool_use', { runId: RUN_ID })
+		expect(order).toEqual(['guard', 'observer'])
+	})
+
+	it('lets a guard deny before anything downstream can stop the chain', async () => {
+		const order: string[] = []
+		const manager = makeManager()
+		// Registered first, so under install order it would have run first
+		// and short-circuited before the guard ever saw the call.
+		manager.registerHook('p_other' as PluginId, {
+			event: 'pre_tool_use',
+			handler: record(order, 'other', { action: 'skip', reason: 'unrelated' }),
+		})
+		manager.registerHook('p_guard' as PluginId, {
+			event: 'pre_tool_use',
+			priority: 1,
+			handler: record(order, 'guard', { action: 'error', message: 'denied' }),
+		})
+
+		const results = await manager.executeHooks('pre_tool_use', { runId: RUN_ID })
+		expect(order).toEqual(['guard'])
+		expect(results).toEqual([{ action: 'error', message: 'denied' }])
+	})
+
+	it('keeps registration order for equal priorities', async () => {
+		const order: string[] = []
+		const manager = makeManager()
+		for (const name of ['a', 'b', 'c']) {
+			manager.registerHook(`p_${name}` as PluginId, {
+				event: 'iteration_start',
+				handler: record(order, name),
+			})
+		}
+
+		// A plugin that never sets a priority behaves exactly as before.
+		await manager.executeHooks('iteration_start', { runId: RUN_ID })
+		expect(order).toEqual(['a', 'b', 'c'])
+	})
+
+	it('unwinds a post hook in the opposite order, so a guard closes last', async () => {
+		const order: string[] = []
+		const manager = makeManager()
+		// Registered observer-first on purpose: under plain registration
+		// order the reversal alone would already produce the expected
+		// result, and the assertion would hold with no sorting at all.
+		manager.registerHook('p_observer' as PluginId, {
+			event: 'post_tool_use',
+			priority: 900,
+			handler: record(order, 'observer'),
+		})
+		manager.registerHook('p_guard' as PluginId, {
+			event: 'post_tool_use',
+			priority: 1,
+			handler: record(order, 'guard'),
+		})
+
+		// Post hooks unwind, so whichever opened first closes last — the
+		// wrapping order a guard needs.
+		await manager.executeHooks('post_tool_use', { runId: RUN_ID })
+		expect(order).toEqual(['observer', 'guard'])
+	})
+
+	it('composes modify in priority order', async () => {
+		const seen: unknown[] = []
+		const manager = makeManager()
+		manager.registerHook('p_second' as PluginId, {
+			event: 'pre_tool_use',
+			priority: 200,
+			handler: async (ctx) => {
+				seen.push(ctx.toolInput)
+				return { action: 'modify', input: { ...(ctx.toolInput as object), second: true } }
+			},
+		})
+		manager.registerHook('p_first' as PluginId, {
+			event: 'pre_tool_use',
+			priority: 100,
+			handler: async (ctx) => {
+				seen.push(ctx.toolInput)
+				return { action: 'modify', input: { ...(ctx.toolInput as object), first: true } }
+			},
+		})
+
+		const results = await manager.executeHooks('pre_tool_use', {
+			runId: RUN_ID,
+			toolInput: { base: true },
+		})
+
+		// What each hook SAW, not just the merged result: the merged object
+		// is identical either way round, so asserting on it alone would hold
+		// with no ordering at all.
+		expect(seen).toEqual([{ base: true }, { base: true, first: true }])
+		expect(results.at(-1)).toEqual({
+			action: 'modify',
+			input: { base: true, first: true, second: true },
+		})
+	})
+})
+
+describe('the deadline timer', () => {
+	it('does not keep a timer armed after the hook resolves', async () => {
+		const manager = makeManager(60_000)
+		manager.registerHook('p' as PluginId, {
+			event: 'run_start',
+			handler: async () => ({ action: 'continue' }),
+		})
+
+		vi.useFakeTimers()
+		try {
+			await manager.executeHooks('run_start', { runId: RUN_ID })
+			// An armed timer keeps the Node event loop alive. Hooks fire on
+			// every tool call and every model call, so a leak here meant a
+			// short run could not exit until the last deadline expired.
+			expect(vi.getTimerCount()).toBe(0)
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+
+	it('clears the timer even when the hook throws', async () => {
+		const manager = makeManager(60_000)
+		manager.registerHook('p' as PluginId, {
+			event: 'run_start',
+			handler: async () => {
+				throw new Error('boom')
+			},
+		})
+
+		vi.useFakeTimers()
+		try {
+			const results = await manager.executeHooks('run_start', { runId: RUN_ID })
+			expect(results[0]?.action).toBe('error')
+			expect(vi.getTimerCount()).toBe(0)
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+
+	it('leaves nothing armed across a chain of hooks', async () => {
+		const manager = makeManager(60_000)
+		for (let i = 0; i < 5; i++) {
+			manager.registerHook(`p${i}` as PluginId, {
+				event: 'iteration_start',
+				handler: async () => ({ action: 'continue' }),
+			})
+		}
+
+		vi.useFakeTimers()
+		try {
+			await manager.executeHooks('iteration_start', { runId: RUN_ID })
+			expect(vi.getTimerCount()).toBe(0)
+		} finally {
+			vi.useRealTimers()
+		}
+	})
+
+	it('tells a slow hook it was abandoned instead of only walking away', async () => {
+		const manager = makeManager(5)
+		let aborted = false
+		manager.registerHook('p' as PluginId, {
+			event: 'run_start',
+			handler: async (ctx) => {
+				ctx.signal?.addEventListener('abort', () => {
+					aborted = true
+				})
+				await new Promise((resolve) => setTimeout(resolve, 100))
+				return { action: 'continue' }
+			},
+		})
+
+		const results = await manager.executeHooks('run_start', { runId: RUN_ID })
+		expect(results[0]).toEqual({ action: 'error', message: 'Hook timeout' })
+		// Without this the hook never learns it was dropped, and an HTTP
+		// request inside it keeps a socket open for a run that moved on.
+		expect(aborted).toBe(true)
+	})
+
+	it('does not abort a hook that finished in time', async () => {
+		const manager = makeManager(10_000)
+		let aborted = false
+		manager.registerHook('p' as PluginId, {
+			event: 'run_start',
+			handler: async (ctx) => {
+				ctx.signal?.addEventListener('abort', () => {
+					aborted = true
+				})
+				return { action: 'continue' }
+			},
+		})
+
+		await manager.executeHooks('run_start', { runId: RUN_ID })
+		await new Promise((resolve) => setTimeout(resolve, 20))
+		expect(aborted).toBe(false)
+	})
+})

package/src/plugin/__tests__/install-time-refusal.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, it } from 'vitest'
+
+import type { PluginManifest } from '../../types/plugin/index.js'
+import { assertEnableable } from '../loader.js'
+
+/**
+ * The manifest schema accepts and validates `skills`, `connectors` and
+ * `personas` with per-type caps, and enabling then refused all three
+ * wholesale — before any contribution loaded. So a plugin shipping four
+ * tools and one skill validated clean, installed clean, was persisted as
+ * `installed`, and contributed zero tools.
+ *
+ * The refusal was right. Its position was not: a plugin that can never
+ * enable was being recorded under a status that says it is fine, and the
+ * author found out only when something tried to use it — at which point
+ * every supported contribution it also shipped went down with it.
+ */
+
+const manifest = (extra: Partial<PluginManifest> = {}): PluginManifest =>
+	({
+		name: 'demo',
+		version: '1.0.0',
+		...extra,
+	}) as PluginManifest
+
+describe('a manifest declaring what the runtime cannot enable', () => {
+	it.each(['skills', 'connectors', 'personas'] as const)('is refused for %s', (kind) => {
+		expect(() => assertEnableable(manifest({ [kind]: ['x'] } as never))).toThrow(new RegExp(kind))
+	})
+
+	it('names every unsupported type, not just the first', () => {
+		expect(() => assertEnableable(manifest({ skills: ['a'], personas: ['b'] } as never))).toThrow(
+			/skills, personas/,
+		)
+	})
+
+	it('says what would have been lost, so the refusal is actionable', () => {
+		// The author's real question is "why did my four tools not load".
+		expect(() => assertEnableable(manifest({ skills: ['a'] } as never))).toThrow(
+			/contributes nothing/,
+		)
+	})
+
+	it('points at the path that does work', () => {
+		// The registries all exist and are wired to agents through host
+		// configuration; what is missing is the manifest route into them.
+		expect(() => assertEnableable(manifest({ skills: ['a'] } as never))).toThrow(/registries/)
+	})
+})
+
+describe('a manifest the runtime can enable', () => {
+	it('passes with supported contributions', () => {
+		expect(() =>
+			assertEnableable(manifest({ tools: ['./tools.js'], hooks: ['./hooks.js'] } as never)),
+		).not.toThrow()
+	})
+
+	it('passes with the keys present but empty', () => {
+		// An empty array declares nothing, so there is nothing to refuse.
+		expect(() =>
+			assertEnableable(manifest({ skills: [], connectors: [], personas: [] } as never)),
+		).not.toThrow()
+	})
+
+	it('passes with no contributions at all', () => {
+		expect(() => assertEnableable(manifest())).not.toThrow()
+	})
+})