@ap3x/agent-core 0.1.0

package/dist/loader.d.ts

@@ -0,0 +1,142 @@
+/**
+ * Agent loading + registration.
+ *
+ * - {@link AgentLoader} parses agent *specifications* from Markdown (YAML
+ *   frontmatter), YAML, or CSV files. It does not construct runtime agents (the
+ *   orchestration layer maps specs → `AgentBackend`s); it produces validated
+ *   {@link AgentSpec} objects.
+ *
+ * - {@link AgentRegistry} is a name-keyed store of agent records with add/get/
+ *   list/query/find-by-name/find-by-id. Records are validated against TypeBox
+ *   schemas ({@link AgentConfigSchema} / {@link AgentRegistrySchema}).
+ *
+ * Concurrency uses `Promise.all` (Node is single-threaded); the markdown/yaml/csv parsers are
+ * hand-rolled so the accepted grammar is fully specified here and dependency-free.
+ */
+import { type Static } from "@ap3x/ai";
+/** TypeBox schema for a parsed agent specification. */
+export declare const AgentSpecSchema: import("@sinclair/typebox").TObject<{
+    name: import("@sinclair/typebox").TString;
+    description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    modelName: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    systemPrompt: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    temperature: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TNumber>;
+    maxLoops: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    maxTokens: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    contextLength: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    outputType: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    autosave: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    verbose: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    streamingOn: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    dynamicTemperatureEnabled: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TBoolean>;
+    retryAttempts: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    userName: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+/** A validated agent specification produced by {@link AgentLoader}. */
+export type AgentSpec = Static<typeof AgentSpecSchema>;
+/** Parse YAML frontmatter from markdown content, returning the data + body. */
+export declare function parseYamlFrontmatter(content: string): {
+    frontmatter: Record<string, unknown>;
+    body: string;
+};
+/** Loads agent specifications from Markdown, YAML, or CSV files. */
+export declare class AgentLoader {
+    readonly concurrent: boolean;
+    constructor(options?: {
+        concurrent?: boolean;
+    });
+    /** Parse one markdown file (YAML frontmatter + body as system prompt). */
+    loadAgentFromMarkdown(filePath: string): Promise<AgentSpec>;
+    /** Parse one or more markdown files. */
+    loadAgentsFromMarkdown(filePaths: string | string[], options?: {
+        concurrent?: boolean;
+    }): Promise<AgentSpec[]>;
+    /** Parse a YAML file containing one agent or a list under `agents`. */
+    loadAgentsFromYaml(yamlFile: string): Promise<AgentSpec[]>;
+    /** Parse several YAML files. */
+    loadManyAgentsFromYaml(yamlFiles: string[]): Promise<AgentSpec[][]>;
+    /** Parse a CSV file (first row is the header). */
+    loadAgentsFromCsv(csvFile: string): Promise<AgentSpec[]>;
+    /** Dispatch by file extension (.md / .yaml / .yml / .csv). */
+    auto(filePath: string): Promise<AgentSpec[]>;
+    /** Load a single spec from a file via {@link auto}. */
+    loadSingleAgent(filePath: string): Promise<AgentSpec>;
+    /** Load specs from several files (each may yield multiple), flattened. */
+    loadMultipleAgents(filePaths: string[]): Promise<AgentSpec[]>;
+}
+/** TypeBox schema for a single registry entry. */
+export declare const AgentConfigSchema: import("@sinclair/typebox").TObject<{
+    uuid: import("@sinclair/typebox").TString;
+    name: import("@sinclair/typebox").TString;
+    description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    timeAdded: import("@sinclair/typebox").TString;
+    config: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+}>;
+/** A validated registry entry. */
+export type AgentConfig = Static<typeof AgentConfigSchema>;
+/** TypeBox schema for the whole registry. */
+export declare const AgentRegistrySchema: import("@sinclair/typebox").TObject<{
+    name: import("@sinclair/typebox").TString;
+    description: import("@sinclair/typebox").TString;
+    agents: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        uuid: import("@sinclair/typebox").TString;
+        name: import("@sinclair/typebox").TString;
+        description: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+        timeAdded: import("@sinclair/typebox").TString;
+        config: import("@sinclair/typebox").TRecord<import("@sinclair/typebox").TString, import("@sinclair/typebox").TUnknown>;
+    }>>;
+    timeRegistryCreated: import("@sinclair/typebox").TString;
+    numberOfAgents: import("@sinclair/typebox").TInteger;
+}>;
+/** A validated registry snapshot. */
+export type AgentRegistrySnapshot = Static<typeof AgentRegistrySchema>;
+/** The minimal shape a registered agent must expose. */
+export interface RegistrableAgent {
+    agentName?: string;
+    name?: string;
+    id?: string;
+    description?: string;
+    toDict?: () => Record<string, unknown>;
+    [key: string]: unknown;
+}
+/** A name-keyed store of agents with query + find helpers. */
+export declare class AgentRegistry<TAgent extends RegistrableAgent = RegistrableAgent> {
+    readonly name: string;
+    readonly description: string;
+    private readonly agents;
+    private readonly timeCreated;
+    constructor(options?: {
+        name?: string;
+        description?: string;
+        agents?: TAgent[];
+    });
+    /** Add an agent. Throws if the name is already taken. */
+    add(agent: TAgent): void;
+    /** Add several agents. */
+    addMany(agents: TAgent[]): void;
+    /** Delete an agent by name. Throws if it does not exist. */
+    delete(name: string): void;
+    /** Replace an agent by name. Throws if it does not exist. */
+    updateAgent(name: string, newAgent: TAgent): void;
+    /** Get an agent by name. Throws if it does not exist. */
+    get(name: string): TAgent;
+    /** List all registered agent names. */
+    listAgents(): string[];
+    /** Return all registered agents. */
+    returnAllAgents(): TAgent[];
+    /** Filter agents by a predicate (or return all when omitted). */
+    query(condition?: (agent: TAgent) => boolean): TAgent[];
+    /** Find an agent by name (undefined if absent). */
+    findAgentByName(name: string): TAgent | undefined;
+    /** Find an agent by id (undefined if absent). */
+    findAgentById(id: string): TAgent | undefined;
+    /** Number of registered agents. */
+    get size(): number;
+    /** Serialize every agent's `toDict()` keyed by name. */
+    agentsToJson(): string;
+    /** Build a validated {@link AgentConfig} record for an agent. */
+    agentToModel(agent: TAgent): AgentConfig;
+    /** A validated snapshot of the whole registry. */
+    toSchema(): AgentRegistrySnapshot;
+}
+//# sourceMappingURL=loader.d.ts.map

