typed-agents 1.0.0

package/dist/agents/agent.types.d.ts

@@ -0,0 +1,245 @@
+import { LLMClient, LLMMessage, LLMResponse } from "../clients/llm.client";
+import { ToolClass, ToolDefinition, ToolMapEntry } from "../tools/tool.types";
+/**
+ * Represents a tool dependency registered with an agent.
+ * Can be a decorated class, an instantiated tool object, or the "auto" string
+ * to allow automatic tool resolution.
+ */
+export type ToolDependency = ToolClass | object | "auto";
+/**
+ * Agent initial configuration options as provided by the user.
+ * These are the settings used when creating a new agent instance.
+ */
+export interface AgentOptions {
+    /** Unique symbolic name for the agent (e.g. "assistant", "research_agent"). */
+    name: string;
+    /** LLM model name to use (optional if `llmClient` is already provided). */
+    model?: string;
+    /** LLM client instance to use for API calls. */
+    llmClient?: LLMClient;
+    /** List of tools available for this agent. */
+    tools?: ToolDependency[];
+    /** Maximum number of reasoning steps before terminating. */
+    maxSteps?: number;
+    /** Optional system prompt to include at the start of the context. */
+    systemPrompt?: string;
+    /** Behavior directives, either a string or an array of strings. */
+    behavior?: string | string[];
+}
+/**
+ * Agent metadata after option normalization.
+ * Used at runtime for validation and direct value access.
+ */
+export interface AgentMetadata {
+    name: string;
+    model?: string;
+    llmClient?: LLMClient;
+    tools: ToolDependency[];
+    maxSteps?: number;
+    systemPrompt?: string;
+    behavior?: string | string[];
+}
+/**
+ * Runtime state tracked during agent execution.
+ */
+export interface AgentState {
+    steps: number;
+    toolCalls: number;
+    startTime: number;
+}
+/**
+ * Logging level used by execution trace events.
+ */
+export type LogLevel = "info" | "warn" | "error";
+/**
+ * Basic log metadata emitted by the agent.
+ */
+export interface LogMeta {
+    level: LogLevel;
+    message: string;
+}
+/**
+ * Persistence layer configuration.
+ * - none: no persistence
+ * - memory: only in-memory persistence
+ * - file: persistence on filesystem
+ */
+export interface PersistConfig {
+    mode: "none" | "memory" | "file";
+    dir?: string;
+    maxHistory?: number;
+    persistCache?: boolean;
+}
+/**
+ * Agent planning mode.
+ * - none: standard ReAct loop
+ * - basic: adds a PLAN step before execution
+ * - reflect: adds a PLAN step and a REFLECTION step after each tool call
+ */
+export type PlanningMode = "none" | "basic" | "reflect";
+/**
+ * Runtime options for `agent.run()`.
+ */
+export interface RunOptions {
+    maxSteps?: number;
+    temperature?: number;
+    silent?: boolean;
+    maxRetries?: number;
+    retryDelayMs?: number;
+    backoff?: boolean;
+    persist?: PersistConfig | boolean;
+    resumeId?: string;
+    persistCache?: boolean;
+    planning?: PlanningMode;
+}
+/**
+ * Serialized snapshot of an agent run for resume and audit.
+ */
+export interface SerializedState {
+    runId: string;
+    agentName: string;
+    messages: LLMMessage[];
+    state: AgentState;
+    step: number;
+    timestamp: number;
+    isFinished: boolean;
+}
+/**
+ * Typed result for a tool called during execution.
+ */
+export type ToolResult = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    error: string;
+    toolName: string;
+};
+/**
+ * Constructs a successful ToolResult.
+ */
+export declare function toolSuccess(value: string): ToolResult;
+/**
+ * Constructs a failed ToolResult.
+ */
+export declare function toolFailure(toolName: string, error: string): ToolResult;
+/**
+ * Events emitted by the agent during the lifecycle of a run.
+ */
+export type AgentEvent = {
+    type: "agent:start";
+    log: LogMeta;
+    payload: {
+        agent: string;
+        input: string;
+    };
+} | {
+    type: "agent:step";
+    log: LogMeta;
+    payload: {
+        step: number;
+    };
+} | {
+    type: "agent:plan";
+    log: LogMeta;
+    payload: {
+        plan: string;
+    };
+} | {
+    type: "agent:reflect";
+    log: LogMeta;
+    payload: {
+        reflection: string;
+    };
+} | {
+    type: "agent:finish";
+    log: LogMeta;
+    payload: {
+        output: string;
+    };
+} | {
+    type: "agent:max_steps";
+    log: LogMeta;
+} | {
+    type: "agent:resume";
+    log: LogMeta;
+    payload: {
+        runId: string;
+    };
+} | {
+    type: "llm:response";
+    log: LogMeta;
+    payload: LLMResponse;
+} | {
+    type: "llm:stream_chunk";
+    log: LogMeta;
+    payload: {
+        delta: string;
+    };
+} | {
+    type: "tool:call";
+    log: LogMeta;
+    payload: {
+        name: string;
+        args: unknown;
+    };
+} | {
+    type: "tool:result";
+    log: LogMeta;
+    payload: {
+        name: string;
+        result: string;
+    };
+} | {
+    type: "tool:error";
+    log: LogMeta;
+    payload: {
+        name: string;
+        error: string;
+    };
+} | {
+    type: "retry:attempt";
+    log: LogMeta;
+    payload: {
+        name: string;
+        attempt: number;
+        error: string;
+    };
+} | {
+    type: "state:saved";
+    log: LogMeta;
+    payload: {
+        runId: string;
+    };
+};
+/**
+ * Context passed to every agent execution callback.
+ */
+export interface AgentContext {
+    agentName: string;
+    input: string;
+    messages: LLMMessage[];
+    state: AgentState;
+    step: number;
+    toolMap: Map<string, ToolMapEntry>;
+    tools: ToolDefinition[];
+    startTime: number;
+    emit: <E extends AgentEvent>(event: E) => void;
+    runId: string;
+}
+/**
+ * Type guard to identify a composable sub-agent tool.
+ */
+export declare function isComposableTool(t: ToolDependency): t is ComposableTool;
+/**
+ * Data structure representing a composable tool that wraps a dedicated agent.
+ */
+export interface ComposableTool {
+    __isComposable: true;
+    AgentClass: new () => object;
+    name?: string;
+    description?: string;
+    inputKey: string;
+    maxSteps?: number;
+}
+//# sourceMappingURL=agent.types.d.ts.map

