ultracode-shared 1.3.0

package/dist/types/events.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Event-bus contracts.
+ *
+ * UltraCode is event-driven: subsystems publish typed {@link UltraCodeEvent}s
+ * onto an {@link IEventBus}. Events are a discriminated union keyed by `type`.
+ * The concrete {@link import("../events/EventBus.js").EventBus} implementation
+ * isolates handler failures so one bad subscriber cannot break others.
+ */
+import type { SerializedError } from "../errors.js";
+import type { VersionSuggestion } from "./versioning.js";
+/** A tool finished executing. */
+export interface ToolExecutedEvent {
+    type: "tool.executed";
+    /** Name of the executed tool. */
+    toolName: string;
+    /** Whether the execution succeeded. */
+    ok: boolean;
+    /** Execution wall-clock time in milliseconds. */
+    durationMs: number;
+}
+/** The active agent changed. */
+export interface AgentSwitchedEvent {
+    type: "agent.switched";
+    /** Previous agent name (`null` at startup). */
+    from: string | null;
+    /** New agent name. */
+    to: string;
+}
+/** A session started. */
+export interface SessionStartedEvent {
+    type: "session.started";
+    /** Identifier of the started session. */
+    sessionId: string;
+}
+/** A session ended. */
+export interface SessionEndedEvent {
+    type: "session.ended";
+    /** Identifier of the ended session. */
+    sessionId: string;
+}
+/** An error occurred somewhere in the pipeline. */
+export interface ErrorEvent {
+    type: "error";
+    /** The serialised error. */
+    error: SerializedError;
+}
+/** A version was suggested by the versioning engine. */
+export interface VersionSuggestedEvent {
+    type: "version.suggested";
+    /** The suggestion produced. */
+    suggestion: VersionSuggestion;
+}
+/** The full event union published on the bus. */
+export type UltraCodeEvent = ToolExecutedEvent | AgentSwitchedEvent | SessionStartedEvent | SessionEndedEvent | ErrorEvent | VersionSuggestedEvent;
+/** Discriminator literal of any {@link UltraCodeEvent}. */
+export type UltraCodeEventType = UltraCodeEvent["type"];
+/** Narrow an event to its concrete shape by `type`. */
+export type EventOfType<T extends UltraCodeEventType> = Extract<UltraCodeEvent, {
+    type: T;
+}>;
+/** Handler for a specific event type. */
+export type EventHandler<T extends UltraCodeEventType> = (event: EventOfType<T>) => void;
+/**
+ * The event-bus interface.
+ *
+ * Contract:
+ * - `emit` synchronously invokes all subscribers for the event's `type`; a
+ *   throwing handler must not prevent other handlers from running.
+ * - `on` returns an unsubscribe function that is safe to call at any time,
+ *   including from within a handler during an active `emit`.
+ */
+export interface IEventBus {
+    /** Publish an event to all matching subscribers. */
+    emit(event: UltraCodeEvent): void;
+    /** Subscribe to a specific event type; returns an unsubscribe function. */
+    on<T extends UltraCodeEventType>(type: T, handler: EventHandler<T>): () => void;
+}
+//# sourceMappingURL=events.d.ts.map

package/dist/types/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AAEzD,iCAAiC;AACjC,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,iCAAiC;IACjC,QAAQ,EAAE,MAAM,CAAC;IACjB,uCAAuC;IACvC,EAAE,EAAE,OAAO,CAAC;IACZ,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,gCAAgC;AAChC,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,gBAAgB,CAAC;IACvB,+CAA+C;IAC/C,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,sBAAsB;IACtB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,yBAAyB;AACzB,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,iBAAiB,CAAC;IACxB,yCAAyC;IACzC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,uBAAuB;AACvB,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,eAAe,CAAC;IACtB,uCAAuC;IACvC,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,mDAAmD;AACnD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,OAAO,CAAC;IACd,4BAA4B;IAC5B,KAAK,EAAE,eAAe,CAAC;CACxB;AAED,wDAAwD;AACxD,MAAM,WAAW,qBAAqB;IACpC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,+BAA+B;IAC/B,UAAU,EAAE,iBAAiB,CAAC;CAC/B;AAED,iDAAiD;AACjD,MAAM,MAAM,cAAc,GACtB,iBAAiB,GACjB,kBAAkB,GAClB,mBAAmB,GACnB,iBAAiB,GACjB,UAAU,GACV,qBAAqB,CAAC;AAE1B,2DAA2D;AAC3D,MAAM,MAAM,kBAAkB,GAAG,cAAc,CAAC,MAAM,CAAC,CAAC;AAExD,uDAAuD;AACvD,MAAM,MAAM,WAAW,CAAC,CAAC,SAAS,kBAAkB,IAAI,OAAO,CAAC,cAAc,EAAE;IAAE,IAAI,EAAE,CAAC,CAAA;CAAE,CAAC,CAAC;AAE7F,yCAAyC;AACzC,MAAM,MAAM,YAAY,CAAC,CAAC,SAAS,kBAAkB,IAAI,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC;AAEzF;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,oDAAoD;IACpD,IAAI,CAAC,KAAK,EAAE,cAAc,GAAG,IAAI,CAAC;IAClC,2EAA2E;IAC3E,EAAE,CAAC,CAAC,SAAS,kBAAkB,EAAE,IAAI,EAAE,CAAC,EAAE,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;CACjF"}

