@ap3x/agent-core 0.1.0

package/dist/session.d.ts

@@ -0,0 +1,251 @@
+import type { ImageContent, TextContent } from "@ap3x/ai";
+import type { AgentMessage } from "./types";
+/** The kinds of entry that can appear in a session tree. */
+export type SessionEntryType = "message" | "compaction" | "model_change" | "label" | "leaf" | "thinking_level_change" | "active_tools_change" | "branch_summary" | "session_info" | "custom" | "custom_message";
+interface BaseEntry {
+    id: string;
+    parentId: string | null;
+    timestamp: number;
+    type: SessionEntryType;
+}
+/** A transcript message persisted into the tree. */
+export interface MessageEntry extends BaseEntry {
+    type: "message";
+    message: AgentMessage;
+}
+/** A compaction boundary: a summary replacing all history before a kept entry. */
+export interface CompactionEntry extends BaseEntry {
+    type: "compaction";
+    summary: string;
+    firstKeptEntryId: string;
+    tokensBefore: number;
+}
+/** A record that the model changed at this point in the conversation. */
+export interface ModelChangeEntry extends BaseEntry {
+    type: "model_change";
+    provider: string;
+    modelId: string;
+}
+/** A human-readable label attached to another entry. */
+export interface LabelEntry extends BaseEntry {
+    type: "label";
+    targetId: string;
+    label: string;
+}
+/** A leaf marker repointing the conversation head to an existing entry. */
+export interface LeafEntry extends BaseEntry {
+    type: "leaf";
+    targetId: string;
+}
+/** A record that the reasoning/thinking level changed at this point. */
+export interface ThinkingLevelChangeEntry extends BaseEntry {
+    type: "thinking_level_change";
+    thinkingLevel: string;
+}
+/** A record that the set of active tool names changed at this point. */
+export interface ActiveToolsChangeEntry extends BaseEntry {
+    type: "active_tools_change";
+    activeToolNames: string[];
+}
+/**
+ * A summary of a branch the conversation returned from. When present on the
+ * current path it is folded into the reconstructed context as a summary message.
+ */
+export interface BranchSummaryEntry<TDetails = unknown> extends BaseEntry {
+    type: "branch_summary";
+    /** The entry the conversation moved back to (or "root"). */
+    fromId: string;
+    summary: string;
+    details?: TDetails;
+    fromHook?: boolean;
+}
+/** Session-level metadata carried in the tree (currently the session name). */
+export interface SessionInfoEntry extends BaseEntry {
+    type: "session_info";
+    name?: string;
+}
+/** An arbitrary host-defined entry carrying a keyed, typed payload. */
+export interface CustomEntry<TData = unknown> extends BaseEntry {
+    type: "custom";
+    customType: string;
+    data?: TData;
+}
+/** A message-like host-defined entry with model-visible content. */
+export interface CustomMessageEntry<TDetails = unknown> extends BaseEntry {
+    type: "custom_message";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: TDetails;
+}
+export type SessionEntry = MessageEntry | CompactionEntry | ModelChangeEntry | LabelEntry | LeafEntry | ThinkingLevelChangeEntry | ActiveToolsChangeEntry | BranchSummaryEntry | SessionInfoEntry | CustomEntry | CustomMessageEntry;
+/** The reconstructed conversation state for a path through the tree. */
+export interface SessionContext {
+    messages: AgentMessage[];
+    /**
+     * The latest {@link CompactionEntry}'s summary along the branch, when one
+     * exists. Callers seeding a live run from this context thread it into the
+     * loop as `previousSummary` so the next compaction MERGES into it
+     * (UPDATE_SUMMARIZATION) instead of summarizing from scratch.
+     */
+    compactionSummary?: string;
+    model?: {
+        provider: string;
+        modelId: string;
+    };
+    /** Last thinking-level along the branch, if any was recorded. */
+    thinkingLevel?: string;
+    /** Last active-tool-name set along the branch, if any was recorded. */
+    activeToolNames?: string[];
+    /** Current session name (last non-empty `session_info` along the branch). */
+    sessionName?: string;
+}
+/** Persistence backend for a session tree. All ids are tree-unique. */
+export interface SessionStorage {
+    getMetadata(): SessionMetadata;
+    getLeafId(): string | null;
+    setLeafId(id: string | null): void;
+    createEntryId(): string;
+    appendEntry(entry: SessionEntry): void;
+    getEntry(id: string): SessionEntry | undefined;
+    getEntries(): SessionEntry[];
+    findEntries(type: SessionEntryType): SessionEntry[];
+    getLabel(id: string): string | undefined;
+    /** Root → leaf path of entries, throwing on a broken chain. */
+    getPathToRoot(leafId: string): SessionEntry[];
+}
+/** Header metadata for a session. */
+export interface SessionMetadata {
+    id: string;
+    timestamp: number;
+    cwd: string;
+    parentSessionId?: string;
+}
+/** Generate a fresh session id. */
+export declare function createSessionId(): string;
+/**
+ * Whether an entry produces a message in {@link buildSessionContext}'s
+ * reconstructed context: transcript messages plus non-empty branch summaries
+ * (folded in as synthetic user messages). Anchor arithmetic that aligns a
+ * compaction's kept-message suffix with branch entries MUST filter with this
+ * predicate — an inline re-derivation counting `message` entries alone lands
+ * the anchor one entry early whenever a branch-summary synthetic sits in the
+ * kept tail. buildSessionContext itself folds through this predicate, so the
+ * counting rule cannot drift apart from the folding rule.
+ */
+export declare function producesContextMessage(entry: SessionEntry): boolean;
+/** Pure reducer: collapse a root→leaf path into a {@link SessionContext}. */
+export declare function buildSessionContext(path: SessionEntry[]): SessionContext;
+/** A branchable session tree backed by a {@link SessionStorage}. */
+export declare class Session {
+    private readonly storage;
+    constructor(storage: SessionStorage);
+    getStorage(): SessionStorage;
+    getMetadata(): SessionMetadata;
+    getLeafId(): string | null;
+    getEntry(id: string): SessionEntry | undefined;
+    getEntries(): SessionEntry[];
+    getLabel(id: string): string | undefined;
+    /** The root→leaf path of entries for the current (or a given) leaf. */
+    getBranch(fromId?: string): SessionEntry[];
+    /** Reconstruct the conversation context from the current branch. */
+    buildContext(): SessionContext;
+    private appendUnder;
+    /** Append a transcript message under the current leaf. Returns the new id. */
+    appendMessage(message: AgentMessage): string;
+    /** Append a compaction boundary. Returns the new id. */
+    appendCompaction(summary: string, firstKeptEntryId: string, tokensBefore: number): string;
+    /** Record a model change at the current leaf. Returns the new id. */
+    appendModelChange(provider: string, modelId: string): string;
+    /** Attach a label to a target entry. Returns the new id. */
+    appendLabel(targetId: string, label: string): string;
+    /**
+     * Branch the conversation: repoint the leaf to an existing entry. Subsequent
+     * appends grow a new branch from that point. Returns the new leaf id.
+     */
+    branch(targetId: string): string;
+    /**
+     * Repoint the conversation head to an existing entry (or `null` to clear it),
+     * optionally recording a summary of the branch being left behind. When a
+     * summary is supplied the new leaf becomes that {@link BranchSummaryEntry}
+     * (parented to `entryId`) so it folds into the reconstructed context;
+     * otherwise the leaf is `entryId` itself. Returns the new branch-summary id,
+     * or `undefined` when no summary was recorded.
+     */
+    moveTo(entryId: string | null, summary?: {
+        summary: string;
+        details?: unknown;
+        fromHook?: boolean;
+    }): string | undefined;
+    /**
+     * Record (or update) the human-readable session name. Line breaks are
+     * collapsed to spaces and the value is trimmed. Returns the new id.
+     */
+    appendSessionName(name: string): string;
+}
+/** An in-memory session storage. Useful for tests and ephemeral sessions. */
+export declare class InMemorySessionStorage implements SessionStorage {
+    private readonly inner;
+    private readonly state;
+    constructor(options?: {
+        cwd?: string;
+        sessionId?: string;
+    });
+    getMetadata(): SessionMetadata;
+    getLeafId(): string | null;
+    setLeafId(id: string | null): void;
+    createEntryId(): string;
+    appendEntry(entry: SessionEntry): void;
+    getEntry(id: string): SessionEntry | undefined;
+    getEntries(): SessionEntry[];
+    findEntries(type: SessionEntryType): SessionEntry[];
+    getLabel(id: string): string | undefined;
+    getPathToRoot(leafId: string): SessionEntry[];
+}
+/** Minimal append-only file surface so JSONL storage stays env-agnostic. */
+export interface JsonlFile {
+    /** Read the entire file. Returns "" when it does not exist. */
+    read(): string;
+    /** Append a line (the caller supplies the trailing newline). */
+    append(line: string): void;
+}
+/**
+ * Append-only JSONL session storage. Line 1 is a session header; each later
+ * line is one tree entry. The leaf is recomputed after each entry: a `leaf`
+ * entry repoints to its `targetId`, otherwise the entry becomes the leaf.
+ */
+export declare class JsonlSessionStorage implements SessionStorage {
+    private readonly file;
+    private readonly state;
+    private readonly inner;
+    private constructor();
+    /** Create a brand-new JSONL session, writing the header line. */
+    static create(file: JsonlFile, options?: {
+        cwd?: string;
+        sessionId?: string;
+        parentSessionId?: string;
+    }): JsonlSessionStorage;
+    /** Open an existing JSONL session, replaying entries to rebuild the tree. */
+    static open(file: JsonlFile): JsonlSessionStorage;
+    getMetadata(): SessionMetadata;
+    getLeafId(): string | null;
+    setLeafId(id: string | null): void;
+    createEntryId(): string;
+    appendEntry(entry: SessionEntry): void;
+    getEntry(id: string): SessionEntry | undefined;
+    getEntries(): SessionEntry[];
+    findEntries(type: SessionEntryType): SessionEntry[];
+    getLabel(id: string): string | undefined;
+    getPathToRoot(leafId: string): SessionEntry[];
+}
+/** An in-memory {@link JsonlFile} for tests (no disk). */
+export declare class StringJsonlFile implements JsonlFile {
+    private buffer;
+    constructor(initial?: string);
+    read(): string;
+    append(line: string): void;
+    /** The current serialized contents (the JSONL text). */
+    toString(): string;
+}
+export {};
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

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

