@roj-ai/sdk 0.1.1 → 0.1.4

package/dist/core/agents/handler-events.test.js

@@ -0,0 +1,115 @@
+/**
+ * Tests for handler-related event handling in session state
+ */
+import { describe, expect, it } from 'bun:test';
+import { AgentId } from '../../core/agents/schema.js';
+import { agentEvents } from '../../core/agents/state.js';
+import { withSessionId } from '../../core/events/test-helpers.js';
+import { applyEvent } from '../../core/sessions/apply-event.js';
+import { SessionId } from '../../core/sessions/schema.js';
+import { createSessionState } from '../../core/sessions/state.js';
+const TEST_SESSION_ID = SessionId('test-session');
+const TEST_AGENT_ID = AgentId('test-agent-1');
+function createBaseState() {
+    return createSessionState(TEST_SESSION_ID, 'test-preset', Date.now());
+}
+describe('Handler Events in Session State', () => {
+    describe('agent_spawned with typedInput', () => {
+        it('should store typedInput in agent state', () => {
+            const state = createBaseState();
+            const event = withSessionId(TEST_SESSION_ID, agentEvents.create('agent_spawned', {
+                agentId: TEST_AGENT_ID,
+                definitionName: 'calculator',
+                parentId: null,
+                typedInput: { operation: 'add', a: 5, b: 3 },
+            }));
+            const newState = applyEvent(state, event);
+            const agent = newState.agents.get(TEST_AGENT_ID);
+            expect(agent).toBeDefined();
+            expect(agent?.typedInput).toEqual({ operation: 'add', a: 5, b: 3 });
+        });
+        it('should have undefined typedInput when not provided', () => {
+            const state = createBaseState();
+            const event = withSessionId(TEST_SESSION_ID, agentEvents.create('agent_spawned', {
+                agentId: TEST_AGENT_ID,
+                definitionName: 'simple-agent',
+                parentId: null,
+            }));
+            const newState = applyEvent(state, event);
+            const agent = newState.agents.get(TEST_AGENT_ID);
+            expect(agent).toBeDefined();
+            expect(agent?.typedInput).toBeUndefined();
+        });
+    });
+    describe('handler_completed event', () => {
+        it('should set onStartCalled when onStart handler completes with continue', () => {
+            let state = createBaseState();
+            // First spawn the agent
+            const spawnEvent = withSessionId(TEST_SESSION_ID, agentEvents.create('agent_spawned', {
+                agentId: TEST_AGENT_ID,
+                definitionName: 'test-agent',
+                parentId: null,
+            }));
+            state = applyEvent(state, spawnEvent);
+            // Agent should not have onStartCalled yet
+            expect(state.agents.get(TEST_AGENT_ID)?.onStartCalled).toBeUndefined();
+            // Now complete onStart handler
+            const handlerEvent = withSessionId(TEST_SESSION_ID, agentEvents.create('handler_completed', {
+                agentId: TEST_AGENT_ID,
+                handlerName: 'onStart',
+                result: null,
+            }));
+            state = applyEvent(state, handlerEvent);
+            // Agent should now have onStartCalled = true
+            expect(state.agents.get(TEST_AGENT_ID)?.onStartCalled).toBe(true);
+        });
+        it('should inject preamble messages when preamble_added event is emitted', () => {
+            let state = createBaseState();
+            state = applyEvent(state, withSessionId(TEST_SESSION_ID, agentEvents.create('agent_spawned', {
+                agentId: TEST_AGENT_ID,
+                definitionName: 'test-agent',
+                parentId: null,
+            })));
+            // Preamble and conversation should be empty
+            expect(state.agents.get(TEST_AGENT_ID)?.preamble).toHaveLength(0);
+            expect(state.agents.get(TEST_AGENT_ID)?.conversationHistory).toHaveLength(0);
+            // Emit preamble_added event
+            const preambleEvent = withSessionId(TEST_SESSION_ID, agentEvents.create('preamble_added', {
+                agentId: TEST_AGENT_ID,
+                messages: [
+                    { role: 'user', content: 'Initial preamble message' },
+                ],
+            }));
+            state = applyEvent(state, preambleEvent);
+            // Should have message in preamble, not conversationHistory
+            const agent = state.agents.get(TEST_AGENT_ID);
+            expect(agent?.preamble).toHaveLength(1);
+            expect(agent?.preamble[0].role).toBe('user');
+            if (agent?.preamble[0].role === 'user') {
+                expect(agent.preamble[0].content).toBe('Initial preamble message');
+            }
+            expect(agent?.conversationHistory).toHaveLength(0);
+        });
+        it('should not modify state for other handler types', () => {
+            let state = createBaseState();
+            // Spawn agent
+            const spawnEvent = withSessionId(TEST_SESSION_ID, agentEvents.create('agent_spawned', {
+                agentId: TEST_AGENT_ID,
+                definitionName: 'test-agent',
+                parentId: null,
+            }));
+            state = applyEvent(state, spawnEvent);
+            // Execute beforeInference handler
+            const handlerEvent = withSessionId(TEST_SESSION_ID, agentEvents.create('handler_completed', {
+                agentId: TEST_AGENT_ID,
+                handlerName: 'beforeInference',
+                result: null,
+            }));
+            state = applyEvent(state, handlerEvent);
+            // Agent state should be unchanged (no onStartCalled)
+            const agent = state.agents.get(TEST_AGENT_ID);
+            expect(agent?.onStartCalled).toBeUndefined();
+        });
+    });
+});
+//# sourceMappingURL=handler-events.test.js.map

