@namzu/sdk 0.1.3 → 0.1.4-rc.2

package/src/index.ts

@@ -1,6 +1,12 @@
 export { VERSION } from './version.js'
-export { RuntimeConfigSchema, RUNTIME_DEFAULTS } from './config/runtime.js'
-export type { RuntimeConfig } from './config/runtime.js'
+export {
+	RuntimeConfigSchema,
+	TaskRouterConfigSchema,
+	CompactionConfigSchema,
+	PluginRuntimeConfigSchema,
+	RUNTIME_DEFAULTS,
+} from './config/runtime.js'
+export type { RuntimeConfig, CompactionConfig, PluginRuntimeConfig } from './config/runtime.js'
 
 export * from './constants/index.js'
 
@@ -27,6 +33,21 @@ export * from './types/connector/index.js'
 export * from './types/skills/index.js'
 export * from './types/a2a/index.js'
 export * from './types/conversation/index.js'
+export * from './types/router/index.js'
+export * from './types/advisory/index.js'
+export * from './types/memory/index.js'
+export * from './types/plugin/index.js'
+
+export {
+	AdvisorRegistry,
+	AdvisoryExecutor,
+	TriggerEvaluator,
+	AdvisoryContext,
+} from './advisory/index.js'
+export type {
+	AdvisoryCallContext,
+	AdvisoryExecutionResult,
+} from './advisory/index.js'
 
 export {
 	assembleSystemPrompt,
@@ -45,10 +66,20 @@ export * from './utils/cost.js'
 export * from './utils/error.js'
 export * from './utils/logger.js'
 export { hashToolResult, buildToolResultHashes } from './utils/hash.js'
+export {
+	compressShellOutput,
+	compressShellOutputFull,
+} from './utils/shell-compress.js'
+export type {
+	ShellCompressResult,
+	ShellCompressOptions,
+} from './utils/shell-compress.js'
 export { createChildAbortController } from './utils/abort.js'
 export { memoizeAsync } from './utils/memoize.js'
 export { extractFinalResponse } from './utils/conversation.js'
 
+export { resolveTaskModel } from './router/task-router.js'
+
 export { query, drainQuery } from './runtime/query/index.js'
 export type { QueryParams } from './runtime/query/index.js'
 export { ContextCache } from './runtime/query/context-cache.js'
@@ -71,12 +102,27 @@ export type { DefineAgentOptions } from './agents/index.js'
 
 export { InMemoryStore } from './store/InMemoryStore.js'
 export type { Identifiable, Timestamped } from './store/InMemoryStore.js'
+export { InMemoryMemoryIndex } from './store/memory/index.js'
+export { InMemoryMemoryStore } from './store/memory/memory.js'
+export { DiskMemoryStore } from './store/memory/disk.js'
+export type { DiskMemoryStoreConfig } from './store/memory/disk.js'
 
 export { Registry } from './registry/Registry.js'
 export { ManagedRegistry } from './registry/ManagedRegistry.js'
 export type { ManagedRegistryConfig } from './registry/ManagedRegistry.js'
 export { AgentRegistry } from './registry/agent/definitions.js'
+export { PluginRegistry } from './registry/plugin/index.js'
+
+export {
+	PluginLifecycleManager,
+	PluginResolver,
+	discoverPlugins,
+	loadPluginManifest,
+	discoverAllPluginDirs,
+} from './plugin/index.js'
+export type { PluginLifecycleManagerConfig } from './plugin/lifecycle.js'
 
+export { EmergencySaveManager } from './manager/run/emergency.js'
 export { RunPersistence } from './manager/run/persistence.js'
 export { RunDiskStore } from './store/run/disk.js'
 export { SessionStore } from './store/run/disk.js'
@@ -92,6 +138,9 @@ export {
 	buildTaskUpdateTool,
 	buildTaskListTool,
 } from './tools/task/index.js'
+export { buildAdvisoryTools } from './tools/advisory/index.js'
+export type { AdvisoryToolsOptions } from './tools/advisory/index.js'
+export { buildMemoryTools } from './tools/memory/index.js'
 export { InMemoryConversationStore } from './store/conversation/memory.js'
 export type { InMemoryConversationStoreConfig } from './store/conversation/memory.js'
 export { PlanManager } from './manager/plan/lifecycle.js'
@@ -223,3 +272,21 @@ export {
 } from './telemetry/index.js'
 export type { PlatformMetrics } from './telemetry/index.js'
 export * from './telemetry/attributes.js'
+
+export {
+	WorkingStateManager,
+	serializeState,
+	extractFromToolCall,
+	extractFromToolResult,
+	extractFromUserMessage,
+	extractFromAssistantMessage,
+	buildVerifiedSummary,
+} from './compaction/index.js'
+export type {
+	WorkingState,
+	PlanSlot,
+	FileSlot,
+	FileAction,
+	ToolResultSlot,
+	CompactionStrategy,
+} from './compaction/index.js'

package/src/manager/run/emergency.ts

@@ -0,0 +1,117 @@
+import {
+	mkdirSync,
+	readFileSync,
+	readdirSync,
+	renameSync,
+	unlinkSync,
+	writeFileSync,
+} from 'node:fs'
+import { join } from 'node:path'
+import {
+	EMERGENCY_DIR_NAME,
+	EMERGENCY_EVENTS,
+	EMERGENCY_SIGNALS,
+} from '../../constants/emergency.js'
+import type { EmergencySaveData } from '../../types/run/emergency.js'
+import type { Logger } from '../../utils/logger.js'
+import type { RunPersistence } from './persistence.js'
+
+export class EmergencySaveManager {
+	private static _instance: EmergencySaveManager | undefined
+	private sessionRef: WeakRef<RunPersistence> | undefined
+	private outputDir: string | undefined
+	private signalHandlers: Map<string, () => void> = new Map()
+	private log: Logger
+
+	private constructor(log: Logger) {
+		this.log = log
+	}
+
+	static instance(log?: Logger): EmergencySaveManager {
+		if (!EmergencySaveManager._instance) {
+			if (!log) {
+				throw new Error('EmergencySaveManager requires a logger on first initialization')
+			}
+			EmergencySaveManager._instance = new EmergencySaveManager(log)
+		}
+		return EmergencySaveManager._instance
+	}
+
+	attach(sessionMgr: RunPersistence, outputDir: string, log: Logger): void {
+		this.detach()
+		this.sessionRef = new WeakRef(sessionMgr)
+		this.outputDir = outputDir
+		this.log = log.child({ component: 'EmergencySaveManager' })
+
+		for (const signal of EMERGENCY_SIGNALS) {
+			const handler = (): void => {
+				this.emergencySave(signal)
+			}
+			this.signalHandlers.set(signal, handler)
+			process.on(signal, handler)
+		}
+
+		for (const event of EMERGENCY_EVENTS) {
+			const handler = (): void => {
+				this.emergencySave(event)
+			}
+			this.signalHandlers.set(event, handler)
+			process.on(event, handler)
+		}
+
+		this.log.info('Emergency save handlers attached', { outputDir })
+	}
+
+	detach(): void {
+		for (const [signal, handler] of this.signalHandlers) {
+			process.removeListener(signal, handler)
+		}
+		this.signalHandlers.clear()
+		this.sessionRef = undefined
+		this.outputDir = undefined
+	}
+
+	emergencySave(signal: string): void {
+		const sessionMgr = this.sessionRef?.deref()
+		if (!sessionMgr || !this.outputDir) {
+			return
+		}
+
+		const snapshot = sessionMgr.toEmergencySnapshot(signal)
+
+		const emergencyDir = join(this.outputDir, '..', EMERGENCY_DIR_NAME)
+		mkdirSync(emergencyDir, { recursive: true })
+
+		const tmpPath = join(emergencyDir, `${snapshot.runId}.json.tmp`)
+		const finalPath = join(emergencyDir, `${snapshot.runId}.json`)
+
+		writeFileSync(tmpPath, JSON.stringify(snapshot, null, '\t'), 'utf-8')
+		renameSync(tmpPath, finalPath)
+
+		this.log.warn('Emergency save completed', {
+			runId: snapshot.runId,
+			signal,
+			path: finalPath,
+		})
+	}
+
+	static listSaves(baseDir: string): string[] {
+		const emergencyDir = join(baseDir, EMERGENCY_DIR_NAME)
+		try {
+			return readdirSync(emergencyDir)
+				.filter((f) => f.endsWith('.json'))
+				.map((f) => join(emergencyDir, f))
+		} catch {
+			return []
+		}
+	}
+
+	static loadSave(filePath: string): EmergencySaveData {
+		const raw = readFileSync(filePath, 'utf-8')
+		return JSON.parse(raw) as EmergencySaveData
+	}
+
+	static clearSave(filePath: string): void {
+		unlinkSync(filePath)
+	}
+}

package/src/manager/run/persistence.ts

@@ -7,9 +7,11 @@ import {
 } from '../../types/common/index.js'
 import type { RunId } from '../../types/ids/index.js'
 import type { AssistantMessage, Message } from '../../types/message/index.js'
+import type { EmergencySaveData } from '../../types/run/emergency.js'
 import type { AgentRun, StopReason } from '../../types/run/index.js'
 import type { RunPersistenceConfig } from '../../types/run/index.js'
 import { type ModelPricing, ZERO_COST, accumulateCost } from '../../utils/cost.js'
+import { generateEmergencySaveId } from '../../utils/id.js'
 import type { Logger } from '../../utils/logger.js'
 
 export class RunPersistence {
@@ -156,6 +158,20 @@ export class RunPersistence {
 		}
 	}
 
+	toEmergencySnapshot(signal: string): EmergencySaveData {
+		return {
+			id: generateEmergencySaveId(),
+			runId: this.run.id,
+			messages: this.run.messages,
+			tokenUsage: this.run.tokenUsage,
+			currentIteration: this.run.currentIteration,
+			startedAt: this.run.startedAt,
+			savedAt: Date.now(),
+			processSignal: signal,
+			lastError: this.run.lastError,
+		}
+	}
+
 	async persist(): Promise<void> {
 		await this.runStore.writeRunMeta(this.run)
 		await this.runStore.writeMessages(this.run)

package/src/persona/assembler.ts

@@ -1,4 +1,4 @@
-import type { AgentPersona } from '../types/persona/index.js'
+import type { AgentPersona, OutputDiscipline } from '../types/persona/index.js'
 import type { Skill } from '../types/skills/index.js'
 
 export function assembleSystemPrompt(persona: AgentPersona, skills?: Skill[]): string {
@@ -33,6 +33,10 @@ export function assembleSystemPrompt(persona: AgentPersona, skills?: Skill[]): s
 		}
 	}
 
+	if (persona.reflexes?.outputDiscipline) {
+		sections.push(renderOutputDiscipline(persona.reflexes.outputDiscipline))
+	}
+
 	if (persona.output) {
 		sections.push(`## Output Format\n${persona.output.format.trim()}`)
 	}
@@ -44,6 +48,36 @@ export function assembleSystemPrompt(persona: AgentPersona, skills?: Skill[]): s
 	return sections.join('\n\n')
 }
 
