rhachet-roles-bhrain 0.3.0 → 0.5.2

package/dist/domain.objects/BrainArch1/BrainArch1Atom.d.ts

@@ -0,0 +1,40 @@
+import type { BrainArch1Context } from './BrainArch1Context';
+import type { BrainArch1MemoryTokenUsage } from './BrainArch1MemoryTokenUsage';
+import type { BrainArch1SessionMessage } from './BrainArch1SessionMessage';
+import type { BrainArch1ToolDefinition } from './BrainArch1ToolDefinition';
+/**
+ * .what = plugin interface for llm atom generation
+ * .why = enables swappable atoms (claude, qwen, openai) with same brain structure
+ *
+ * .note = this is a plugin interface - implementations are instantiated with their
+ *         provider-specific configuration and expose a unified `.generate()` method
+ *
+ * .todo = support a meta-atom plugin that chooses which model to use based on
+ *         context, task complexity, cost optimization, etc. Today we only support
+ *         using one atom for the entire session.
+ */
+export interface BrainArch1Atom {
+    /**
+     * the platform this atom uses (e.g., 'anthropic', 'openai', 'qwen')
+     */
+    platform: string;
+    /**
+     * the model this atom uses (e.g., 'claude-3-5-sonnet-latest', 'gpt-4o')
+     */
+    model: string;
+    /**
+     * human-readable description of this atom
+     */
+    description: string;
+    /**
+     * generates an llm response using this atom's platform and model
+     */
+    generate: (input: {
+        messages: BrainArch1SessionMessage[];
+        tools: BrainArch1ToolDefinition[];
+        maxTokens?: number;
+    }, context: BrainArch1Context) => Promise<{
+        message: BrainArch1SessionMessage;
+        tokenUsage: BrainArch1MemoryTokenUsage;
+    }>;
+}

package/dist/domain.objects/BrainArch1/BrainArch1Atom.js

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

package/dist/domain.objects/BrainArch1/BrainArch1Atom.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1Atom.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1Atom.ts"],"names":[],"mappings":""}

package/dist/domain.objects/BrainArch1/BrainArch1Context.d.ts

@@ -0,0 +1,30 @@
+import type { ContextLogTrail } from 'as-procedure';
+/**
+ * .what = runtime context containing provider-keyed credentials for llm apis
+ * .why = enables dependency injection of credentials per provider
+ *
+ * .note = this is not a DomainLiteral because it contains functions (log)
+ *         and is a runtime dependency injection container, not a serializable value
+ */
+export interface BrainArch1Context extends ContextLogTrail {
+    /**
+     * provider-keyed credentials for llm api access
+     */
+    creds: {
+        anthropic: {
+            apiKey: string;
+            url: string | null;
+        };
+        openai: {
+            apiKey: string;
+            url: string | null;
+        };
+        qwen: {
+            apiKey: string;
+            url: string | null;
+        };
+        tavily: {
+            apiKey: string;
+        };
+    };
+}

package/dist/domain.objects/BrainArch1/BrainArch1Context.js

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

package/dist/domain.objects/BrainArch1/BrainArch1Context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1Context.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1Context.ts"],"names":[],"mappings":""}

package/dist/domain.objects/BrainArch1/BrainArch1LoopIteration.d.ts

@@ -0,0 +1,34 @@
+import { DomainLiteral } from 'domain-objects';
+import type { BrainArch1MemoryTokenUsage } from './BrainArch1MemoryTokenUsage';
+/**
+ * .what = captures the state and metrics of a single loop iteration
+ * .why = enables tracking and observability of each iteration cycle
+ */
+export interface BrainArch1LoopIteration {
+    /**
+     * iteration number (0-indexed)
+     */
+    iterationNumber: number;
+    /**
+     * whether this iteration generated any tool calls
+     */
+    hadToolCalls: boolean;
+    /**
+     * number of tool calls generated in this iteration
+     */
+    toolCallCount: number;
+    /**
+     * token usage for the llm call in this iteration
+     */
+    tokenUsage: BrainArch1MemoryTokenUsage;
+    /**
+     * timestamp when this iteration started
+     */
+    startedAt: string;
+    /**
+     * timestamp when this iteration completed
+     */
+    completedAt: string;
+}
+export declare class BrainArch1LoopIteration extends DomainLiteral<BrainArch1LoopIteration> implements BrainArch1LoopIteration {
+}