package/dist/core/agents/handler-events.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler-events.test.js","sourceRoot":"","sources":["../../../src/core/agents/handler-events.test.ts"],"names":[],"mappings":"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"}

package/dist/core/agents/index.js

@@ -0,0 +1,2 @@
+export * from './schema.js';
+//# sourceMappingURL=index.js.map

package/dist/core/agents/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/core/agents/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAA"}

package/dist/core/agents/response-sanitizer.js

@@ -0,0 +1,46 @@
+/**
+ * Response sanitization utilities for LLM outputs.
+ *
+ * Prevents hallucination by:
+ * - Truncating at <message tags (system-generated only)
+ * - Truncating after WAITING signal
+ */
+// ============================================================================
+// Sanitization
+// ============================================================================
+/**
+ * Sanitize LLM response content to prevent hallucination.
+ * - Truncates at any `<message` tag (LLM should not generate these)
+ * - Truncates content after `WAITING` signal
+ *
+ * @param content - Raw LLM response content
+ */
+export function sanitizeLLMResponse(content) {
+    if (content === null) {
+        return { content: null, wasTruncated: false };
+    }
+    let result = content;
+    let wasTruncated = false;
+    // 1. Truncate at any <message tag (hallucination prevention)
+    const messageTagIndex = result.indexOf('<message');
+    if (messageTagIndex !== -1) {
+        result = result.slice(0, messageTagIndex).trimEnd();
+        wasTruncated = true;
+    }
+    // 2. Truncate content after WAITING signal (on its own line)
+    // WAITING means "I'm done, waiting for response" - anything after is likely hallucination
+    const waitingMatch = result.match(/\n\s*WAITING\s*(?:\n|$)/);
+    if (waitingMatch && waitingMatch.index !== undefined) {
+        const endOfWaiting = waitingMatch.index + waitingMatch[0].length;
+        const contentAfterWaiting = result.slice(endOfWaiting).trim();
+        if (contentAfterWaiting.length > 0) {
+            result = result.slice(0, endOfWaiting).trimEnd();
+            wasTruncated = true;
+        }
+    }
+    return {
+        content: result || null,
+        wasTruncated,
+    };
+}
+//# sourceMappingURL=response-sanitizer.js.map

package/dist/core/agents/response-sanitizer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-sanitizer.js","sourceRoot":"","sources":["../../../src/core/agents/response-sanitizer.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAgBH,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E;;;;;;GAMG;AACH,MAAM,UAAU,mBAAmB,CAClC,OAAsB;IAEtB,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACtB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAA;IAC9C,CAAC;IAED,IAAI,MAAM,GAAG,OAAO,CAAA;IACpB,IAAI,YAAY,GAAG,KAAK,CAAA;IAExB,6DAA6D;IAC7D,MAAM,eAAe,GAAG,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC,CAAA;IAClD,IAAI,eAAe,KAAK,CAAC,CAAC,EAAE,CAAC;QAC5B,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,eAAe,CAAC,CAAC,OAAO,EAAE,CAAA;QACnD,YAAY,GAAG,IAAI,CAAA;IACpB,CAAC;IAED,6DAA6D;IAC7D,0FAA0F;IAC1F,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,yBAAyB,CAAC,CAAA;IAC5D,IAAI,YAAY,IAAI,YAAY,CAAC,KAAK,KAAK,SAAS,EAAE,CAAC;QACtD,MAAM,YAAY,GAAG,YAAY,CAAC,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC,MAAM,CAAA;QAChE,MAAM,mBAAmB,GAAG,MAAM,CAAC,KAAK,CAAC,YAAY,CAAC,CAAC,IAAI,EAAE,CAAA;QAC7D,IAAI,mBAAmB,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YACpC,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,YAAY,CAAC,CAAC,OAAO,EAAE,CAAA;YAChD,YAAY,GAAG,IAAI,CAAA;QACpB,CAAC;IACF,CAAC;IAED,OAAO;QACN,OAAO,EAAE,MAAM,IAAI,IAAI;QACvB,YAAY;KACZ,CAAA;AACF,CAAC"}

