@illuma-ai/agents 1.1.25 → 1.3.0

package/dist/types/tools/memory/memoryGetTool.d.ts

@@ -0,0 +1,22 @@
+import { type MemoryToolBinding } from './shared';
+export declare function createMemoryGetTool(binding: MemoryToolBinding): import("@langchain/core/tools").DynamicStructuredTool<import("zod").ZodObject<{
+    path: import("zod").ZodString;
+    from: import("zod").ZodOptional<import("zod").ZodNumber>;
+    lines: import("zod").ZodOptional<import("zod").ZodNumber>;
+}, "strip", import("zod").ZodTypeAny, {
+    path: string;
+    from?: number | undefined;
+    lines?: number | undefined;
+}, {
+    path: string;
+    from?: number | undefined;
+    lines?: number | undefined;
+}>, {
+    path: string;
+    from?: number | undefined;
+    lines?: number | undefined;
+}, {
+    path: string;
+    from?: number | undefined;
+    lines?: number | undefined;
+}, string>;

package/dist/types/tools/memory/memorySearchTool.d.ts

@@ -0,0 +1,22 @@
+import { type MemoryToolBinding } from './shared';
+export declare function createMemorySearchTool(binding: MemoryToolBinding): import("@langchain/core/tools").DynamicStructuredTool<import("zod").ZodObject<{
+    query: import("zod").ZodString;
+    maxResults: import("zod").ZodOptional<import("zod").ZodNumber>;
+    minScore: import("zod").ZodOptional<import("zod").ZodNumber>;
+}, "strip", import("zod").ZodTypeAny, {
+    query: string;
+    maxResults?: number | undefined;
+    minScore?: number | undefined;
+}, {
+    query: string;
+    maxResults?: number | undefined;
+    minScore?: number | undefined;
+}>, {
+    query: string;
+    maxResults?: number | undefined;
+    minScore?: number | undefined;
+}, {
+    query: string;
+    maxResults?: number | undefined;
+    minScore?: number | undefined;
+}, string>;

package/dist/types/tools/memory/shared.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Shared Zod schemas + helpers for the memory tool family.
+ *
+ * The tool schemas deliberately do NOT expose `agent_id` or `user_id`. Scope
+ * is captured in a closure at tool construction time by {@link buildMemoryTools},
+ * so even a hallucinated tool call with extra fields cannot influence it.
+ */
+import { z } from 'zod';
+import type { MemoryAppendInput, MemoryBackend, MemoryEntry, MemoryScope } from '@/memory/types';
+export declare const MemorySearchSchema: z.ZodObject<{
+    query: z.ZodString;
+    maxResults: z.ZodOptional<z.ZodNumber>;
+    minScore: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    maxResults?: number | undefined;
+    minScore?: number | undefined;
+}, {
+    query: string;
+    maxResults?: number | undefined;
+    minScore?: number | undefined;
+}>;
+export declare const MemoryGetSchema: z.ZodObject<{
+    path: z.ZodString;
+    from: z.ZodOptional<z.ZodNumber>;
+    lines: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    path: string;
+    from?: number | undefined;
+    lines?: number | undefined;
+}, {
+    path: string;
+    from?: number | undefined;
+    lines?: number | undefined;
+}>;
+export declare const MemoryAppendSchema: z.ZodObject<{
+    path: z.ZodString;
+    content: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    path: string;
+}, {
+    content: string;
+    path: string;
+}>;
+export type MemorySearchArgs = z.infer<typeof MemorySearchSchema>;
+export type MemoryGetArgs = z.infer<typeof MemoryGetSchema>;
+export type MemoryAppendArgs = z.infer<typeof MemoryAppendSchema>;
+/** Shape returned by `memory_search` — serialised as the tool result string. */
+export interface MemorySearchToolResult {
+    results: Array<Pick<MemoryEntry, 'id' | 'path' | 'content' | 'score' | 'createdAt'> & {
+        citation?: string;
+    }>;
+    disabled?: boolean;
+    unavailable?: boolean;
+    error?: string;
+    warning?: string;
+    action?: string;
+}
+/** Shape returned by `memory_get`. */
+export interface MemoryGetToolResult {
+    path: string;
+    text: string;
+    disabled?: boolean;
+    error?: string;
+}
+export declare function buildMemorySearchUnavailableResult(error: string | undefined): MemorySearchToolResult;
+/**
+ * Clamp a ranked result list to a total character budget.
+ * Ported from upstream `tools.citations.ts::clampResultsByInjectedChars`.
+ */
+export declare function clampResultsByInjectedChars<T extends {
+    content: string;
+}>(results: T[], maxInjectedChars?: number): T[];
+export interface MemoryToolBinding {
+    backend: MemoryBackend;
+    scope: MemoryScope;
+    maxInjectedChars?: number;
+    /** Phase 2 — per-call search options propagated into backend.search. */
+    searchOptions?: {
+        mmr?: {
+            enabled?: boolean;
+            lambda?: number;
+        };
+        temporalDecay?: {
+            enabled?: boolean;
+            halfLifeDays?: number;
+        };
+        citations?: 'on' | 'off' | 'auto';
+    };
+    /** Phase 2 — optional best-effort recall recorder. */
+    recallTracker?: {
+        record(params: {
+            agentId: string;
+            query: string;
+            hits: Array<{
+                id: string;
+                path: string;
+                score: number;
+            }>;
+        }): Promise<void>;
+    };
+}
+export declare function assertAppendAllowed(path: string): void;
+/** Normalise an append call into the backend input shape. */
+export declare function toAppendInput(args: MemoryAppendArgs): MemoryAppendInput;