package/dist/loader.d.ts.map

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

package/dist/logger.d.ts

@@ -0,0 +1,36 @@
+/**
+ * A tiny, dependency-free leveled logger for AP3X library code.
+ *
+ * A library must be QUIET by default — stray `console.warn`/`console.error`
+ * calls from deep in the orchestration layer leak into a host application's
+ * stderr (and into test output). This logger gates every emission behind an
+ * active level that DEFAULTS TO `silent`; a host opts in by setting the
+ * `AP3X_LOG_LEVEL` environment variable (case-insensitive) or by calling
+ * {@link setLogLevel}.
+ *
+ * Levels are ordered by increasing verbosity:
+ *
+ *   silent < error < warn < info < debug
+ *
+ * A message at level L is emitted only when the active level is >= L. So at
+ * `warn`, `warn`/`error` emit but `info`/`debug` are suppressed; at `silent`
+ * nothing is emitted at all. Each level routes to its matching `console`
+ * method, so existing stderr/stdout semantics are preserved when enabled.
+ */
+/** The set of recognized log levels, ordered from least to most verbose. */
+export type LogLevel = "silent" | "error" | "warn" | "info" | "debug";
+/** Set the active log level (for hosts and tests). */
+export declare function setLogLevel(level: LogLevel): void;
+/** Get the active log level. */
+export declare function getLogLevel(): LogLevel;
+/**
+ * The shared leveled logger. Each method emits to the matching `console` method
+ * ONLY when the active level permits; otherwise it is a no-op.
+ */
+export declare const logger: {
+    debug(message?: unknown, ...args: unknown[]): void;
+    info(message?: unknown, ...args: unknown[]): void;
+    warn(message?: unknown, ...args: unknown[]): void;
+    error(message?: unknown, ...args: unknown[]): void;
+};
+//# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,4EAA4E;AAC5E,MAAM,MAAM,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAqBtE,sDAAsD;AACtD,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,gCAAgC;AAChC,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AAOD;;;GAGG;AACH,eAAO,MAAM,MAAM;oBACD,OAAO,WAAW,OAAO,EAAE,GAAG,IAAI;mBAGnC,OAAO,WAAW,OAAO,EAAE,GAAG,IAAI;mBAGlC,OAAO,WAAW,OAAO,EAAE,GAAG,IAAI;oBAGjC,OAAO,WAAW,OAAO,EAAE,GAAG,IAAI;CAGnD,CAAC"}