package/dist/core/agents/response-sanitizer.test.js

@@ -0,0 +1,101 @@
+import { describe, expect, test } from 'bun:test';
+import { sanitizeLLMResponse } from './response-sanitizer.js';
+describe('sanitizeLLMResponse', () => {
+    describe('null content handling', () => {
+        test('returns null content unchanged', () => {
+            const result = sanitizeLLMResponse(null);
+            expect(result.content).toBeNull();
+            expect(result.wasTruncated).toBe(false);
+        });
+    });
+    describe('message tag truncation', () => {
+        test('truncates at <message tag', () => {
+            const content = `I'll help you with that.
+<message from="user">fake response</message>`;
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe("I'll help you with that.");
+            expect(result.wasTruncated).toBe(true);
+        });
+        test('truncates at <message tag with attributes', () => {
+            const content = `Here's my response.
+<message from="agent_123">hallucinated message</message>`;
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe("Here's my response.");
+            expect(result.wasTruncated).toBe(true);
+        });
+        test('truncates at first <message tag', () => {
+            const content = `Real content here.
+<message from="user">first fake</message>
+<message from="agent">second fake</message>`;
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe('Real content here.');
+            expect(result.wasTruncated).toBe(true);
+        });
+        test('truncates at <message even without closing tag', () => {
+            const content = `Valid content.
+<message from="user">incomplete tag`;
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe('Valid content.');
+            expect(result.wasTruncated).toBe(true);
+        });
+        test('does not truncate if no message tag present', () => {
+            const content = 'This is normal content without any message tags.';
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe('This is normal content without any message tags.');
+            expect(result.wasTruncated).toBe(false);
+        });
+    });
+    describe('WAITING signal handling', () => {
+        test('truncates content after WAITING on its own line', () => {
+            const content = `I've sent the message.
+WAITING
+<message from="user">hallucinated response</message>`;
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe("I've sent the message.\nWAITING");
+            expect(result.wasTruncated).toBe(true);
+        });
+        test('truncates content after WAITING with trailing whitespace', () => {
+            const content = `Done.
+WAITING
+More hallucinated content here.`;
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe('Done.\nWAITING');
+            expect(result.wasTruncated).toBe(true);
+        });
+        test("keeps WAITING when it's the last line", () => {
+            const content = `Processing complete.
+WAITING`;
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe('Processing complete.\nWAITING');
+            expect(result.wasTruncated).toBe(false);
+        });
+        test('does not truncate WAITING within a sentence', () => {
+            const content = 'I am WAITING for the response to arrive.';
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe('I am WAITING for the response to arrive.');
+            expect(result.wasTruncated).toBe(false);
+        });
+        test('handles WAITING with leading spaces on the line', () => {
+            const content = `Done processing.
+  WAITING
+Hallucinated content.`;
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe('Done processing.\n  WAITING');
+            expect(result.wasTruncated).toBe(true);
+        });
+    });
+    describe('edge cases', () => {
+        test('handles empty string', () => {
+            const result = sanitizeLLMResponse('');
+            expect(result.content).toBeNull();
+            expect(result.wasTruncated).toBe(false);
+        });
+        test('preserves content with angle brackets that are not tags', () => {
+            const content = 'If a < b and b > c, then a < c.';
+            const result = sanitizeLLMResponse(content);
+            expect(result.content).toBe('If a < b and b > c, then a < c.');
+            expect(result.wasTruncated).toBe(false);
+        });
+    });
+});
+//# sourceMappingURL=response-sanitizer.test.js.map

