@namzu/sdk 0.4.1 → 0.4.2

package/src/public-runtime.ts

@@ -0,0 +1,373 @@
+// Public runtime surface of `@namzu/sdk`.
+//
+// Every runtime value a consumer might need: classes (agents, managers,
+// stores, registries), functions (helpers, ID generators, runtime entry
+// points), zod schemas, constants, error classes. See §4.2 of
+// `docs.local/sessions/ses_011-sdk-public-surface/design.md`.
+//
+// Rule: no type-only exports here (types live in public-types.ts). No tool
+// definitions or builders (tools live in public-tools.ts).
+
+// ─── version + config ────────────────────────────────────────────────────
+
+export { VERSION } from './version.js'
+
+export {
+	CompactionConfigSchema,
+	PluginRuntimeConfigSchema,
+	RUNTIME_DEFAULTS,
+	RuntimeConfigSchema,
+	SandboxConfigSchema,
+	TaskRouterConfigSchema,
+} from './config/runtime.js'
+
+// ─── constants ───────────────────────────────────────────────────────────
+
+export * from './constants/index.js'
+
+// ─── wire schemas + a2a (contracts/) ─────────────────────────────────────
+
+export {
+	CreateMessageSchema,
+	CreateRunSchema,
+	CreateStatelessRunSchema,
+	MessageIdSchema,
+	PaginationSchema,
+	ProjectIdSchema,
+	RunConfigSchema,
+	RunIdSchema,
+	zodErrorToApiError,
+} from './contracts/schemas.js'
+
+export * from './contracts/a2a.js'
+
+// ─── ID generators + parsers ─────────────────────────────────────────────
+
+export * from './utils/id.js'
+
+// ─── utility helpers ─────────────────────────────────────────────────────
+
+export { accumulateCost, calculateCost, formatCost, ZERO_COST } from './utils/cost.js'
+export { toErrorMessage } from './utils/error.js'
+export { configureLogger, getRootLogger, Logger } from './utils/logger.js'
+export { buildToolResultHashes, hashToolResult } from './utils/hash.js'
+export { compressShellOutput, compressShellOutputFull } from './utils/shell-compress.js'
+export { createChildAbortController } from './utils/abort.js'
+export { memoizeAsync } from './utils/memoize.js'
+export { extractFinalResponse } from './utils/conversation.js'
+
+// ─── router, runtime, run ────────────────────────────────────────────────
+
+export { resolveTaskModel } from './router/task-router.js'
+export { drainQuery, query } from './runtime/query/index.js'
+export { ContextCache } from './runtime/query/context-cache.js'
+export { CheckpointManager, projectEmergencyToCheckpoint } from './runtime/query/checkpoint.js'
+export { prepareReplayState } from './runtime/query/replay/prepare.js'
+export { listCheckpoints } from './runtime/query/replay/list.js'
+export { DecisionParser, FallbackResolver } from './runtime/decision/index.js'
+export {
+	buildLimitConfig,
+	checkLimitsDetailed,
+	createRunReporter,
+} from './run/index.js'
+
+// ─── personas, skills, advisory ──────────────────────────────────────────
+
+export { assembleSystemPrompt, mergePersonas, withSessionContext } from './persona/index.js'
+export { discoverSkills, loadSkill, resolveSkillChain, SkillRegistry } from './skills/index.js'
+export {
+	AdvisorRegistry,
+	AdvisoryContext,
+	AdvisoryExecutor,
+	TriggerEvaluator,
+} from './advisory/index.js'
+
+// ─── agents ──────────────────────────────────────────────────────────────
+
+export {
+	AbstractAgent,
+	ConcurrentInvocationError,
+	defineAgent,
+	InvocationLock,
+	PipelineAgent,
+	ReactiveAgent,
+	RouterAgent,
+	SupervisorAgent,
+} from './agents/index.js'
+
+// ─── registries, stores, managers, plugin, gateway ───────────────────────
+
+export {
+	ActivityStore,
+	DiskMemoryStore,
+	DiskTaskStore,
+	InMemoryMemoryIndex,
+	InMemoryMemoryStore,
+	InMemoryStore,
+	InMemoryTaskStore,
+	RunDiskStore,
+} from './store/index.js'
+
+export {
+	AgentRegistry,
+	ManagedRegistry,
+	PluginRegistry,
+	Registry,
+	ToolRegistry,
+} from './registry/index.js'
+
+export {
+	discoverAllPluginDirs,
+	discoverPlugins,
+	loadPluginManifest,
+	PluginLifecycleManager,
+	PluginResolver,
+} from './plugin/index.js'
+
+export {
+	AgentManager,
+	EmergencySaveManager,
+	PlanManager,
+	RunPersistence,
+} from './manager/index.js'
+
+export { LocalTaskGateway } from './gateway/local.js'
+
+// ─── providers, sandbox, vault ───────────────────────────────────────────
+
+export {
+	DuplicateProviderError,
+	MOCK_CAPABILITIES,
+	MockLLMProvider,
+	ProviderRegistry,
+	registerMock,
+	UnknownProviderError,
+} from './provider/index.js'
+
+export { LocalSandboxProvider, SandboxProviderFactory } from './sandbox/index.js'
+
+export { InMemoryCredentialVault } from './vault/index.js'
+
+// ─── RAG runtime (generic; createRAGTool is in public-tools.ts) ──────────
+
+export {
+	assembleRAGContext,
+	cosineSimilarity,
+	DEFAULT_CHUNKING_CONFIG,
+	DEFAULT_RAG_CONTEXT_CONFIG,
+	DEFAULT_RETRIEVAL_CONFIG,
+	DefaultIngestionPipeline,
+	DefaultKnowledgeBase,
+	DefaultRetriever,
+	InMemoryVectorStore,
+	OpenRouterEmbeddingProvider,
+	TextChunker,
+} from './rag/index.js'
+
+// ─── connectors ──────────────────────────────────────────────────────────
+
+export {
+	BaseConnector,
+	BaseExecutionContext,
+	ConnectorManager,
+	ConnectorRegistry,
+	EnvironmentConnectorManager,
+	ExecutionContextFactory,
+	HttpConnector,
+	HttpSseTransport,
+	HybridExecutionContext,
+	LocalExecutionContext,
+	MCPClient,
+	MCPConnectorBridge,
+	MCPServer,
+	MCPToolDiscovery,
+	mcpJsonSchemaToZod,
+	mcpToolResultToToolResult,
+	mcpToolToToolDefinition,
+	RemoteExecutionContext,
+	ScopedConnectorRegistry,
+	StdioTransport,
+	TenantConnectorManager,
+	toolDefinitionToMCPTool,
+	toolResultToMCPToolResult,
+	WebhookConnector,
+	zodToMCPJsonSchema,
+} from './connector/index.js'
+
+// ─── bridges (a2a + sse) ─────────────────────────────────────────────────
+
+export {
+	a2aMessageToCreateRun,
+	a2aMessageToInput,
+	buildAgentCard,
+	extractTextFromA2AMessage,
+	isTerminalState,
+	mapRunToA2AEvent,
+	mapSessionToA2AEvent,
+	messageToA2A,
+	runStatusToA2AState,
+	runToA2ATask,
+} from './bridge/a2a/index.js'
+
+export { mapRunToStreamEvent, mapSessionToStreamEvent } from './bridge/sse/index.js'
+
+// ─── bus, verification ───────────────────────────────────────────────────
+
+export {
+	AgentBus,
+	CircuitBreaker,
+	EditOwnershipTracker,
+	FileLockManager,
+} from './bus/index.js'
+
+export { evaluateRule, VerificationGate } from './verification/index.js'
+
+// ─── session runtime — explicit named lists, no `export *` ───────────────
+// See §1.5 + §4.2 of design.md. Types flow through public-types.ts.
+
+export { RUN_EVENT_SCHEMA_VERSION } from './session/events/index.js'
+
+export {
+	DefaultPathBuilder,
+	GitWorktreeDriver,
+	parseWorktreeList,
+	WorkspaceBackendRegistry,
+} from './session/workspace/index.js'
+
+export {
+	DefaultCapacityValidator,
+	DelegationCapacityExceeded,
+	executeBroadcastHandoff,
+	executeSingleHandoff,
+	HandoffLockRejected,
+	HandoffVersionConflict,
+	NOOP_HANDOFF_SINK,
+	NOOP_RUN_STATUS_RESOLVER,
+} from './session/handoff/index.js'
+
+export {
+	AGENT_SUMMARY_MAX_CHARS,
+	AgentSummaryTooLongError,
+	SessionAlreadySummarizedError,
+	SessionSummaryMaterializer,
+} from './session/summary/index.js'
+
+export {
+	ArtifactRefCycleError,
+	InterventionDepthExceeded,
+	validatePrevArtifactChain,
+} from './session/intervention/index.js'
+
+export {
+	acceptLegacyThreadId,
+	acquireMigrationLock,
+	DefaultFilesystemMigrator,
+	FilesystemMigrationError,
+	LEGACY_DEFAULT_PROJECT_PREFIX,
+	LEGACY_DEFAULT_SESSION_ID,
+	LOCK_REL_PATH,
+	MARKER_REL_PATH,
+	MIGRATION_VERSION,
+	NOOP_FILESYSTEM_MIGRATION_SINK,
+	NOOP_MIGRATION_WARNING_SINK,
+	readMarker,
+	rejectLegacyPrefix,
+	releaseMigrationLock,
+	StalePrefixError,
+	WINDOW_OPEN,
+	writeMarker,
+} from './session/migration/index.js'
+
+export {
+	ArchivalManager,
+	ArchiveNotConfiguredError,
+	ArchiveNotFoundError,
+	DiskArchiveBackend,
+	RETENTION_POLICY_DISABLED,
+	SubSessionNotArchivableError,
+	SubSessionNotArchivedError,
+} from './session/retention/index.js'
+
+// NOTE: `deriveStatus` intentionally NOT re-exported here — it was not part
+// of the pre-ses_011 public surface. Consumers needing it import from the
+// internal path. Promoting it to public surface requires an explicit
+// follow-up session.
+
+export {
+	AncestryCycleError,
+	TenantIsolationError,
+	WorkspaceBackendError,
+} from './session/errors.js'
+
+// ─── store/session runtime — explicit named (types live in public-types.ts)
+
+export {
+	DiskSessionStore,
+	getAncestry,
+	getChildren,
+	InMemorySessionStore,
+	orderChildren,
+} from './store/session/index.js'
+
+// ─── runtime helpers colocated with shapes under `types/` (§1.5) ─────────
+
+export { A2AProtocolError } from './types/a2a/index.js'
+export { isTerminalActivityStatus, resolveActivityTracking } from './types/activity/index.js'
+export { isTerminalAgentTaskState } from './types/agent/task.js'
+export { accumulateTokenUsage, isTerminalStatus } from './types/common/index.js'
+export { assertComputerUseActionType, assertDisplayServer } from './types/computer-use/index.js'
+export { isConnectorActive } from './types/connector/core.js'
+export { CONNECTOR_SCOPE_ORDER } from './types/connector/scope.js'
+export { RoutingResponseSchema } from './types/decision/index.js'
+export { autoApproveHandler } from './types/hitl/index.js'
+export { UNKNOWN_TENANT_ID } from './types/ids/index.js'
+export { deriveChildState } from './types/invocation/index.js'
+export { assertMemoryStatus } from './types/memory/index.js'
+export {
+	createAssistantMessage,
+	createSystemMessage,
+	createToolMessage,
+	createUserMessage,
+} from './types/message/index.js'
+export { isTerminalPlanStatus } from './types/plan/index.js'
+export {
+	assertPluginContributionType,
+	assertPluginHookEvent,
+	assertPluginHookResult,
+	assertPluginScope,
+	assertPluginStatus,
+	PluginManifestSchema,
+	PluginMCPServerConfigSchema,
+} from './types/plugin/index.js'
+export { EmergencySaveConfigSchema } from './types/run/emergency.js'
+export { MutationNotApplicableError } from './types/run/replay.js'
+export {
+	assertSandboxEnvironment,
+	assertSandboxStatus,
+} from './types/sandbox/index.js'
+// `SandboxConfigSchema` is already re-exported above from `./config/runtime.js`
+// (the project-wide config barrel surfaces it first). types/sandbox also exports
+// one under the same name; `@namzu/sdk` root barrel exposes one symbol — the
+// config/runtime version is the canonical path. Keep it out of this block.
+export { assertTaskStatus, isTerminalTaskStatus } from './types/task/index.js'
+// NOTE: `VerificationRuleSchema` and `VerificationGateConfigSchema` are NOT
+// re-exported — they were not part of the pre-ses_011 public surface.
+
+// ─── compaction runtime ──────────────────────────────────────────────────
+
+export {
+	buildVerifiedSummary,
+	createConversationManager,
+	extractFromAssistantMessage,
+	extractFromToolCall,
+	extractFromToolResult,
+	extractFromUserMessage,
+	findDanglingMessages,
+	findSafeTrimIndex,
+	NullManager,
+	removeDanglingMessages,
+	serializeState,
+	SlidingWindowManager,
+	StructuredCompactionManager,
+	WorkingStateManager,
+} from './compaction/index.js'

