@namzu/sdk 0.1.3 → 0.1.4-rc.2

package/src/plugin/loader.ts

@@ -0,0 +1,91 @@
+import { readFile, readdir, stat } from 'node:fs/promises'
+import { homedir } from 'node:os'
+import { join } from 'node:path'
+import {
+	PLUGIN_MANIFEST_FILENAME,
+	PLUGIN_NAME_PATTERN,
+	PROJECT_PLUGIN_DIR,
+	USER_PLUGIN_DIR,
+} from '../constants/plugin/index.js'
+import { type PluginManifest, PluginManifestSchema } from '../types/plugin/index.js'
+import { getRootLogger } from '../utils/logger.js'
+
+const logger = getRootLogger().child({ component: 'PluginLoader' })
+
+/**
+ * Scans a directory for subdirectories containing a plugin manifest.
+ * Returns an array of absolute paths to plugin directories.
+ */
+export async function discoverPlugins(parentDir: string): Promise<string[]> {
+	const dirs: string[] = []
+
+	try {
+		const entries = await readdir(parentDir)
+		for (const entry of entries) {
+			if (entry.startsWith('.') || entry.startsWith('_')) continue
+			const fullPath = join(parentDir, entry)
+			const s = await stat(fullPath)
+			if (!s.isDirectory()) continue
+
+			const manifestPath = join(fullPath, PLUGIN_MANIFEST_FILENAME)
+			try {
+				await stat(manifestPath)
+				dirs.push(fullPath)
+			} catch {
+				// No manifest in this directory — skip
+			}
+		}
+	} catch {
+		logger.debug('Plugins directory not found', { parentDir })
+	}
+
+	return dirs
+}
+
+/**
+ * Reads and validates a plugin manifest from a plugin directory.
+ * Throws on invalid manifest (fail fast).
+ */
+export async function loadPluginManifest(pluginDir: string): Promise<PluginManifest> {
+	const manifestPath = join(pluginDir, PLUGIN_MANIFEST_FILENAME)
+	const raw = await readFile(manifestPath, 'utf-8')
+	const parsed: unknown = JSON.parse(raw)
+	return PluginManifestSchema.parse(parsed)
+}
+
+/**
+ * Validates that the plugin name matches the directory name
+ * and conforms to the plugin name pattern.
+ */
+export function validatePluginName(name: string, dirName: string): void {
+	if (!PLUGIN_NAME_PATTERN.test(name)) {
+		throw new Error(
+			`Plugin name "${name}" is invalid. Must be lowercase alphanumeric with hyphens (pattern: ${PLUGIN_NAME_PATTERN.source})`,
+		)
+	}
+	if (name !== dirName) {
+		throw new Error(`Plugin name "${name}" must match directory name "${dirName}"`)
+	}
+}
+
+/**
+ * Discovers plugin directories from both project-level and user-level locations.
+ * Returns categorized arrays of absolute paths.
+ */
+export async function discoverAllPluginDirs(
+	workingDirectory?: string,
+): Promise<{ project: string[]; user: string[] }> {
+	const projectDir = workingDirectory
+		? join(workingDirectory, PROJECT_PLUGIN_DIR)
+		: join(process.cwd(), PROJECT_PLUGIN_DIR)
+	const userDir = join(homedir(), USER_PLUGIN_DIR)
+
+	const [project, user] = await Promise.all([discoverPlugins(projectDir), discoverPlugins(userDir)])
+
+	logger.debug('Plugin discovery complete', {
+		projectCount: project.length,
+		userCount: user.length,
+	})
+
+	return { project, user }
+}

package/src/plugin/resolver.ts