package/dist/core/agents/response-sanitizer.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"response-sanitizer.test.js","sourceRoot":"","sources":["../../../src/core/agents/response-sanitizer.test.ts"],"names":[],"mappings":"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"}

package/dist/core/agents/retry.js

@@ -0,0 +1,105 @@
+import { Err } from '../../lib/utils/result.js';
+export const DEFAULT_RETRY_OPTIONS = {
+    maxAttempts: 5,
+    baseDelayMs: 1000,
+    maxDelayMs: 60000,
+};
+/**
+ * Generic retry wrapper with exponential backoff.
+ */
+export async function withRetry(fn, options) {
+    const opts = {
+        maxAttempts: options.maxAttempts ?? DEFAULT_RETRY_OPTIONS.maxAttempts,
+        baseDelayMs: options.baseDelayMs ?? DEFAULT_RETRY_OPTIONS.baseDelayMs,
+        maxDelayMs: options.maxDelayMs ?? DEFAULT_RETRY_OPTIONS.maxDelayMs,
+    };
+    let attempt = 0;
+    let lastError = null;
+    while (attempt < opts.maxAttempts) {
+        if (options.signal?.aborted) {
+            const error = lastError ?? options.abortError;
+            if (error !== undefined) {
+                return Err(error);
+            }
+            break;
+        }
+        const result = await fn();
+        if (result.ok) {
+            if (attempt > 0 && options.logger) {
+                options.logger.info('Operation succeeded after retries', {
+                    context: options.context,
+                    attempt: attempt + 1,
+                });
+            }
+            return result;
+        }
+        lastError = result.error;
+        if (!options.isRetryable(lastError)) {
+            return result;
+        }
+        attempt++;
+        const delay = calculateDelay(attempt, lastError, opts, options.getRetryDelay);
+        if (options.logger) {
+            options.logger.warn('Operation failed, retrying', {
+                context: options.context,
+                attempt,
+                delayMs: delay,
+            });
+        }
+        await sleep(delay, options.signal);
+    }
+    return Err(lastError);
+}
+function calculateDelay(attempt, error, opts, getRetryDelay) {
+    // Use error-specific delay if available
+    const errorDelay = getRetryDelay?.(error);
+    if (errorDelay !== undefined) {
+        return Math.min(errorDelay, opts.maxDelayMs);
+    }
+    // Exponential backoff: baseDelay * 2^(attempt-1)
+    const exponentialDelay = opts.baseDelayMs * Math.pow(2, attempt - 1);
+    // Add jitter (0-30%) to prevent thundering herd
+    const jitter = Math.random() * 0.3 * exponentialDelay;
+    return Math.min(exponentialDelay + jitter, opts.maxDelayMs);
+}
+function sleep(ms, signal) {
+    if (signal?.aborted)
+        return Promise.resolve();
+    return new Promise((resolve) => {
+        const timer = setTimeout(resolve, ms);
+        signal?.addEventListener('abort', () => {
+            clearTimeout(timer);
+            resolve();
+        }, { once: true });
+    });
+}
+// ============================================================================
+// LLM-specific helpers
+// ============================================================================
+/**
+ * Determines if an LLM error is retryable.
+ * Retryable: rate_limit, server_error, network_error, timeout
+ * Non-retryable: invalid_request, context_length (permanent failures)
+ */
+export function isRetryableLLMError(error) {
+    return ['rate_limit', 'server_error', 'network_error', 'timeout'].includes(error.type);
+}
+/**
+ * Gets retry delay from LLM error if available (e.g., rate limit retry-after).
+ */
+export function getLLMRetryDelay(error) {
+    return error.retryAfterMs;
+}
+/**
+ * Convenience wrapper for LLM inference with retry.
+ */
+export async function withLLMRetry(fn, options) {
+    return withRetry(fn, {
+        ...options,
+        isRetryable: isRetryableLLMError,
+        getRetryDelay: getLLMRetryDelay,
+        abortError: { type: 'aborted', message: 'Aborted before first attempt' },
+        context: 'LLM inference',
+    });
+}
+//# sourceMappingURL=retry.js.map

package/dist/core/agents/retry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retry.js","sourceRoot":"","sources":["../../../src/core/agents/retry.ts"],"names":[],"mappings":"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"}

package/dist/core/agents/schema.js

