agentx-sdk 0.1.0

package/dist/contracts/entities/agent-skill.d.ts

@@ -0,0 +1,59 @@
+import type { AgentTool } from './agent-tool.js';
+/** A skill that modifies Agent behavior when activated */
+export interface AgentSkill {
+    name: string;
+    description: string;
+    instructions: string;
+    /** Custom predicate for pattern-based activation */
+    match?: (input: string, context: SkillMatchContext) => boolean;
+    /** Exact prefix match (e.g. "/review") */
+    triggerPrefix?: string;
+    /** Alternative names for slash-command invocation */
+    aliases?: string[];
+    /** Higher number = higher priority when multiple skills match */
+    priority?: number;
+    /** If true, blocks all other skills when activated */
+    exclusive?: boolean;
+    /** Dynamic prompt generator — when provided, overrides static `instructions` */
+    getPrompt?: (args: string, context: SkillPromptContext) => Promise<string> | string;
+    /** Named argument placeholders for substitution ($argName in instructions) */
+    argNames?: string[];
+    /** Detailed usage scenarios — helps model decide WHEN to invoke proactively */
+    whenToUse?: string;
+    /** Tools available only when this skill is active */
+    tools?: AgentTool[];
+    /** Restrict which global tools the skill can use (allowlist) */
+    allowedTools?: string[];
+    /** Override model for this skill's execution */
+    model?: string;
+    /** Execution mode: 'inline' injects into current context */
+    context?: 'inline';
+    /** Computational effort hint (1-10) */
+    effort?: number;
+    /** Keeps the skill active across subsequent turns after initial activation.
+     *  true = active until clearStickySkills() is called (e.g. on clearHistory).
+     *  number = number of additional turns to remain active after activation (e.g. 10). */
+    sticky?: boolean | number;
+    /** Glob patterns — skill only activates when matching files are touched */
+    paths?: string[];
+    /** Feature-flag function — skill hidden when returns false */
+    isEnabled?: () => boolean;
+    /** Whether model can invoke this skill proactively (default: true) */
+    modelInvocable?: boolean;
+    /** Source of the skill (for diagnostics/listing) */
+    source?: 'programmatic' | 'directory' | 'mcp' | 'bundled';
+    /** Base directory for skill resources (set automatically for .md skills) */
+    skillDir?: string;
+}
+/** Context passed to skill.match() */
+export interface SkillMatchContext {
+    threadId: string;
+    recentMessages: number;
+}
+/** Context passed to skill.getPrompt() */
+export interface SkillPromptContext {
+    threadId: string;
+    traceId: string;
+    skillDir?: string;
+}
+//# sourceMappingURL=agent-skill.d.ts.map

package/dist/contracts/entities/agent-skill.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skill.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/agent-skill.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEjD,0DAA0D;AAC1D,MAAM,WAAW,UAAU;IAEzB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IAGrB,oDAAoD;IACpD,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,iBAAiB,KAAK,OAAO,CAAC;IAC/D,0CAA0C;IAC1C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,qDAAqD;IACrD,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,iEAAiE;IACjE,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,SAAS,CAAC,EAAE,OAAO,CAAC;IAGpB,gFAAgF;IAChF,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,kBAAkB,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;IACpF,8EAA8E;IAC9E,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IAGnB,qDAAqD;IACrD,KAAK,CAAC,EAAE,SAAS,EAAE,CAAC;IACpB,gEAAgE;IAChE,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,QAAQ,CAAC;IACnB,uCAAuC;IACvC,MAAM,CAAC,EAAE,MAAM,CAAC;IAGhB;;2FAEuF;IACvF,MAAM,CAAC,EAAE,OAAO,GAAG,MAAM,CAAC;IAG1B,2EAA2E;IAC3E,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,OAAO,CAAC;IAC1B,sEAAsE;IACtE,cAAc,CAAC,EAAE,OAAO,CAAC;IAGzB,oDAAoD;IACpD,MAAM,CAAC,EAAE,cAAc,GAAG,WAAW,GAAG,KAAK,GAAG,SAAS,CAAC;IAC1D,4EAA4E;IAC5E,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,sCAAsC;AACtC,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,0CAA0C;AAC1C,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB"}

package/dist/contracts/entities/agent-skill.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-skill.js.map