package/dist/shell-blocklist.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A cross-platform deny-list for shell commands. It rejects the most dangerous
+ * destructive operations across POSIX shells (bash/sh/zsh) AND Windows
+ * `cmd.exe` / PowerShell equivalents. This is a coarse safety net, not a
+ * sandbox: it raises the bar against accidental catastrophic commands while
+ * letting ordinary tooling through.
+ */
+export interface BlocklistMatch {
+    /** Human-readable reason the command was blocked. */
+    reason: string;
+    /** The pattern source that triggered the block. */
+    pattern: string;
+}
+/** Inspect a command; return a match when it is denied, or `undefined`. */
+export declare function matchBlocklist(command: string): BlocklistMatch | undefined;
+/** Convenience predicate over {@link matchBlocklist}. */
+export declare function isBlockedCommand(command: string): boolean;
+//# sourceMappingURL=shell-blocklist.d.ts.map

package/dist/shell-blocklist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"shell-blocklist.d.ts","sourceRoot":"","sources":["../src/shell-blocklist.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,cAAc;IAC7B,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,OAAO,EAAE,MAAM,CAAC;CACjB;AA6ED,2EAA2E;AAC3E,wBAAgB,cAAc,CAAC,OAAO,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS,CAQ1E;AAED,yDAAyD;AACzD,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAEzD"}

