@ap3x/agent-core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,320 @@
+import type { AssistantMessage, AssistantMessageEvent, Context, ImageContent, Message, Model, SimpleStreamOptions, StopReason, TSchema, TextContent, Tool, ToolCall, ToolResultMessage, Usage } from "@ap3x/ai";
+import type { CompactionSettings } from "./compaction";
+/**
+ * Extensible interface for host-defined custom message types. A host adds its
+ * own transcript message types by declaration-merging into this interface:
+ *
+ * ```ts
+ * declare module "@ap3x/agent-core" {
+ *   interface CustomAgentMessages {
+ *     note: { role: "note"; text: string; timestamp: number };
+ *   }
+ * }
+ * ```
+ *
+ * Empty by default, so `CustomAgentMessages[keyof CustomAgentMessages]` is
+ * `never` and {@link AgentMessage} stays exactly the `@ap3x/ai` {@link Message}
+ * union until a host augments it. A host that adds a custom type is responsible
+ * for mapping it down to a standard `Message` via
+ * {@link AgentHooks.convertToLlm} before the provider is called.
+ */
+export interface CustomAgentMessages {
+}
+/**
+ * A message in an agent transcript: the `@ap3x/ai` {@link Message} union
+ * (`user` | `assistant` | `toolResult`) plus any host-defined custom message
+ * types registered through {@link CustomAgentMessages}. With no augmentation
+ * this is exactly {@link Message}.
+ */
+export type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
+/** Provider-agnostic reasoning intensity used across the agent surface. */
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh";
+/** A snapshot of everything the loop needs to produce the next assistant turn. */
+export interface AgentContext {
+    systemPrompt?: string;
+    messages: AgentMessage[];
+    tools?: Tool[];
+}
+/** The structured payload a tool returns from {@link AgentTool.execute}. */
+export interface AgentToolResult<TDetails = unknown> {
+    /** Model-visible content blocks for the resulting `toolResult` message. */
+    content: (TextContent | ImageContent)[];
+    /** Structured, non-model-visible payload preserved on the message. */
+    details?: TDetails;
+    /** When true, signals the loop should stop after this batch (see batch rule). */
+    terminate?: boolean;
+    /** Marks the tool result as an error result. */
+    isError?: boolean;
+}
+/** A partial result streamed mid-execution via the `onUpdate` callback. */
+export type AgentToolUpdate<TDetails = unknown> = Partial<AgentToolResult<TDetails>>;
+/**
+ * A callable tool the agent can invoke. Extends the `@ap3x/ai` {@link Tool}
+ * (name + description + TypeBox/JSON-schema parameters) with an executor.
+ */
+export interface AgentTool<TParameters extends TSchema = TSchema, TDetails = unknown> extends Tool<TParameters> {
+    /** Optional human-friendly label for UIs/logs. */
+    label?: string;
+    /** Force this tool to run sequentially even when the batch is parallel. */
+    executionMode?: "sequential" | "parallel";
+    /**
+     * Reshape raw model-provided arguments before validation. Only the returned
+     * object is used when it differs by reference from the input (identity check).
+     */
+    prepareArguments?: (rawArguments: Record<string, unknown>) => Record<string, unknown>;
+    /** Run the tool. Throwing is allowed; the loop wraps throws into error results. */
+    execute: (toolCallId: string, args: Record<string, unknown>, signal?: AbortSignal, onUpdate?: (update: AgentToolUpdate<TDetails>) => void) => Promise<AgentToolResult<TDetails>> | AgentToolResult<TDetails>;
+}
+/** Any registered tool, regardless of its parameter schema / details type. */
+export type AnyAgentTool = AgentTool<TSchema, unknown>;
+/**
+ * How a host-queued pending message is delivered to a live (or next) run.
+ * - `steer`: inject mid-run at the next turn boundary — before the next
+ *   assistant turn streams. A steer left in the queue at the final turn (queued
+ *   after that turn's steering drain) is rescued as a follow-up so it still
+ *   extends the run instead of being dropped.
+ * - `followUp`: extend the run once it would otherwise stop.
+ * - `nextTurn`: at the Agent level this shares the follow-up drain (delivered
+ *   when the run would stop), but is tagged distinctly so a host/harness can
+ *   layer richer next-prompt semantics on top (see P28b-2).
+ */
+export type QueueMode = "steer" | "followUp" | "nextTurn";
+/** Lifecycle + streaming events emitted by the loop. */
+export type AgentEvent = {
+    type: "agent_start";
+} | {
+    type: "agent_end";
+    messages: AgentMessage[];
+} | {
+    /**
+     * The Agent's pending message queue changed (a `steer`/`followUp`/
+     * `nextTurn` was enqueued, or entries were drained into a run). Each array
+     * is a snapshot of the messages still queued under that mode. Emitted only
+     * when the queue actually changes, so a run that never touches the queue
+     * stays byte-identical.
+     */
+    type: "queue_update";
+    steer: AgentMessage[];
+    followUp: AgentMessage[];
+    nextTurn: AgentMessage[];
+} | {
+    type: "turn_start";
+} | {
+    type: "turn_end";
+    message: AssistantMessage;
+    toolResults: ToolResultMessage[];
+} | {
+    /**
+     * A mid-run compaction was swapped into the working context. Emitted once
+     * per successful swap (SOFT and HARD paths alike) so a host can persist a
+     * durable compaction boundary. The two counts are swap-time snapshots: a
+     * persister must re-derive the kept count at persist time as
+     * `retainedAtSwap + (finalNewMessageCount - newMessagesAtSwap)`, because
+     * new messages keep arriving after the swap.
+     */
+    type: "compaction";
+    summary: string;
+    tokensBefore: number;
+    /** Real messages kept in the working context at swap time (excludes the synthetic summary message). */
+    retainedAtSwap: number;
+    /** The run's new-message count at swap time. */
+    newMessagesAtSwap: number;
+} | {
+    type: "message_start";
+    message: AgentMessage;
+} | {
+    type: "message_update";
+    message: AssistantMessage;
+    assistantMessageEvent: AssistantMessageEvent;
+} | {
+    type: "message_end";
+    message: AgentMessage;
+} | {
+    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;
+};
+/** Sink the loop drives with each {@link AgentEvent}; may be async. */
+export type AgentEventSink = (event: AgentEvent) => void | Promise<void>;
+/** The function that turns a model + context into a streamed assistant message. */
+export type StreamFn = (model: Model<string>, context: Context, options?: SimpleStreamOptions) => import("@ap3x/ai").AssistantMessageEventStream;
+/** Decision returned by {@link AgentHooks.beforeToolCall} to gate a tool. */
+export interface ToolCallGate {
+    block?: boolean;
+    reason?: string;
+    /**
+     * Replacement arguments adopted for the execution. Re-validated against the
+     * tool's schema; a failing rewrite becomes an isError tool result and the
+     * tool does not run.
+     */
+    updatedArgs?: Record<string, unknown>;
+}
+/**
+ * Rich context handed to {@link AgentHooks.beforeToolCall} as an optional
+ * trailing argument. It is additive — the leading positional args are kept for
+ * backward compatibility — and is supplied only when the loop drives the call.
+ */
+export interface BeforeToolCallContext {
+    /** The assistant message that requested this tool call. */
+    assistantMessage: AssistantMessage;
+    /** The raw tool-call block from the assistant message. */
+    toolCall: ToolCall;
+    /** Validated tool arguments (post-schema coercion). */
+    args: Record<string, unknown>;
+    /** The loop's working context at the moment the call is prepared. */
+    agentContext: AgentContext;
+    /** The run's abort signal; the hook is responsible for honoring it. */
+    signal?: AbortSignal;
+}
+/**
+ * Rich context handed to {@link AgentHooks.afterToolCall} as an optional
+ * trailing argument (additive). Extends the before-context with the executed
+ * result and its current error flag.
+ */
+export interface AfterToolCallContext {
+    /** The assistant message that requested this tool call. */
+    assistantMessage: AssistantMessage;
+    /** The raw tool-call block from the assistant message. */
+    toolCall: ToolCall;
+    /** Validated tool arguments (post-schema coercion). */
+    args: Record<string, unknown>;
+    /** The executed tool result before any `afterToolCall` overrides. */
+    result: AgentToolResult;
+    /** Whether the executed result is currently treated as an error. */
+    isError: boolean;
+    /** The loop's working context at the moment the call is finalized. */
+    agentContext: AgentContext;
+    /** The run's abort signal; the hook is responsible for honoring it. */
+    signal?: AbortSignal;
+}
+/** Hooks that can observe and patch loop behaviour. All are optional. */
+export interface AgentHooks {
+    /**
+     * Prune/replace the message list before it is sent to the provider. May
+     * return a promise (awaited) and receives the run's abort signal, so a host
+     * can run async/LLM-backed compaction here. Existing sync hooks keep working.
+     */
+    transformContext?: (messages: AgentMessage[], signal?: AbortSignal) => AgentMessage[] | Promise<AgentMessage[]>;
+    /**
+     * Convert the transcript into the LLM-domain message list handed to the
+     * provider. Applied AFTER {@link transformContext}, as the final step before
+     * the model call — the seam where a host maps its own transcript messages
+     * (e.g. host-specific/custom message types) down to standard `@ap3x/ai`
+     * {@link Message}s. Return the messages the model should see. When this hook
+     * is absent the (already transformed) transcript passes straight through, so
+     * the provider context is byte-identical without it.
+     */
+    convertToLlm?: (messages: AgentMessage[]) => Message[] | Promise<Message[]>;
+    /**
+     * Inspect/gate a tool call before it runs; return `{block, reason}` to block.
+     * The optional trailing `context` carries the assistant message, raw tool
+     * call, validated args, the working {@link AgentContext} and the abort signal
+     * (present when the loop drives the call).
+     */
+    beforeToolCall?: (toolName: string, args: Record<string, unknown>, toolCallId: string, context?: BeforeToolCallContext) => ToolCallGate | undefined | Promise<ToolCallGate | undefined>;
+    /**
+     * Patch a tool result after it runs. Returned fields override field-by-field.
+     * The optional trailing `context` mirrors {@link AfterToolCallContext}.
+     */
+    afterToolCall?: (toolName: string, result: AgentToolResult, toolCallId: string, context?: AfterToolCallContext) => Partial<AgentToolResult> | undefined | Promise<Partial<AgentToolResult> | undefined>;
+    /** Observe each completed assistant message. */
+    onResponse?: (message: AssistantMessage) => void | Promise<void>;
+    /**
+     * Resolve an API key per model call. Consulted once before each provider
+     * request so a host can supply a freshly-minted short-lived key (e.g. an
+     * expiring Copilot token). Return `undefined` to fall back to the default
+     * auth resolution. When this hook is absent behaviour is unchanged.
+     */
+    getApiKey?: (provider: string) => string | undefined | Promise<string | undefined>;
+    /**
+     * Supply steering messages to inject mid-run. Consulted once at each turn
+     * boundary — before the next assistant turn streams — so returned messages
+     * enter the working context and the transcript ahead of that turn. Return
+     * `[]` to inject nothing (no busy-loop or re-injection). The loop does not
+     * consult this once the run is aborting. When this hook is absent behaviour
+     * is unchanged.
+     */
+    getSteeringMessages?: () => AgentMessage[] | Promise<AgentMessage[]>;
+    /**
+     * Supply follow-up messages when the loop would otherwise stop — an assistant
+     * turn requesting no tools, or a terminating tool batch. Non-empty messages
+     * become the next user turn and the loop continues (post-stop extension); `[]`
+     * lets the loop stop as before. `maxLoops` still bounds the run, and an
+     * error/aborted stop is never extended. When this hook is absent behaviour is
+     * unchanged.
+     */
+    getFollowUpMessages?: () => AgentMessage[] | Promise<AgentMessage[]>;
+    /**
+     * PreCompact veto. Consulted just before the loop would LAUNCH a compaction
+     * (hard or soft tier). Return `{ defer: true }` to skip launching this turn
+     * (re-consulted next turn; at the hard tier the run proceeds un-compacted at
+     * the host's risk). An already-launched in-flight compaction still applies.
+     * A throwing hook never blocks compaction. Absent = unchanged behaviour.
+     */
+    beforeCompaction?: () => {
+        defer?: boolean;
+    } | undefined | Promise<{
+        defer?: boolean;
+    } | undefined>;
+}
+/** Tunable configuration for one run of the loop. */
+export interface AgentLoopConfig {
+    model: Model<string>;
+    systemPrompt?: string;
+    tools?: AnyAgentTool[];
+    /** Reasoning level forwarded to the provider's simple entry point. */
+    reasoning?: Exclude<ThinkingLevel, "off">;
+    /**
+     * Hard cap on assistant turns; the loop stops once reached. Defaults to a
+     * high, non-truncating guard (see `DEFAULT_MAX_LOOPS`) so legitimate long
+     * tool runs aren't silently cut. Set a low number to cap explicitly, or
+     * `Infinity` to disable the guard entirely (an uncapped loop).
+     */
+    maxLoops?: number;
+    /** Sequential or parallel tool execution. Default: "parallel". */
+    toolExecution?: "sequential" | "parallel";
+    /** Per-call provider options merged into the stream request. */
+    streamOptions?: SimpleStreamOptions;
+    /** Hooks observing/patching the loop. */
+    hooks?: AgentHooks;
+    /** Provider entry point. Default: `@ap3x/ai` `streamSimple`. */
+    streamFn?: StreamFn;
+    /** Auto-compaction tunables. Absent → DEFAULT_COMPACTION_SETTINGS (enabled). */
+    compaction?: CompactionSettings;
+    /**
+     * Summary of a PRIOR compaction (e.g. the durable CompactionEntry a resumed
+     * session was seeded from). Seeds the loop's summary threading so this run's
+     * FIRST compaction merges into it (UPDATE_SUMMARIZATION) rather than
+     * re-summarizing the seeded summary message as ordinary text.
+     */
+    previousSummary?: string;
+    /** Test seam: override the summary-generation call (mirrors compact()'s `complete`). */
+    compactionComplete?: (model: Model<string>, context: Context, options?: SimpleStreamOptions) => Promise<AssistantMessage>;
+    /**
+     * Chooses the model per assistant turn. Return undefined to use `model`. Precedence: turn > config.
+     * Affects only the assistant-response stream: compaction (context-window tiering and summarization)
+     * always uses the static `model`.
+     */
+    selectModel?: (info: ModelSelectionInfo) => AgentLoopConfig["model"] | undefined;
+}
+/** Input to AgentLoopConfig.selectModel — one call per assistant turn. */
+export interface ModelSelectionInfo {
+    /** 0-based assistant turn counter for this run. */
+    turn: number;
+    /** Current working transcript (read-only). */
+    messages: readonly AgentMessage[];
+}
+export type { AssistantMessage, StopReason, ToolCall, ToolResultMessage, Usage };
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/uuid.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A dependency-free, time-ordered, monotonic UUIDv7 generator.
+ *
+ * UUIDv7 packs a 48-bit Unix-millisecond timestamp into the high bytes, which
+ * makes the resulting string lexically sortable by creation time. To keep ids
+ * unique and ordered even when many are minted within the same millisecond, we
+ * carry a monotonic counter that increments while the clock is frozen, and only
+ * reseed it from fresh randomness once the millisecond advances.
+ */
+/** Generate a monotonic, sortable UUIDv7 string. */
+export declare function uuidv7(): string;
+/**
+ * A short, collision-checked id derived from a {@link uuidv7}.
+ *
+ * Takes the id's trailing (random) hex, NOT the leading hex: a uuidv7 begins
+ * with a 48-bit millisecond timestamp, so two ids minted in the same
+ * millisecond share an identical prefix. Front-slicing would make every
+ * candidate in a millisecond identical — silently colliding when no `existing`
+ * set is given, and defeating the retry loop when one is. Slicing the random
+ * tail gives genuine intra-millisecond entropy.
+ */
+export declare function shortId(existing?: ReadonlySet<string>, length?: number): string;
+//# sourceMappingURL=uuid.d.ts.map

package/dist/uuid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uuid.d.ts","sourceRoot":"","sources":["../src/uuid.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAoBH,oDAAoD;AACpD,wBAAgB,MAAM,IAAI,MAAM,CAkD/B;AAED;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,QAAQ,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,SAAI,GAAG,MAAM,CAM1E"}

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ap3x/agent-core",
+  "version": "0.1.0",
+  "description": "Agent loop, tool calling, sessions, compaction, and the AgentBackend interface",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AP3X-Dev/AP3X.git",
+    "directory": "packages/agent-core"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --clean --tsconfig tsconfig.build.json && tsc -p tsconfig.build.json",
+    "prepublishOnly": "node ../../scripts/publish-gate.mjs",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@ap3x/ai": "0.1.0",
+    "yaml": "^2.9.0"
+  }
+}