package/dist/contracts/entities/agent-skill.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-skill.js","sourceRoot":"","sources":["../../../src/contracts/entities/agent-skill.ts"],"names":[],"mappings":""}

package/dist/contracts/entities/agent-tool.d.ts

@@ -0,0 +1,42 @@
+import type { ZodSchema } from 'zod';
+import type { AgentToolResult } from './tool-call.js';
+/** Progress callback — tools call this to report incremental updates */
+export type ToolProgressCallback = (data: Record<string, unknown>) => void;
+/** A tool that the Agent can invoke during the ReactLoop */
+export interface AgentTool {
+    name: string;
+    description: string;
+    parameters: ZodSchema;
+    execute: (args: unknown, signal: AbortSignal, onProgress?: ToolProgressCallback) => Promise<string | AgentToolResult>;
+    /** Semantic validation — return error string to reject, null to allow. Called before execute. */
+    validate?: (args: unknown, context: ToolValidationContext) => Promise<string | null>;
+    /**
+     * Whether this tool is safe to run concurrently with other concurrency-safe tools.
+     * Read-only tools (search, read) should be `true`; write tools (edit, bash) should be `false`.
+     * Can be a function to decide per-invocation based on args.
+     * Default: false (serial execution).
+     */
+    isConcurrencySafe?: boolean | ((args: unknown) => boolean);
+    /** Whether this tool only reads data (no side effects). */
+    isReadOnly?: boolean | ((args: unknown) => boolean);
+    /** Whether this tool performs irreversible operations (delete, send, overwrite). */
+    isDestructive?: boolean | ((args: unknown) => boolean);
+    /** Extract file path(s) from args — enables conditional skill activation when files are touched. */
+    getFilePath?: (args: unknown) => string | string[] | undefined;
+    /** Per-tool timeout in milliseconds. Wraps execute with AbortSignal. */
+    timeoutMs?: number;
+    /** Max characters for tool result before truncation. Default: 10_000. */
+    maxResultChars?: number;
+    /** Transform result before sending to model. */
+    mapResult?: (result: AgentToolResult) => AgentToolResult;
+    /** Whether transient failures should be retried. Default: false. */
+    retryable?: boolean | ((error: unknown) => boolean);
+    /** Max retry attempts for transient failures. Default: 2. */
+    maxRetries?: number;
+}
+/** Context passed to tool.validate() for semantic validation */
+export interface ToolValidationContext {
+    threadId: string;
+    recentMessages: number;
+}
+//# sourceMappingURL=agent-tool.d.ts.map

package/dist/contracts/entities/agent-tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/agent-tool.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,KAAK,CAAC;AACrC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEtD,wEAAwE;AACxE,MAAM,MAAM,oBAAoB,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAE3E,4DAA4D;AAC5D,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,SAAS,CAAC;IACtB,OAAO,EAAE,CACP,IAAI,EAAE,OAAO,EACb,MAAM,EAAE,WAAW,EACnB,UAAU,CAAC,EAAE,oBAAoB,KAC9B,OAAO,CAAC,MAAM,GAAG,eAAe,CAAC,CAAC;IAEvC,iGAAiG;IACjG,QAAQ,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,EAAE,OAAO,EAAE,qBAAqB,KAAK,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAErF;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC;IAE3D,2DAA2D;IAC3D,UAAU,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC;IAEpD,oFAAoF;IACpF,aAAa,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC;IAEvD,oGAAoG;IACpG,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAE/D,wEAAwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB,yEAAyE;IACzE,cAAc,CAAC,EAAE,MAAM,CAAC;IAExB,gDAAgD;IAChD,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,eAAe,CAAC;IAEzD,oEAAoE;IACpE,SAAS,CAAC,EAAE,OAAO,GAAG,CAAC,CAAC,KAAK,EAAE,OAAO,KAAK,OAAO,CAAC,CAAC;IAEpD,6DAA6D;IAC7D,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,gEAAgE;AAChE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CACxB"}

package/dist/contracts/entities/agent-tool.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=agent-tool.js.map

package/dist/contracts/entities/agent-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-tool.js","sourceRoot":"","sources":["../../../src/contracts/entities/agent-tool.ts"],"names":[],"mappings":""}

package/dist/contracts/entities/chat-message.d.ts