package/src/public-tools.ts

@@ -0,0 +1,63 @@
+// Public tools surface of `@namzu/sdk`.
+//
+// Consumer scenario: "I want to define a tool for my agent, use a built-in
+// tool, or produce Tool objects from a connector / RAG store / task system."
+//
+// Every symbol here produces or defines a Tool in the agent-tool sense.
+// Generic RAG runtime (vector stores, retrievers, embeddings, knowledge
+// base) lives in `public-runtime.ts`; only `createRAGTool` belongs here.
+//
+// See §4.3 of `docs.local/sessions/ses_011-sdk-public-surface/design.md`.
+
+// ─── Tool definition primitive ───────────────────────────────────────────
+
+export { defineTool } from './tools/defineTool.js'
+
+// ─── Built-in tools ──────────────────────────────────────────────────────
+
+export { getBuiltinTools } from './tools/builtins/index.js'
+export { ReadFileTool } from './tools/builtins/read-file.js'
+export { WriteFileTool } from './tools/builtins/write-file.js'
+export { EditTool } from './tools/builtins/edit.js'
+export { BashTool } from './tools/builtins/bash.js'
+export { GlobTool } from './tools/builtins/glob.js'
+export { GrepTool } from './tools/builtins/grep.js'
+export { LsTool } from './tools/builtins/ls.js'
+export { SearchToolsTool } from './tools/builtins/search-tools.js'
+export {
+	createStructuredOutputTool,
+	STRUCTURED_OUTPUT_TOOL_NAME,
+} from './tools/builtins/structuredOutput.js'
+export {
+	COMPUTER_USE_TOOL_NAME,
+	createComputerUseTool,
+} from './tools/builtins/computer-use.js'
+
+// ─── Domain tool builders ────────────────────────────────────────────────
+
+export {
+	buildTaskCreateTool,
+	buildTaskListTool,
+	buildTaskTools,
+	buildTaskUpdateTool,
+} from './tools/task/index.js'
+export { buildAdvisoryTools } from './tools/advisory/index.js'
+export { buildMemoryTools } from './tools/memory/index.js'
+export { buildCoordinatorTools } from './tools/coordinator/index.js'
+
+// ─── RAG tool builder ────────────────────────────────────────────────────
+
+export { createRAGTool } from './rag/index.js'
+
+// ─── Connector tool bridge ───────────────────────────────────────────────
+
+export {
+	allConnectorTools,
+	connectorInstanceToTools,
+	connectorMethodToTool,
+	ConnectorToolRouter,
+	createConnectorExecuteTool,
+	createConnectorListTool,
+	createConnectorRouterTool,
+	createConnectorTools,
+} from './bridge/tools/connector/index.js'