package/dist/domain.objects/BrainArch1/BrainArch1LoopIteration.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainArch1LoopIteration = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainArch1LoopIteration extends domain_objects_1.DomainLiteral {
+}
+exports.BrainArch1LoopIteration = BrainArch1LoopIteration;
+//# sourceMappingURL=BrainArch1LoopIteration.js.map

package/dist/domain.objects/BrainArch1/BrainArch1LoopIteration.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1LoopIteration.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1LoopIteration.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AAwC/C,MAAa,uBACX,SAAQ,8BAAsC;CACT;AAFvC,0DAEuC"}

package/dist/domain.objects/BrainArch1/BrainArch1LoopIterationCompletedEvent.d.ts

@@ -0,0 +1,23 @@
+import { DomainEvent } from 'domain-objects';
+import type { BrainArch1LoopIteration } from './BrainArch1LoopIteration';
+/**
+ * .what = event emitted when a loop iteration completes
+ * .why = enables observability and logging of iteration progress
+ */
+export interface BrainArch1LoopIterationCompletedEvent {
+    /**
+     * session uuid this event belongs to
+     */
+    sessionUuid: string;
+    /**
+     * timestamp when this event occurred
+     */
+    occurredAt: string;
+    /**
+     * the completed iteration data
+     */
+    iteration: BrainArch1LoopIteration;
+}
+export declare class BrainArch1LoopIterationCompletedEvent extends DomainEvent<BrainArch1LoopIterationCompletedEvent> implements BrainArch1LoopIterationCompletedEvent {
+    static unique: readonly ["sessionUuid", "iteration.iterationNumber"];
+}

package/dist/domain.objects/BrainArch1/BrainArch1LoopIterationCompletedEvent.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainArch1LoopIterationCompletedEvent = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainArch1LoopIterationCompletedEvent extends domain_objects_1.DomainEvent {
+}
+exports.BrainArch1LoopIterationCompletedEvent = BrainArch1LoopIterationCompletedEvent;
+BrainArch1LoopIterationCompletedEvent.unique = ['sessionUuid', 'iteration.iterationNumber'];
+//# sourceMappingURL=BrainArch1LoopIterationCompletedEvent.js.map

package/dist/domain.objects/BrainArch1/BrainArch1LoopIterationCompletedEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1LoopIterationCompletedEvent.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1LoopIterationCompletedEvent.ts"],"names":[],"mappings":";;;AAAA,mDAA6C;AAyB7C,MAAa,qCACX,SAAQ,4BAAkD;;AAD5D,sFAKC;AADe,4CAAM,GAAG,CAAC,aAAa,EAAE,2BAA2B,CAAU,CAAC"}

package/dist/domain.objects/BrainArch1/BrainArch1LoopResult.d.ts

@@ -0,0 +1,49 @@
+import { DomainLiteral } from 'domain-objects';
+import type { BrainArch1LoopIteration } from './BrainArch1LoopIteration';
+import type { BrainArch1MemoryTokenUsage } from './BrainArch1MemoryTokenUsage';
+import type { BrainArch1SessionMessage } from './BrainArch1SessionMessage';
+/**
+ * .what = reason why the loop terminated
+ * .why = enables the caller to understand loop completion state
+ */
+export type BrainArch1LoopTerminationReason = 'NATURAL_COMPLETION' | 'MAX_ITERATIONS' | 'ERROR';
+/**
+ * .what = captures the final result of a completed agentic loop
+ * .why = enables the caller to receive the brain's output and metrics
+ */
+export interface BrainArch1LoopResult {
+    /**
+     * why the loop terminated
+     */
+    terminationReason: BrainArch1LoopTerminationReason;
+    /**
+     * final text response from the brain (may be null if error)
+     */
+    finalResponse: string | null;
+    /**
+     * final assistant message (includes tool calls if any)
+     */
+    finalMessage: BrainArch1SessionMessage | null;
+    /**
+     * all messages in the conversation context
+     */
+    messages: BrainArch1SessionMessage[];
+    /**
+     * history of all loop iterations
+     */
+    iterations: BrainArch1LoopIteration[];
+    /**
+     * total number of iterations executed
+     */
+    iterationCount: number;
+    /**
+     * cumulative token usage across all iterations
+     */
+    totalTokenUsage: BrainArch1MemoryTokenUsage;
+    /**
+     * error message if terminated due to error
+     */
+    error: string | null;
+}
+export declare class BrainArch1LoopResult extends DomainLiteral<BrainArch1LoopResult> implements BrainArch1LoopResult {
+}