@@ -0,0 +1,13 @@
+import type { MessageRole } from '../enums/index.js';
+import type { ContentPart } from './content-part.js';
+import type { ToolCall } from './tool-call.js';
+/** A single message in a conversation thread */
+export interface ChatMessage {
+    role: MessageRole;
+    content: string | ContentPart[];
+    toolCalls?: ToolCall[];
+    toolCallId?: string;
+    pinned?: boolean;
+    createdAt: number;
+}
+//# sourceMappingURL=chat-message.d.ts.map

package/dist/contracts/entities/chat-message.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-message.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/chat-message.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAE/C,gDAAgD;AAChD,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,WAAW,CAAC;IAClB,OAAO,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAChC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;CACnB"}

package/dist/contracts/entities/chat-message.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=chat-message.js.map

package/dist/contracts/entities/chat-message.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"chat-message.js","sourceRoot":"","sources":["../../../src/contracts/entities/chat-message.ts"],"names":[],"mappings":""}

package/dist/contracts/entities/content-part.d.ts

@@ -0,0 +1,16 @@
+/** Text content part */
+export interface TextContentPart {
+    type: 'text';
+    text: string;
+}
+/** Image URL content part */
+export interface ImageContentPart {
+    type: 'image_url';
+    image_url: {
+        url: string;
+        detail?: 'auto' | 'low' | 'high';
+    };
+}
+/** Multimodal content — text or image */
+export type ContentPart = TextContentPart | ImageContentPart;
+//# sourceMappingURL=content-part.d.ts.map

package/dist/contracts/entities/content-part.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-part.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/content-part.ts"],"names":[],"mappings":"AAAA,wBAAwB;AACxB,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED,6BAA6B;AAC7B,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,WAAW,CAAC;IAClB,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,MAAM,CAAC,EAAE,MAAM,GAAG,KAAK,GAAG,MAAM,CAAA;KAAE,CAAC;CAC9D;AAED,yCAAyC;AACzC,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,gBAAgB,CAAC"}

package/dist/contracts/entities/content-part.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=content-part.js.map

package/dist/contracts/entities/content-part.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-part.js","sourceRoot":"","sources":["../../../src/contracts/entities/content-part.ts"],"names":[],"mappings":""}

package/dist/contracts/entities/execution-context.d.ts

@@ -0,0 +1,9 @@
+/** Tracing context for a single chat/stream execution */
+export interface ExecutionContext {
+    traceId: string;
+    threadId: string;
+    startedAt: number;
+    model: string;
+    parentTraceId?: string;
+}
+//# sourceMappingURL=execution-context.d.ts.map

package/dist/contracts/entities/execution-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-context.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/execution-context.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB"}

package/dist/contracts/entities/execution-context.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=execution-context.js.map

package/dist/contracts/entities/execution-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"execution-context.js","sourceRoot":"","sources":["../../../src/contracts/entities/execution-context.ts"],"names":[],"mappings":""}

package/dist/contracts/entities/index.d.ts

@@ -0,0 +1,11 @@
+export type { ContentPart, TextContentPart, ImageContentPart } from './content-part.js';
+export type { ChatMessage } from './chat-message.js';
+export type { ToolCall, AgentToolResult } from './tool-call.js';
+export type { KnowledgeDocument, KnowledgeChunk, RetrievedKnowledge } from './knowledge.js';
+export type { ExecutionContext } from './execution-context.js';
+export type { TokenUsage } from './token-usage.js';
+export type { AgentTool, ToolValidationContext, ToolProgressCallback } from './agent-tool.js';
+export type { AgentSkill, SkillMatchContext, SkillPromptContext } from './agent-skill.js';
+export type { VectorStore, ConversationStore, } from './stores.js';
+export type { AgentEvent, AgentStartEvent, TextDeltaEvent, TextDoneEvent, ToolCallStartEvent, ToolCallDeltaEvent, ToolCallEndEvent, MemoryExtractedEvent, KnowledgeRetrievedEvent, SkillActivatedEvent, TurnStartEvent, TurnEndEvent, ErrorEvent, WarningEvent, ToolProgressEvent, CompactionEvent, RecoveryEvent, ModelFallbackEvent, AgentEndEvent, } from './agent-event.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/contracts/entities/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,WAAW,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AACxF,YAAY,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,YAAY,EAAE,QAAQ,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAChE,YAAY,EAAE,iBAAiB,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAC5F,YAAY,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC/D,YAAY,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,YAAY,EAAE,SAAS,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAC9F,YAAY,EAAE,UAAU,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC1F,YAAY,EACV,WAAW,EACX,iBAAiB,GAClB,MAAM,aAAa,CAAC;AACrB,YAAY,EACV,UAAU,EACV,eAAe,EACf,cAAc,EACd,aAAa,EACb,kBAAkB,EAClB,kBAAkB,EAClB,gBAAgB,EAChB,oBAAoB,EACpB,uBAAuB,EACvB,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,UAAU,EACV,YAAY,EACZ,iBAAiB,EACjB,eAAe,EACf,aAAa,EACb,kBAAkB,EAClB,aAAa,GACd,MAAM,kBAAkB,CAAC"}