package/dist/output-formatter.d.ts

@@ -0,0 +1,27 @@
+/**
+ * `historyOutputFormatter` — the single, pure rendering function that turns a
+ * {@link Conversation} into one of 17 output shapes.
+ *
+ * Every swarm orchestrator funnels its final return through this function so
+ * the `output_type` contract is honored uniformly. It is a **total function**:
+ * the switch handles all 17 named modes plus a default fall-through (which
+ * mirrors `"list"`), so no mode falls through to an error for a value in the
+ * {@link HistoryOutputType} union.
+ *
+ * Modes (17): list · dict · dictionary · string · str · final · last · json ·
+ * all · yaml · xml · dict-all-except-first · str-all-except-first · basemodel ·
+ * dict-final · list-final.
+ */
+import type { Conversation } from "./conversation";
+/** The closed union of output modes a swarm may request. */
+export type HistoryOutputType = "list" | "dict" | "dictionary" | "string" | "str" | "final" | "last" | "json" | "all" | "yaml" | "xml" | "dict-all-except-first" | "str-all-except-first" | "basemodel" | "dict-final" | "list-final";
+/** Alias of {@link HistoryOutputType}. */
+export type OutputType = HistoryOutputType;
+/**
+ * Render `conversation` into the shape named by `type`.
+ *
+ * Returns a varied type by design (string | array | object | tuple) to match
+ * the swarms `output_type` contract. The caller knows which shape it asked for.
+ */
+export declare function historyOutputFormatter(conversation: Conversation, type?: HistoryOutputType): unknown;
+//# sourceMappingURL=output-formatter.d.ts.map

package/dist/output-formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output-formatter.d.ts","sourceRoot":"","sources":["../src/output-formatter.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAEnD,4DAA4D;AAC5D,MAAM,MAAM,iBAAiB,GACzB,MAAM,GACN,MAAM,GACN,YAAY,GACZ,QAAQ,GACR,KAAK,GACL,OAAO,GACP,MAAM,GACN,MAAM,GACN,KAAK,GACL,MAAM,GACN,KAAK,GACL,uBAAuB,GACvB,sBAAsB,GACtB,WAAW,GACX,YAAY,GACZ,YAAY,CAAC;AAEjB,0CAA0C;AAC1C,MAAM,MAAM,UAAU,GAAG,iBAAiB,CAAC;AAiC3C;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,YAAY,EAAE,YAAY,EAC1B,IAAI,GAAE,iBAA0B,GAC/B,OAAO,CA0CT"}