package/dist/domain.objects/BrainArch1/BrainArch1LoopResult.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainArch1LoopResult = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainArch1LoopResult extends domain_objects_1.DomainLiteral {
+}
+exports.BrainArch1LoopResult = BrainArch1LoopResult;
+//# sourceMappingURL=BrainArch1LoopResult.js.map

package/dist/domain.objects/BrainArch1/BrainArch1LoopResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1LoopResult.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1LoopResult.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AA6D/C,MAAa,oBACX,SAAQ,8BAAmC;CACT;AAFpC,oDAEoC"}

package/dist/domain.objects/BrainArch1/BrainArch1MemoryCompactedEvent.d.ts

@@ -0,0 +1,31 @@
+import { DomainEvent } from 'domain-objects';
+import type { BrainArch1MemoryCompactionResult } from './BrainArch1MemoryCompactionResult';
+/**
+ * .what = event emitted when memory compaction completes
+ * .why = enables observability and logging of memory optimization
+ */
+export interface BrainArch1MemoryCompactedEvent {
+    /**
+     * session uuid this event belongs to
+     */
+    sessionUuid: string;
+    /**
+     * iteration number after which compaction occurred
+     */
+    afterIterationNumber: number;
+    /**
+     * timestamp when this event occurred
+     */
+    occurredAt: string;
+    /**
+     * the compaction result
+     */
+    result: BrainArch1MemoryCompactionResult;
+    /**
+     * name of the memory manager that performed compaction
+     */
+    managerName: string;
+}
+export declare class BrainArch1MemoryCompactedEvent extends DomainEvent<BrainArch1MemoryCompactedEvent> implements BrainArch1MemoryCompactedEvent {
+    static unique: readonly ["sessionUuid", "afterIterationNumber"];
+}

package/dist/domain.objects/BrainArch1/BrainArch1MemoryCompactedEvent.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainArch1MemoryCompactedEvent = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainArch1MemoryCompactedEvent extends domain_objects_1.DomainEvent {
+}
+exports.BrainArch1MemoryCompactedEvent = BrainArch1MemoryCompactedEvent;
+BrainArch1MemoryCompactedEvent.unique = ['sessionUuid', 'afterIterationNumber'];
+//# sourceMappingURL=BrainArch1MemoryCompactedEvent.js.map

package/dist/domain.objects/BrainArch1/BrainArch1MemoryCompactedEvent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1MemoryCompactedEvent.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1MemoryCompactedEvent.ts"],"names":[],"mappings":";;;AAAA,mDAA6C;AAmC7C,MAAa,8BACX,SAAQ,4BAA2C;;AADrD,wEAKC;AADe,qCAAM,GAAG,CAAC,aAAa,EAAE,sBAAsB,CAAU,CAAC"}

package/dist/domain.objects/BrainArch1/BrainArch1MemoryCompactionResult.d.ts

@@ -0,0 +1,27 @@
+import { DomainLiteral } from 'domain-objects';
+import type { BrainArch1MemoryTokenUsage } from './BrainArch1MemoryTokenUsage';
+import type { BrainArch1SessionMessage } from './BrainArch1SessionMessage';
+/**
+ * .what = captures the result of a memory compaction operation
+ * .why = enables the loop to apply compacted context and track token reduction
+ */
+export interface BrainArch1MemoryCompactionResult {
+    /**
+     * the compacted messages to replace current context
+     */
+    messages: BrainArch1SessionMessage[];
+    /**
+     * token usage before compaction
+     */
+    tokensBefore: number;
+    /**
+     * token usage after compaction
+     */
+    tokensAfter: number;
+    /**
+     * tokens used for the compaction operation itself (e.g., summarization llm call)
+     */
+    compactionTokenUsage: BrainArch1MemoryTokenUsage | null;
+}
+export declare class BrainArch1MemoryCompactionResult extends DomainLiteral<BrainArch1MemoryCompactionResult> implements BrainArch1MemoryCompactionResult {
+}

package/dist/domain.objects/BrainArch1/BrainArch1MemoryCompactionResult.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainArch1MemoryCompactionResult = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainArch1MemoryCompactionResult extends domain_objects_1.DomainLiteral {
+}
+exports.BrainArch1MemoryCompactionResult = BrainArch1MemoryCompactionResult;
+//# sourceMappingURL=BrainArch1MemoryCompactionResult.js.map