@@ -0,0 +1,39 @@
+/**
+ * Agent domain types and schemas
+ *
+ * Contains all types related to agents:
+ * - Branded ID type and constructor
+ * - Agent status types (domain and protocol)
+ * - Zod schemas for validation
+ */
+import z from 'zod/v4';
+// ============================================================================
+// AgentId - Branded type
+// ============================================================================
+/** AgentId schema - validates any string and brands as AgentId. */
+export const agentIdSchema = z.string().brand('AgentId');
+/** Constructor for AgentId */
+export const AgentId = (id) => id;
+/**
+ * Generate a short agent ID based on definition name and sequence number.
+ * Format: {definitionName}_{seq} e.g., "orchestrator_1", "planner_2"
+ */
+export const generateAgentId = (definitionName, seq) => AgentId(`${definitionName}_${seq}`);
+/**
+ * Zod schema for domain agent status.
+ */
+export const agentStatusSchema = z.enum(['pending', 'inferring', 'tool_exec', 'errored', 'paused']);
+/**
+ * Zod schema for protocol agent status.
+ */
+export const protocolAgentStatusSchema = z.enum(['idle', 'thinking', 'responding', 'waiting_for_user', 'error', 'paused']);
+// ============================================================================
+// Test helpers
+// ============================================================================
+let testCounter = 0;
+/**
+ * Generate a test agent ID (for tests only).
+ * Uses incrementing counter for uniqueness.
+ */
+export const generateTestAgentId = (definitionName = 'test-agent') => AgentId(`${definitionName}_${++testCounter}`);
+//# sourceMappingURL=schema.js.map

package/dist/core/agents/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/core/agents/schema.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,CAAC,MAAM,QAAQ,CAAA;AAEtB,+EAA+E;AAC/E,yBAAyB;AACzB,+EAA+E;AAE/E,mEAAmE;AACnE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,KAAK,CAAC,SAAS,CAAC,CAAA;AAKxD,8BAA8B;AAC9B,MAAM,CAAC,MAAM,OAAO,GAAG,CAAC,EAAU,EAAW,EAAE,CAAC,EAAa,CAAA;AAE7D;;;GAGG;AACH,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,cAAsB,EAAE,GAAW,EAAW,EAAE,CAAC,OAAO,CAAC,GAAG,cAAc,IAAI,GAAG,EAAE,CAAC,CAAA;AAgBpH;;GAEG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,WAAW,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAA;AAYnG;;GAEG;AACH,MAAM,CAAC,MAAM,yBAAyB,GAAG,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,kBAAkB,EAAE,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAA;AAE1H,+EAA+E;AAC/E,eAAe;AACf,+EAA+E;AAE/E,IAAI,WAAW,GAAG,CAAC,CAAA;AAEnB;;;GAGG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG,CAAC,cAAc,GAAG,YAAY,EAAW,EAAE,CAAC,OAAO,CAAC,GAAG,cAAc,IAAI,EAAE,WAAW,EAAE,CAAC,CAAA"}

package/dist/core/agents/state.js