package/dist/prompt-templates.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Prompt templates: reusable prompt bodies rendered with shell-style positional
+ * argument substitution.
+ *
+ * A prompt template is a Markdown file whose YAML frontmatter carries metadata
+ * (a `description`) and whose body is the template text. Rendering substitutes
+ * shell-style placeholders with a list of positional arguments — the mechanism
+ * behind parameterised slash-command prompts.
+ *
+ * This module is a standalone runtime primitive: it does NOT depend on the
+ * system-prompt assembly (S1). It reuses {@link parseYamlFrontmatter} for the
+ * frontmatter split (see loader.ts) rather than re-implementing it.
+ *
+ * Supported substitution tokens (see {@link substituteArgs} for exact edge
+ * behaviour):
+ * - `$1`, `$2`, … `$N` — the 1-based Nth argument (multi-digit indices allowed).
+ *   `$0` and out-of-range indices render empty.
+ * - `$@` / `$ARGUMENTS`  — every argument, space-joined.
+ * - `${@:N}` / `${@:N:L}` — the array slice starting at the 1-based Nth argument
+ *   (optionally limited to L items), space-joined.
+ *
+ * Everything else — a lone `$`, `$word`, the colon-less brace form `${@}` — is
+ * left untouched. Substitution is a pure string transform (deterministic; no
+ * clock / randomness).
+ */
+/** A reusable prompt template: a named body plus a short description. */
+export interface PromptTemplate {
+    /** Identifier — a Markdown template's basename without the `.md` suffix. */
+    name: string;
+    /** Short description: the frontmatter `description`, else a body preview. */
+    description: string;
+    /** Template body; the text rendered by {@link renderPromptTemplate}. */
+    content: string;
+}
+/**
+ * Split an argument string into positional arguments using shell-style single
+ * and double quoting.
+ *
+ * Runs of spaces/tabs separate arguments; single or double quotes group
+ * whitespace and are removed from the result. Quotes may open mid-token
+ * (`foo"bar baz"` → `foobar baz`). Empty quoted tokens (`""`) contribute no
+ * argument.
+ */
+export declare function parseCommandArgs(argsString: string): string[];
+/**
+ * Substitute prompt-template placeholders with positional arguments.
+ *
+ * Order and edge behaviour:
+ * 1. `$N` (one or more digits) → the 1-based Nth arg, or `""` when absent (so
+ *    `$0` and out-of-range indices render empty). A `$` followed by digits in
+ *    prose (`$5`) is therefore treated as a positional token.
+ * 2. `${@:N}` / `${@:N:L}` → the arg slice from the 1-based Nth arg (a start
+ *    below 1 clamps to the first arg), optionally limited to L items (including
+ *    `L=0` → empty). A start or length past the end simply yields fewer/no args.
+ *    The colon-less brace form `${@}` is NOT a token and stays literal.
+ * 3. `$ARGUMENTS` and `$@` → every arg space-joined.
+ *
+ * Anything else (a lone `$`, `$word`) is left untouched.
+ */
+export declare function substituteArgs(content: string, args: string[]): string;
+/**
+ * Parse Markdown template content into a {@link PromptTemplate}.
+ *
+ * The frontmatter is split via {@link parseYamlFrontmatter}; the trimmed body
+ * becomes {@link PromptTemplate.content}. The description is the frontmatter
+ * `description` when present, otherwise a preview of the first non-blank body
+ * line (truncated to 60 chars with an ellipsis). Pure — no filesystem access.
+ */
+export declare function parsePromptTemplate(name: string, content: string): PromptTemplate;
+/**
+ * Load a Markdown prompt-template file. The template name is the file's
+ * basename without the `.md` suffix; the rest is delegated to
+ * {@link parsePromptTemplate}.
+ */
+export declare function loadPromptTemplate(filePath: string): Promise<PromptTemplate>;
+/** Render a prompt template's body against positional arguments. */
+export declare function renderPromptTemplate(template: PromptTemplate, args?: string[]): string;
+//# sourceMappingURL=prompt-templates.d.ts.map

package/dist/prompt-templates.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-templates.d.ts","sourceRoot":"","sources":["../src/prompt-templates.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAMH,yEAAyE;AACzE,MAAM,WAAW,cAAc;IAC7B,4EAA4E;IAC5E,IAAI,EAAE,MAAM,CAAC;IACb,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,wEAAwE;IACxE,OAAO,EAAE,MAAM,CAAC;CACjB;AAKD;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,EAAE,CAuB7D;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAqBtE;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,cAAc,CAWjF;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAIlF;AAED,oEAAoE;AACpE,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,cAAc,EAAE,IAAI,GAAE,MAAM,EAAO,GAAG,MAAM,CAE1F"}

package/dist/result.d.ts