package/dist/domain.objects/BrainArch1/BrainArch1MemoryCompactionResult.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1MemoryCompactionResult.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1MemoryCompactionResult.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AA+B/C,MAAa,gCACX,SAAQ,8BAA+C;CACT;AAFhD,4EAEgD"}

package/dist/domain.objects/BrainArch1/BrainArch1MemoryManager.d.ts

@@ -0,0 +1,45 @@
+import type { BrainArch1Context } from './BrainArch1Context';
+import type { BrainArch1MemoryCompactionResult } from './BrainArch1MemoryCompactionResult';
+import type { BrainArch1SessionMessage } from './BrainArch1SessionMessage';
+/**
+ * .what = function signature for checking if compaction should occur
+ * .why = enables memory managers to decide when to compact based on token usage
+ */
+export type BrainArch1MemoryShouldCompactFn = (input: {
+    messages: BrainArch1SessionMessage[];
+    currentTokens: number;
+    maxTokens: number;
+}, context: BrainArch1Context) => Promise<boolean>;
+/**
+ * .what = function signature for performing memory compaction
+ * .why = enables pluggable compaction strategies (summarize, truncate, etc.)
+ */
+export type BrainArch1MemoryCompactFn = (input: {
+    messages: BrainArch1SessionMessage[];
+    currentTokens: number;
+    targetTokens: number;
+}, context: BrainArch1Context) => Promise<BrainArch1MemoryCompactionResult>;
+/**
+ * .what = interface for a memory manager plugin
+ * .why = enables pluggable memory strategies to control context window optimization
+ *
+ * .note = this is an interface, not a DomainLiteral, because it contains functions
+ */
+export interface BrainArch1MemoryManager {
+    /**
+     * name of this memory manager
+     */
+    name: string;
+    /**
+     * description of what this manager does
+     */
+    description: string;
+    /**
+     * check whether compaction should occur
+     */
+    shouldCompact: BrainArch1MemoryShouldCompactFn;
+    /**
+     * perform memory compaction
+     */
+    compact: BrainArch1MemoryCompactFn;
+}

package/dist/domain.objects/BrainArch1/BrainArch1MemoryManager.js

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

package/dist/domain.objects/BrainArch1/BrainArch1MemoryManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1MemoryManager.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1MemoryManager.ts"],"names":[],"mappings":""}

package/dist/domain.objects/BrainArch1/BrainArch1MemoryTokenUsage.d.ts

@@ -0,0 +1,29 @@
+import { DomainLiteral } from 'domain-objects';
+/**
+ * .what = tracks token consumption for a single llm api call
+ * .why = enables monitoring context usage and triggering memory compaction
+ */
+export interface BrainArch1MemoryTokenUsage {
+    /**
+     * tokens consumed by the input/prompt
+     */
+    inputTokens: number;
+    /**
+     * tokens generated in the output/response
+     */
+    outputTokens: number;
+    /**
+     * total tokens used (input + output)
+     */
+    totalTokens: number;
+    /**
+     * tokens read from cache, if applicable
+     */
+    cacheReadTokens: number | null;
+    /**
+     * tokens written to cache, if applicable
+     */
+    cacheWriteTokens: number | null;
+}
+export declare class BrainArch1MemoryTokenUsage extends DomainLiteral<BrainArch1MemoryTokenUsage> implements BrainArch1MemoryTokenUsage {
+}

package/dist/domain.objects/BrainArch1/BrainArch1MemoryTokenUsage.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainArch1MemoryTokenUsage = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainArch1MemoryTokenUsage extends domain_objects_1.DomainLiteral {
+}
+exports.BrainArch1MemoryTokenUsage = BrainArch1MemoryTokenUsage;
+//# sourceMappingURL=BrainArch1MemoryTokenUsage.js.map

package/dist/domain.objects/BrainArch1/BrainArch1MemoryTokenUsage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1MemoryTokenUsage.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1MemoryTokenUsage.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AAiC/C,MAAa,0BACX,SAAQ,8BAAyC;CACT;AAF1C,gEAE0C"}

package/dist/domain.objects/BrainArch1/BrainArch1PermissionDecision.d.ts