package/dist/agents/agent.types.d.ts.map

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

package/dist/agents/agent.types.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.toolSuccess = toolSuccess;
+exports.toolFailure = toolFailure;
+exports.isComposableTool = isComposableTool;
+/**
+ * Constructs a successful ToolResult.
+ */
+function toolSuccess(value) {
+    return { ok: true, value };
+}
+/**
+ * Constructs a failed ToolResult.
+ */
+function toolFailure(toolName, error) {
+    return { ok: false, error, toolName };
+}
+/**
+ * Type guard to identify a composable sub-agent tool.
+ */
+function isComposableTool(t) {
+    return (typeof t === "object" &&
+        t !== null &&
+        "__isComposable" in t &&
+        t.__isComposable === true);
+}
+//# sourceMappingURL=agent.types.js.map

package/dist/agents/agent.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.types.js","sourceRoot":"","sources":["../../src/agents/agent.types.ts"],"names":[],"mappings":";;AAoIA,kCAEC;AAKD,kCAEC;AA4CD,4CAOC;AA/DD;;GAEG;AACH,SAAgB,WAAW,CAAC,KAAa;IACvC,OAAO,EAAE,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,CAAC;AAC7B,CAAC;AAED;;GAEG;AACH,SAAgB,WAAW,CAAC,QAAgB,EAAE,KAAa;IACzD,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE,QAAQ,EAAE,CAAC;AACxC,CAAC;AAyCD;;GAEG;AACH,SAAgB,gBAAgB,CAAC,CAAiB;IAChD,OAAO,CACL,OAAO,CAAC,KAAK,QAAQ;QACrB,CAAC,KAAK,IAAI;QACV,gBAAgB,IAAI,CAAC;QACpB,CAAoB,CAAC,cAAc,KAAK,IAAI,CAC9C,CAAC;AACJ,CAAC"}

