@ap3x/agent-core 0.1.0

package/dist/conversation.d.ts

@@ -0,0 +1,215 @@
+/**
+ * `Conversation` — the shared memory substrate for agents and swarms.
+ *
+ * An append-only, ordered transcript of `{role, content, ...}` messages with a
+ * free-form `role` (System / User / agent-name / "Tool Executor" / …). It is
+ * the shared memory every swarm orchestrator reads and writes, and the source
+ * the {@link import("./output-formatter").historyOutputFormatter} renders from.
+ *
+ * Beyond add/read/format, it provides:
+ * - JSON/YAML persistence (save/load/export/import),
+ * - token-budget management (dynamic auto-chunking + tokenizer truncation with
+ *   a binary-search character cutoff),
+ * - MEMORY.md durable persistence (init/preload/append/archive/compact), keyed
+ *   on the conversation **name** for cross-restart stability.
+ *
+ * Two invariants worth calling out: the id is generated **per instance** (never once at import
+ * time), and the `addMultiple` write order is deterministic — no shared-list race.
+ */
+/** Estimate the number of tokens in a piece of text. */
+export type TokenCounter = (text: string, model?: string) => number;
+/** Provider-agnostic token estimate: ~4 characters per token. */
+export declare function estimateTokens(text: string): number;
+/** A single transcript entry. `role` is free-form; `content` is anything. */
+export interface ConversationMessage {
+    role: string;
+    content: unknown;
+    timestamp?: string;
+    message_id?: string;
+    category?: string;
+    token_count?: number;
+    [key: string]: unknown;
+}
+/** A `{role, content}` provider-format message. */
+export interface RoleContentMessage {
+    role: string;
+    content: unknown;
+}
+/** Generate a unique, per-call conversation id. */
+export declare function generateConversationId(): string;
+/** Resolve (and create) the default directory for stored conversations. */
+export declare function getConversationDir(): string;
+/** Constructor options for {@link Conversation}. */
+export interface ConversationOptions {
+    id?: string;
+    name?: string;
+    systemPrompt?: string;
+    timeEnabled?: boolean;
+    autosave?: boolean;
+    saveFilepath?: string;
+    loadFilepath?: string;
+    contextLength?: number;
+    rules?: string;
+    customRulesPrompt?: string;
+    user?: string;
+    saveAsYamlOn?: boolean;
+    saveAsJsonBool?: boolean;
+    tokenCount?: boolean;
+    messageIdOn?: boolean;
+    tokenizerModelName?: string;
+    conversationsDir?: string;
+    exportMethod?: "json" | "yaml";
+    dynamicContextWindow?: boolean;
+    cacheEnabled?: boolean;
+    outputMetadata?: boolean;
+    memoryMdPath?: string;
+    /** Pluggable token counter (defaults to a chars/4 heuristic). */
+    countTokens?: TokenCounter;
+}
+export declare class Conversation {
+    readonly id: string;
+    name: string;
+    systemPrompt?: string;
+    timeEnabled: boolean;
+    autosave: boolean;
+    saveFilepath?: string;
+    loadFilepath?: string;
+    contextLength: number;
+    rules?: string;
+    customRulesPrompt?: string;
+    user: string;
+    saveAsYamlOn: boolean;
+    saveAsJsonBool: boolean;
+    tokenCount: boolean;
+    messageIdOn: boolean;
+    tokenizerModelName: string;
+    conversationsDir?: string;
+    exportMethod: "json" | "yaml";
+    dynamicContextWindow: boolean;
+    caching: boolean;
+    outputMetadata: boolean;
+    memoryMdPath?: string;
+    conversationHistory: ConversationMessage[];
+    private readonly countTokens;
+    private strCache;
+    private cacheHits;
+    private cacheMisses;
+    private lastCachedTokens;
+    private suppressMemoryMd;
+    constructor(options?: ConversationOptions);
+    private initializeNewConversation;
+    /** Append a message to the in-memory transcript (no MEMORY.md / autosave). */
+    addInMemory(role: string, content: unknown, category?: string): ConversationMessage;
+    /** Append a message; honors autosave. The primary write entrypoint. */
+    add(role: string, content: unknown, _metadata?: Record<string, unknown>, category?: string): ConversationMessage;
+    /** Append multiple messages in order (roles and contents must be equal length). */
+    addMultiple(roles: string[], contents: unknown[]): ConversationMessage[];
+    /** Alias of {@link addMultiple} that also honors autosave once. */
+    addMultipleMessages(roles: string[], contents: unknown[]): ConversationMessage[];
+    /** Append pre-built message objects directly. */
+    batchAdd(messages: ConversationMessage[]): void;
+    /** Append a tool's output as a message under `role`. */
+    addToolOutputToAgent(role: string, toolOutput: unknown): ConversationMessage;
+    /** Delete the message at `index`. */
+    delete(index: number): void;
+    /** Overwrite the role+content of the message at `index`. */
+    update(index: number, role: string, content: unknown): void;
+    /** Return the message at `index`, or undefined. */
+    query(index: number): ConversationMessage | undefined;
+    /** Remove every message. */
+    clear(): void;
+    /** Alias of {@link clear}. */
+    clearMemory(): void;
+    /** Return messages whose stringified content contains `keyword`. */
+    search(keyword: string): ConversationMessage[];
+    /** Alias of {@link search}. */
+    searchKeywordInConversation(keyword: string): ConversationMessage[];
+    /** Filter messages visible to `agentName` at/before `turn`. */
+    getVisibleMessages(agentName: string, turn: number): ConversationMessage[];
+    /** Count messages per role. */
+    countMessagesByRole(): Record<string, number>;
+    /** Return the transcript as a single `role: content` string (with caching). */
+    returnHistoryAsString(): string;
+    /** Alias of {@link returnHistoryAsString}. */
+    getStr(): string;
+    private buildHistoryString;
+    private historyStringWorker;
+    /** Cache stats for {@link returnHistoryAsString}. */
+    getCacheStats(): {
+        hits: number;
+        misses: number;
+        cachedTokens: number;
+        hitRate: number;
+    };
+    /** The raw transcript array — the canonical serialized form. */
+    toDict(): ConversationMessage[];
+    /** The transcript as a list (alias of {@link toDict}). */
+    toList(): ConversationMessage[];
+    /** The transcript serialized to a JSON string. */
+    toJson(): string;
+    /** The transcript serialized to a YAML string. */
+    toYaml(): string;
+    /** Each message as a `role: content` string. */
+    returnMessagesAsList(): string[];
+    /** Canonical provider format: `[{role, content}]`. */
+    returnMessagesAsDictionary(): RoleContentMessage[];
+    /** Provider format serialized to a pretty JSON string. */
+    returnJson(): string;
+    /** The last message as `role: content`, or "". */
+    getLastMessageAsString(): string;
+    /** The final message as `role: content`, or "". */
+    getFinalMessage(): string;
+    /** The content of the final message, or "". */
+    getFinalMessageContent(): unknown;
+    /** Final message content as a `[role, content]` 2-tuple. */
+    returnDictFinal(): [unknown, unknown];
+    /** Final message content wrapped in a single-element list. */
+    returnListFinal(): unknown[];
+    /** All messages except the first two (system + first user). */
+    returnAllExceptFirst(): ConversationMessage[];
+    /** {@link returnAllExceptFirst} rendered as a newline-joined content string. */
+    returnAllExceptFirstString(): string;
+    /** Save the transcript to `saveFilepath` as JSON. */
+    saveAsJson(force?: boolean): void;
+    /** Save the transcript to `saveFilepath` as YAML. */
+    saveAsYaml(force?: boolean): void;
+    /** Save using the configured `exportMethod`. */
+    export(force?: boolean): void;
+    /** Load the transcript from a JSON file. */
+    loadFromJson(filename: string): void;
+    /** Load the transcript from a YAML file. */
+    loadFromYaml(filename: string): void;
+    /** Load the transcript, dispatching on file extension. */
+    load(filename: string): void;
+    /** Export the transcript to `filename` (JSON for `.json`, plain text otherwise). */
+    exportConversation(filename: string): void;
+    /** Import a transcript from a JSON file. */
+    importConversation(filename: string): void;
+    /** Truncate, from the front, the rendered history so it fits `contextLength`. */
+    dynamicAutoChunking(): string;
+    private dynamicAutoChunkingWorker;
+    /** Truncate the transcript message-by-message until it fits `contextLength`. */
+    truncateMemoryWithTokenizer(): void;
+    /** Binary-search the longest prefix of `text` fitting `targetTokens`. */
+    binarySearchTruncate(text: string, targetTokens: number, modelName: string): string;
+    /** Sum tokens for messages tagged `category: "input"` / `"output"`. */
+    exportAndCountCategories(): {
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+    };
+    private initMemoryMd;
+    private preloadMemoryMd;
+    private appendToMemoryMd;
+    private archiveMemoryMd;
+    /**
+     * Collapse the interaction history into a single `summary`, preserving the
+     * static context (system prompt → rules → custom rules → summary). When
+     * MEMORY.md is configured it is archived, wiped, and re-seeded so the on-disk
+     * log stops growing across compactions.
+     */
+    compact(summary: string, summaryRole?: string): void;
+    /** Load a conversation by name (or explicit file) from a directory. */
+    static loadConversation(name: string, conversationsDir?: string, loadFilepath?: string): Conversation;
+}
+//# sourceMappingURL=conversation.d.ts.map