package/src/public-types.ts

@@ -0,0 +1,156 @@
+// Public types surface of `@namzu/sdk`.
+//
+// Every pure shape a consumer might need for TypeScript type-checking:
+// branded IDs, wire types, domain entities, discriminated unions, store
+// contracts, event unions, config types.
+//
+// Rule: this file contains ONLY `export type` statements. Runtime values
+// (classes, functions, constants, zod schemas, errors) live in
+// `public-runtime.ts`. Tool builders live in `public-tools.ts`.
+//
+// See `docs.local/sessions/ses_011-sdk-public-surface/design.md` for the
+// three-bucket taxonomy and migration rationale.
+
+// ─── per-domain shape surfaces ────────────────────────────────────────────
+
+export type * from './types/ids/index.js'
+export type * from './types/message/index.js'
+export type * from './types/common/index.js'
+export type * from './types/tool/index.js'
+export type * from './types/permission/index.js'
+export type * from './types/run/index.js'
+export type * from './types/provider/index.js'
+export type * from './types/agent/index.js'
+export type * from './types/decision/index.js'
+export type * from './types/persona/index.js'
+export type * from './types/activity/index.js'
+export type * from './types/task/index.js'
+export type * from './types/plan/index.js'
+export type * from './types/hitl/index.js'
+export type * from './types/rag/index.js'
+export type * from './types/execution/index.js'
+export type * from './types/connector/index.js'
+export type * from './types/skills/index.js'
+export type * from './types/a2a/index.js'
+export type * from './types/router/index.js'
+export type * from './types/advisory/index.js'
+export type * from './types/memory/index.js'
+export type * from './types/plugin/index.js'
+export type * from './types/sandbox/index.js'
+export type * from './types/structured-output/index.js'
+export type * from './types/invocation/index.js'
+export type * from './types/computer-use/index.js'
+export type * from './types/verification/index.js'
+
+// Session-hierarchy type surface (ses_010 moved entities here).
+export type * from './types/session/index.js'
+
+// ─── wire surface (contracts/) ────────────────────────────────────────────
+
+export type {
+	AgentDefaults,
+	AgentInfo,
+	ApiError,
+	ApiErrorType,
+	ApiPermissionMode,
+	CreateMessageRequest,
+	CreateRunRequest,
+	CreateStatelessRunRequest,
+	ISOTimestamp,
+	PaginatedResponse,
+	PaginationParams,
+	RunConfig,
+	RunHierarchyNode,
+	RunStopReason,
+	RunUsage,
+	StreamEvent,
+	StreamEventType,
+	ToolCallInfo,
+	WireRun,
+	WireRunStatus,
+} from './contracts/api.js'
+
+// ─── runtime-config type shapes ───────────────────────────────────────────
+
+export type {
+	CompactionConfig,
+	PluginRuntimeConfig,
+	RuntimeConfig,
+} from './config/runtime.js'
+
+// ─── named type re-exports from mixed runtime+type modules ────────────────
+// These modules contain runtime exports too; those go in public-runtime.ts.
+
+export type { AdvisoryCallContext, AdvisoryExecutionResult } from './advisory/index.js'
+
+export type { ModelPricing } from './utils/cost.js'
+export type { Logger } from './utils/logger.js'
+export type { ShellCompressOptions, ShellCompressResult } from './utils/shell-compress.js'
+
+export type { QueryParams } from './runtime/query/index.js'
+export type { ContextCacheConfig, PromptCacheInput } from './runtime/query/context-cache.js'
+
+export type { LimitCheckResult, LimitCheckerState, RunReporter } from './run/index.js'
+
+export type { ConcurrencyMode, DefineAgentOptions, Disposable } from './agents/index.js'
+
+export type {
+	ActivityEvent,
+	ActivityEventListener,
+	DiskMemoryStoreConfig,
+	DiskTaskStoreConfig,
+	Identifiable,
+	Timestamped,
+} from './store/index.js'
+
+export type { ManagedRegistryConfig, ToolExecutionResult } from './registry/index.js'
+
+export type { PluginLifecycleManagerConfig } from './plugin/lifecycle.js'
+
+export type { PlanApprovalHandler, PlanEvent, PlanEventListener } from './manager/index.js'
+
+export type { DefineToolOptions } from './tools/defineTool.js'
+
+export type { AdvisoryToolsOptions } from './tools/advisory/index.js'
+
+export type { CoordinatorToolsOptions, TaskLaunchedCallback } from './tools/coordinator/index.js'
+
+export type {
+	ConnectorManagerConfig,
+	EnvironmentConnectorManagerConfig,
+	EnvironmentConnectorSetup,
+	HybridExecutionContextOptions,
+	LocalExecutionContextOptions,
+	MCPServerResourceProvider,
+	MCPServerToolProvider,
+	RemoteExecutionContextOptions,
+	TenantConnectorManagerConfig,
+} from './connector/index.js'
+
+export type {
+	ConnectorRouterInput,
+	ConnectorToolConfig,
+	ConnectorToolRouterConfig,
+	ConnectorToolStrategy,
+} from './bridge/tools/connector/index.js'
+
+export type { CreateRunFromA2A } from './bridge/a2a/index.js'
+
+export type { MappedStreamEvent } from './bridge/sse/index.js'
+
+export type { AgentBusConfig } from './bus/index.js'
+
+export type { ToolCallContext } from './verification/index.js'
+
+export type { DiskSessionStoreConfig, LinkageView } from './store/session/index.js'
+
+export type {
+	ConversationManager,
+	CompactionStrategy,
+	DanglingResult,
+	FileAction,
+	FileSlot,
+	PlanSlot,
+	ToolResultSlot,
+	WorkingState,
+} from './compaction/index.js'