@@ -0,0 +1,95 @@
+import { 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 { PluginContributionType } from '../types/plugin/index.js'
+
+export class PluginResolver {
+	private pluginRegistry: PluginRegistry
+	private toolRegistry: ToolRegistry
+
+	constructor(pluginRegistry: PluginRegistry, toolRegistry: ToolRegistry) {
+		this.pluginRegistry = pluginRegistry
+		this.toolRegistry = toolRegistry
+	}
+
+	/**
+	 * Parses a qualified tool name in `pluginName:toolName` format.
+	 * Returns null if the name is not namespaced.
+	 */
+	resolveToolName(qualifiedName: string): { pluginName: string; toolName: string } | null {
+		const sepIndex = qualifiedName.indexOf(PLUGIN_NAMESPACE_SEPARATOR)
+		if (sepIndex === -1) return null
+
+		return {
+			pluginName: qualifiedName.slice(0, sepIndex),
+			toolName: qualifiedName.slice(sepIndex + PLUGIN_NAMESPACE_SEPARATOR.length),
+		}
+	}
+
+	/**
+	 * Lists all tool names contributed by a specific plugin.
+	 * Matches tools whose name starts with `manifest.name:`.
+	 */
+	getPluginTools(pluginId: PluginId): string[] {
+		const definition = this.pluginRegistry.getOrThrow(pluginId)
+		const prefix = definition.manifest.name + PLUGIN_NAMESPACE_SEPARATOR
+		return this.toolRegistry.listNames().filter((name) => name.startsWith(prefix))
+	}
+
+	/**
+	 * Resolves a fully qualified component name to its plugin, contribution type, and local name.
+	 */
+	resolveComponent(
+		qualifiedName: string,
+	):
+		| { pluginId: PluginId; contributionType: PluginContributionType; componentName: string }
+		| undefined {
+		const sepIndex = qualifiedName.indexOf(PLUGIN_NAMESPACE_SEPARATOR)
+		if (sepIndex === -1) return undefined
+
+		const pluginName = qualifiedName.slice(0, sepIndex)
+		const componentName = qualifiedName.slice(sepIndex + PLUGIN_NAMESPACE_SEPARATOR.length)
+
+		const definition = this.pluginRegistry.findByName(pluginName)
+		if (!definition) return undefined
+
+		const contributionType = this.inferContributionType(definition.id, pluginName, componentName)
+		if (!contributionType) return undefined
+
+		return {
+			pluginId: definition.id,
+			contributionType,
+			componentName,
+		}
+	}
+
+	/**
+	 * Returns a namespaced name in `pluginName:componentName` format.
+	 */
+	namespaceName(pluginName: string, componentName: string): string {
+		return pluginName + PLUGIN_NAMESPACE_SEPARATOR + componentName
+	}
+
+	private inferContributionType(
+		pluginId: PluginId,
+		pluginName: string,
+		componentName: string,
+	): PluginContributionType | undefined {
+		const definition = this.pluginRegistry.getOrThrow(pluginId)
+		const manifest = definition.manifest
+
+		if (manifest.tools?.includes(componentName)) return 'tool'
+		if (manifest.skills?.includes(componentName)) return 'skill'
+		if (manifest.hooks?.includes(componentName)) return 'hook'
+		if (manifest.connectors?.includes(componentName)) return 'connector'
+		if (manifest.personas?.includes(componentName)) return 'persona'
+		if (manifest.mcpServers?.some((s) => s.name === componentName)) return 'mcp_server'
+
+		// Check if it exists as a registered tool (runtime registration)
+		const namespacedToolName = pluginName + PLUGIN_NAMESPACE_SEPARATOR + componentName
+		if (this.toolRegistry.has(namespacedToolName)) return 'tool'
+
+		return undefined
+	}
+}

package/src/registry/plugin/index.ts

@@ -0,0 +1,20 @@
+import type { PluginDefinition, PluginScope, PluginStatus } from '../../types/plugin/index.js'
+import { ManagedRegistry } from '../ManagedRegistry.js'
+
+export class PluginRegistry extends ManagedRegistry<PluginDefinition> {
+	constructor() {
+		super({ componentName: 'PluginRegistry', idField: 'id' })
+	}
+
+	listByScope(scope: PluginScope): PluginDefinition[] {
+		return this.getAll().filter((def) => def.scope === scope)
+	}
+
+	listByStatus(status: PluginStatus): PluginDefinition[] {
+		return this.getAll().filter((def) => def.status === status)
+	}
+
+	findByName(name: string): PluginDefinition | undefined {
+		return this.getAll().find((def) => def.manifest.name === name)
+	}
+}

package/src/registry/tool/execute.ts

@@ -9,6 +9,7 @@ import type {
 	ToolDefinition,
 	ToolRegistryConfig,
 	ToolResult,
+	ToolTierConfig,
 } from '../../types/tool/index.js'
 import { toErrorMessage } from '../../utils/error.js'
 import { type Logger, getRootLogger } from '../../utils/logger.js'
@@ -22,12 +23,14 @@ export interface ToolExecutionResult extends ToolResult {
 export class ToolRegistry extends Registry<ToolDefinition> {
 	private log: Logger
 	private availability: Map<string, ToolAvailability> = new Map()
+	private tierConfig?: ToolTierConfig
 
 	constructor(config?: ToolRegistryConfig) {
 		super()
 		this.log = (config?.logger ?? getRootLogger()).child({
 			component: 'ToolRegistry',
 		})
+		this.tierConfig = config?.tierConfig
 	}
 
 	override register(id: string, tool: ToolDefinition): void
@@ -61,6 +64,14 @@ export class ToolRegistry extends Registry<ToolDefinition> {
 	}
 
 	private registerOne(id: string, tool: ToolDefinition, state: ToolAvailability): void {
+		if (tool.tier && this.tierConfig) {
+			const validIds = this.tierConfig.tiers.map((t) => t.id)
+			if (!validIds.includes(tool.tier)) {
+				throw new Error(
+					`Tool "${id}" has tier "${tool.tier}" which is not defined. Valid tiers: ${validIds.join(', ')}`,
+				)
+			}
+		}
 		if (this.has(id)) {
 			this.log.warn(`Tool "${id}" is already registered, overwriting.`)
 		}
@@ -122,6 +133,26 @@ export class ToolRegistry extends Registry<ToolDefinition> {
 		)
 	}
 
+	assignTiers(mapping: Record<string, string>): void {
+		for (const [toolName, tierId] of Object.entries(mapping)) {
+			const tool = this.getOrThrow(toolName)
+			if (this.tierConfig) {
+				const validIds = this.tierConfig.tiers.map((t) => t.id)
+				if (!validIds.includes(tierId)) {
+					throw new Error(
+						`Tier "${tierId}" for tool "${toolName}" is not defined. Valid tiers: ${validIds.join(', ')}`,
+					)
+				}
+			}
+			tool.tier = tierId
+		}
+	}
+
+	toTierGuidance(): string | null {
+		if (!this.tierConfig?.guidanceTemplate) return null
+		return this.tierConfig.guidanceTemplate(this.tierConfig.tiers)
+	}
+
 	getOrThrow(name: string): ToolDefinition {
 		const tool = this.get(name)
 		if (!tool) {
@@ -159,17 +190,26 @@ export class ToolRegistry extends Registry<ToolDefinition> {
 	toLLMTools(toolNames?: string[]): LLMToolSchema[] {
 		const toolsToConvert = this.getByAvailability(['active', 'suspended'], toolNames)
 
-		return toolsToConvert.map((tool) => ({
-			type: 'function' as const,
-			function: {
-				name: tool.name,
-				description: tool.description,
-				parameters: zodToJsonSchema(tool.inputSchema, {
-					target: 'jsonSchema7',
-					$refStrategy: 'none',
-				}) as Record<string, unknown>,
-			},
-		}))
+		return toolsToConvert.map((tool) => {
+			let description = tool.description
+			if (this.tierConfig?.labelInDescription && tool.tier) {
+				const tierDef = this.tierConfig.tiers.find((t) => t.id === tool.tier)
+				if (tierDef) {
+					description = `[${tierDef.label}] ${description}`
+				}
+			}
+			return {
+				type: 'function' as const,
+				function: {
+					name: tool.name,
+					description,
+					parameters: zodToJsonSchema(tool.inputSchema, {
+						target: 'jsonSchema7',
+						$refStrategy: 'none',
+					}) as Record<string, unknown>,
+				},
+			}
+		})
 	}
 
 	getCallableTools(toolNames?: string[]): ToolDefinition[] {

package/src/router/index.ts

@@ -0,0 +1 @@
+export { resolveTaskModel } from './task-router.js'

package/src/router/task-router.ts

@@ -0,0 +1,24 @@
+import type { TaskRouterConfig, TaskType } from '../types/router/index.js'
+
+/**
+ * Resolves the model ID for a given task type using the router config.
+ *
+ * Fallback chain: `router[taskType]` -> `router.default` -> `primaryModel`
+ */
+export function resolveTaskModel(
+	taskType: TaskType,
+	router: TaskRouterConfig | undefined,
+	primaryModel: string,
+): string {
+	if (!router) return primaryModel
+
+	const specific = router[taskType]
+	if (specific) return specific
+
+	if (taskType !== 'default') {
+		const fallback = router.default
+		if (fallback) return fallback
+	}
+
+	return primaryModel
+}

package/src/run/reporter.ts

@@ -154,6 +154,23 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 				})
 				break
 
+			case 'plugin_hook_executing':
+				log.debug('Plugin hook executing', {
+					runId: event.runId,
+					pluginId: event.pluginId,
+					hookEvent: event.hookEvent,
+				})
+				break
+
+			case 'plugin_hook_completed':
+				log.debug('Plugin hook completed', {
+					runId: event.runId,
+					pluginId: event.pluginId,
+					hookEvent: event.hookEvent,
+					action: event.result.action,
+				})
+				break
+
 			default: {
 				const _exhaustive: never = event
 				throw new Error(`Unhandled run event type: ${(_exhaustive as RunEvent).type}`)

package/src/runtime/query/context-cache.ts

@@ -1,9 +1,11 @@
 import { createHash } from 'node:crypto'
 import type { ToolRegistry } from '../../registry/tool/execute.js'
+import type { AgentContextLevel } from '../../types/agent/factory.js'
 import type { ThreadId } from '../../types/ids/index.js'
 import type { AgentPersona } from '../../types/persona/index.js'
 import type { Skill } from '../../types/skills/index.js'
 import { PromptBuilder } from './prompt.js'
+import type { PromptSegments } from './prompt.js'
 
 export interface ContextCacheConfig {
 	agentId: string
@@ -25,6 +27,8 @@ export class ContextCache {
 
 	private cachedPrompt: string | undefined
 	private cachedConfigHash: string | undefined
+	private cachedStaticSegment: string | undefined
+	private cachedStaticHash: string | undefined
 
 	constructor(config: ContextCacheConfig) {
 		this.threadId = config.threadId
@@ -61,9 +65,55 @@ export class ContextCache {
 		return this.computeConfigHash(input) !== this.cachedConfigHash
 	}
 
+	getSystemPromptSegmented(
+		input: PromptCacheInput,
+		contextLevel: AgentContextLevel = 'full',
+		workingDirectory?: string,
+	): PromptSegments {
+		const staticHash = this.computeStaticHash(input)
+
+		const builder = new PromptBuilder({
+			systemPrompt: input.systemPrompt,
+			persona: input.persona,
+			skills: input.skills,
+			basePrompt: input.basePrompt,
+			tools: input.tools,
+			allowedTools: input.allowedTools,
+		})
+
+		const segments = builder.buildSegmented(contextLevel, workingDirectory)
+
+		if (this.cachedStaticHash === staticHash && this.cachedStaticSegment !== undefined) {
+			return {
+				static: this.cachedStaticSegment,
+				dynamic: segments.dynamic,
+			}
+		}
+
+		this.cachedStaticSegment = segments.static
+		this.cachedStaticHash = staticHash
+
+		return segments
+	}
+
 	invalidate(): void {
 		this.cachedPrompt = undefined
 		this.cachedConfigHash = undefined
+		this.cachedStaticSegment = undefined
+		this.cachedStaticHash = undefined
+	}
+
+	private computeStaticHash(input: PromptCacheInput): string {
+		const parts: string[] = [
+			this.agentId,
+			input.systemPrompt ?? '',
+			input.persona?.identity?.role ?? '',
+			input.persona?.identity?.description ?? '',
+			input.basePrompt ?? '',
+			...(input.skills?.map((s) => s.metadata.name) ?? []),
+		]
+
+		return createHash('sha256').update(parts.join('\0')).digest('hex').slice(0, 16)
 	}
 
 	private computeConfigHash(input: PromptCacheInput): string {

package/src/runtime/query/executor.ts

@@ -1,3 +1,5 @@
+import { extractFromToolCall, extractFromToolResult } from '../../compaction/extractor.js'
+import type { WorkingStateManager } from '../../compaction/manager.js'
 import type { ToolRegistry } from '../../registry/tool/execute.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
@@ -7,6 +9,7 @@ import type { ChatCompletionResponse } from '../../types/provider/index.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type { ToolContext } from '../../types/tool/index.js'
 import type { Logger } from '../../utils/logger.js'
+import { compressShellOutput } from '../../utils/shell-compress.js'
 
 export type EmitEvent = (event: RunEvent) => Promise<void>
 
@@ -29,6 +32,7 @@ export class ToolExecutor {
 	private activityStore: ActivityStore
 	private emitEvent: EmitEvent
 	private log: Logger
+	private workingStateManager?: WorkingStateManager
 
 	constructor(
 		config: ToolExecutorConfig,
@@ -42,6 +46,10 @@ export class ToolExecutor {
 		this.log = log
 	}
 
+	setWorkingStateManager(manager: WorkingStateManager): void {
+		this.workingStateManager = manager
+	}
+
 	async executeBatch(response: ChatCompletionResponse): Promise<ToolExecutionBatch> {
 		const toolCalls = response.message.toolCalls
 		if (!toolCalls) {
@@ -119,14 +127,24 @@ export class ToolExecutor {
 			input,
 		})
 
+		if (this.workingStateManager) {
+			extractFromToolCall(this.workingStateManager, toolName, toolCall.function.arguments)
+		}
+
 		const startMs = Date.now()
 		const result = await this.config.tools.execute(toolName, input, toolContext)
 		const durationMs = Date.now() - startMs
 
-		const output = result.success
+		const rawOutput = result.success
 			? result.output
 			: `Error: ${result.error ?? 'Tool execution failed'}`
 
+		const output = result.success ? this.maybeCompress(toolName, rawOutput) : rawOutput
+
+		if (this.workingStateManager) {
+			extractFromToolResult(this.workingStateManager, toolName, output, !result.success)
+		}
+
 		if (result.success) {
 			this.log.debug('Tool executed successfully', {
 				runId: this.config.runId,
@@ -160,4 +178,22 @@ export class ToolExecutor {
 
 		return { toolCallId: toolCall.id, output }
 	}
+
+	private maybeCompress(toolName: string, output: string): string {
+		const tool = this.config.tools.get(toolName)
+		if (!tool || tool.category !== 'shell') {
+			return output
+		}
+
+		const compressed = compressShellOutput(output)
+		if (compressed.length < output.length) {
+			this.log.debug('Shell output compressed', {
+				tool: toolName,
+				originalLength: output.length,
+				compressedLength: compressed.length,
+				reductionPercent: Math.round((1 - compressed.length / output.length) * 100),
+			})
+		}
+		return compressed
+	}
 }