package/dist/skills.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Skills: model-facing skill primitives.
+ *
+ * A skill is a Markdown file whose YAML frontmatter carries metadata (`name`,
+ * `description`) and whose body is the full instructions. Skills reach the model
+ * through progressive disclosure: a compact `<available_skills>` catalog (name /
+ * description / location) is placed in the system prompt via the S1 skills slot,
+ * and the model loads a skill's full body from its file with the read tool on
+ * demand when a task matches its description.
+ *
+ * This module is a standalone runtime primitive. It reuses
+ * {@link parseYamlFrontmatter} for the frontmatter split (loader.ts) and mirrors
+ * the {@link AgentRegistry} shape for the name-keyed store. Parsing is pure —
+ * deterministic, with no clock or randomness. A host composes the catalog into a
+ * system prompt with S1:
+ *
+ *   builder.section(SYSTEM_PROMPT_SECTIONS.skills, formatSkillsForSystemPrompt(skills));
+ */
+/** A skill: named instructions the model can load on demand. */
+export interface Skill {
+    /** Identifier — frontmatter `name`, else the file basename (without `.md`). */
+    name: string;
+    /** Short description shown in the catalog so the model can match a task to it. */
+    description: string;
+    /** Source file path; shown in the catalog for the model to read on demand. */
+    location: string;
+    /** Full skill instructions (the Markdown body). */
+    body: string;
+    /**
+     * When true the skill is hidden from the model-facing catalog
+     * ({@link formatSkillsForSystemPrompt}) — it is invoked explicitly, never by
+     * the model.
+     */
+    disableModelInvocation?: boolean;
+}
+/**
+ * Parse Markdown skill content into a {@link Skill}. Pure — no filesystem access.
+ *
+ * The frontmatter is split via {@link parseYamlFrontmatter}. The name is the
+ * frontmatter `name` when present, otherwise `fallbackName` (the loader passes
+ * the file basename). The description is the frontmatter `description` (else an
+ * empty string). The trimmed body becomes {@link Skill.body}.
+ * {@link Skill.disableModelInvocation} reflects the frontmatter
+ * `disable-model-invocation` flag.
+ */
+export declare function parseSkill(fallbackName: string, content: string, location: string): Skill;
+/**
+ * Load a Markdown skill file. The name falls back to the file's basename without
+ * the `.md` suffix (a frontmatter `name` overrides it); {@link Skill.location} is
+ * the file path.
+ */
+export declare function loadSkill(filePath: string): Promise<Skill>;
+/** Load several skill files (concurrently), preserving input order. */
+export declare function loadSkills(filePaths: string[]): Promise<Skill[]>;
+/**
+ * Finds skill files under `dir`: `<dir>/<name>/SKILL.md` and flat `<dir>/<name>.md`.
+ * Missing/unreadable dir returns []. Sorted for determinism.
+ */
+export declare function discoverSkillFiles(dir: string): Promise<string[]>;
+/**
+ * Loads every discovered skill. SKILL.md files fall back to their directory name;
+ * a loose SKILL.md in the scanned root falls back to "SKILL". Unreadable files are
+ * skipped; symlinked entries are not followed.
+ */
+export declare function discoverSkills(dir: string): Promise<Skill[]>;
+/** A name-keyed store of {@link Skill}s (mirrors the AgentRegistry shape). */
+export declare class SkillRegistry {
+    private readonly skills;
+    constructor(options?: {
+        skills?: Skill[];
+    });
+    /** Add a skill. Throws if the name is already registered. */
+    add(skill: Skill): void;
+    /** Add several skills. */
+    addMany(skills: Skill[]): void;
+    /** Get a skill by name. Throws if it does not exist. */
+    get(name: string): Skill;
+    /** Find a skill by name (undefined if absent). */
+    find(name: string): Skill | undefined;
+    /** List all registered skills. */
+    list(): Skill[];
+    /** Filter skills by a predicate (or return all when omitted). */
+    query(condition?: (skill: Skill) => boolean): Skill[];
+    /** Number of registered skills. */
+    get size(): number;
+}
+/**
+ * Build the `<available_skills>` catalog string for the system prompt (the S1
+ * `skills` slot). Each visible skill contributes its name, description, and
+ * location. Skills flagged {@link Skill.disableModelInvocation} are filtered out
+ * so the model is never told to invoke them. Returns `""` when there is nothing
+ * to show (empty input, or every skill filtered) so S1 omits the slot cleanly.
+ */
+export declare function formatSkillsForSystemPrompt(skills: readonly Skill[]): string;
+//# sourceMappingURL=skills.d.ts.map