package/dist/types/events.js

@@ -0,0 +1,10 @@
+/**
+ * Event-bus contracts.
+ *
+ * UltraCode is event-driven: subsystems publish typed {@link UltraCodeEvent}s
+ * onto an {@link IEventBus}. Events are a discriminated union keyed by `type`.
+ * The concrete {@link import("../events/EventBus.js").EventBus} implementation
+ * isolates handler failures so one bad subscriber cannot break others.
+ */
+export {};
+//# sourceMappingURL=events.js.map

package/dist/types/events.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.js","sourceRoot":"","sources":["../../src/types/events.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/types/memory.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Session/memory contracts.
+ *
+ * A session is an ordered conversation owned by an agent. All timestamps are
+ * ISO-8601 strings (UTC). The {@link ISessionStore} abstracts persistence
+ * (SQLite, JSON files, in-memory, …).
+ */
+import type { ChatMessage } from "./provider.js";
+/** Lightweight session header, returned by listings. */
+export interface SessionMeta {
+    /** Unique session identifier. */
+    id: string;
+    /** Human-readable title (derived or user-supplied). */
+    title: string;
+    /** Creation time, ISO-8601 (UTC). */
+    createdAt: string;
+    /** Last-modification time, ISO-8601 (UTC). */
+    updatedAt: string;
+    /** Name of the agent that owns the session. */
+    agentName: string;
+    /** Number of messages currently stored. */
+    messageCount: number;
+}
+/** A full session: its header plus the complete message history. */
+export interface SessionRecord extends SessionMeta {
+    /** Ordered conversation history. */
+    messages: ChatMessage[];
+}
+/**
+ * Persistence boundary for sessions.
+ *
+ * Contract:
+ * - Mutating methods bump `updatedAt` and keep `messageCount` consistent.
+ * - `get` resolves `null` for an unknown id (it does not throw).
+ * - `delete` resolves `false` when the id did not exist.
+ * - Hard storage failures reject with
+ *   {@link import("../errors.js").SessionError}.
+ */
+export interface ISessionStore {
+    /** Create a new, empty session and return its header. */
+    create(agentName: string, title?: string): Promise<SessionMeta>;
+    /** Load a full session by id, or `null` if absent. */
+    get(id: string): Promise<SessionRecord | null>;
+    /** Append messages to a session, updating its metadata. */
+    appendMessages(id: string, msgs: ChatMessage[]): Promise<void>;
+    /** List session headers, most-recent first, capped by `limit` when given. */
+    list(limit?: number): Promise<SessionMeta[]>;
+    /** Delete a session; resolves `true` if it existed. */
+    delete(id: string): Promise<boolean>;
+    /** Retain only the `maxSessions` most-recent sessions; returns the count removed. */
+    prune(maxSessions: number): Promise<number>;
+}
+//# sourceMappingURL=memory.d.ts.map