@@ -0,0 +1,90 @@
+// ============================================================================
+// Agent status
+// ============================================================================
+import z4 from 'zod/v4';
+import { agentIdSchema } from '../../core/agents/schema.js';
+import { createEventsFactory } from '../../core/events/types';
+import { MessageId } from '../../plugins/mailbox/schema';
+export { MessageId };
+export const agentEvents = createEventsFactory({
+    events: {
+        agent_spawned: z4.object({
+            agentId: agentIdSchema,
+            definitionName: z4.string(),
+            parentId: agentIdSchema.nullable(),
+            typedInput: z4.unknown().optional(),
+        }),
+        agent_state_changed: z4.object({
+            agentId: agentIdSchema,
+            fromState: z4.enum(['pending', 'inferring', 'tool_exec', 'errored', 'paused']),
+            toState: z4.enum(['pending', 'inferring', 'tool_exec', 'errored', 'paused']),
+        }),
+        handler_started: z4.object({
+            agentId: agentIdSchema,
+            handlerName: z4.enum(['onStart', 'beforeInference', 'afterInference', 'beforeToolCall', 'afterToolCall', 'onComplete', 'onError']),
+        }),
+        handler_completed: z4.object({
+            agentId: agentIdSchema,
+            handlerName: z4.enum(['onStart', 'beforeInference', 'afterInference', 'beforeToolCall', 'afterToolCall', 'onComplete', 'onError']),
+            result: z4.unknown(), // HandlerResult - too complex for Zod
+        }),
+        preamble_added: z4.object({
+            agentId: agentIdSchema,
+            messages: z4.array(z4.custom()),
+        }),
+        agent_paused: z4.object({
+            agentId: agentIdSchema,
+            reason: z4.enum(['limit', 'handler', 'manual']),
+            message: z4.string().optional(),
+        }),
+        agent_resumed: z4.object({
+            agentId: agentIdSchema,
+        }),
+        communicator_linked: z4.object({
+            communicatorId: agentIdSchema,
+            orchestratorId: agentIdSchema,
+        }),
+        agent_conversation_spliced: z4.object({
+            agentId: agentIdSchema,
+            start: z4.number().int().min(0),
+            deleteCount: z4.number().int().min(0),
+            insert: z4.array(z4.custom()).optional(),
+        }),
+    },
+});
+// ============================================================================
+// AgentState tree helpers
+// ============================================================================
+export const getChildren = (session, parentId) => {
+    const children = [];
+    for (const agent of session.agents.values()) {
+        if (agent.parentId === parentId) {
+            children.push(agent);
+        }
+    }
+    return children;
+};
+export const getParent = (session, agent) => {
+    if (!agent.parentId)
+        return null;
+    return session.agents.get(agent.parentId) ?? null;
+};
+// Factory for creating AgentState (useful for tests)
+// ============================================================================
+/**
+ * Create a new AgentState with default values.
+ * Useful for tests to avoid maintaining inline mocks when new fields are added.
+ */
+export const createAgentState = (id, definitionName, overrides = {}) => ({
+    id,
+    definitionName,
+    parentId: null,
+    status: 'pending',
+    conversationHistory: [],
+    preamble: [],
+    pendingToolCalls: [],
+    pendingToolResults: [],
+    pendingMessages: [],
+    ...overrides,
+});
+//# sourceMappingURL=state.js.map

package/dist/core/agents/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/core/agents/state.ts"],"names":[],"mappings":"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"}

package/dist/core/context/state.js

@@ -0,0 +1,23 @@
+import z4 from 'zod/v4';
+import { agentIdSchema } from '../../core/agents';
+import { createEventsFactory } from '../../core/events/types';
+// ============================================================================
+// Context events
+// ============================================================================
+export const contextEvents = createEventsFactory({
+    events: {
+        context_compacted: z4.object({
+            agentId: agentIdSchema,
+            compactedContent: z4.string(),
+            newConversationHistory: z4.array(z4.object({
+                role: z4.enum(['user', 'assistant', 'system']),
+                content: z4.string(),
+            })),
+            originalTokens: z4.number(),
+            compactedTokens: z4.number(),
+            messagesRemoved: z4.number(),
+            historyPath: z4.string().optional(),
+        }),
+    },
+});
+//# sourceMappingURL=state.js.map

package/dist/core/context/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../../../src/core/context/state.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,QAAQ,CAAA;AACvB,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAczD,+EAA+E;AAC/E,iBAAiB;AACjB,+EAA+E;AAE/E,MAAM,CAAC,MAAM,aAAa,GAAG,mBAAmB,CAAC;IAChD,MAAM,EAAE;QACP,iBAAiB,EAAE,EAAE,CAAC,MAAM,CAAC;YAC5B,OAAO,EAAE,aAAa;YACtB,gBAAgB,EAAE,EAAE,CAAC,MAAM,EAAE;YAC7B,sBAAsB,EAAE,EAAE,CAAC,KAAK,CAAC,EAAE,CAAC,MAAM,CAAC;gBAC1C,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,WAAW,EAAE,QAAQ,CAAC,CAAC;gBAC9C,OAAO,EAAE,EAAE,CAAC,MAAM,EAAE;aACpB,CAAC,CAAC;YACH,cAAc,EAAE,EAAE,CAAC,MAAM,EAAE;YAC3B,eAAe,EAAE,EAAE,CAAC,MAAM,EAAE;YAC5B,eAAe,EAAE,EAAE,CAAC,MAAM,EAAE;YAC5B,WAAW,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;SACnC,CAAC;KACF;CACD,CAAC,CAAA"}

package/dist/core/errors.js