package/dist/agents/behavior-engine/behavior.types.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Defines the structure of an agent behavior configuration.
+ * Behaviors can specify role, rules, planning instructions, and answer formatting,
+ * and can extend other behaviors.
+ */
+export interface AgentBehavior {
+    /** Optional role description for the agent (e.g., "You are a helpful assistant"). */
+    role?: string;
+    /** Optional rules or guidelines the agent must follow. */
+    rules?: string;
+    /** Optional planning instructions for multi-step reasoning. */
+    planning?: string;
+    /** Optional formatting instructions for answers. */
+    answer?: string;
+    /** Optional name of another behavior to extend/inherit from. */
+    extends?: string;
+}
+/**
+ * Union type for the keys of AgentBehavior sections.
+ * Used for dynamic access and validation of behavior properties.
+ */
+export type BehaviorSection = "role" | "rules" | "planning" | "answer" | "extends";
+//# sourceMappingURL=behavior.types.d.ts.map

package/dist/agents/behavior-engine/behavior.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior.types.d.ts","sourceRoot":"","sources":["../../../src/agents/behavior-engine/behavior.types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,0DAA0D;IAC1D,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+DAA+D;IAC/D,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,gEAAgE;IAChE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,OAAO,GAAG,UAAU,GAAG,QAAQ,GAAG,SAAS,CAAC"}

package/dist/agents/behavior-engine/behavior.types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=behavior.types.js.map

package/dist/agents/behavior-engine/behavior.types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"behavior.types.js","sourceRoot":"","sources":["../../../src/agents/behavior-engine/behavior.types.ts"],"names":[],"mappings":""}

package/dist/agents/behavior-engine/build-system-prompt.d.ts

@@ -0,0 +1,12 @@
+import { AgentBehavior } from "./behavior.types";
+/**
+ * Builds a formatted system prompt string from an AgentBehavior configuration.
+ *
+ * Concatenates each defined behavior section (role, rules, planning, answer)
+ * into a structured prompt with section headers. Sections are joined with double newlines.
+ *
+ * @param behavior - The behavior configuration to build the prompt from.
+ * @returns A formatted system prompt string.
+ */
+export declare function buildSystemPrompt(behavior: AgentBehavior): string;
+//# sourceMappingURL=build-system-prompt.d.ts.map

package/dist/agents/behavior-engine/build-system-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-system-prompt.d.ts","sourceRoot":"","sources":["../../../src/agents/behavior-engine/build-system-prompt.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,aAAa,GAAG,MAAM,CAoBjE"}

package/dist/agents/behavior-engine/build-system-prompt.js

@@ -0,0 +1,29 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildSystemPrompt = buildSystemPrompt;
+/**
+ * Builds a formatted system prompt string from an AgentBehavior configuration.
+ *
+ * Concatenates each defined behavior section (role, rules, planning, answer)
+ * into a structured prompt with section headers. Sections are joined with double newlines.
+ *
+ * @param behavior - The behavior configuration to build the prompt from.
+ * @returns A formatted system prompt string.
+ */
+function buildSystemPrompt(behavior) {
+    const parts = [];
+    if (behavior.role) {
+        parts.push(`## ROLE\n${behavior.role}`);
+    }
+    if (behavior.rules) {
+        parts.push(`## RULES\n${behavior.rules}`);
+    }
+    if (behavior.planning) {
+        parts.push(`## PLANNING\n${behavior.planning}`);
+    }
+    if (behavior.answer) {
+        parts.push(`## ANSWER STYLE\n${behavior.answer}`);
+    }
+    return parts.join("\n\n");
+}
+//# sourceMappingURL=build-system-prompt.js.map