@@ -0,0 +1,22 @@
+import { DomainLiteral } from 'domain-objects';
+/**
+ * .what = possible verdicts from a permission guard
+ * .why = enables explicit control over tool execution authorization
+ */
+export type BrainArch1PermissionVerdict = 'allow' | 'deny' | 'prompt';
+/**
+ * .what = captures the decision from a permission guard for a tool call
+ * .why = enables the brain to understand and react to permission decisions
+ */
+export interface BrainArch1PermissionDecision {
+    /**
+     * the verdict: allow (proceed), deny (reject), or prompt (ask user)
+     */
+    verdict: BrainArch1PermissionVerdict;
+    /**
+     * reason for the decision (useful for deny/prompt cases)
+     */
+    reason: string | null;
+}
+export declare class BrainArch1PermissionDecision extends DomainLiteral<BrainArch1PermissionDecision> implements BrainArch1PermissionDecision {
+}

package/dist/domain.objects/BrainArch1/BrainArch1PermissionDecision.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainArch1PermissionDecision = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainArch1PermissionDecision extends domain_objects_1.DomainLiteral {
+}
+exports.BrainArch1PermissionDecision = BrainArch1PermissionDecision;
+//# sourceMappingURL=BrainArch1PermissionDecision.js.map

package/dist/domain.objects/BrainArch1/BrainArch1PermissionDecision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1PermissionDecision.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1PermissionDecision.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AAwB/C,MAAa,4BACX,SAAQ,8BAA2C;CACT;AAF5C,oEAE4C"}

package/dist/domain.objects/BrainArch1/BrainArch1PermissionGuard.d.ts

@@ -0,0 +1,30 @@
+import type { BrainArch1Context } from './BrainArch1Context';
+import type { BrainArch1PermissionDecision } from './BrainArch1PermissionDecision';
+import type { BrainArch1ToolCall } from './BrainArch1ToolCall';
+/**
+ * .what = function signature for checking permission on a tool call
+ * .why = enables pluggable permission policies (allowAll, promptForWrites, denyDangerous)
+ */
+export type BrainArch1PermissionCheckFn = (input: {
+    call: BrainArch1ToolCall;
+}, context: BrainArch1Context) => Promise<BrainArch1PermissionDecision>;
+/**
+ * .what = interface for a permission guard plugin
+ * .why = enables pluggable permission strategies to control tool execution
+ *
+ * .note = this is an interface, not a DomainLiteral, because it contains functions
+ */
+export interface BrainArch1PermissionGuard {
+    /**
+     * name of this permission guard
+     */
+    name: string;
+    /**
+     * description of what this guard does
+     */
+    description: string;
+    /**
+     * check whether a tool call is permitted
+     */
+    check: BrainArch1PermissionCheckFn;
+}

package/dist/domain.objects/BrainArch1/BrainArch1PermissionGuard.js

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

package/dist/domain.objects/BrainArch1/BrainArch1PermissionGuard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1PermissionGuard.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1PermissionGuard.ts"],"names":[],"mappings":""}

package/dist/domain.objects/BrainArch1/BrainArch1Session.d.ts

@@ -0,0 +1,47 @@
+import { DomainEntity } from 'domain-objects';
+import type { BrainArch1MemoryTokenUsage } from './BrainArch1MemoryTokenUsage';
+import type { BrainArch1SessionMessage } from './BrainArch1SessionMessage';
+/**
+ * .what = status of a brain session
+ * .why = enables tracking session lifecycle
+ */
+export type BrainArch1SessionStatus = 'ACTIVE' | 'COMPLETED' | 'TERMINATED';
+/**
+ * .what = captures the state of an ongoing brain session
+ * .why = enables tracking and managing the execution lifecycle
+ */
+export interface BrainArch1Session {
+    /**
+     * unique identifier for this session
+     */
+    uuid?: string;
+    /**
+     * current status of the session
+     */
+    status: BrainArch1SessionStatus;
+    /**
+     * number of loop iterations executed so far
+     */
+    iterationCount: number;
+    /**
+     * cumulative token usage across all iterations
+     */
+    totalTokenUsage: BrainArch1MemoryTokenUsage;
+    /**
+     * current conversation context
+     */
+    messages: BrainArch1SessionMessage[];
+    /**
+     * timestamp when session started
+     */
+    startedAt: string;
+    /**
+     * timestamp when session completed (null if still active)
+     */
+    completedAt: string | null;
+}
+export declare class BrainArch1Session extends DomainEntity<BrainArch1Session> implements BrainArch1Session {
+    static primary: readonly ["uuid"];
+    static unique: readonly ["uuid"];
+    static updatable: readonly ["status", "iterationCount", "totalTokenUsage", "messages", "completedAt"];
+}

package/dist/domain.objects/BrainArch1/BrainArch1Session.js