package/dist/contracts/entities/index.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.js.map

package/dist/contracts/entities/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contracts/entities/index.ts"],"names":[],"mappings":""}

package/dist/contracts/entities/knowledge.d.ts

@@ -0,0 +1,21 @@
+/** A document to be ingested for RAG */
+export interface KnowledgeDocument {
+    content: string;
+    metadata?: Record<string, unknown>;
+}
+/** A chunk of a document with its embedding */
+export interface KnowledgeChunk {
+    id: string;
+    content: string;
+    embedding: Float32Array;
+    metadata?: Record<string, unknown>;
+    createdAt: number;
+}
+/** A knowledge chunk retrieved by similarity search */
+export interface RetrievedKnowledge {
+    id: string;
+    content: string;
+    score: number;
+    metadata?: Record<string, unknown>;
+}
+//# sourceMappingURL=knowledge.d.ts.map

package/dist/contracts/entities/knowledge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/knowledge.ts"],"names":[],"mappings":"AAAA,wCAAwC;AACxC,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC;AAED,+CAA+C;AAC/C,MAAM,WAAW,cAAc;IAC7B,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,YAAY,CAAC;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uDAAuD;AACvD,MAAM,WAAW,kBAAkB;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACpC"}

package/dist/contracts/entities/knowledge.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=knowledge.js.map

package/dist/contracts/entities/knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"knowledge.js","sourceRoot":"","sources":["../../../src/contracts/entities/knowledge.ts"],"names":[],"mappings":""}

package/dist/contracts/entities/stores.d.ts

@@ -0,0 +1,18 @@
+import type { ChatMessage } from './chat-message.js';
+import type { KnowledgeChunk, RetrievedKnowledge } from './knowledge.js';
+/** Pluggable interface for vector storage (knowledge/RAG) */
+export interface VectorStore {
+    upsert(chunk: KnowledgeChunk): void;
+    search(queryEmbedding: Float32Array, topK: number): RetrievedKnowledge[];
+    delete(id: string): void;
+    listAll(): KnowledgeChunk[];
+    deleteBySource(sourceId: string): void;
+}
+/** Pluggable interface for conversation history persistence */
+export interface ConversationStore {
+    appendMessage(message: ChatMessage, threadId: string): void;
+    listThread(threadId: string): ChatMessage[];
+    listPinned(threadId: string): ChatMessage[];
+    clearThread(threadId: string): void;
+}
+//# sourceMappingURL=stores.d.ts.map

package/dist/contracts/entities/stores.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/stores.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AACrD,OAAO,KAAK,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEzE,6DAA6D;AAC7D,MAAM,WAAW,WAAW;IAC1B,MAAM,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IACpC,MAAM,CAAC,cAAc,EAAE,YAAY,EAAE,IAAI,EAAE,MAAM,GAAG,kBAAkB,EAAE,CAAC;IACzE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,IAAI,cAAc,EAAE,CAAC;IAC5B,cAAc,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACxC;AAED,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,aAAa,CAAC,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5D,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAC5C,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,WAAW,EAAE,CAAC;IAC5C,WAAW,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;CACrC"}

package/dist/contracts/entities/stores.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=stores.js.map

package/dist/contracts/entities/stores.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stores.js","sourceRoot":"","sources":["../../../src/contracts/entities/stores.ts"],"names":[],"mappings":""}