@@ -0,0 +1,26 @@
+/**
+ * A `Result` is the explicit success-or-failure value AP3X uses instead of
+ * throwing for *expected* failures. The loop, the filesystem layer and the
+ * shell layer all return `Result` so callers handle errors as data.
+ */
+export type Result<TValue, TError> = {
+    readonly ok: true;
+    readonly value: TValue;
+} | {
+    readonly ok: false;
+    readonly error: TError;
+};
+/** Construct a successful {@link Result}. */
+export declare function ok<TValue, TError = never>(value: TValue): Result<TValue, TError>;
+/** Construct a failed {@link Result}. */
+export declare function err<TError, TValue = never>(error: TError): Result<TValue, TError>;
+/** Unwrap a {@link Result}, throwing the error if it failed. For tests and adapter seams. */
+export declare function getOrThrow<TValue, TError>(result: Result<TValue, TError>): TValue;
+/**
+ * Unwrap a {@link Result}, returning `undefined` on failure. Constrained to
+ * object values so primitive falsy successes are never confused with failure.
+ */
+export declare function getOrUndefined<TValue extends object, TError>(result: Result<TValue, TError>): TValue | undefined;
+/** Coerce any thrown value into an `Error` so it can be used as a typed cause. */
+export declare function toError(value: unknown): Error;
+//# sourceMappingURL=result.d.ts.map

package/dist/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../src/result.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,IAC7B;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CAAC;AAEnD,6CAA6C;AAC7C,wBAAgB,EAAE,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEhF;AAED,yCAAyC;AACzC,wBAAgB,GAAG,CAAC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAEjF;AAED,6FAA6F;AAC7F,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAAG,MAAM,CAGjF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,MAAM,SAAS,MAAM,EAAE,MAAM,EAC1D,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,MAAM,GAAG,SAAS,CAEpB;AAED,kFAAkF;AAClF,wBAAgB,OAAO,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,CAQ7C"}

package/dist/serialization.d.ts

@@ -0,0 +1,75 @@
+/**
+ * Safe serialization + state persistence for orchestration structures.
+ *
+ * Two collaborators:
+ *
+ * - {@link serializeState} / {@link SerializableMixin} — a best-effort,
+ *   defensive object-to-dict serializer. Callables become `{name, doc}`
+ *   descriptors; objects exposing `toDict()` recurse; JSON-serializable values
+ *   pass through; everything else becomes a `<Non-serializable: Type>` marker.
+ *   An exclusion list lets subclasses skip sensitive/heavy fields.
+ *
+ * - {@link SafeStateManager} — saves/loads only *safe* (JSON-round-trippable)
+ *   fields of an object to disk, preserving live class-instance fields across a
+ *   load (they are never overwritten by the loaded state). Saves are atomic
+ *   (temp file + backup + rename) — a partial write never clobbers a good file.
+ */
+/** A callable serialized to a name/doc descriptor. */
+export interface CallableDescriptor {
+    name: string;
+    doc: string | null;
+}
+/** Anything exposing a `toDict()` method participates in nested serialization. */
+export interface HasToDict {
+    toDict(): Record<string, unknown>;
+}
+/** Serialize a single attribute value defensively (see module docs). */
+export declare function serializeAttr(value: unknown): unknown;
+/**
+ * Serialize an object's own enumerable fields to a plain dictionary, skipping
+ * any field listed in `exclude`.
+ */
+export declare function serializeState(obj: Record<string, unknown>, exclude?: ReadonlyArray<string>): Record<string, unknown>;
+/**
+ * Mixin-equivalent base providing a defensive `toDict()`.
+ *
+ * Subclasses set `_toDictExclude` to skip fields. Extend this class to inherit
+ * `toDict`.
+ */
+export declare class SerializableMixin {
+    /** Field names to omit from `toDict()`. Override in subclasses. */
+    protected _toDictExclude: ReadonlyArray<string>;
+    /** Serialize this instance's own enumerable fields to a plain dictionary. */
+    toDict(): Record<string, unknown>;
+}
+/**
+ * Is `value` a "safe" type — directly JSON-round-trippable without losing
+ * identity (primitives, null, arrays/dicts of safe values)?
+ */
+export declare function isSafeType(value: unknown): boolean;
+/** Is `value` a live class instance (not a plain object/primitive)? */
+export declare function isClassInstance(value: unknown): boolean;
+/** Collect the subset of an object's own fields that are safe to persist. */
+export declare function createStateDict(obj: Record<string, unknown>): Record<string, unknown>;
+/** Collect the object's own fields that are live class instances. */
+export declare function preserveInstances(obj: Record<string, unknown>): Record<string, unknown>;
+/**
+ * Saves and loads object state to/from JSON on disk, automatically handling
+ * complex/live-instance fields (they are preserved across a load, never
+ * clobbered by persisted data).
+ */
+export declare const SafeStateManager: {
+    /**
+     * Atomically save the object's safe state to `filePath`.
+     *
+     * Writes a temp file, backs up any existing file, then renames the temp into
+     * place so a crash mid-write never corrupts the target.
+     */
+    saveState(obj: Record<string, unknown>, filePath: string): Promise<void>;
+    /**
+     * Load persisted safe state into `obj`, preserving any live class-instance
+     * fields the object already holds.
+     */
+    loadState(obj: Record<string, unknown>, filePath: string): Promise<void>;
+};
+//# sourceMappingURL=serialization.d.ts.map