@@ -0,0 +1,17 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainArch1Session = void 0;
+const domain_objects_1 = require("domain-objects");
+class BrainArch1Session extends domain_objects_1.DomainEntity {
+}
+exports.BrainArch1Session = BrainArch1Session;
+BrainArch1Session.primary = ['uuid'];
+BrainArch1Session.unique = ['uuid'];
+BrainArch1Session.updatable = [
+    'status',
+    'iterationCount',
+    'totalTokenUsage',
+    'messages',
+    'completedAt',
+];
+//# sourceMappingURL=BrainArch1Session.js.map

package/dist/domain.objects/BrainArch1/BrainArch1Session.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1Session.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1Session.ts"],"names":[],"mappings":";;;AAAA,mDAA8C;AAoD9C,MAAa,iBACX,SAAQ,6BAA+B;;AADzC,8CAaC;AATe,yBAAO,GAAG,CAAC,MAAM,CAAU,CAAC;AAC5B,wBAAM,GAAG,CAAC,MAAM,CAAU,CAAC;AAC3B,2BAAS,GAAG;IACxB,QAAQ;IACR,gBAAgB;IAChB,iBAAiB;IACjB,UAAU;IACV,aAAa;CACL,CAAC"}

package/dist/domain.objects/BrainArch1/BrainArch1SessionMessage.d.ts

@@ -0,0 +1,34 @@
+import { DomainLiteral } from 'domain-objects';
+import { BrainArch1ToolCall } from './BrainArch1ToolCall';
+/**
+ * .what = role of the message sender in the conversation
+ * .why = llm apis require role to understand context
+ */
+export type BrainArch1SessionMessageRole = 'system' | 'user' | 'assistant' | 'tool';
+/**
+ * .what = captures a single message in the brain's conversation context
+ * .why = enables building and managing the conversation history for llm calls
+ */
+export interface BrainArch1SessionMessage {
+    /**
+     * role of the message sender
+     */
+    role: BrainArch1SessionMessageRole;
+    /**
+     * text content of the message (null if tool-only response)
+     */
+    content: string | null;
+    /**
+     * tool calls generated by assistant (null if no tools called)
+     */
+    toolCalls: BrainArch1ToolCall[] | null;
+    /**
+     * tool result callId this message responds to (only for role=tool)
+     */
+    toolCallId: string | null;
+}
+export declare class BrainArch1SessionMessage extends DomainLiteral<BrainArch1SessionMessage> implements BrainArch1SessionMessage {
+    static nested: {
+        toolCalls: typeof BrainArch1ToolCall;
+    };
+}

package/dist/domain.objects/BrainArch1/BrainArch1SessionMessage.js

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.BrainArch1SessionMessage = void 0;
+const domain_objects_1 = require("domain-objects");
+const BrainArch1ToolCall_1 = require("./BrainArch1ToolCall");
+class BrainArch1SessionMessage extends domain_objects_1.DomainLiteral {
+}
+exports.BrainArch1SessionMessage = BrainArch1SessionMessage;
+BrainArch1SessionMessage.nested = {
+    toolCalls: BrainArch1ToolCall_1.BrainArch1ToolCall,
+};
+//# sourceMappingURL=BrainArch1SessionMessage.js.map

package/dist/domain.objects/BrainArch1/BrainArch1SessionMessage.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"BrainArch1SessionMessage.js","sourceRoot":"","sources":["../../../src/domain.objects/BrainArch1/BrainArch1SessionMessage.ts"],"names":[],"mappings":";;;AAAA,mDAA+C;AAE/C,6DAA0D;AAsC1D,MAAa,wBACX,SAAQ,8BAAuC;;AADjD,4DAOC;AAHe,+BAAM,GAAG;IACrB,SAAS,EAAE,uCAAkB;CAC9B,CAAC"}

package/dist/domain.objects/BrainArch1/BrainArch1ToolCall.d.ts

@@ -0,0 +1,21 @@
+import { DomainLiteral } from 'domain-objects';
+/**
+ * .what = captures a single tool invocation request from the llm
+ * .why = enables routing and execution of tool calls generated by the brain
+ */
+export interface BrainArch1ToolCall {
+    /**
+     * unique identifier for this tool call (used to match with result)
+     */
+    id: string;
+    /**
+     * name of the tool to invoke
+     */
+    name: string;
+    /**
+     * input arguments for the tool (parsed json object)
+     */
+    input: Record<string, unknown>;
+}
+export declare class BrainArch1ToolCall extends DomainLiteral<BrainArch1ToolCall> implements BrainArch1ToolCall {
+}