package/dist/skills.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"skills.d.ts","sourceRoot":"","sources":["../src/skills.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAOH,gEAAgE;AAChE,MAAM,WAAW,KAAK;IACpB,+EAA+E;IAC/E,IAAI,EAAE,MAAM,CAAC;IACb,kFAAkF;IAClF,WAAW,EAAE,MAAM,CAAC;IACpB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;CAClC;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,KAAK,CAYzF;AAED;;;;GAIG;AACH,wBAAsB,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,CAIhE;AAED,uEAAuE;AACvE,wBAAsB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAEtE;AAED;;;GAGG;AACH,wBAAsB,kBAAkB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAuBvE;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,KAAK,EAAE,CAAC,CAmBlE;AAID,8EAA8E;AAC9E,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA4B;gBAEvC,OAAO,GAAE;QAAE,MAAM,CAAC,EAAE,KAAK,EAAE,CAAA;KAAO;IAI9C,6DAA6D;IAC7D,GAAG,CAAC,KAAK,EAAE,KAAK,GAAG,IAAI;IAOvB,0BAA0B;IAC1B,OAAO,CAAC,MAAM,EAAE,KAAK,EAAE,GAAG,IAAI;IAI9B,wDAAwD;IACxD,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK;IAMxB,kDAAkD;IAClD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,KAAK,GAAG,SAAS;IAIrC,kCAAkC;IAClC,IAAI,IAAI,KAAK,EAAE;IAIf,iEAAiE;IACjE,KAAK,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,KAAK,KAAK,OAAO,GAAG,KAAK,EAAE;IAKrD,mCAAmC;IACnC,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AASD;;;;;;GAMG;AACH,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,MAAM,CAc5E"}