package/dist/serialization.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serialization.d.ts","sourceRoot":"","sources":["../src/serialization.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAKH,sDAAsD;AACtD,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,kFAAkF;AAClF,MAAM,WAAW,SAAS;IACxB,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAmBD,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAcrD;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC5B,OAAO,GAAE,aAAa,CAAC,MAAM,CAAM,GAClC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAQzB;AAED;;;;;GAKG;AACH,qBAAa,iBAAiB;IAC5B,mEAAmE;IACnE,SAAS,CAAC,cAAc,EAAE,aAAa,CAAC,MAAM,CAAC,CAAM;IAErD,6EAA6E;IAC7E,MAAM,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;CAGlC;AAID;;;GAGG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAalD;AAED,uEAAuE;AACvE,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAMvD;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOrF;AAED,qEAAqE;AACrE,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAOvF;AAED;;;;GAIG;AACH,eAAO,MAAM,gBAAgB;IAC3B;;;;;OAKG;mBACkB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAmB9E;;;OAGG;mBACkB,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,YAAY,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAqB/E,CAAC"}

package/dist/session-repo.d.ts

@@ -0,0 +1,90 @@
+import { type JsonlFile, Session } from "./session";
+/**
+ * A filesystem-backed {@link JsonlFile}: appends and reads lines to a real file
+ * on disk. Mirrors {@link StringJsonlFile}'s method contract (the sync model the
+ * session storage already uses) but persists via `node:fs`. Parent directories
+ * are created on first append.
+ */
+export declare class FileJsonlFile implements JsonlFile {
+    private readonly path;
+    private ensuredDir;
+    constructor(path: string);
+    /** Read the entire file, or "" when it does not exist yet. */
+    read(): string;
+    /** Append a line (the caller supplies the trailing newline). */
+    append(line: string): void;
+}
+/** Options for creating (or forking into) a new persisted session. */
+export interface SessionCreateOptions {
+    /** Reuse a specific session id instead of minting one. */
+    id?: string;
+    /** Working directory recorded in the session header. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Records the session this one descends from. */
+    parentSessionId?: string;
+}
+/** Options selecting the fork point within a source session. */
+export interface SessionForkOptions extends SessionCreateOptions {
+    /** Fork up to this entry. When omitted the whole session is copied. */
+    entryId?: string;
+    /**
+     * `"at"` keeps `entryId` on the new branch; `"before"` (the default) stops
+     * just before it — in which case `entryId` must be a user message, so the
+     * fork begins fresh from that user turn's parent.
+     */
+    position?: "before" | "at";
+}
+/** Per-session listing metadata surfaced by {@link SessionRepo.list}. */
+export interface SessionListEntry {
+    id: string;
+    /** Absolute path of the backing `.jsonl` file. */
+    path: string;
+    cwd: string;
+    /** Current session name, when one was recorded along the branch. */
+    name?: string;
+    /** Id of the session this one was forked from, when applicable. */
+    parentSessionId?: string;
+    /** Header timestamp (ms since epoch) — when the session was created. */
+    createdAt: number;
+    /** File mtime (ms since epoch) — when the session was last written. */
+    updatedAt: number;
+}
+/**
+ * A store of persisted sessions: create / open / list / delete, plus `fork`
+ * (branch a session into a new independent id that shares history up to a fork
+ * point). Faithfully shaped from the pi `SessionRepo`, AP3X-native (sessions are
+ * addressed by id, matching the one-file-per-id layout).
+ */
+export interface SessionRepo {
+    /** Mint a new session (id + backing file) and return it. */
+    create(options?: SessionCreateOptions): Session;
+    /** Load an existing session by id. Throws `not_found` when it is absent. */
+    open(id: string): Session;
+    /** List persisted sessions, newest first. Tolerates corrupt files. */
+    list(): SessionListEntry[];
+    /** Remove a session's backing file. A missing id is a no-op. */
+    delete(id: string): void;
+    /**
+     * Fork a session into a new independent id whose file shares history up to the
+     * fork point. Mutating either side afterwards never affects the other.
+     */
+    fork(id: string, options?: SessionForkOptions): Session;
+}
+/**
+ * A {@link SessionRepo} storing one `.jsonl` file per session id under a root
+ * directory (default `~/.ap3x/sessions`; injectable so tests use a temp dir).
+ */
+export declare class JsonlSessionRepo implements SessionRepo {
+    private readonly root;
+    constructor(options?: {
+        root?: string;
+    });
+    private pathFor;
+    private fileFor;
+    create(options?: SessionCreateOptions): Session;
+    open(id: string): Session;
+    list(): SessionListEntry[];
+    delete(id: string): void;
+    fork(id: string, options?: SessionForkOptions): Session;
+}
+//# sourceMappingURL=session-repo.d.ts.map