package/dist/agents/behavior-engine/build-system-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-system-prompt.js","sourceRoot":"","sources":["../../../src/agents/behavior-engine/build-system-prompt.ts"],"names":[],"mappings":";;AAWA,8CAoBC;AA7BD;;;;;;;;GAQG;AACH,SAAgB,iBAAiB,CAAC,QAAuB;IACvD,MAAM,KAAK,GAAa,EAAE,CAAC;IAE3B,IAAI,QAAQ,CAAC,IAAI,EAAE,CAAC;QAClB,KAAK,CAAC,IAAI,CAAC,YAAY,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,IAAI,QAAQ,CAAC,KAAK,EAAE,CAAC;QACnB,KAAK,CAAC,IAAI,CAAC,aAAa,QAAQ,CAAC,KAAK,EAAE,CAAC,CAAC;IAC5C,CAAC;IAED,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACtB,KAAK,CAAC,IAAI,CAAC,gBAAgB,QAAQ,CAAC,QAAQ,EAAE,CAAC,CAAC;IAClD,CAAC;IAED,IAAI,QAAQ,CAAC,MAAM,EAAE,CAAC;QACpB,KAAK,CAAC,IAAI,CAAC,oBAAoB,QAAQ,CAAC,MAAM,EAAE,CAAC,CAAC;IACpD,CAAC;IAED,OAAO,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;AAC5B,CAAC"}

package/dist/agents/behavior-engine/index.d.ts

@@ -0,0 +1,7 @@
+export * from './behavior.types';
+export * from './build-system-prompt';
+export * from './load-behavior';
+export * from './merge-behavior';
+export * from './parse-behavior';
+export * from './watch-behavior';
+//# sourceMappingURL=index.d.ts.map

package/dist/agents/behavior-engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/agents/behavior-engine/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC"}

package/dist/agents/behavior-engine/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./behavior.types"), exports);
+__exportStar(require("./build-system-prompt"), exports);
+__exportStar(require("./load-behavior"), exports);
+__exportStar(require("./merge-behavior"), exports);
+__exportStar(require("./parse-behavior"), exports);
+__exportStar(require("./watch-behavior"), exports);
+//# sourceMappingURL=index.js.map

package/dist/agents/behavior-engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/agents/behavior-engine/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,mDAAiC;AACjC,wDAAsC;AACtC,kDAAgC;AAChC,mDAAiC;AACjC,mDAAiC;AACjC,mDAAiC"}

package/dist/agents/behavior-engine/load-behavior.d.ts

@@ -0,0 +1,16 @@
+import { AgentBehavior } from "./behavior.types";
+/**
+ * Loads and merges behavior configurations from file paths or names.
+ *
+ * Parses each behavior file, merges them into a single AgentBehavior,
+ * and caches the result to avoid re-parsing. Supports single string or array of strings.
+ *
+ * @param input - Single behavior file path/name or array of them.
+ * @returns The merged AgentBehavior configuration.
+ */
+export declare function loadBehavior(input: string | string[]): AgentBehavior;
+/**
+ * Clears the in-memory cache. Called by watchBehavior and in tests.
+ */
+export declare function clearLoadBehaviorCache(): void;
+//# sourceMappingURL=load-behavior.d.ts.map

package/dist/agents/behavior-engine/load-behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-behavior.d.ts","sourceRoot":"","sources":["../../../src/agents/behavior-engine/load-behavior.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AASjD;;;;;;;;GAQG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,aAAa,CASpE;AAED;;GAEG;AACH,wBAAgB,sBAAsB,IAAI,IAAI,CAE7C"}

package/dist/agents/behavior-engine/load-behavior.js