package/dist/system-prompt.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Composable system-prompt assembly.
+ *
+ * A runtime-level primitive for building the final `systemPrompt` string from an
+ * ordered list of NAMED sections. Any agent (not just a coding agent) composes
+ * its system prompt from the same standard slots: a base/persona section, an
+ * optional custom section, a skills-catalog slot (filled by the skills
+ * subsystem), and an environment section (date + working directory) that agents
+ * conventionally place last.
+ *
+ * Assembly is pure section concatenation — there is no template interpolation
+ * here; reusable prompt templates + variable substitution are a separate
+ * utility. This module only orders sections, omits empty ones cleanly, and
+ * renders deterministically.
+ *
+ * Additive: the produced string feeds the existing `systemPrompt` option. The
+ * builder is an optional producer of that string; nothing that already sets
+ * `systemPrompt` directly is affected.
+ */
+/** One named part of a system prompt. Empty/whitespace-only/absent → omitted. */
+export interface SystemPromptSection {
+    /** Section identifier (for the standard slots and for later lookup). */
+    name: string;
+    /** Section body. Absent or blank after trimming means the section is omitted. */
+    content?: string;
+}
+/** Options controlling how sections are joined. */
+export interface AssembleSystemPromptOptions {
+    /** Separator inserted between rendered sections. Default: a blank line. */
+    separator?: string;
+}
+/**
+ * The standard section slots an agent's system prompt is assembled from. The
+ * skills catalog is a general slot the skills subsystem fills; it renders as an
+ * empty (omitted) section until then.
+ */
+export declare const SYSTEM_PROMPT_SECTIONS: {
+    /** Base persona / role instructions. */
+    readonly persona: "persona";
+    /** Caller-supplied extra instructions appended to the base. */
+    readonly custom: "custom";
+    /** Skills catalog slot — filled by the skills subsystem. */
+    readonly skills: "skills";
+    /** Runtime environment: current date + working directory (placed last). */
+    readonly environment: "environment";
+};
+/** A standard section slot name. */
+export type SystemPromptSectionName = (typeof SYSTEM_PROMPT_SECTIONS)[keyof typeof SYSTEM_PROMPT_SECTIONS];
+/**
+ * Assemble a system-prompt string from ordered named sections.
+ *
+ * Sections render in the given order. Empty, whitespace-only, or content-less
+ * sections are omitted with no stray separator. Each section's outer whitespace
+ * is trimmed so the join is clean and the render is deterministic (identical
+ * input → identical string).
+ */
+export declare function assembleSystemPrompt(sections: readonly SystemPromptSection[], options?: AssembleSystemPromptOptions): string;
+/**
+ * A small chainable builder over {@link assembleSystemPrompt}. Register named
+ * sections in order, then `render()`. Adding an empty/absent section reserves
+ * its ordered slot without emitting anything (e.g. a `skills` slot the skills
+ * subsystem fills later).
+ */
+export declare class SystemPromptBuilder {
+    private readonly sections;
+    private readonly separator;
+    constructor(options?: AssembleSystemPromptOptions);
+    /** Append a named section in order. Chainable. */
+    section(name: string, content?: string): this;
+    /** Render the accumulated sections to a single system-prompt string. */
+    render(): string;
+}
+/** Inputs for the environment section. */
+export interface EnvironmentSectionInput {
+    /** Current working directory (backslashes normalized to `/` on render). */
+    cwd?: string;
+    /**
+     * The date to stamp — REQUIRED so this section is a pure function of its
+     * inputs (deterministic). The caller supplies the current time at the call
+     * site, or a fixed date; the library never reads the wall clock itself.
+     */
+    date: Date;
+}
+/**
+ * Build the environment section (current date + working directory) that agents
+ * conventionally place last in the system prompt. The date is stamped as
+ * `YYYY-MM-DD`; the working-directory line is omitted when no `cwd` is given.
+ */
+export declare function environmentSection(input: EnvironmentSectionInput): SystemPromptSection;
+//# sourceMappingURL=system-prompt.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.d.ts","sourceRoot":"","sources":["../src/system-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,iFAAiF;AACjF,MAAM,WAAW,mBAAmB;IAClC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,iFAAiF;IACjF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED,mDAAmD;AACnD,MAAM,WAAW,2BAA2B;IAC1C,2EAA2E;IAC3E,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAKD;;;;GAIG;AACH,eAAO,MAAM,sBAAsB;IACjC,wCAAwC;;IAExC,+DAA+D;;IAE/D,4DAA4D;;IAE5D,2EAA2E;;CAEnE,CAAC;AAEX,oCAAoC;AACpC,MAAM,MAAM,uBAAuB,GACjC,CAAC,OAAO,sBAAsB,CAAC,CAAC,MAAM,OAAO,sBAAsB,CAAC,CAAC;AAQvE;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,SAAS,mBAAmB,EAAE,EACxC,OAAO,GAAE,2BAAgC,GACxC,MAAM,CAQR;AAED;;;;;GAKG;AACH,qBAAa,mBAAmB;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA6B;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,OAAO,GAAE,2BAAgC;IAIrD,kDAAkD;IAClD,OAAO,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAK7C,wEAAwE;IACxE,MAAM,IAAI,MAAM;CAGjB;AAED,0CAA0C;AAC1C,MAAM,WAAW,uBAAuB;IACtC,2EAA2E;IAC3E,GAAG,CAAC,EAAE,MAAM,CAAC;IACb;;;;OAIG;IACH,IAAI,EAAE,IAAI,CAAC;CACZ;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,uBAAuB,GAAG,mBAAmB,CAUtF"}