package/dist/session-repo.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-repo.d.ts","sourceRoot":"","sources":["../src/session-repo.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,KAAK,SAAS,EAEd,OAAO,EAIR,MAAM,WAAW,CAAC;AAEnB;;;;;GAKG;AACH,qBAAa,aAAc,YAAW,SAAS;IAEjC,OAAO,CAAC,QAAQ,CAAC,IAAI;IADjC,OAAO,CAAC,UAAU,CAAS;gBACE,IAAI,EAAE,MAAM;IAEzC,8DAA8D;IAC9D,IAAI,IAAI,MAAM;IASd,gEAAgE;IAChE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;CAS3B;AAED,sEAAsE;AACtE,MAAM,WAAW,oBAAoB;IACnC,0DAA0D;IAC1D,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,qFAAqF;IACrF,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,gEAAgE;AAChE,MAAM,WAAW,kBAAmB,SAAQ,oBAAoB;IAC9D,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,QAAQ,GAAG,IAAI,CAAC;CAC5B;AAED,yEAAyE;AACzE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAC;IACX,kDAAkD;IAClD,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,oEAAoE;IACpE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAC;IAClB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;CACnB;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,4DAA4D;IAC5D,MAAM,CAAC,OAAO,CAAC,EAAE,oBAAoB,GAAG,OAAO,CAAC;IAChD,4EAA4E;IAC5E,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC;IAC1B,sEAAsE;IACtE,IAAI,IAAI,gBAAgB,EAAE,CAAC;IAC3B,gEAAgE;IAChE,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;OAGG;IACH,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,kBAAkB,GAAG,OAAO,CAAC;CACzD;AA+BD;;;GAGG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,QAAQ,CAAC,IAAI,CAAS;gBAElB,OAAO,CAAC,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE;IAIvC,OAAO,CAAC,OAAO;IAIf,OAAO,CAAC,OAAO;IAIf,MAAM,CAAC,OAAO,GAAE,oBAAyB,GAAG,OAAO;IAUnD,IAAI,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO;IAOzB,IAAI,IAAI,gBAAgB,EAAE;IAmC1B,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI;IAIxB,IAAI,CAAC,EAAE,EAAE,MAAM,EAAE,OAAO,GAAE,kBAAuB,GAAG,OAAO;CAe5D"}