+export function renderOutputDiscipline(discipline: OutputDiscipline): string {
+	const lines: string[] = []
+
+	if (discipline.betweenToolCalls === 'silent') {
+		lines.push('- Emit zero words between tool calls. Call tools back-to-back with no narration.')
+	} else {
+		lines.push(
+			'- Emit minimal text between tool calls. Keep inter-tool narration to a single short sentence.',
+		)
+	}
+
+	if (discipline.suppressInnerMonologue) {
+		lines.push('- Do not output inner monologue, reasoning traces, or planning text between turns.')
+	}
+
+	if (discipline.finalResponse?.singleFileMaxWords) {
+		lines.push(
+			`- Final response for single-file changes: ${discipline.finalResponse.singleFileMaxWords} words maximum. Describe the why, not the what.`,
+		)
+	}
+
+	if (discipline.finalResponse?.multiFileMaxWords) {
+		lines.push(
+			`- Final response for multi-file changes: ${discipline.finalResponse.multiFileMaxWords} words maximum. Summarize intent and scope.`,
+		)
+	}
+
+	return `## Output Discipline\n${lines.join('\n')}`
+}
+
 export function mergePersonas(base: AgentPersona, override: Partial<AgentPersona>): AgentPersona {
 	return {
 		identity: override.identity ?? base.identity,
@@ -56,6 +90,7 @@ export function mergePersonas(base: AgentPersona, override: Partial<AgentPersona
 				...(override.reflexes?.constraints ?? []),
 			],
 			toolGuidance: override.reflexes?.toolGuidance ?? base.reflexes?.toolGuidance,
+			outputDiscipline: override.reflexes?.outputDiscipline ?? base.reflexes?.outputDiscipline,
 		},
 		output: override.output ?? base.output,
 		sessionContext: override.sessionContext ?? base.sessionContext,

package/src/plugin/index.ts

@@ -0,0 +1,3 @@
+export { discoverPlugins, loadPluginManifest, discoverAllPluginDirs } from './loader.js'
+export { PluginLifecycleManager } from './lifecycle.js'
+export { PluginResolver } from './resolver.js'

package/src/plugin/lifecycle.ts

@@ -0,0 +1,308 @@
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { HOOK_TIMEOUT_MS, PLUGIN_NAMESPACE_SEPARATOR } from '../constants/plugin/index.js'
+import type { PluginRegistry } from '../registry/plugin/index.js'
+import type { ToolRegistry } from '../registry/tool/execute.js'
+import type { PluginId } from '../types/ids/index.js'
+import type {
+	PluginDefinition,
+	PluginEventListener,
+	PluginHookContext,
+	PluginHookDefinition,
+	PluginHookEvent,
+	PluginHookResult,
+	PluginLifecycleEvent,
+	PluginScope,
+} from '../types/plugin/index.js'
+import type { ToolDefinition } from '../types/tool/index.js'
+import { toErrorMessage } from '../utils/error.js'
+import { generatePluginId } from '../utils/id.js'
+import type { Logger } from '../utils/logger.js'
+import { loadPluginManifest } from './loader.js'
+
+export interface PluginLifecycleManagerConfig {
+	pluginRegistry: PluginRegistry
+	toolRegistry: ToolRegistry
+	log: Logger
+	hookTimeoutMs?: number
+}
+
+export class PluginLifecycleManager {
+	private pluginRegistry: PluginRegistry
+	private toolRegistry: ToolRegistry
+	private listeners: PluginEventListener[] = []
+	private hookHandlers: Map<
+		PluginHookEvent,
+		Array<{ pluginId: PluginId; handler: PluginHookDefinition['handler'] }>
+	> = new Map()
+	private pluginContributions: Map<PluginId, string[]> = new Map()
+	private hookTimeoutMs: number
+	private log: Logger
+
+	constructor(config: PluginLifecycleManagerConfig) {
+		this.pluginRegistry = config.pluginRegistry
+		this.toolRegistry = config.toolRegistry
+		this.hookTimeoutMs = config.hookTimeoutMs ?? HOOK_TIMEOUT_MS
+		this.log = config.log.child({ component: 'PluginLifecycleManager' })
+	}
+
+	on(listener: PluginEventListener): void {
+		this.listeners.push(listener)
+	}
+
+	off(listener: PluginEventListener): void {
+		const index = this.listeners.indexOf(listener)
+		if (index >= 0) this.listeners.splice(index, 1)
+	}
+
+	async install(pluginDir: string, scope: PluginScope): Promise<PluginDefinition> {
+		const manifest = await loadPluginManifest(pluginDir)
+
+		const existing = this.pluginRegistry.findByName(manifest.name)
+		if (existing) {
+			throw new Error(`Plugin "${manifest.name}" is already installed (id: ${existing.id})`)
+		}
+
+		const pluginId = generatePluginId()
+		const definition: PluginDefinition = {
+			id: pluginId,
+			manifest,
+			scope,
+			status: 'installed',
+			rootDir: pluginDir,
+			installedAt: Date.now(),
+		}
+
+		this.pluginRegistry.register(definition)
+
+		this.emit({
+			type: 'plugin_installed',
+			pluginId,
+			name: manifest.name,
+			scope,
+		})
+
+		this.log.info(`Plugin installed: ${manifest.name}`, {
+			pluginId,
+			scope,
+			version: manifest.version,
+		})
+
+		return definition
+	}
+
+	async enable(pluginId: PluginId): Promise<void> {
+		const plugin = this.pluginRegistry.getOrThrow(pluginId)
+
+		if (plugin.status !== 'installed' && plugin.status !== 'disabled') {
+			throw new Error(
+				`Cannot enable plugin "${plugin.manifest.name}": status is "${plugin.status}" (expected "installed" or "disabled")`,
+			)
+		}
+
+		const registeredToolNames: string[] = []
+		const { manifest } = plugin
+
+		// Load tools
+		if (manifest.tools && manifest.tools.length > 0) {
+			for (const toolPath of manifest.tools) {
+				const absolutePath = join(plugin.rootDir, toolPath)
+				const fileUrl = pathToFileURL(absolutePath).href
+				const mod = (await import(fileUrl)) as { tools?: ToolDefinition[] }
+
+				if (!mod.tools || !Array.isArray(mod.tools)) {
+					throw new Error(
+						`Plugin "${manifest.name}": tool module "${toolPath}" must export a "tools" array`,
+					)
+				}
+
+				for (const tool of mod.tools) {
+					const namespacedName = manifest.name + PLUGIN_NAMESPACE_SEPARATOR + tool.name
+					const namespacedTool: ToolDefinition = { ...tool, name: namespacedName }
+					this.toolRegistry.register(namespacedTool, 'deferred')
+					registeredToolNames.push(namespacedName)
+				}
+			}
+		}
+
+		// Load hooks
+		if (manifest.hooks && manifest.hooks.length > 0) {
+			for (const hookPath of manifest.hooks) {
+				const absolutePath = join(plugin.rootDir, hookPath)
+				const fileUrl = pathToFileURL(absolutePath).href
+				const mod = (await import(fileUrl)) as { hooks?: PluginHookDefinition[] }
+
+				if (!mod.hooks || !Array.isArray(mod.hooks)) {
+					throw new Error(
+						`Plugin "${manifest.name}": hook module "${hookPath}" must export a "hooks" array`,
+					)
+				}
+
+				for (const hook of mod.hooks) {
+					const handlers = this.hookHandlers.get(hook.event) ?? []
+					handlers.push({ pluginId, handler: hook.handler })
+					this.hookHandlers.set(hook.event, handlers)
+				}
+			}
+		}
+
+		// Log unsupported contribution types
+		if (manifest.skills && manifest.skills.length > 0) {
+			this.log.info(`Plugin "${manifest.name}": skills contribution not yet supported`)
+		}
+		if (manifest.mcpServers && manifest.mcpServers.length > 0) {
+			this.log.info(`Plugin "${manifest.name}": MCP servers contribution not yet supported`)
+		}
+		if (manifest.connectors && manifest.connectors.length > 0) {
+			this.log.info(`Plugin "${manifest.name}": connectors contribution not yet supported`)
+		}
+		if (manifest.personas && manifest.personas.length > 0) {
+			this.log.info(`Plugin "${manifest.name}": personas contribution not yet supported`)
+		}
+
+		// Track contributions for cleanup
+		this.pluginContributions.set(pluginId, registeredToolNames)
+
+		// Update status to enabled
+		const enabled: PluginDefinition = {
+			...plugin,
+			status: 'enabled',
+			enabledAt: Date.now(),
+		}
+		this.pluginRegistry.register(enabled)
+
+		this.emit({
+			type: 'plugin_enabled',
+			pluginId,
+			name: manifest.name,
+		})
+
+		this.log.info(`Plugin enabled: ${manifest.name}`, {
+			pluginId,
+			toolCount: registeredToolNames.length,
+		})
+	}
+
+	async disable(pluginId: PluginId): Promise<void> {
+		const plugin = this.pluginRegistry.getOrThrow(pluginId)
+
+		if (plugin.status !== 'enabled') {
+			throw new Error(
+				`Cannot disable plugin "${plugin.manifest.name}": status is "${plugin.status}" (expected "enabled")`,
+			)
+		}
+
+		// Unregister contributed tools
+		const toolNames = this.pluginContributions.get(pluginId) ?? []
+		for (const name of toolNames) {
+			this.toolRegistry.unregister(name)
+		}
+
+		// Remove hook handlers for this plugin
+		for (const [event, handlers] of this.hookHandlers) {
+			const filtered = handlers.filter((h) => h.pluginId !== pluginId)
+			if (filtered.length === 0) {
+				this.hookHandlers.delete(event)
+			} else {
+				this.hookHandlers.set(event, filtered)
+			}
+		}
+
+		// Clear contributions tracking
+		this.pluginContributions.delete(pluginId)
+
+		// Update status to disabled
+		const disabled: PluginDefinition = {
+			...plugin,
+			status: 'disabled',
+			enabledAt: undefined,
+		}
+		this.pluginRegistry.register(disabled)
+
+		this.emit({
+			type: 'plugin_disabled',
+			pluginId,
+			name: plugin.manifest.name,
+		})
+
+		this.log.info(`Plugin disabled: ${plugin.manifest.name}`, { pluginId })
+	}
+
+	async uninstall(pluginId: PluginId): Promise<void> {
+		const plugin = this.pluginRegistry.getOrThrow(pluginId)
+
+		if (plugin.status === 'enabled') {
+			await this.disable(pluginId)
+		}
+
+		this.pluginRegistry.unregister(pluginId)
+
+		this.emit({
+			type: 'plugin_uninstalled',
+			pluginId,
+			name: plugin.manifest.name,
+		})
+
+		this.log.info(`Plugin uninstalled: ${plugin.manifest.name}`, { pluginId })
+	}
+
+	async executeHooks(
+		event: PluginHookEvent,
+		context: Omit<PluginHookContext, 'pluginId' | 'event'>,
+	): Promise<PluginHookResult[]> {
+		const handlers = this.hookHandlers.get(event)
+		if (!handlers || handlers.length === 0) {
+			return []
+		}
+
+		const results: PluginHookResult[] = []
+
+		for (const { pluginId, handler } of handlers) {
+			const hookContext: PluginHookContext = {
+				...context,
+				pluginId,
+				event,
+			}
+
+			const start = performance.now()
+			let result: PluginHookResult
+
+			try {
+				result = await Promise.race([
+					handler(hookContext),
+					new Promise<PluginHookResult>((_, reject) =>
+						setTimeout(() => reject(new Error('Hook timeout')), this.hookTimeoutMs),
+					),
+				])
+			} catch (err) {
+				const message = toErrorMessage(err)
+				result = { action: 'error', message }
+			}
+
+			const durationMs = Math.round(performance.now() - start)
+
+			this.emit({
+				type: 'plugin_hook_executed',
+				pluginId,
+				hookEvent: event,
+				durationMs,
+			})
+
+			results.push(result)
+		}
+
+		return results
+	}
+
+	private emit(event: PluginLifecycleEvent): void {
+		for (const listener of this.listeners) {
+			try {
+				listener(event)
+			} catch (err) {
+				this.log.error('Plugin event listener error', {
+					error: toErrorMessage(err),
+				})
+			}
+		}
+	}
+}