package/dist/tools.d.ts

@@ -0,0 +1,61 @@
+import { type AssistantMessage, type TSchema, type ToolCall, type ToolResultMessage } from "@ap3x/ai";
+import type { AgentContext, AgentHooks, AgentToolResult, AgentToolUpdate, AnyAgentTool } from "./types";
+/**
+ * Declare a tool from a plain object. The `parameters` schema is a TypeBox
+ * `TSchema` (re-exported from `@ap3x/ai` as `Type`), validated and coerced
+ * before `execute` runs.
+ */
+export declare function defineTool<TParameters extends TSchema, TDetails = unknown>(spec: {
+    name: string;
+    description: string;
+    parameters: TParameters;
+    label?: string;
+    executionMode?: "sequential" | "parallel";
+    prepareArguments?: (rawArguments: Record<string, unknown>) => Record<string, unknown>;
+    execute: (toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal, onUpdate?: (update: AgentToolUpdate<TDetails>) => void) => Promise<AgentToolResult<TDetails>> | AgentToolResult<TDetails>;
+}): AnyAgentTool;
+export interface ToolBatchResult {
+    /** Tool-result messages in source order (matching the tool-call order). */
+    messages: ToolResultMessage[];
+    /** True when EVERY result in the batch requested termination. */
+    terminate: boolean;
+}
+export interface ExecuteToolCallsOptions {
+    toolCalls: ToolCall[];
+    tools: AnyAgentTool[];
+    hooks?: AgentHooks;
+    signal?: AbortSignal;
+    /** "sequential" or "parallel". Any per-tool sequential mode forces sequential. */
+    mode?: "sequential" | "parallel";
+    /** The assistant message that requested this batch (enriches the hook context). */
+    assistantMessage?: AssistantMessage;
+    /** The loop's working context at batch time (enriches the hook context). */
+    context?: AgentContext;
+    emit: (event: ToolExecutionEvent) => void | Promise<void>;
+}
+/** Events emitted during tool execution, forwarded by the loop to its sink. */
+export type ToolExecutionEvent = {
+    type: "tool_execution_start";
+    toolCallId: string;
+    toolName: string;
+    args: Record<string, unknown>;
+} | {
+    type: "tool_execution_update";
+    toolCallId: string;
+    toolName: string;
+    update: AgentToolUpdate;
+} | {
+    type: "tool_execution_end";
+    toolCallId: string;
+    toolName: string;
+    result: ToolResultMessage;
+    isError: boolean;
+};
+/**
+ * Execute a batch of tool calls. Sequential mode preserves strict order and
+ * breaks early on abort. Parallel mode runs all ready calls concurrently but
+ * emits `tool_execution_end` and the result messages in SOURCE order so the
+ * transcript stays deterministic.
+ */
+export declare function executeToolCalls(options: ExecuteToolCallsOptions): Promise<ToolBatchResult>;
+//# sourceMappingURL=tools.d.ts.map

