@namzu/sdk 0.4.1 → 0.4.3

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/rag/chunking.test.ts

@@ -0,0 +1,107 @@
+/**
+ * Current-code invariants asserted (2026-04-21, ses_006 Phase 4):
+ *
+ *   - `TextChunker.chunk(content, config)` dispatches by
+ *     `config.strategy`. Unknown strategy hits an exhaustive-check
+ *     throw (unreachable via types).
+ *   - `fixed` strategy: slides a window of `chunkSize` by
+ *     `chunkSize − chunkOverlap` (min 1) and emits trimmed non-empty
+ *     slices. Indices are 0-based and contiguous.
+ *   - `sentence` / `paragraph` strategies split by their separator
+ *     sets and then merge small parts until the budget fills.
+ *   - `recursive` strategy: short content returns as a single chunk;
+ *     otherwise it splits by the first separator that produces >1
+ *     parts, merges, and recurses into parts that still exceed
+ *     `chunkSize`. Falls back to `fixed` when no separator splits.
+ *   - Overlap is applied in `mergeSmallParts` via
+ *     `current.slice(current.length - chunkOverlap) + part`.
+ */
+
+import { describe, expect, it } from 'vitest'
+
+import type { ChunkingConfig } from '../types/rag/index.js'
+
+import { TextChunker } from './chunking.js'
+
+const chunker = new TextChunker()
+
+describe('TextChunker — fixed', () => {
+	const fixed: ChunkingConfig = { strategy: 'fixed', chunkSize: 10, chunkOverlap: 2 }
+
+	it('emits trimmed non-empty slices with contiguous indices', () => {
+		const result = chunker.chunk('0123456789abcdefghij', fixed)
+		expect(result).toHaveLength(3)
+		expect(result.map((c) => c.index)).toEqual([0, 1, 2])
+	})
+
+	it('skips whitespace-only slices', () => {
+		const result = chunker.chunk('abc           def', {
+			strategy: 'fixed',
+			chunkSize: 5,
+			chunkOverlap: 0,
+		})
+		expect(result.map((c) => c.content)).not.toContain('')
+	})
+
+	it('clamps step to at least 1 when overlap >= chunkSize', () => {
+		const result = chunker.chunk('abcdefghij', {
+			strategy: 'fixed',
+			chunkSize: 3,
+			chunkOverlap: 3,
+		})
+		// step = max(1, 3-3) = 1; eagerly emits many overlapping slices
+		expect(result.length).toBeGreaterThan(1)
+	})
+})
+
+describe('TextChunker — sentence', () => {
+	it('splits by sentence separators and merges up to the budget', () => {
+		const result = chunker.chunk('First sentence. Second sentence. Third sentence.', {
+			strategy: 'sentence',
+			chunkSize: 100,
+			chunkOverlap: 0,
+		})
+		expect(result.length).toBeGreaterThanOrEqual(1)
+		expect(result[0]?.content).toContain('First sentence')
+	})
+})
+
+describe('TextChunker — paragraph', () => {
+	it('splits by paragraph separators', () => {
+		const result = chunker.chunk('para one\n\npara two\n\npara three', {
+			strategy: 'paragraph',
+			chunkSize: 200,
+			chunkOverlap: 0,
+		})
+		expect(result.length).toBeGreaterThanOrEqual(1)
+	})
+})
+
+describe('TextChunker — recursive', () => {
+	it('short content fits into a single chunk', () => {
+		const result = chunker.chunk('tiny', {
+			strategy: 'recursive',
+			chunkSize: 100,
+			chunkOverlap: 0,
+		})
+		expect(result).toEqual([{ content: 'tiny', index: 0 }])
+	})
+
+	it('long content recursively splits to stay within chunkSize', () => {
+		const content = 'paragraph one. more text.\n\nparagraph two. more.'
+		const result = chunker.chunk(content, {
+			strategy: 'recursive',
+			chunkSize: 30,
+			chunkOverlap: 0,
+		})
+		for (const c of result) {
+			expect(c.content.length).toBeLessThanOrEqual(30)
+		}
+	})
+
+	it('empty or whitespace-only content yields empty result', () => {
+		expect(chunker.chunk('   ', { strategy: 'recursive', chunkSize: 10, chunkOverlap: 0 })).toEqual(
+			[],
+		)
+	})
+})