package/dist/types/types/graph.d.ts

@@ -23,6 +23,12 @@ export type AgentTransitionEvent = {
     destinationAgentName: string;
     edgeType: string;
     timestamp: number;
+    /** When true, this event signals handoff completion (child → parent return) */
+    isCompletion?: boolean;
+    /** Duration of child agent execution in milliseconds (only on completion events) */
+    durationMs?: number;
+    /** Length of child agent result text in characters (only on completion events) */
+    resultLength?: number;
 };
 export type GraphNode = GraphNodeKeys | typeof START;
 export type ClientCallback<T extends unknown[]> = (graph: StandardGraph, ...args: T) => void;
@@ -288,6 +294,13 @@ export type GraphEdge = {
      * Defaults to DEFAULT_HANDOFF_MAX_RESULT_CHARS (32768 chars, ~8192 tokens).
      */
     maxResultChars?: number;
+    /**
+     * For handoff edges: When true, the child agent receives the full parent
+     * conversation history plus the orchestrator's instructions appended.
+     * When false (default), the child only receives the orchestrator's scoped
+     * instructions — isolated from the parent conversation.
+     */
+    passthrough?: boolean;
     /**
      * Approval gate configuration for sequence edges.
      * When set, inserts an approval gate node between source and destination.
@@ -538,7 +551,7 @@ export interface AgentInputs {
     discoveredTools?: string[];
     /**
      * Optional callback for summarizing messages that were pruned from context.
-     * When provided, discarded messages are summarized by the caller (e.g., Ranger)
+     * When provided, discarded messages are summarized by the host caller
      * using a cheap LLM call, and the summary is prepended to the context.
      */
     summarizeCallback?: (messagesToRefine: import('@langchain/core/messages').BaseMessage[]) => Promise<string | undefined>;
@@ -546,7 +559,7 @@ export interface AgentInputs {
      * Pre-existing summary text loaded from persistent storage (MongoDB/Redis).
      * When provided, this summary is injected into the initial message context
      * so the agent has prior conversation history even on new turns.
-     * Set by Ranger's SummaryStore when resuming a conversation.
+     * Set by the host's summary store when resuming a conversation.
      */
     persistedSummary?: string;
     /**
@@ -567,7 +580,7 @@ export interface AgentInputs {
      *   - file_search (RAG semantic search over embedded files)
      *   - content_tool read (by contentId for exact file retrieval)
      *
-     * Built by the orchestrator (e.g., Ranger) from message_file_map
+     * Built by the host orchestrator from message_file_map
      * and metadata.context_files across all conversation messages.
      */
     fileManifest?: FileManifestEntry[];

package/dist/types/utils/childAgentContext.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Child-agent context preparation utilities.
+ *
+ * When a parent agent invokes a child agent — via handoff, sequence edge,
+ * or scoped subgraph — the child cannot just receive `state.messages`
+ * verbatim. The parent's conversation contains tool_use/tool_result blocks
+ * that are (a) often incompatible with the child's tool registry, and
+ * (b) actively harmful to the child's ability to reason cleanly about its
+ * own task (noise → schema confusion → malformed tool_use).
+ *
+ * This module provides the two canonical strategies, extracted from
+ * `MultiAgentGraph` so they can be unit-tested in isolation and reused by
+ * future sub-agent orchestrators:
+ *
+ *   1. `prepareHandoffMessages` — "cleaned parent history"
+ *      Used when the child still needs the orchestrator's context (it's
+ *      the handoff target). Drops orphaned tool_use, compacts paired
+ *      tool_use/tool_result into text summaries, and guarantees the tail
+ *      is a HumanMessage so Bedrock/VertexAI won't reject the conversation
+ *      with "assistant message prefill" errors.
+ *
+ *   2. `prepareIsolatedChildMessages` — "fresh session"
+ *      Used for downstream sequence-node children inside a scoped subgraph.
+ *      The child sees only the original user request plus a synthetic
+ *      HumanMessage summarizing the upstream agent's final text output and
+ *      directing the child to act. Raw upstream tool_use/tool_result blocks
+ *      are discarded.
+ *
+ * Both helpers are pure functions over message arrays — no I/O, no
+ * LangGraph coupling — so they can be exercised by unit tests with
+ * synthetic message fixtures.
+ */
+import type { BaseMessage } from '@langchain/core/messages';
+/**
+ * Prefix injected in front of a trailing AIMessage when we flip it to a
+ * HumanMessage to satisfy provider "last message must be user" rules.
+ */
+export declare const HANDOFF_TAIL_CONTEXT_PREFIX = "[Context from orchestrator]: ";
+/**
+ * Directive task-framing wrapper for downstream scoped-subgraph children.
+ *
+ * Design notes — each line is load-bearing:
+ *  - "Prior step output" names the upstream role without leaking the
+ *    agent's internal id.
+ *  - "You MUST now perform..." replaces ambiguity with obligation.
+ *  - "system instructions" references the agent's stored system prompt
+ *    as the source of task definition — so operators can tune behavior
+ *    via data, not code.
+ *  - The tool-first clause prevents small/fast models from stalling on a
+ *    text-only acknowledgement when a tool action is expected.
+ */
+export declare function buildIsolatedChildPrompt(upstreamText: string): string;
+/**
+ * Prepare messages for a handoff child agent.
+ *
+ * Handles two problems that break Bedrock/Anthropic conversations:
+ *
+ * 1. **Orphaned tool_use**: The parent's AI message contains a `tool_use`
+ *    block for the handoff tool itself, with no matching `tool_result`.
+ *    Providers (Bedrock/Anthropic) reject this.
+ *
+ * 2. **Paired tool_use/tool_result in history**: The child may not have
+ *    the same tools as the parent. Bedrock requires `toolConfig` when any
+ *    tool_use/tool_result blocks exist in the history. Compacting these
+ *    into text summaries avoids the requirement and reduces context bloat.
+ *
+ * Also ensures the tail is a HumanMessage — some providers reject a
+ * conversation that ends with an assistant message.
+ *
+ * @param messages - Current state messages from the parent
+ * @returns A sanitized copy, safe to pass to any provider as the child's
+ *          input regardless of which tools the child has registered.
+ */
+export declare function prepareHandoffMessages(messages: BaseMessage[]): BaseMessage[];
+/**
+ * Build an ISOLATED message context for a downstream scoped-subgraph node.
+ *
+ * Unlike `prepareHandoffMessages` (which cleans up tool_use artifacts but
+ * preserves most of the parent history), this helper produces a fresh
+ * minimal context containing only:
+ *
+ *   1. The original user request (first HumanMessage in the history)
+ *   2. A synthetic HumanMessage summarizing the upstream agent's final
+ *      text output and directing the downstream agent to act on it
+ *
+ * Tool_use / tool_result blocks from the upstream agent are discarded —
+ * the downstream agent shouldn't reason about how the upstream agent did
+ * its work, only about the result.
+ *
+ * This "fresh subagent session" pattern is the primary defense against
+ * schema confusion / malformed tool_use JSON that occurs when downstream
+ * models see a noisy upstream conversation.
+ *
+ * Defensive fallback: if the messages array contains neither a user
+ * message nor a non-empty upstream AI message, return the input unchanged
+ * so the caller still has something to invoke on. This only matters for
+ * malformed state fixtures in tests.
+ */
+export declare function prepareIsolatedChildMessages(messages: BaseMessage[]): BaseMessage[];

package/dist/types/utils/events.d.ts

@@ -1,6 +1,27 @@
 import type { RunnableConfig } from '@langchain/core/runnables';
+/**
+ * Returns the RunnableConfig currently active in LangChain's AsyncLocalStorage,
+ * or undefined if none is installed. This is the per-async-branch config that
+ * LangGraph installs when entering a node — it carries the correct
+ * `metadata.spawnKey` for child subgraph invocations inside `Promise.all`
+ * parallel handoffs.
+ *
+ * Prefer this over any Graph-instance-cached config (e.g. `this.config`)
+ * when dispatching events from code that may run concurrently across multiple
+ * child subgraphs. An instance-level cache is shared state and races between
+ * siblings — the last child to enter wins, so events fire with the wrong
+ * child's metadata and the backend routes them to the wrong spawnKey.
+ */
+export declare function getCurrentRunnableConfig(): RunnableConfig | undefined;
 /**
  * Safely dispatches a custom event and properly awaits it to avoid
  * race conditions where events are dispatched after run cleanup.
+ *
+ * **Parallel-handoff correctness:** callers should prefer passing
+ * `undefined` (or the per-node runtime config). When `config` is omitted,
+ * LangChain's `ensureConfig` reads the current RunnableConfig from
+ * AsyncLocalStorage, which is correctly isolated per async branch under
+ * `Promise.all`. Passing a stale instance-cached config overrides that
+ * implicit config's metadata and cross-contaminates parallel children.
  */
 export declare function safeDispatchCustomEvent(event: string, payload: unknown, config?: RunnableConfig): Promise<void>;

package/dist/types/utils/finishReasons.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Finish-reason constants and helpers.
+ *
+ * LLM providers emit different keys (`finish_reason`, `stop_reason`,
+ * `stopReason`, `finishReason`) and different values for the same concept.
+ * This module is the single source of truth for detecting *truncation* —
+ * i.e., the model hit its output budget and the response is incomplete.
+ *
+ * Used by:
+ *  - `Graph.ts` — sticky `lastFinishReason` across inner subgraph invokes,
+ *    so host's continuation retry can detect truncation that happens
+ *    inside a scoped-subgraph child node.
+ *  - Any future continuation / auto-retry logic added to agents.
+ *
+ * Kept as a small utils module (instead of inline in Graph.ts) so that
+ * additional callers — e.g., structured output recovery, sub-agent
+ * orchestrators — can reuse the exact same detection logic without drift.
+ */
+/**
+ * Canonical set of finish-reason strings that mean "output was truncated".
+ *
+ * Covers:
+ *  - `max_tokens` — Anthropic direct API, Bedrock
+ *  - `length`    — OpenAI/Azure
+ *  - `MAX_TOKENS` — VertexAI/Google (uppercased enum)
+ */
+export declare const TRUNCATION_FINISH_REASONS: ReadonlySet<string>;
+/**
+ * @returns true when the given finish/stop reason indicates the response
+ *          was cut short by the output token budget.
+ */
+export declare function isTruncationReason(reason: string | undefined | null): boolean;

package/dist/types/utils/logging.d.ts

@@ -1 +1,3 @@
+export declare const mlog: (...args: any[]) => void;
+export declare const mwarn: (...args: any[]) => void;
 export declare function setupLogging(logFileName: string): void;

package/dist/types/utils/toolCallNormalization.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Tool-call name normalization for malformed LLM tool_use outputs.
+ *
+ * LLMs — especially smaller / faster models — frequently emit tool_use
+ * blocks with names that don't exactly match the registered tool name:
+ *
+ *   - Wrong delimiter: `outlook/operations` vs `outlook_operations`
+ *   - Function-prefix style: `functions.outlook_operations`
+ *   - Case drift: `Outlook_Operations`
+ *   - Counter suffix: `outlook_operations_1`
+ *   - Missing name, only id: `{name: "", id: "tool_outlook_operations_42"}`
+ *
+ * Before this normalization layer, any of the above caused the LangGraph
+ * ToolNode to throw "Tool X not found" and the whole turn to fail. With
+ * normalization, we resolve to the correct registered name case-insensitively
+ * and transparently fix the tool_call in place.
+ *
+ * Resolution order:
+ *   1. Exact match
+ *   2. Normalized delimiter + exact
+ *   3. Case-insensitive match
+ *   4. Structured candidates (strip prefixes, take suffix segments)
+ *   5. Infer from tool_call id (strip trailing digits, function/tool prefix)
+ *
+ * Any unresolvable tool_call is left as-is — the downstream ToolNode will
+ * fail with its usual error and the auto-recovery path kicks in.
+ */
+/**
+ * Produce the best allowed tool name for a raw LLM tool_use name.
+ * Returns the original name unchanged if no resolution is possible —
+ * the downstream executor will then fail with its normal error path.
+ */
+export declare function normalizeToolCallName(rawName: string, allowedToolNames: Set<string>, rawToolCallId?: string): string;
+/**
+ * In-place normalization of all tool_calls on an AIMessage-like object.
+ *
+ * Applies `normalizeToolCallName` to each tool_call's `name` field using the
+ * provided allowed-tool set (derived from the agent's toolMap keys). Also
+ * rewrites the `name` field inside any content blocks of type `tool_use` so
+ * that downstream providers see the corrected name.
+ *
+ * Returns `true` if any name was rewritten.
+ */
+export declare function normalizeMessageToolCalls(message: unknown, allowedToolNames: Set<string>): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.1.25",
+  "version": "1.3.0",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",
@@ -123,6 +123,8 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.73.0",
     "@aws-sdk/client-bedrock-runtime": "^3.980.0",
+    "@illuma-ai/observability-langchain": "^0.2.1",
+    "@illuma-ai/observability-otel": "^0.2.1",
     "@langchain/anthropic": "^0.3.26",
     "@langchain/aws": "^0.1.15",
     "@langchain/core": "^0.3.80",
@@ -134,8 +136,6 @@
     "@langchain/openai": "0.5.18",
     "@langchain/textsplitters": "^0.1.0",
     "@langchain/xai": "^0.0.3",
-    "@illuma-ai/observability-langchain": "^0.2.1",
-    "@illuma-ai/observability-otel": "^0.2.1",
     "@opentelemetry/sdk-node": "^0.207.0",
     "@scarf/scarf": "^1.4.0",
     "@toon-format/toon": "^2.1.0",
@@ -148,7 +148,8 @@
     "mathjs": "^15.1.0",
     "nanoid": "^3.3.7",
     "okapibm25": "^1.4.1",
-    "openai": "5.8.2"
+    "openai": "5.8.2",
+    "pg": "^8.20.0"
   },
   "imports": {
     "@/*": "./src/*",
@@ -166,6 +167,7 @@
     "@types/jest": "^30.0.0",
     "@types/node": "^20.14.11",
     "@types/node-fetch": "^2.6.13",
+    "@types/pg": "^8.20.0",
     "@types/yargs-parser": "^21.0.3",
     "@typescript-eslint/eslint-plugin": "^8.24.0",
     "@typescript-eslint/parser": "^8.24.0",

package/src/agents/AgentContext.ts

@@ -622,18 +622,41 @@ export class AgentContext {
     const isParallel = parallelSiblings.length > 0;
 
     const lines: string[] = [];
-    lines.push('## Multi-Agent Workflow');
+    lines.push('## Subagent Context');
+    lines.push('');
     lines.push(
-      `You are "${displayName}", transferred from "${sourceAgentName}".`
+      `You are "${displayName}", a subagent spawned by "${sourceAgentName}" for a specific task.`
     );
 
     if (isParallel) {
       lines.push(`Running in parallel with: ${parallelSiblings.join(', ')}.`);
     }
 
+    lines.push('');
+    lines.push('### Your Role');
+    lines.push('- Complete your assigned task. That is your entire purpose.');
+    lines.push(`- You are NOT "${sourceAgentName}". Do not try to be.`);
+    lines.push('');
+    lines.push('### Rules');
+    lines.push('1. **Stay focused** — Do your assigned task, nothing else.');
     lines.push(
-      'Execute only tasks relevant to your role. Routing is already handled if requested, unless you can route further.'
+      '2. **Complete the task** — Your final message will be automatically reported back.'
     );
+    lines.push(
+      '3. **Be autonomous** — Execute directly without asking for user confirmation. Use your tools and best judgment.'
+    );
+    lines.push(
+      '4. **No placeholders** — Never generate fake or placeholder data. If you cannot retrieve real data, say so.'
+    );
+    lines.push(
+      '5. **No side effects** — Do not send messages, emails, or notifications unless explicitly tasked to do so.'
+    );
+    lines.push('');
+    lines.push('### Output');
+    lines.push('When complete, your final response should include:');
+    lines.push('- What you accomplished or found');
+    lines.push('- Any relevant details the orchestrator should know');
+    lines.push('- Keep it concise but informative');
 
     return lines.join('\n');
   }

package/src/common/__tests__/enum.test.ts

@@ -1,7 +1,7 @@
 /**
  * Unit tests for centralized enums in @illuma-ai/agents.
  * Verifies enum values remain stable — these are part of the public API
- * and are referenced by ranger validation schemas and MongoDB documents.
+ * and are referenced by host validation schemas and MongoDB documents.
  */
 import {
   EdgeType,
@@ -33,7 +33,9 @@ describe('EdgeType enum', () => {
   it('has three members: handoff, transfer, sequence', () => {
     const values = Object.values(EdgeType);
     expect(values).toHaveLength(3);
-    expect(values).toEqual(expect.arrayContaining(['handoff', 'transfer', 'sequence']));
+    expect(values).toEqual(
+      expect.arrayContaining(['handoff', 'transfer', 'sequence'])
+    );
   });
 });
 

package/src/common/__tests__/spawnPath.test.ts

@@ -0,0 +1,110 @@
+import {
+  SPAWN_PATH_SEP,
+  MAX_NESTING_DEPTH,
+  buildSpawnPath,
+  spawnPathDepth,
+  parentSpawnPath,
+  spawnPathParts,
+  leafSpawnKey,
+  isAncestorSpawnPath,
+} from '../spawnPath';
+
+describe('spawnPath utilities', () => {
+  describe('constants', () => {
+    it('exports a slash separator', () => {
+      expect(SPAWN_PATH_SEP).toBe('/');
+    });
+    it('default max nesting depth is 5', () => {
+      expect(MAX_NESTING_DEPTH).toBe(5);
+    });
+  });
+
+  describe('buildSpawnPath', () => {
+    it('returns key as-is when parent is empty/null/undefined', () => {
+      expect(buildSpawnPath('', 'a')).toBe('a');
+      expect(buildSpawnPath(null, 'a')).toBe('a');
+      expect(buildSpawnPath(undefined, 'a')).toBe('a');
+    });
+    it('appends key to parent with separator', () => {
+      expect(buildSpawnPath('a', 'b')).toBe('a/b');
+      expect(buildSpawnPath('a/b', 'c')).toBe('a/b/c');
+    });
+    it('throws on empty key', () => {
+      expect(() => buildSpawnPath('a', '')).toThrow(/empty key/);
+    });
+  });
+
+  describe('spawnPathDepth', () => {
+    it('root is depth 0', () => {
+      expect(spawnPathDepth('')).toBe(0);
+      expect(spawnPathDepth(null)).toBe(0);
+      expect(spawnPathDepth(undefined)).toBe(0);
+    });
+    it('single segment is depth 1', () => {
+      expect(spawnPathDepth('a')).toBe(1);
+    });
+    it('multi segment counts segments', () => {
+      expect(spawnPathDepth('a/b')).toBe(2);
+      expect(spawnPathDepth('a/b/c/d')).toBe(4);
+    });
+    it('ignores empty segments from stray separators', () => {
+      expect(spawnPathDepth('a//b')).toBe(2);
+      expect(spawnPathDepth('/a/b')).toBe(2);
+    });
+  });
+
+  describe('parentSpawnPath', () => {
+    it('root returns null', () => {
+      expect(parentSpawnPath('')).toBeNull();
+      expect(parentSpawnPath(null)).toBeNull();
+    });
+    it('single segment returns empty (root)', () => {
+      expect(parentSpawnPath('a')).toBe('');
+    });
+    it('multi segment drops last', () => {
+      expect(parentSpawnPath('a/b')).toBe('a');
+      expect(parentSpawnPath('a/b/c')).toBe('a/b');
+    });
+  });
+
+  describe('spawnPathParts', () => {
+    it('empty path returns empty array', () => {
+      expect(spawnPathParts('')).toEqual([]);
+      expect(spawnPathParts(null)).toEqual([]);
+    });
+    it('splits segments', () => {
+      expect(spawnPathParts('a/b/c')).toEqual(['a', 'b', 'c']);
+    });
+  });
+
+  describe('leafSpawnKey', () => {
+    it('root returns null', () => {
+      expect(leafSpawnKey('')).toBeNull();
+    });
+    it('returns last segment', () => {
+      expect(leafSpawnKey('a')).toBe('a');
+      expect(leafSpawnKey('a/b/c')).toBe('c');
+    });
+  });
+
+  describe('isAncestorSpawnPath', () => {
+    it('root is ancestor of any non-root path', () => {
+      expect(isAncestorSpawnPath('', 'a')).toBe(true);
+      expect(isAncestorSpawnPath('', 'a/b')).toBe(true);
+    });
+    it('root is not ancestor of root', () => {
+      expect(isAncestorSpawnPath('', '')).toBe(false);
+    });
+    it('strict ancestor detection', () => {
+      expect(isAncestorSpawnPath('a', 'a/b')).toBe(true);
+      expect(isAncestorSpawnPath('a/b', 'a/b/c')).toBe(true);
+      expect(isAncestorSpawnPath('a', 'a')).toBe(false);
+    });
+    it('sibling is not ancestor', () => {
+      expect(isAncestorSpawnPath('a/b', 'a/c')).toBe(false);
+    });
+    it('partial-prefix is not ancestor (must respect segment boundary)', () => {
+      expect(isAncestorSpawnPath('ab', 'abc')).toBe(false);
+    });
+  });
+});

package/src/common/index.ts

@@ -1,4 +1,5 @@
 // src/common/index.ts
 export * from './enum';
 export * from './constants';
+export * from './spawnPath';
 export * from '../tools/approval/constants';