package/dist/contracts/entities/token-usage.d.ts

@@ -0,0 +1,7 @@
+/** Token usage accumulator for cost tracking */
+export interface TokenUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+//# sourceMappingURL=token-usage.d.ts.map

package/dist/contracts/entities/token-usage.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-usage.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/token-usage.ts"],"names":[],"mappings":"AAAA,gDAAgD;AAChD,MAAM,WAAW,UAAU;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,WAAW,EAAE,MAAM,CAAC;CACrB"}

package/dist/contracts/entities/token-usage.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=token-usage.js.map

package/dist/contracts/entities/token-usage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"token-usage.js","sourceRoot":"","sources":["../../../src/contracts/entities/token-usage.ts"],"names":[],"mappings":""}

package/dist/contracts/entities/tool-call.d.ts

@@ -0,0 +1,16 @@
+/** A tool call requested by the LLM */
+export interface ToolCall {
+    id: string;
+    type: 'function';
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/** Result of a tool execution */
+export interface AgentToolResult {
+    content: string;
+    metadata?: Record<string, unknown>;
+    isError?: boolean;
+}
+//# sourceMappingURL=tool-call.d.ts.map

package/dist/contracts/entities/tool-call.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call.d.ts","sourceRoot":"","sources":["../../../src/contracts/entities/tool-call.ts"],"names":[],"mappings":"AAAA,uCAAuC;AACvC,MAAM,WAAW,QAAQ;IACvB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QACR,IAAI,EAAE,MAAM,CAAC;QACb,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED,iCAAiC;AACjC,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB"}

package/dist/contracts/entities/tool-call.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=tool-call.js.map

package/dist/contracts/entities/tool-call.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-call.js","sourceRoot":"","sources":["../../../src/contracts/entities/tool-call.ts"],"names":[],"mappings":""}

package/dist/contracts/enums/index.d.ts

@@ -0,0 +1,21 @@
+/** Message role in a conversation */
+export type MessageRole = 'user' | 'assistant' | 'system' | 'tool';
+/** File-based memory type (closed taxonomy) */
+export type { MemoryType } from '../../memory/memory-types.js';
+/** State of a ReactLoop execution */
+export type ReactLoopState = 'idle' | 'streaming' | 'executing_tools' | 'completed' | 'error' | 'cost_limited' | 'aborted';
+/** Terminal states of ReactLoop — no further transitions allowed */
+export declare const REACT_LOOP_TERMINAL_STATES: ReadonlySet<ReactLoopState>;
+/** Agent session lifecycle state */
+export type AgentSessionState = 'initializing' | 'ready' | 'executing' | 'cost_exhausted' | 'destroying' | 'destroyed';
+/** MCP connection lifecycle state */
+export type MCPConnectionState = 'disconnected' | 'connecting' | 'connected' | 'error' | 'reconnecting';
+/** What to do when a tool call errors */
+export type OnToolError = 'continue' | 'stop' | 'retry';
+/** What to do when cost limit is reached */
+export type OnLimitReached = 'stop' | 'warn';
+/** Log level for the built-in logger */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'silent';
+/** Response format for structured output */
+export type ResponseFormatType = 'text' | 'json_object' | 'json_schema';
+//# sourceMappingURL=index.d.ts.map

package/dist/contracts/enums/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/contracts/enums/index.ts"],"names":[],"mappings":"AAAA,qCAAqC;AACrC,MAAM,MAAM,WAAW,GAAG,MAAM,GAAG,WAAW,GAAG,QAAQ,GAAG,MAAM,CAAC;AAEnE,+CAA+C;AAC/C,YAAY,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D,qCAAqC;AACrC,MAAM,MAAM,cAAc,GACtB,MAAM,GACN,WAAW,GACX,iBAAiB,GACjB,WAAW,GACX,OAAO,GACP,cAAc,GACd,SAAS,CAAC;AAEd,oEAAoE;AACpE,eAAO,MAAM,0BAA0B,EAAE,WAAW,CAAC,cAAc,CAKjE,CAAC;AAEH,oCAAoC;AACpC,MAAM,MAAM,iBAAiB,GACzB,cAAc,GACd,OAAO,GACP,WAAW,GACX,gBAAgB,GAChB,YAAY,GACZ,WAAW,CAAC;AAEhB,qCAAqC;AACrC,MAAM,MAAM,kBAAkB,GAC1B,cAAc,GACd,YAAY,GACZ,WAAW,GACX,OAAO,GACP,cAAc,CAAC;AAEnB,yCAAyC;AACzC,MAAM,MAAM,WAAW,GAAG,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAExD,4CAA4C;AAC5C,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,CAAC;AAE7C,wCAAwC;AACxC,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEtE,4CAA4C;AAC5C,MAAM,MAAM,kBAAkB,GAAG,MAAM,GAAG,aAAa,GAAG,aAAa,CAAC"}

package/dist/contracts/enums/index.js

@@ -0,0 +1,8 @@
+/** Terminal states of ReactLoop — no further transitions allowed */
+export const REACT_LOOP_TERMINAL_STATES = new Set([
+    'completed',
+    'error',
+    'cost_limited',
+    'aborted',
+]);
+//# sourceMappingURL=index.js.map

package/dist/contracts/enums/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/contracts/enums/index.ts"],"names":[],"mappings":"AAgBA,oEAAoE;AACpE,MAAM,CAAC,MAAM,0BAA0B,GAAgC,IAAI,GAAG,CAAC;IAC7E,WAAW;IACX,OAAO;IACP,cAAc;IACd,SAAS;CACV,CAAC,CAAC"}

package/dist/contracts/index.d.ts

@@ -0,0 +1,3 @@
+export * from './entities/index.js';
+export * from './enums/index.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/contracts/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}

package/dist/contracts/index.js

@@ -0,0 +1,3 @@
+export * from './entities/index.js';
+export * from './enums/index.js';
+//# sourceMappingURL=index.js.map

package/dist/contracts/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/contracts/index.ts"],"names":[],"mappings":"AAAA,cAAc,qBAAqB,CAAC;AACpC,cAAc,kBAAkB,CAAC"}

package/dist/core/compaction/autocompact.d.ts

@@ -0,0 +1,18 @@
+import type { OpenRouterMessage } from '../../llm/message-types.js';
+import type { OpenRouterClient } from '../../llm/openrouter-client.js';
+export interface AutocompactOptions {
+    maxContextTokens: number;
+    compactionThreshold: number;
+    tailProtection: number;
+}
+export interface AutocompactResult {
+    messages: OpenRouterMessage[];
+    tokensFreed: number;
+}
+/**
+ * Summarizes conversation history via LLM when token usage exceeds threshold.
+ * Preserves: system messages (always), tail messages (recent context).
+ * Returns null if compaction not needed or fails.
+ */
+export declare function autocompact(messages: readonly OpenRouterMessage[], client: OpenRouterClient, options: AutocompactOptions): Promise<AutocompactResult | null>;
+//# sourceMappingURL=autocompact.d.ts.map

package/dist/core/compaction/autocompact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"autocompact.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/autocompact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AACpE,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gCAAgC,CAAC;AAGvE,MAAM,WAAW,kBAAkB;IACjC,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,WAAW,EAAE,MAAM,CAAC;CACrB;AASD;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,MAAM,EAAE,gBAAgB,EACxB,OAAO,EAAE,kBAAkB,GAC1B,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CA4DnC"}