package/dist/types/memory.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../../src/types/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAEjD,wDAAwD;AACxD,MAAM,WAAW,WAAW;IAC1B,iCAAiC;IACjC,EAAE,EAAE,MAAM,CAAC;IACX,uDAAuD;IACvD,KAAK,EAAE,MAAM,CAAC;IACd,qCAAqC;IACrC,SAAS,EAAE,MAAM,CAAC;IAClB,8CAA8C;IAC9C,SAAS,EAAE,MAAM,CAAC;IAClB,+CAA+C;IAC/C,SAAS,EAAE,MAAM,CAAC;IAClB,2CAA2C;IAC3C,YAAY,EAAE,MAAM,CAAC;CACtB;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAc,SAAQ,WAAW;IAChD,oCAAoC;IACpC,QAAQ,EAAE,WAAW,EAAE,CAAC;CACzB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,aAAa;IAC5B,yDAAyD;IACzD,MAAM,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAChE,sDAAsD;IACtD,GAAG,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,GAAG,IAAI,CAAC,CAAC;IAC/C,2DAA2D;IAC3D,cAAc,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,6EAA6E;IAC7E,IAAI,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAC7C,uDAAuD;IACvD,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACrC,qFAAqF;IACrF,KAAK,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CAC7C"}

package/dist/types/memory.js

@@ -0,0 +1,9 @@
+/**
+ * Session/memory contracts.
+ *
+ * A session is an ordered conversation owned by an agent. All timestamps are
+ * ISO-8601 strings (UTC). The {@link ISessionStore} abstracts persistence
+ * (SQLite, JSON files, in-memory, …).
+ */
+export {};
+//# sourceMappingURL=memory.js.map

package/dist/types/memory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"memory.js","sourceRoot":"","sources":["../../src/types/memory.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG"}

package/dist/types/provider.d.ts