package/dist/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,OAAO,EACZ,KAAK,QAAQ,EACb,KAAK,iBAAiB,EAEvB,MAAM,UAAU,CAAC;AAGlB,OAAO,KAAK,EAEV,YAAY,EACZ,UAAU,EACV,eAAe,EACf,eAAe,EACf,YAAY,EAEb,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,WAAW,SAAS,OAAO,EAAE,QAAQ,GAAG,OAAO,EAAE,IAAI,EAAE;IAChF,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,EAAE,WAAW,CAAC;IACxB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,aAAa,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IAC1C,gBAAgB,CAAC,EAAE,CAAC,YAAY,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtF,OAAO,EAAE,CACP,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,MAAM,CAAC,EAAE,WAAW,EACpB,QAAQ,CAAC,EAAE,CAAC,MAAM,EAAE,eAAe,CAAC,QAAQ,CAAC,KAAK,IAAI,KACnD,OAAO,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC,GAAG,eAAe,CAAC,QAAQ,CAAC,CAAC;CACrE,GAAG,YAAY,CAEf;AAyJD,MAAM,WAAW,eAAe;IAC9B,2EAA2E;IAC3E,QAAQ,EAAE,iBAAiB,EAAE,CAAC;IAC9B,iEAAiE;IACjE,SAAS,EAAE,OAAO,CAAC;CACpB;AAED,MAAM,WAAW,uBAAuB;IACtC,SAAS,EAAE,QAAQ,EAAE,CAAC;IACtB,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,KAAK,CAAC,EAAE,UAAU,CAAC;IACnB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,kFAAkF;IAClF,IAAI,CAAC,EAAE,YAAY,GAAG,UAAU,CAAC;IACjC,mFAAmF;IACnF,gBAAgB,CAAC,EAAE,gBAAgB,CAAC;IACpC,4EAA4E;IAC5E,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,IAAI,EAAE,CAAC,KAAK,EAAE,kBAAkB,KAAK,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC3D;AAED,+EAA+E;AAC/E,MAAM,MAAM,kBAAkB,GAC1B;IACE,IAAI,EAAE,sBAAsB,CAAC;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAC/B,GACD;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,UAAU,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,eAAe,CAAA;CAAE,GAChG;IACE,IAAI,EAAE,oBAAoB,CAAC;IAC3B,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,iBAAiB,CAAC;IAC1B,OAAO,EAAE,OAAO,CAAC;CAClB,CAAC;AAiDN;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,OAAO,EAAE,uBAAuB,GAAG,OAAO,CAAC,eAAe,CAAC,CAkDjG"}