package/src/run/LimitChecker.ts

@@ -13,15 +13,6 @@ export type LimitCheckResult =
 	| { type: 'warning'; reason: StopReason }
 	| { type: 'hard_stop'; reason: StopReason }
 
-export function checkLimits(
-	config: LimitCheckerConfig,
-	state: LimitCheckerState,
-): StopReason | null {
-	const result = checkLimitsDetailed(config, state)
-	if (result.type === 'ok') return null
-	return result.reason
-}
-
 export function checkLimitsDetailed(
 	config: LimitCheckerConfig,
 	state: LimitCheckerState,

package/src/run/reporter.ts

@@ -1,4 +1,4 @@
-import type { AgentRun, RunEvent, RunEventListener } from '../types/run/index.js'
+import type { Run, RunEvent, RunEventListener } from '../types/run/index.js'
 import { formatCost } from '../utils/cost.js'
 import { type Logger, getRootLogger } from '../utils/logger.js'
 
@@ -13,7 +13,7 @@ function formatDuration(ms: number): string {
 
 export interface RunReporter {
 	listener: RunEventListener
-	summary(run: AgentRun): void
+	summary(run: Run): void
 }
 
 export function createRunReporter(parentLogger?: Logger): RunReporter {
@@ -229,7 +229,7 @@ export function createRunReporter(parentLogger?: Logger): RunReporter {
 		}
 	}
 
-	function summary(run: AgentRun): void {
+	function summary(run: Run): void {
 		const elapsed = (run.endedAt ?? Date.now()) - run.startedAt
 		const { tokenUsage, costInfo, currentIteration, stopReason } = run