@@ -0,0 +1,129 @@
+/**
+ * LLM provider contracts.
+ *
+ * Providers are the integration boundary to a model backend (Mistral,
+ * Anthropic, OpenAI, local). Unlike tools, **providers throw on failure** —
+ * specifically {@link ProviderError} (with `retryable` set appropriately) — so
+ * the execution engine can apply retry/backoff policy.
+ */
+import type { ToolDefinition } from "./tool.js";
+/** Well-known provider identifiers. */
+export type ProviderName = "mistral" | "anthropic" | "openai" | "local";
+/**
+ * A provider identifier. Accepts the well-known {@link ProviderName} values
+ * while remaining open to custom backends via the `string & {}` trick (which
+ * preserves literal autocompletion without collapsing to `string`).
+ */
+export type ProviderId = ProviderName | (string & {});
+/** Role of a message in a chat completion. */
+export type ChatRole = "system" | "user" | "assistant" | "tool";
+/** A model's request to invoke a tool, emitted as part of a completion. */
+export interface ToolCallRequest {
+    /** Provider-assigned identifier correlating the call with its result. */
+    id: string;
+    /** Name of the tool to invoke. */
+    name: string;
+    /** Parsed arguments object for the tool. */
+    arguments: Record<string, unknown>;
+}
+/** A single message in a conversation. */
+export interface ChatMessage {
+    /** Message role. */
+    role: ChatRole;
+    /** Textual content. May be empty for assistant turns that only call tools. */
+    content: string;
+    /** For assistant messages: tool calls requested this turn. */
+    toolCalls?: ToolCallRequest[];
+    /** For `role: "tool"` messages: the {@link ToolCallRequest.id} being answered. */
+    toolCallId?: string;
+    /** Optional speaker/tool name (provider-specific addressing). */
+    name?: string;
+}
+/** Token accounting for a completion. */
+export interface TokenUsage {
+    /** Tokens consumed by the prompt. */
+    inputTokens: number;
+    /** Tokens produced by the model. */
+    outputTokens: number;
+}
+/** A request for a (streaming or non-streaming) chat completion. */
+export interface CompletionRequest {
+    /** Ordered conversation history. */
+    messages: ChatMessage[];
+    /** Target model identifier. */
+    model: string;
+    /** Upper bound on generated tokens. */
+    maxTokens?: number;
+    /** Sampling temperature, typically `0.0`–`1.0`. */
+    temperature?: number;
+    /** Tool definitions exposed to the model for this turn. */
+    tools?: ToolDefinition[];
+    /** Cancellation signal for the in-flight request. */
+    signal?: AbortSignal;
+}
+/** A single chunk emitted by {@link ILLMProvider.stream}. */
+export interface CompletionChunk {
+    /**
+     * Chunk discriminator:
+     * - `"text"`      — incremental assistant text in `text`.
+     * - `"tool_call"` — a (possibly partial) tool call in `toolCall`.
+     * - `"done"`      — terminal chunk; `usage` is populated.
+     */
+    type: "text" | "tool_call" | "done";
+    /** Present for `type: "text"`. */
+    text?: string;
+    /** Present for `type: "tool_call"`. */
+    toolCall?: ToolCallRequest;
+    /** Present for `type: "done"`. */
+    usage?: TokenUsage;
+}
+/** Reason a completion finished. */
+export type FinishReason = "stop" | "tool_calls" | "length" | "error";
+/** Aggregated result of a non-streaming completion. */
+export interface CompletionResult {
+    /** Full assistant text. */
+    text: string;
+    /** Tool calls requested by the model (empty when none). */
+    toolCalls: ToolCallRequest[];
+    /** Token accounting for the call. */
+    usage: TokenUsage;
+    /** Why generation stopped. */
+    finishReason: FinishReason;
+}
+/**
+ * The implementable provider interface.
+ *
+ * Contract:
+ * - All async methods **throw {@link ProviderError}** on failure; transient
+ *   failures set `retryable: true`.
+ * - `stream` yields {@link CompletionChunk}s and terminates with a `"done"`
+ *   chunk carrying {@link TokenUsage}.
+ * - `healthCheck` resolves `false` (rather than throwing) for a reachable but
+ *   unhealthy backend; it may throw for hard configuration errors.
+ */
+export interface ILLMProvider {
+    /** Stable provider identifier. */
+    readonly name: ProviderId;
+    /** List model identifiers available from this provider. */
+    listModels(): Promise<string[]>;
+    /** Run a non-streaming completion. */
+    complete(req: CompletionRequest): Promise<CompletionResult>;
+    /** Run a streaming completion. */
+    stream(req: CompletionRequest): AsyncIterable<CompletionChunk>;
+    /** Lightweight liveness/auth probe. */
+    healthCheck(): Promise<boolean>;
+}
+/** Construction options shared by provider implementations. */
+export interface ProviderOptions {
+    /** API key/credential. Often injected from the environment, not config. */
+    apiKey?: string;
+    /** Override base URL for self-hosted/proxy endpoints. */
+    baseUrl?: string;
+    /** Per-request timeout in milliseconds. */
+    timeoutMs: number;
+    /** Maximum retry attempts for retryable failures. */
+    maxRetries: number;
+    /** Base delay between retries in milliseconds (subject to backoff). */
+    retryDelayMs: number;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/types/provider.d.ts.map

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

package/dist/types/provider.js

@@ -0,0 +1,10 @@
+/**
+ * LLM provider contracts.
+ *
+ * Providers are the integration boundary to a model backend (Mistral,
+ * Anthropic, OpenAI, local). Unlike tools, **providers throw on failure** —
+ * specifically {@link ProviderError} (with `retryable` set appropriately) — so
+ * the execution engine can apply retry/backoff policy.
+ */
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/types/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/types/provider.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG"}

package/dist/types/tool.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Tool contracts.
+ *
+ * A tool is a single, named, side-effecting (or read-only) capability that an
+ * agent can invoke. The cardinal rule of this contract: **tools never throw
+ * from `execute`** — failures are reported as a {@link ToolResult} with
+ * `ok: false` and a serialised error. `validate` is the *only* method allowed
+ * to throw, and it throws exactly {@link ValidationError}.
+ */
+import type { SerializedError } from "../errors.js";
+import type { Logger } from "../logger.js";
+/**
+ * Permission disposition for a tool.
+ * - `"ask"`    — prompt the user via {@link ToolContext.confirm} before running.
+ * - `"always"` — run without prompting.
+ * - `"never"`  — the tool is blocked; execution must be refused.
+ */
+export type ToolPermission = "ask" | "always" | "never";
+/** Logical grouping of tools, used for filtering and default permissions. */
+export type ToolCategory = "file" | "search" | "system" | "project" | "ai" | "utility" | "mcp";
+/**
+ * JSON-Schema-like description of a tool's accepted arguments.
+ *
+ * This is intentionally a pragmatic subset of JSON Schema sufficient to drive
+ * LLM tool-calling and runtime validation. `properties` describes object
+ * fields; `items` describes array elements; `enum` restricts a value to a fixed
+ * set.
+ */
+export interface ToolParameterSchema {
+    /** JSON Schema primitive/composite type. */
+    type: "object" | "array" | "string" | "number" | "integer" | "boolean" | "null";
+    /** Human-readable description, surfaced to the model. */
+    description?: string;
+    /** For `type: "object"`, the names of required properties. */
+    required?: string[];
+    /** For `type: "object"`, the schema of each named property. */
+    properties?: Record<string, ToolParameterSchema>;
+    /** For `type: "array"`, the schema of each element. */
+    items?: ToolParameterSchema;
+    /** Restricts the value to one of the listed constants. */
+    enum?: ReadonlyArray<string | number | boolean | null>;
+    /** Default value, advisory for the model and validation. */
+    default?: unknown;
+}
+/** Static, registry-level description of a tool. */
+export interface ToolDefinition {
+    /** Unique tool name (e.g. `"read"`, `"git_status"`). */
+    name: string;
+    /** One-line description of what the tool does. */
+    description: string;
+    /** Category for grouping and default permission resolution. */
+    category: ToolCategory;
+    /** Schema for the tool's arguments (typically an `object` schema). */
+    parameters: ToolParameterSchema;
+    /** Default permission disposition; may be overridden by config. */
+    permission: ToolPermission;
+}
+/**
+ * Execution context handed to a tool at call time.
+ *
+ * The context is the tool's *only* sanctioned window onto the outside world:
+ * working directory, environment, cancellation, user confirmation and logging.
+ */
+export interface ToolContext {
+    /** Absolute working directory the tool should resolve paths against. */
+    cwd: string;
+    /** Read-only snapshot of the process environment. */
+    env: Readonly<Record<string, string | undefined>>;
+    /** Cancellation signal; tools SHOULD abort promptly when aborted. */
+    signal?: AbortSignal;
+    /**
+     * Request interactive confirmation for an `"ask"`-permission action.
+     * Resolves `true` to proceed, `false` to refuse. Absent in non-interactive
+     * contexts — tools must treat absence as "no confirmation available".
+     */
+    confirm?: (msg: string) => Promise<boolean>;
+    /** Structured logger scoped to this execution. */
+    logger: Logger;
+}
+/**
+ * Outcome of a single tool execution. Always returned, never thrown.
+ *
+ * @typeParam T - shape of the successful `output` payload.
+ */
+export interface ToolResult<T = unknown> {
+    /** `true` on success; `false` when `error` is populated. */
+    ok: boolean;
+    /** Result payload. On failure this is implementation-defined (often `null`). */
+    output: T;
+    /** Populated iff `ok === false`; a JSON-safe error description. */
+    error?: SerializedError;
+    /** Wall-clock execution time in milliseconds. */
+    durationMs: number;
+    /** `true` when `output` was truncated to respect output limits. */
+    truncated?: boolean;
+}
+/**
+ * The implementable tool interface.
+ *
+ * @typeParam TArgs - validated argument shape produced by {@link ITool.validate}.
+ * @typeParam TOut  - successful output payload type.
+ *
+ * Contract:
+ * - `validate(args)` parses/narrows untrusted input, throwing
+ *   {@link ValidationError} on any mismatch.
+ * - `execute(args, ctx)` performs the work and **always** resolves with a
+ *   {@link ToolResult}; it must not reject. Permission denial, timeouts and
+ *   not-found conditions are reported as `ok: false` with the appropriate
+ *   serialised error code.
+ */
+export interface ITool<TArgs = Record<string, unknown>, TOut = unknown> {
+    /** Static description used by the registry and the model. */
+    readonly definition: ToolDefinition;
+    /**
+     * Validate and narrow raw arguments.
+     * @throws {ValidationError} when `args` does not satisfy the schema.
+     */
+    validate(args: unknown): TArgs;
+    /** Execute the tool. Resolves with a {@link ToolResult}; never rejects. */
+    execute(args: TArgs, ctx: ToolContext): Promise<ToolResult<TOut>>;
+}
+//# sourceMappingURL=tool.d.ts.map

package/dist/types/tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAmB,MAAM,cAAc,CAAC;AACrE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAE3C;;;;;GAKG;AACH,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,QAAQ,GAAG,OAAO,CAAC;AAExD,6EAA6E;AAC7E,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,IAAI,GACJ,SAAS,GACT,KAAK,CAAC;AAEV;;;;;;;GAOG;AACH,MAAM,WAAW,mBAAmB;IAClC,4CAA4C;IAC5C,IAAI,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,GAAG,MAAM,CAAC;IAChF,yDAAyD;IACzD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,8DAA8D;IAC9D,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,+DAA+D;IAC/D,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,mBAAmB,CAAC,CAAC;IACjD,uDAAuD;IACvD,KAAK,CAAC,EAAE,mBAAmB,CAAC;IAC5B,0DAA0D;IAC1D,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,CAAC;IACvD,4DAA4D;IAC5D,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,oDAAoD;AACpD,MAAM,WAAW,cAAc;IAC7B,wDAAwD;IACxD,IAAI,EAAE,MAAM,CAAC;IACb,kDAAkD;IAClD,WAAW,EAAE,MAAM,CAAC;IACpB,+DAA+D;IAC/D,QAAQ,EAAE,YAAY,CAAC;IACvB,sEAAsE;IACtE,UAAU,EAAE,mBAAmB,CAAC;IAChC,mEAAmE;IACnE,UAAU,EAAE,cAAc,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,GAAG,EAAE,MAAM,CAAC;IACZ,qDAAqD;IACrD,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAClD,qEAAqE;IACrE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB;;;;OAIG;IACH,OAAO,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;IAC5C,kDAAkD;IAClD,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC,GAAG,OAAO;IACrC,4DAA4D;IAC5D,EAAE,EAAE,OAAO,CAAC;IACZ,gFAAgF;IAChF,MAAM,EAAE,CAAC,CAAC;IACV,mEAAmE;IACnE,KAAK,CAAC,EAAE,eAAe,CAAC;IACxB,iDAAiD;IACjD,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,KAAK,CAAC,KAAK,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,IAAI,GAAG,OAAO;IACpE,6DAA6D;IAC7D,QAAQ,CAAC,UAAU,EAAE,cAAc,CAAC;IACpC;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,OAAO,GAAG,KAAK,CAAC;IAC/B,2EAA2E;IAC3E,OAAO,CAAC,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC;CACnE"}

package/dist/types/tool.js

@@ -0,0 +1,11 @@
+/**
+ * Tool contracts.
+ *
+ * A tool is a single, named, side-effecting (or read-only) capability that an
+ * agent can invoke. The cardinal rule of this contract: **tools never throw
+ * from `execute`** — failures are reported as a {@link ToolResult} with
+ * `ok: false` and a serialised error. `validate` is the *only* method allowed
+ * to throw, and it throws exactly {@link ValidationError}.
+ */
+export {};
+//# sourceMappingURL=tool.js.map

package/dist/types/tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool.js","sourceRoot":"","sources":["../../src/types/tool.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG"}

package/dist/types/versioning.d.ts

@@ -0,0 +1,141 @@
+/**
+ * AI versioning / release-planning contracts.
+ *
+ * These types describe the inputs and outputs of the Change Analysis,
+ * Version Recommender, Release Planning and Quality Gate subsystems.
+ */
+/** Kind of version bump implied by a set of changes. */
+export type BumpType = "major" | "minor" | "patch" | "prerelease" | "none";
+/** A single file's change in a diff. */
+export interface FileChange {
+    /** Repository-relative path. */
+    path: string;
+    /** Change status. */
+    status: "added" | "modified" | "deleted" | "renamed";
+    /** Lines added. */
+    additions: number;
+    /** Lines removed. */
+    deletions: number;
+}
+/** Parsed Conventional-Commit-style metadata for one commit. */
+export interface CommitInfo {
+    /** Commit hash. */
+    hash: string;
+    /** Conventional type (e.g. `"feat"`), or `null` if unparseable. */
+    type: string | null;
+    /** Conventional scope, or `null` if absent. */
+    scope: string | null;
+    /** Commit subject line. */
+    subject: string;
+    /** Whether the commit declares a breaking change. */
+    breaking: boolean;
+}
+/** A detected breaking change. */
+export interface BreakingChange {
+    /** Where the signal came from. */
+    source: "commit" | "api-diff";
+    /** Human-readable description. */
+    description: string;
+    /** Optional location (file, symbol, …). */
+    location?: string;
+}
+/** A security finding from static analysis. */
+export interface SecurityFinding {
+    /** Severity ranking. */
+    severity: "low" | "medium" | "high" | "critical";
+    /** Rule/check identifier. */
+    rule: string;
+    /** Affected file path. */
+    file: string;
+    /** Affected line number, when known. */
+    line?: number;
+    /** Human-readable description. */
+    description: string;
+}
+/** Aggregated analysis of a change set. */
+export interface ChangeAnalysis {
+    /** Changed files. */
+    files: FileChange[];
+    /** Parsed commits. */
+    commits: CommitInfo[];
+    /** Detected breaking changes. */
+    breakingChanges: BreakingChange[];
+    /** Commit-category tallies. */
+    categories: {
+        feat: number;
+        fix: number;
+        docs: number;
+        refactor: number;
+        test: number;
+        chore: number;
+        perf: number;
+        other: number;
+    };
+    /** Security findings discovered during analysis. */
+    securityFindings: SecurityFinding[];
+}
+/** A recommended next version with rationale. */
+export interface VersionSuggestion {
+    /** Current version string. */
+    currentVersion: string;
+    /** Suggested next version string. */
+    suggestedVersion: string;
+    /** The bump that produced the suggestion. */
+    bump: BumpType;
+    /** Confidence in the suggestion, `0`–`1`. */
+    confidence: number;
+    /** Human-readable reasons supporting the suggestion. */
+    reasons: string[];
+}
+/** A release milestone. */
+export interface Milestone {
+    /** Milestone title. */
+    title: string;
+    /** Work items under this milestone. */
+    items: string[];
+    /** Whether the milestone is complete. */
+    done: boolean;
+}
+/** A release risk and its mitigation. */
+export interface Risk {
+    /** Risk description. */
+    description: string;
+    /** Risk severity. */
+    severity: "low" | "medium" | "high";
+    /** Planned mitigation. */
+    mitigation: string;
+}
+/** A drafted release plan. */
+export interface ReleasePlan {
+    /** Target version. */
+    version: string;
+    /** Target date, ISO-8601 (UTC), when set. */
+    targetDate?: string;
+    /** Milestones for the release. */
+    milestones: Milestone[];
+    /** Identified risks. */
+    risks: Risk[];
+    /** Draft changelog text. */
+    changelogDraft: string;
+}
+/** Result of a single quality gate. */
+export interface QualityGateResult {
+    /** Gate identifier (e.g. `"coverage"`, `"review"`). */
+    gate: string;
+    /** Whether the gate passed. */
+    passed: boolean;
+    /** Optional numeric score for the gate. */
+    score?: number;
+    /** Human-readable detail. */
+    details: string;
+}
+/** Aggregated quality report across all gates. */
+export interface QualityReport {
+    /** `true` iff every gate passed. */
+    passed: boolean;
+    /** Per-gate results. */
+    gates: QualityGateResult[];
+    /** Overall score across gates. */
+    overallScore: number;
+}
+//# sourceMappingURL=versioning.d.ts.map

package/dist/types/versioning.d.ts.map

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

package/dist/types/versioning.js

@@ -0,0 +1,8 @@
+/**
+ * AI versioning / release-planning contracts.
+ *
+ * These types describe the inputs and outputs of the Change Analysis,
+ * Version Recommender, Release Planning and Quality Gate subsystems.
+ */
+export {};
+//# sourceMappingURL=versioning.js.map

package/dist/types/versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../../src/types/versioning.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}

package/dist/utils/async.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Async helpers: cancellable {@link sleep}.
+ */
+/**
+ * Resolve after `ms` milliseconds, with optional cancellation.
+ *
+ * - If `signal` is already aborted, rejects immediately with the signal's
+ *   `reason` (or an `AbortError` if none).
+ * - If `signal` aborts before the timer fires, the timer is cleared and the
+ *   promise rejects with the abort reason.
+ * - Negative or non-finite `ms` is clamped to `0`.
+ *
+ * @param ms - delay in milliseconds.
+ * @param signal - optional cancellation signal.
+ */
+export declare function sleep(ms: number, signal?: AbortSignal): Promise<void>;
+//# sourceMappingURL=async.d.ts.map

package/dist/utils/async.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.d.ts","sourceRoot":"","sources":["../../src/utils/async.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;;;;;;;;;;GAWG;AACH,wBAAgB,KAAK,CAAC,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,IAAI,CAAC,CA0BrE"}