@@ -0,0 +1,36 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadBehavior = loadBehavior;
+exports.clearLoadBehaviorCache = clearLoadBehaviorCache;
+const parse_behavior_1 = require("./parse-behavior");
+const merge_behavior_1 = require("./merge-behavior");
+/**
+ * Module-level cache is acceptable here since behavior files are read-only at runtime.
+ * We expose a clear function for unit tests and hot-reload via watchBehavior.
+ */
+const cache = new Map();
+/**
+ * Loads and merges behavior configurations from file paths or names.
+ *
+ * Parses each behavior file, merges them into a single AgentBehavior,
+ * and caches the result to avoid re-parsing. Supports single string or array of strings.
+ *
+ * @param input - Single behavior file path/name or array of them.
+ * @returns The merged AgentBehavior configuration.
+ */
+function loadBehavior(input) {
+    const key = JSON.stringify(input);
+    if (cache.has(key))
+        return cache.get(key);
+    const files = Array.isArray(input) ? input : [input];
+    const merged = (0, merge_behavior_1.mergeBehaviors)(files.map((f) => (0, parse_behavior_1.parseBehavior)(f)));
+    cache.set(key, merged);
+    return merged;
+}
+/**
+ * Clears the in-memory cache. Called by watchBehavior and in tests.
+ */
+function clearLoadBehaviorCache() {
+    cache.clear();
+}
+//# sourceMappingURL=load-behavior.js.map

package/dist/agents/behavior-engine/load-behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"load-behavior.js","sourceRoot":"","sources":["../../../src/agents/behavior-engine/load-behavior.ts"],"names":[],"mappings":";;AAmBA,oCASC;AAKD,wDAEC;AAnCD,qDAAiD;AAEjD,qDAAkD;AAElD;;;GAGG;AACH,MAAM,KAAK,GAAG,IAAI,GAAG,EAAyB,CAAC;AAE/C;;;;;;;;GAQG;AACH,SAAgB,YAAY,CAAC,KAAwB;IACnD,MAAM,GAAG,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC;IAClC,IAAI,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAE,CAAC;IAE3C,MAAM,KAAK,GAAG,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACrD,MAAM,MAAM,GAAG,IAAA,+BAAc,EAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,IAAA,8BAAa,EAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAElE,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,MAAM,CAAC,CAAC;IACvB,OAAO,MAAM,CAAC;AAChB,CAAC;AAED;;GAEG;AACH,SAAgB,sBAAsB;IACpC,KAAK,CAAC,KAAK,EAAE,CAAC;AAChB,CAAC"}

package/dist/agents/behavior-engine/merge-behavior.d.ts

@@ -0,0 +1,12 @@
+import { AgentBehavior } from "./behavior.types";
+/**
+ * Merges multiple AgentBehavior configurations into a single one.
+ *
+ * For most fields (role, answer, extends), later behaviors override earlier ones.
+ * For "rules" and "planning", values are concatenated with newlines to accumulate.
+ *
+ * @param behaviors - Array of behaviors to merge, in order of precedence.
+ * @returns A single merged AgentBehavior.
+ */
+export declare function mergeBehaviors(behaviors: AgentBehavior[]): AgentBehavior;
+//# sourceMappingURL=merge-behavior.d.ts.map

package/dist/agents/behavior-engine/merge-behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-behavior.d.ts","sourceRoot":"","sources":["../../../src/agents/behavior-engine/merge-behavior.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAEjD;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAC5B,SAAS,EAAE,aAAa,EAAE,GACzB,aAAa,CAmBf"}