package/dist/conversation.d.ts.map

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

package/dist/env.d.ts

@@ -0,0 +1,125 @@
+import { ExecutionError, FileError } from "./errors";
+import { type Result } from "./result";
+/** Result of running a shell command. */
+export interface ShellResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+}
+/** Options accepted by {@link Shell.exec}. */
+export interface ExecOptions {
+    cwd?: string;
+    env?: Record<string, string>;
+    /** Timeout in milliseconds. The process tree is killed when it elapses. */
+    timeoutMs?: number;
+    signal?: AbortSignal;
+    onStdout?: (chunk: string) => void;
+    onStderr?: (chunk: string) => void;
+}
+/** Filesystem operations. Failures are returned as `Result`, never thrown. */
+export interface FileSystem {
+    readTextFile(path: string, signal?: AbortSignal): Promise<Result<string, FileError>>;
+    /**
+     * Read a file as raw bytes (no text decoding). Optional so existing
+     * {@link FileSystem}/{@link ExecutionEnv} implementers keep compiling; callers
+     * must feature-detect it. Used by the `read` tool to serve images.
+     */
+    readBinaryFile?(path: string, signal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    writeTextFile(path: string, content: string, signal?: AbortSignal): Promise<Result<void, FileError>>;
+    appendTextFile(path: string, content: string): Promise<Result<void, FileError>>;
+    exists(path: string): Promise<boolean>;
+    listDir(path: string): Promise<Result<string[], FileError>>;
+    createDir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<Result<void, FileError>>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<Result<void, FileError>>;
+    resolvePath(path: string): string;
+}
+/** Shell command execution. */
+export interface Shell {
+    exec(command: string, options?: ExecOptions): Promise<Result<ShellResult, ExecutionError>>;
+}
+/** A combined filesystem + shell execution environment. */
+export interface ExecutionEnv extends FileSystem, Shell {
+    readonly cwd: string;
+}
+/**
+ * Resolve and classify the shell {@link NodeExecutionEnv} will run commands
+ * through, so callers (e.g. the CLI) can tell an LLM exactly what shell + OS it
+ * is driving. `kind` selects the command syntax family: `bash`/`sh` are POSIX,
+ * `cmd` is Windows cmd.exe.
+ */
+export declare function detectShell(customShellPath?: string): Promise<{
+    shell: string;
+    kind: "bash" | "cmd" | "sh";
+}>;
+/** The default Node-backed {@link ExecutionEnv}. */
+export declare class NodeExecutionEnv implements ExecutionEnv {
+    readonly cwd: string;
+    private readonly shellPath?;
+    private readonly shellEnv?;
+    /** When true (default), the shell blocklist rejects dangerous commands. */
+    readonly enforceBlocklist: boolean;
+    /**
+     * When true (default false), {@link writeTextFile} and {@link appendTextFile}
+     * reject any path that resolves outside {@link workspaceRoot}. Off by default
+     * so the write-anywhere behavior is unchanged unless explicitly opted in.
+     */
+    readonly restrictWritesToWorkspace: boolean;
+    /** The boundary used when {@link restrictWritesToWorkspace} is on. */
+    readonly workspaceRoot: string;
+    constructor(options: {
+        cwd: string;
+        shellPath?: string;
+        shellEnv?: Record<string, string>;
+        enforceBlocklist?: boolean;
+        restrictWritesToWorkspace?: boolean;
+        workspaceRoot?: string;
+    });
+    resolvePath(path: string): string;
+    /**
+     * Guard a mutating write when {@link restrictWritesToWorkspace} is on: returns
+     * a {@link FileError} when `resolved` falls outside {@link workspaceRoot}, else
+     * `undefined`. Inside/outside is computed with `path.relative` (NOT naive
+     * string prefixing, which mis-classifies `/work2` against `/work`): a path is
+     * inside iff the relative path is empty, is not absolute, and does not begin
+     * with a `..` segment. `path.relative` already normalizes separators and
+     * Windows drive-letter casing, so a cross-drive or traversal escape resolves
+     * to an absolute (or `..`-leading) relative path and is rejected.
+     */
+    private workspaceWriteError;
+    readTextFile(path: string, signal?: AbortSignal): Promise<Result<string, FileError>>;
+    readBinaryFile(path: string, signal?: AbortSignal): Promise<Result<Uint8Array, FileError>>;
+    writeTextFile(path: string, content: string, signal?: AbortSignal): Promise<Result<void, FileError>>;
+    appendTextFile(path: string, content: string): Promise<Result<void, FileError>>;
+    exists(path: string): Promise<boolean>;
+    listDir(path: string): Promise<Result<string[], FileError>>;
+    createDir(path: string, options?: {
+        recursive?: boolean;
+    }): Promise<Result<void, FileError>>;
+    remove(path: string, options?: {
+        recursive?: boolean;
+        force?: boolean;
+    }): Promise<Result<void, FileError>>;
+    exec(command: string, options?: ExecOptions): Promise<Result<ShellResult, ExecutionError>>;
+}
+/** A capture-and-truncate wrapper around {@link Shell.exec}. */
+export interface ShellCaptureResult extends ShellResult {
+    truncated: boolean;
+}
+/**
+ * Run a command and capture its output, truncating each stream to a byte cap
+ * (default 50KiB) so a runaway command cannot blow up the transcript. Honors a
+ * timeout via an {@link AbortController}.
+ */
+export declare function executeShellWithCapture(env: ExecutionEnv, command: string, options?: {
+    cwd?: string;
+    env?: Record<string, string>;
+    timeoutMs?: number;
+    maxOutputBytes?: number;
+    signal?: AbortSignal;
+}): Promise<Result<ShellCaptureResult, ExecutionError>>;
+//# sourceMappingURL=env.d.ts.map

package/dist/env.d.ts.map

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

package/dist/errors.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Stable, backend-independent error codes for filesystem operations. These are
+ * returned (never thrown) inside a `Result` by the {@link FileSystem} layer.
+ */
+export type FileErrorCode = "aborted" | "not_found" | "permission_denied" | "not_directory" | "is_directory" | "invalid" | "not_supported" | "unknown";
+/** Stable error codes for shell command execution. */
+export type ExecutionErrorCode = "aborted" | "timeout" | "blocked" | "shell_unavailable" | "spawn_error" | "callback_error" | "unknown";
+/** Codes that classify a session-storage or session-tree failure. */
+export type SessionErrorCode = "invalid_session" | "invalid_entry" | "not_found" | "io" | "unknown";
+/** Codes for context-compaction failures. */
+export type CompactionErrorCode = "compaction" | "invalid_session" | "aborted" | "summarization_failed" | "auth" | "unknown";
+/** Codes for stateful-agent / harness lifecycle failures. */
+export type AgentHarnessErrorCode = "busy" | "invalid_state" | "invalid_argument" | "auth" | "aborted" | "unknown";
+/** Base class for every AP3X agent-core error. Carries a stable `code`. */
+export declare abstract class Ap3xError<TCode extends string> extends Error {
+    readonly code: TCode;
+    readonly cause?: unknown;
+    constructor(code: TCode, message: string, cause?: unknown);
+}
+/** A filesystem operation failed. */
+export declare class FileError extends Ap3xError<FileErrorCode> {
+    readonly path?: string;
+    constructor(code: FileErrorCode, message: string, path?: string, cause?: unknown);
+}
+/** A shell command failed, timed out, was aborted, or was blocked. */
+export declare class ExecutionError extends Ap3xError<ExecutionErrorCode> {
+}
+/** A session tree / storage invariant was violated. */
+export declare class SessionError extends Ap3xError<SessionErrorCode> {
+}
+/** Context compaction failed. */
+export declare class CompactionError extends Ap3xError<CompactionErrorCode> {
+}
+/** A stateful `Agent` / harness rejected an operation (e.g. it was busy). */
+export declare class AgentHarnessError extends Ap3xError<AgentHarnessErrorCode> {
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,aAAa,GACrB,SAAS,GACT,WAAW,GACX,mBAAmB,GACnB,eAAe,GACf,cAAc,GACd,SAAS,GACT,eAAe,GACf,SAAS,CAAC;AAEd,sDAAsD;AACtD,MAAM,MAAM,kBAAkB,GAC1B,SAAS,GACT,SAAS,GACT,SAAS,GACT,mBAAmB,GACnB,aAAa,GACb,gBAAgB,GAChB,SAAS,CAAC;AAEd,qEAAqE;AACrE,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,eAAe,GAAG,WAAW,GAAG,IAAI,GAAG,SAAS,CAAC;AAEpG,6CAA6C;AAC7C,MAAM,MAAM,mBAAmB,GAC3B,YAAY,GACZ,iBAAiB,GACjB,SAAS,GACT,sBAAsB,GACtB,MAAM,GACN,SAAS,CAAC;AAEd,6DAA6D;AAC7D,MAAM,MAAM,qBAAqB,GAC7B,MAAM,GACN,eAAe,GACf,kBAAkB,GAClB,MAAM,GACN,SAAS,GACT,SAAS,CAAC;AAEd,2EAA2E;AAC3E,8BAAsB,SAAS,CAAC,KAAK,SAAS,MAAM,CAAE,SAAQ,KAAK;IACjE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAC;IACrB,SAAkB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAEtB,IAAI,EAAE,KAAK,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAM1D;AAED,qCAAqC;AACrC,qBAAa,SAAU,SAAQ,SAAS,CAAC,aAAa,CAAC;IACrD,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;gBACX,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO;CAIjF;AAED,sEAAsE;AACtE,qBAAa,cAAe,SAAQ,SAAS,CAAC,kBAAkB,CAAC;CAAG;AAEpE,uDAAuD;AACvD,qBAAa,YAAa,SAAQ,SAAS,CAAC,gBAAgB,CAAC;CAAG;AAEhE,iCAAiC;AACjC,qBAAa,eAAgB,SAAQ,SAAS,CAAC,mBAAmB,CAAC;CAAG;AAEtE,6EAA6E;AAC7E,qBAAa,iBAAkB,SAAQ,SAAS,CAAC,qBAAqB,CAAC;CAAG"}

package/dist/harness.d.ts

@@ -0,0 +1,110 @@
+import type { AssistantMessage } from "@ap3x/ai";
+import { type AgentOptions } from "./agent";
+import { type CompactionResult, compact } from "./compaction";
+import { type Session } from "./session";
+import type { AgentEvent, AgentMessage } from "./types";
+/**
+ * Construction options for the {@link AgentHarness}.
+ */
+export interface AgentHarnessOptions extends AgentOptions {
+    session: Session;
+}
+/** A harness event subscriber. Mirrors the untyped {@link AgentEvent} stream. */
+type HarnessListener = (event: AgentEvent) => void | Promise<void>;
+/** Narrow an {@link AgentEvent} to a single `type` for the typed {@link AgentHarness.on}. */
+type AgentEventOf<T extends AgentEvent["type"]> = Extract<AgentEvent, {
+    type: T;
+}>;
+/**
+ * A session-backed host harness over an {@link Agent}. Every prompt and its
+ * resulting messages are appended to the session tree, so the conversation can
+ * be reconstructed, branched, or compacted later.
+ *
+ * The harness — not the (rebuildable) inner agent — is the stable event source:
+ * subscribers register with the harness and survive an agent rebuild (compaction
+ * reseed, branch navigation). Live-run steering (`steer`/`followUp`) delegates to
+ * the agent's shared queue; `nextTurn` carries to the *next* prompt instead.
+ */
+export declare class AgentHarness {
+    readonly session: Session;
+    private agent;
+    private readonly agentOptions;
+    /** Harness-owned subscribers; a single forwarder relays each agent's events. */
+    private readonly listeners;
+    /** Unsubscribes the forwarder from the current agent (re-wired on rebuild). */
+    private agentUnsub?;
+    /** Messages queued by {@link nextTurn}, prepended to (and cleared by) the next prompt. */
+    private pendingNextTurn;
+    /**
+     * Summary of an in-memory (unpersistable) compaction — set when {@link compact}
+     * finds no session entry to anchor a durable CompactionEntry on (the agent runs
+     * on seeded `messages` the session never held). Threads into the NEXT compaction
+     * as `previousSummary` so it merges instead of being re-read as conversation
+     * text; cleared whenever the agent is reseeded from the session, which replaces
+     * the in-memory context this summary describes.
+     */
+    private unpersistedSummary?;
+    private busy;
+    constructor(options: AgentHarnessOptions);
+    /**
+     * Run a single turn and persist all new messages to the session. Only
+     * turn-produced messages are appended — seeded {@link AgentOptions.messages}
+     * stay context-only and are never persisted (see that option's doc; B21).
+     */
+    prompt(text: string): Promise<AssistantMessage>;
+    /**
+     * Inject a steering message into the live run at the next turn boundary (or,
+     * while idle, into the next run's first turn). Delegates to the agent's queue.
+     */
+    steer(message: string | AgentMessage): void;
+    /** Queue a follow-up that extends the current run once it would otherwise stop. */
+    followUp(message: string | AgentMessage): void;
+    /**
+     * Carry a message to the NEXT {@link prompt}: it is prepended to that prompt
+     * and the queue is cleared. Unlike {@link followUp}, this never extends the
+     * currently-running turn — the message is held at the harness (session) layer
+     * until the next prompt begins.
+     */
+    nextTurn(message: string | AgentMessage): void;
+    /**
+     * Compact the agent's current context: summarize older history, persist a
+     * compaction boundary to the session, and reseed the agent from the compacted
+     * context so subsequent prompts run against the shortened transcript. Options
+     * are forwarded to the P13 {@link compact}. Throws the underlying
+     * {@link CompactionError} if summarization fails.
+     *
+     * When the agent runs on seeded `messages` the session never held (no entry
+     * can anchor a durable CompactionEntry), the compaction is applied to the
+     * live agent in-memory instead: the returned summary is real and the next
+     * provider call sees the compacted context, but no compaction boundary is
+     * persisted to the session for that run.
+     */
+    compact(options?: Parameters<typeof compact>[2]): Promise<CompactionResult>;
+    /**
+     * Move the session's active branch to `entryId` and reseed the agent from that
+     * branch's reconstructed context, so subsequent prompts continue from the
+     * navigated-to point (rewind / branch-switch).
+     */
+    navigateTree(entryId: string): void;
+    /** Subscribe to the underlying agent's lifecycle events. */
+    subscribe(listener: HarnessListener): () => void;
+    /**
+     * Typed event subscription: `handler` receives only events of `type`, narrowed
+     * to that variant. Returns an unsubscribe function.
+     */
+    on<T extends AgentEvent["type"]>(type: T, handler: (event: AgentEventOf<T>) => void | Promise<void>): () => void;
+    /** Abort the active run. */
+    abort(): void;
+    /**
+     * Rebuild the inner agent over `messages`, re-wiring the event forwarder.
+     * When `previous` is given (a rebuild that CONTINUES the same conversation),
+     * its pending steer/followUp/nextTurn queue is carried into the new agent.
+     */
+    private buildAgent;
+    /** Reseed the agent from the session's current branch context. */
+    private reseedFromSession;
+    /** Normalize a string prompt into a user {@link AgentMessage}. */
+    private toMessage;
+}
+export {};
+//# sourceMappingURL=harness.d.ts.map

package/dist/harness.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness.d.ts","sourceRoot":"","sources":["../src/harness.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AACjD,OAAO,EAAS,KAAK,YAAY,EAAE,MAAM,SAAS,CAAC;AACnD,OAAO,EACL,KAAK,gBAAgB,EAErB,OAAO,EAER,MAAM,cAAc,CAAC;AAEtB,OAAO,EAAE,KAAK,OAAO,EAA0B,MAAM,WAAW,CAAC;AACjE,OAAO,KAAK,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAExD;;GAEG;AACH,MAAM,WAAW,mBAAoB,SAAQ,YAAY;IACvD,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,iFAAiF;AACjF,KAAK,eAAe,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEnE,6FAA6F;AAC7F,KAAK,YAAY,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,IAAI,OAAO,CAAC,UAAU,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC;AAEnF;;;;;;;;;GASG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,OAAO,CAAC,KAAK,CAAS;IACtB,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAe;IAC5C,gFAAgF;IAChF,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,+EAA+E;IAC/E,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,0FAA0F;IAC1F,OAAO,CAAC,eAAe,CAAsB;IAC7C;;;;;;;OAOG;IACH,OAAO,CAAC,kBAAkB,CAAC,CAAS;IACpC,OAAO,CAAC,IAAI,CAAS;gBAET,OAAO,EAAE,mBAAmB;IASxC;;;;OAIG;IACG,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAqBrD;;;OAGG;IACH,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI3C,mFAAmF;IACnF,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI9C;;;;;OAKG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI9C;;;;;;;;;;;;OAYG;IACG,OAAO,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC,OAAO,OAAO,CAAC,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAyEjF;;;;OAIG;IACH,YAAY,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI;IASnC,4DAA4D;IAC5D,SAAS,CAAC,QAAQ,EAAE,eAAe,GAAG,MAAM,IAAI;IAOhD;;;OAGG;IACH,EAAE,CAAC,CAAC,SAAS,UAAU,CAAC,MAAM,CAAC,EAC7B,IAAI,EAAE,CAAC,EACP,OAAO,EAAE,CAAC,KAAK,EAAE,YAAY,CAAC,CAAC,CAAC,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,GACxD,MAAM,IAAI;IAMb,4BAA4B;IAC5B,KAAK,IAAI,IAAI;IAIb;;;;OAIG;IACH,OAAO,CAAC,UAAU;IASlB,kEAAkE;IAClE,OAAO,CAAC,iBAAiB;IAMzB,kEAAkE;IAClE,OAAO,CAAC,SAAS;CAKlB"}

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+export declare const PACKAGE = "@ap3x/agent-core";
+export declare const VERSION = "0.1.0";
+export { type Result, ok, err, getOrThrow, getOrUndefined, toError } from "./result";
+export { Ap3xError, FileError, ExecutionError, SessionError, CompactionError, AgentHarnessError, type FileErrorCode, type ExecutionErrorCode, type SessionErrorCode, type CompactionErrorCode, type AgentHarnessErrorCode, } from "./errors";
+export { uuidv7, shortId } from "./uuid";
+export { createLimiter, mapLimit, availableParallelism } from "./concurrency";
+export type { AgentMessage, CustomAgentMessages, AgentContext, AgentTool, AnyAgentTool, AgentToolResult, AgentToolUpdate, AgentEvent, AgentEventSink, AgentHooks, AgentLoopConfig, QueueMode, BeforeToolCallContext, AfterToolCallContext, ToolCallGate, ThinkingLevel, StreamFn, } from "./types";
+export { defineTool, executeToolCalls, type ToolBatchResult, type ExecuteToolCallsOptions, type ToolExecutionEvent, } from "./tools";
+export { runAgentLoop, runAgentLoopContinue, agentLoop, agentLoopContinue, DEFAULT_MAX_LOOPS, type AgentEventStream, } from "./agent-loop";
+export { Agent, type AgentOptions, type AgentState, type AgentListener, finalTextOf, lastAssistant, } from "./agent";
+export { type AgentBackend, type AgentRunResult, type AgentRunOptions, type BackendCapability, Ap3xRuntimeBackend, createRuntimeBackend, } from "./backend";
+export { AgentHarness, type AgentHarnessOptions } from "./harness";
+export { assembleSystemPrompt, SystemPromptBuilder, environmentSection, SYSTEM_PROMPT_SECTIONS, type SystemPromptSection, type SystemPromptSectionName, type AssembleSystemPromptOptions, type EnvironmentSectionInput, } from "./system-prompt";
+export { loadPromptTemplate, parseCommandArgs, parsePromptTemplate, renderPromptTemplate, substituteArgs, type PromptTemplate, } from "./prompt-templates";
+export { parseSkill, loadSkill, loadSkills, discoverSkillFiles, discoverSkills, SkillRegistry, formatSkillsForSystemPrompt, type Skill, } from "./skills";
+export { Session, buildSessionContext, producesContextMessage, createSessionId, InMemorySessionStorage, JsonlSessionStorage, StringJsonlFile, type SessionStorage, type SessionEntry, type SessionEntryType, type MessageEntry, type CompactionEntry, type ModelChangeEntry, type LabelEntry, type LeafEntry, type ThinkingLevelChangeEntry, type ActiveToolsChangeEntry, type BranchSummaryEntry, type SessionInfoEntry, type CustomEntry, type CustomMessageEntry, type SessionContext, type SessionMetadata, type JsonlFile, } from "./session";
+export { FileJsonlFile, JsonlSessionRepo, type SessionRepo, type SessionCreateOptions, type SessionForkOptions, type SessionListEntry, } from "./session-repo";
+export { compact, prepareCompaction, shouldCompact, compactionTier, resolveCompactionSettings, resolveAutoCompact, findCutPoint, estimateMessageTokens, estimateContextTokens, DEFAULT_COMPACTION_SETTINGS, SUMMARIZATION_SYSTEM_PROMPT, type CompactionSettings, type CompactionTier, type CompactionResult, type CompactionPreparation, type CutPointResult, } from "./compaction";
+export { NodeExecutionEnv, detectShell, executeShellWithCapture, type ExecutionEnv, type FileSystem, type Shell, type ExecOptions, type ShellResult, type ShellCaptureResult, } from "./env";
+export { matchBlocklist, isBlockedCommand, type BlocklistMatch } from "./shell-blocklist";
+export { logger, setLogLevel, getLogLevel, type LogLevel } from "./logger";
+export { Conversation, generateConversationId, getConversationDir, type ConversationMessage, type ConversationOptions, type RoleContentMessage, } from "./conversation";
+export { historyOutputFormatter, type HistoryOutputType, type OutputType, } from "./output-formatter";
+export { estimateTokens, type TokenCounter } from "./conversation";
+export { AgentLoader, AgentRegistry, AgentConfigSchema, AgentRegistrySchema, AgentSpecSchema, parseYamlFrontmatter, type AgentConfig, type AgentRegistrySnapshot, type AgentSpec, type RegistrableAgent, } from "./loader";
+export { SafeStateManager, SerializableMixin, createStateDict, isClassInstance, isSafeType, preserveInstances, serializeAttr, serializeState, type CallableDescriptor, type HasToDict, } from "./serialization";
+export { AgentError, AgentInitializationError, AgentRunError, AgentLLMError, AgentToolError, AgentMemoryError, AgentMCPConnectionError, AgentMCPToolError, type AgentErrorCode, } from "./agent-errors";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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