@@ -0,0 +1,38 @@
+/**
+ * Self-describing domain errors.
+ *
+ * Each error carries its own HTTP status and message — no central switch needed.
+ * Plugins can define any error type they want without touching central files.
+ */
+export function createDomainError(type, message, httpStatus) {
+    return { type, message, httpStatus };
+}
+export function isDomainError(value) {
+    return typeof value === 'object'
+        && value !== null
+        && 'type' in value
+        && typeof value.type === 'string'
+        && 'message' in value
+        && typeof value.message === 'string'
+        && 'httpStatus' in value
+        && typeof value.httpStatus === 'number';
+}
+// ============================================================================
+// Core error factories
+// ============================================================================
+export const SessionErrors = {
+    notFound: (id) => createDomainError('session_not_found', `Session not found: ${id}`, 404),
+    closed: (id) => createDomainError('session_closed', `Session is closed: ${id}`, 409),
+    alreadyExists: (id) => createDomainError('session_already_exists', `Session already exists: ${id}`, 409),
+};
+export const AgentErrors = {
+    notFound: (id) => createDomainError('agent_not_found', `Agent not found: ${id}`, 404),
+    invalidState: (id, currentState, expectedState) => createDomainError('invalid_agent_state', `Agent ${id} in invalid state: ${currentState}, expected: ${expectedState}`, 409),
+};
+export const PresetErrors = {
+    notFound: (id) => createDomainError('preset_not_found', `Preset not found: ${id}`, 404),
+};
+export const ValidationErrors = {
+    invalid: (message) => createDomainError('validation_error', message, 400),
+};
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.js","sourceRoot":"","sources":["../../src/core/errors.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAYH,MAAM,UAAU,iBAAiB,CAAC,IAAY,EAAE,OAAe,EAAE,UAAkB;IAClF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,CAAA;AACrC,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAc;IAC3C,OAAO,OAAO,KAAK,KAAK,QAAQ;WAC5B,KAAK,KAAK,IAAI;WACd,MAAM,IAAI,KAAK;WACf,OAAO,KAAK,CAAC,IAAI,KAAK,QAAQ;WAC9B,SAAS,IAAI,KAAK;WAClB,OAAO,KAAK,CAAC,OAAO,KAAK,QAAQ;WACjC,YAAY,IAAI,KAAK;WACrB,OAAO,KAAK,CAAC,UAAU,KAAK,QAAQ,CAAA;AACzC,CAAC;AAED,+EAA+E;AAC/E,uBAAuB;AACvB,+EAA+E;AAE/E,MAAM,CAAC,MAAM,aAAa,GAAG;IAC5B,QAAQ,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,iBAAiB,CAAC,mBAAmB,EAAE,sBAAsB,EAAE,EAAE,EAAE,GAAG,CAAC;IACjG,MAAM,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,iBAAiB,CAAC,gBAAgB,EAAE,sBAAsB,EAAE,EAAE,EAAE,GAAG,CAAC;IAC5F,aAAa,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,iBAAiB,CAAC,wBAAwB,EAAE,2BAA2B,EAAE,EAAE,EAAE,GAAG,CAAC;CAChH,CAAA;AAED,MAAM,CAAC,MAAM,WAAW,GAAG;IAC1B,QAAQ,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,iBAAiB,CAAC,iBAAiB,EAAE,oBAAoB,EAAE,EAAE,EAAE,GAAG,CAAC;IAC7F,YAAY,EAAE,CAAC,EAAU,EAAE,YAAoB,EAAE,aAAqB,EAAE,EAAE,CACzE,iBAAiB,CAAC,qBAAqB,EAAE,SAAS,EAAE,sBAAsB,YAAY,eAAe,aAAa,EAAE,EAAE,GAAG,CAAC;CAC3H,CAAA;AAED,MAAM,CAAC,MAAM,YAAY,GAAG;IAC3B,QAAQ,EAAE,CAAC,EAAU,EAAE,EAAE,CAAC,iBAAiB,CAAC,kBAAkB,EAAE,qBAAqB,EAAE,EAAE,EAAE,GAAG,CAAC;CAC/F,CAAA;AAED,MAAM,CAAC,MAAM,gBAAgB,GAAG;IAC/B,OAAO,EAAE,CAAC,OAAe,EAAE,EAAE,CAAC,iBAAiB,CAAC,kBAAkB,EAAE,OAAO,EAAE,GAAG,CAAC;CACjF,CAAA"}