package/dist/agents/behavior-engine/merge-behavior.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mergeBehaviors = mergeBehaviors;
+/**
+ * Merges multiple AgentBehavior configurations into a single one.
+ *
+ * For most fields (role, answer, extends), later behaviors override earlier ones.
+ * For "rules" and "planning", values are concatenated with newlines to accumulate.
+ *
+ * @param behaviors - Array of behaviors to merge, in order of precedence.
+ * @returns A single merged AgentBehavior.
+ */
+function mergeBehaviors(behaviors) {
+    const result = {};
+    for (const behavior of behaviors) {
+        for (const key of Object.keys(behavior)) {
+            const value = behavior[key];
+            if (!value)
+                continue;
+            if (key === "rules") {
+                result.rules = [result.rules, value].filter(Boolean).join("\n");
+            }
+            else if (key === "planning") {
+                result.planning = [result.planning, value].filter(Boolean).join("\n");
+            }
+            else {
+                result[key] = value;
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=merge-behavior.js.map

package/dist/agents/behavior-engine/merge-behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"merge-behavior.js","sourceRoot":"","sources":["../../../src/agents/behavior-engine/merge-behavior.ts"],"names":[],"mappings":";;AAWA,wCAqBC;AA9BD;;;;;;;;GAQG;AACH,SAAgB,cAAc,CAC5B,SAA0B;IAE1B,MAAM,MAAM,GAAkB,EAAE,CAAC;IAEjC,KAAK,MAAM,QAAQ,IAAI,SAAS,EAAE,CAAC;QACjC,KAAK,MAAM,GAAG,IAAI,MAAM,CAAC,IAAI,CAAC,QAAQ,CAA4B,EAAE,CAAC;YACnE,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC;YAC5B,IAAI,CAAC,KAAK;gBAAE,SAAS;YAErB,IAAI,GAAG,KAAK,OAAO,EAAE,CAAC;gBACpB,MAAM,CAAC,KAAK,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClE,CAAC;iBAAM,IAAI,GAAG,KAAK,UAAU,EAAE,CAAC;gBAC9B,MAAM,CAAC,QAAQ,GAAG,CAAC,MAAM,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YACxE,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;YACtB,CAAC;QACH,CAAC;IACH,CAAC;IAED,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/agents/behavior-engine/parse-behavior.d.ts

@@ -0,0 +1,10 @@
+import { AgentBehavior } from "./behavior.types";
+/**
+ * Parses a behavior file into an AgentBehavior object, resolving extends.
+ *
+ * @param filePath - Path to the behavior file to parse.
+ * @returns The parsed and extended AgentBehavior.
+ */
+export declare function parseBehavior(filePath: string): AgentBehavior;
+export declare function clearBehaviorCache(): void;
+//# sourceMappingURL=parse-behavior.d.ts.map

package/dist/agents/behavior-engine/parse-behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-behavior.d.ts","sourceRoot":"","sources":["../../../src/agents/behavior-engine/parse-behavior.ts"],"names":[],"mappings":"AAEA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAIjD;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,aAAa,CAE7D;AAgED,wBAAgB,kBAAkB,SAEjC"}

package/dist/agents/behavior-engine/parse-behavior.js

@@ -0,0 +1,66 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseBehavior = parseBehavior;
+exports.clearBehaviorCache = clearBehaviorCache;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const fileCache = new Map();
+/**
+ * Parses a behavior file into an AgentBehavior object, resolving extends.
+ *
+ * @param filePath - Path to the behavior file to parse.
+ * @returns The parsed and extended AgentBehavior.
+ */
+function parseBehavior(filePath) {
+    return parseBehaviorInternal(filePath, new Set());
+}
+/**
+ * Internal recursive function to parse behavior files with cycle detection.
+ *
+ * Parses markdown-like sections (# ROLE, # RULES, etc.) and handles extends.
+ *
+ * @param filePath - Path to the behavior file.
+ * @param visited - Set of visited paths to detect cycles.
+ * @returns The parsed AgentBehavior.
+ * @throws Error on circular extends.
+ */
+function parseBehaviorInternal(filePath, visited) {
+    const fullPath = path_1.default.resolve(filePath);
+    if (fileCache.has(fullPath)) {
+        return fileCache.get(fullPath);
+    }
+    if (visited.has(fullPath)) {
+        throw new Error(`Circular behavior extends detected: ${fullPath}`);
+    }
+    visited.add(fullPath);
+    const content = fs_1.default.readFileSync(fullPath, "utf-8");
+    const sections = {};
+    const regex = /^#\s*(\w+)\s*\n([\s\S]*?)(?=^#|$)/gm;
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+        const [, rawKey, rawValue] = match;
+        if (!rawKey || !rawValue)
+            continue;
+        const key = rawKey.trim().toLowerCase();
+        const value = rawValue.trim();
+        sections[key] = value;
+    }
+    let result = sections;
+    if (sections.extends) {
+        const parentPath = path_1.default.resolve(path_1.default.dirname(fullPath), sections.extends);
+        const parent = parseBehaviorInternal(parentPath, visited);
+        result = {
+            ...parent,
+            ...sections,
+        };
+    }
+    fileCache.set(fullPath, result);
+    return result;
+}
+function clearBehaviorCache() {
+    fileCache.clear();
+}
+//# sourceMappingURL=parse-behavior.js.map

package/dist/agents/behavior-engine/parse-behavior.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parse-behavior.js","sourceRoot":"","sources":["../../../src/agents/behavior-engine/parse-behavior.ts"],"names":[],"mappings":";;;;;AAYA,sCAEC;AAgED,gDAEC;AAhFD,4CAAoB;AACpB,gDAAwB;AAGxB,MAAM,SAAS,GAAG,IAAI,GAAG,EAAyB,CAAC;AAEnD;;;;;GAKG;AACH,SAAgB,aAAa,CAAC,QAAgB;IAC5C,OAAO,qBAAqB,CAAC,QAAQ,EAAE,IAAI,GAAG,EAAE,CAAC,CAAC;AACpD,CAAC;AAED;;;;;;;;;GASG;AACH,SAAS,qBAAqB,CAC5B,QAAgB,EAChB,OAAoB;IAEpB,MAAM,QAAQ,GAAG,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;IAExC,IAAI,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC5B,OAAO,SAAS,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;IAClC,CAAC;IAED,IAAI,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC1B,MAAM,IAAI,KAAK,CAAC,uCAAuC,QAAQ,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IAEtB,MAAM,OAAO,GAAG,YAAE,CAAC,YAAY,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;IAEnD,MAAM,QAAQ,GAAkB,EAAE,CAAC;IAEnC,MAAM,KAAK,GAAG,qCAAqC,CAAC;IACpD,IAAI,KAA6B,CAAC;IAElC,OAAO,CAAC,KAAK,GAAG,KAAK,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,KAAK,IAAI,EAAE,CAAC;QAC9C,MAAM,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,GAAG,KAAK,CAAC;QAEnC,IAAI,CAAC,MAAM,IAAI,CAAC,QAAQ;YAAE,SAAS;QAEnC,MAAM,GAAG,GAAG,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAyB,CAAC;QAC/D,MAAM,KAAK,GAAG,QAAQ,CAAC,IAAI,EAAE,CAAC;QAE7B,QAAgB,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;IACjC,CAAC;IAED,IAAI,MAAM,GAAkB,QAAQ,CAAC;IAErC,IAAI,QAAQ,CAAC,OAAO,EAAE,CAAC;QACrB,MAAM,UAAU,GAAG,cAAI,CAAC,OAAO,CAAC,cAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,QAAQ,CAAC,OAAO,CAAC,CAAC;QAE1E,MAAM,MAAM,GAAG,qBAAqB,CAAC,UAAU,EAAE,OAAO,CAAC,CAAC;QAE1D,MAAM,GAAG;YACP,GAAG,MAAM;YACT,GAAG,QAAQ;SACZ,CAAC;IACJ,CAAC;IAED,SAAS,CAAC,GAAG,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC;IAEhC,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,SAAgB,kBAAkB;IAChC,SAAS,CAAC,KAAK,EAAE,CAAC;AACpB,CAAC"}

package/dist/agents/behavior-engine/watch-behavior.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Sets up file watching for behavior files in a directory.
+ *
+ * Watches for changes to .md files and clears the behavior cache on changes,
+ * enabling hot-reload of behaviors during development.
+ *
+ * @param dir - Directory path to watch for behavior files.
+ */
+export declare function watchBehaviors(dir: string): void;
+//# sourceMappingURL=watch-behavior.d.ts.map

package/dist/agents/behavior-engine/watch-behavior.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watch-behavior.d.ts","sourceRoot":"","sources":["../../../src/agents/behavior-engine/watch-behavior.ts"],"names":[],"mappings":"AAOA;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,QAmBzC"}