package/dist/core/compaction/autocompact.js

@@ -0,0 +1,68 @@
+import { estimateTokens } from '../../utils/token-counter.js';
+function estimateMessagesTokens(messages) {
+    return messages.reduce((sum, m) => {
+        const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+        return sum + estimateTokens(content);
+    }, 0);
+}
+/**
+ * Summarizes conversation history via LLM when token usage exceeds threshold.
+ * Preserves: system messages (always), tail messages (recent context).
+ * Returns null if compaction not needed or fails.
+ */
+export async function autocompact(messages, client, options) {
+    const { maxContextTokens, compactionThreshold, tailProtection } = options;
+    const currentTokens = estimateMessagesTokens(messages);
+    const threshold = maxContextTokens * compactionThreshold;
+    if (currentTokens < threshold)
+        return null;
+    // Split messages into: system, pinned (boundary summaries), compactable, tail
+    const systemMessages = messages.filter(m => m.role === 'system');
+    const nonSystem = messages.filter(m => m.role !== 'system');
+    const pinned = nonSystem.filter(m => m._pinned === true);
+    const unpinned = nonSystem.filter(m => m._pinned !== true);
+    const tailCount = Math.min(tailProtection, unpinned.length);
+    const toCompact = unpinned.slice(0, unpinned.length - tailCount);
+    const tailMessages = unpinned.slice(-tailCount);
+    if (toCompact.length === 0)
+        return null;
+    // Build conversation text for summarization
+    const conversationText = toCompact.map(m => {
+        const content = typeof m.content === 'string' ? m.content : JSON.stringify(m.content);
+        return `${m.role}: ${content.slice(0, 2000)}`; // Limit per message for the summary prompt
+    }).join('\n');
+    try {
+        const response = await client.chat({
+            messages: [
+                {
+                    role: 'system',
+                    content: 'You are a conversation summarizer. Create a concise summary of the following conversation, preserving key facts, decisions, tool results, and context needed for continuation. Be factual and specific. Output only the summary.',
+                },
+                { role: 'user', content: conversationText },
+            ],
+            temperature: 0,
+            maxTokens: 1000,
+        });
+        const summaryMessage = {
+            role: 'user',
+            content: `[Conversation summary — earlier messages were compacted to save context]\n\n${response.content}`,
+            // Mark as compaction boundary — should survive subsequent compactions
+            _pinned: true,
+        };
+        const compactedMessages = [
+            ...systemMessages,
+            ...pinned,
+            summaryMessage,
+            ...tailMessages,
+        ];
+        const newTokens = estimateMessagesTokens(compactedMessages);
+        return {
+            messages: compactedMessages,
+            tokensFreed: currentTokens - newTokens,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=autocompact.js.map

package/dist/core/compaction/autocompact.js.map

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

package/dist/core/compaction/microcompact.d.ts

@@ -0,0 +1,20 @@
+import type { OpenRouterMessage } from '../../llm/message-types.js';
+export interface MicrocompactOptions {
+    maxToolResultChars: number;
+    /** Per-tool max chars override, keyed by tool name. Takes precedence over default. */
+    perToolMaxChars?: Map<string, number>;
+    /** Map from tool_call_id to tool name. Required when perToolMaxChars is used. */
+    toolCallIdToName?: Map<string, string>;
+}
+export interface MicrocompactResult {
+    messages: OpenRouterMessage[];
+    truncatedCount: number;
+}
+/**
+ * Truncates large tool result messages, preserving head and tail.
+ * Runs before autocompact — cheap, no LLM call.
+ *
+ * Supports per-tool max chars overrides via perToolMaxChars map.
+ */
+export declare function microcompact(messages: readonly OpenRouterMessage[], options: MicrocompactOptions): MicrocompactResult;
+//# sourceMappingURL=microcompact.d.ts.map

package/dist/core/compaction/microcompact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"microcompact.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/microcompact.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,sFAAsF;IACtF,eAAe,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACtC,iFAAiF;IACjF,gBAAgB,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACxC;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,cAAc,EAAE,MAAM,CAAC;CACxB;AAKD;;;;;GAKG;AACH,wBAAgB,YAAY,CAC1B,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,OAAO,EAAE,mBAAmB,GAC3B,kBAAkB,CAiCpB"}

package/dist/core/compaction/microcompact.js

@@ -0,0 +1,38 @@
+const DEFAULT_HEAD_RATIO = 0.7;
+const DEFAULT_TAIL_RATIO = 0.2;
+/**
+ * Truncates large tool result messages, preserving head and tail.
+ * Runs before autocompact — cheap, no LLM call.
+ *
+ * Supports per-tool max chars overrides via perToolMaxChars map.
+ */
+export function microcompact(messages, options) {
+    const { maxToolResultChars, perToolMaxChars, toolCallIdToName } = options;
+    let truncatedCount = 0;
+    const result = messages.map(msg => {
+        if (msg.role !== 'tool' || typeof msg.content !== 'string')
+            return msg;
+        // Determine per-tool limit
+        let limit = maxToolResultChars;
+        if (perToolMaxChars && toolCallIdToName && msg.tool_call_id) {
+            const toolName = toolCallIdToName.get(msg.tool_call_id);
+            if (toolName && perToolMaxChars.has(toolName)) {
+                limit = perToolMaxChars.get(toolName);
+            }
+        }
+        if (msg.content.length <= limit)
+            return msg;
+        truncatedCount++;
+        const headSize = Math.floor(limit * DEFAULT_HEAD_RATIO);
+        const tailSize = Math.floor(limit * DEFAULT_TAIL_RATIO);
+        const head = msg.content.slice(0, headSize);
+        const tail = msg.content.slice(-tailSize);
+        const omitted = msg.content.length - headSize - tailSize;
+        return {
+            ...msg,
+            content: `${head}\n\n[truncated ${omitted} characters]\n\n${tail}`,
+        };
+    });
+    return { messages: result, truncatedCount };
+}
+//# sourceMappingURL=microcompact.js.map

package/dist/core/compaction/microcompact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"microcompact.js","sourceRoot":"","sources":["../../../src/core/compaction/microcompact.ts"],"names":[],"mappings":"AAeA,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAC/B,MAAM,kBAAkB,GAAG,GAAG,CAAC;AAE/B;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAC1B,QAAsC,EACtC,OAA4B;IAE5B,MAAM,EAAE,kBAAkB,EAAE,eAAe,EAAE,gBAAgB,EAAE,GAAG,OAAO,CAAC;IAC1E,IAAI,cAAc,GAAG,CAAC,CAAC;IAEvB,MAAM,MAAM,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE;QAChC,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ;YAAE,OAAO,GAAG,CAAC;QAEvE,2BAA2B;QAC3B,IAAI,KAAK,GAAG,kBAAkB,CAAC;QAC/B,IAAI,eAAe,IAAI,gBAAgB,IAAI,GAAG,CAAC,YAAY,EAAE,CAAC;YAC5D,MAAM,QAAQ,GAAG,gBAAgB,CAAC,GAAG,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC;YACxD,IAAI,QAAQ,IAAI,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAC,EAAE,CAAC;gBAC9C,KAAK,GAAG,eAAe,CAAC,GAAG,CAAC,QAAQ,CAAE,CAAC;YACzC,CAAC;QACH,CAAC;QAED,IAAI,GAAG,CAAC,OAAO,CAAC,MAAM,IAAI,KAAK;YAAE,OAAO,GAAG,CAAC;QAE5C,cAAc,EAAE,CAAC;QAEjB,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,kBAAkB,CAAC,CAAC;QACxD,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,kBAAkB,CAAC,CAAC;QACxD,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,EAAE,QAAQ,CAAC,CAAC;QAC5C,MAAM,IAAI,GAAG,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,QAAQ,CAAC,CAAC;QAC1C,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAC;QAEzD,OAAO;YACL,GAAG,GAAG;YACN,OAAO,EAAE,GAAG,IAAI,kBAAkB,OAAO,mBAAmB,IAAI,EAAE;SACnE,CAAC;IACJ,CAAC,CAAC,CAAC;IAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,CAAC;AAC9C,CAAC"}

package/dist/core/compaction/snip-compact.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Snip compact — removes low-value early messages before autocompact.
+ *
+ * Targets orphaned tool results (results not referenced by later messages)
+ * in the compactable region (outside tail protection).
+ *
+ * Runs between tool-result-budget and autocompact in the compaction pipeline.
+ */
+import type { OpenRouterMessage } from '../../llm/message-types.js';
+export interface SnipCompactOptions {
+    tailProtection: number;
+}
+export interface SnipCompactResult {
+    messages: OpenRouterMessage[];
+    snippedCount: number;
+}
+/**
+ * Remove orphaned tool results from early messages.
+ * Preserves: system messages, pinned messages, tail messages.
+ */
+export declare function snipCompact(messages: readonly OpenRouterMessage[], options: SnipCompactOptions): SnipCompactResult;
+//# sourceMappingURL=snip-compact.d.ts.map

package/dist/core/compaction/snip-compact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snip-compact.d.ts","sourceRoot":"","sources":["../../../src/core/compaction/snip-compact.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,4BAA4B,CAAC;AAEpE,MAAM,WAAW,kBAAkB;IACjC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,wBAAgB,WAAW,CACzB,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,OAAO,EAAE,kBAAkB,GAC1B,iBAAiB,CAoDnB"}