@esankhan3/anvil-agent-core 0.1.0

package/dist/types.d.ts

@@ -0,0 +1,249 @@
+/**
+ * `@esankhan3/anvil-agent-core` — public type surface.
+ *
+ * Two interfaces live here, intentionally:
+ *
+ *   1. `LanguageModel` — the new, forward-looking shape. Vendor-agnostic
+ *      streaming/single-shot interface that future code (Phase 5+ of the
+ *      agent-core extract) wires against. Yields typed events; analytical
+ *      callers drain the stream via the default `invoke()` impl.
+ *
+ *   2. `ModelAdapter` — the legacy interface inherited from cli/src/providers.
+ *      Kept verbatim (same field names, same signatures) so the seven existing
+ *      adapters keep compiling unchanged when they move into this package in
+ *      Phase 3+4. New code should not import these — they are bridged into
+ *      `LanguageModel` via `legacyAdapterToLanguageModel()` (Phase 3).
+ *
+ * `ProviderName` is shared between the two interfaces and uses the EXISTING
+ * values (`'claude' | 'openai' | …`) — see ADR D15. Renaming would cascade
+ * through every `ProviderRegistry.get()` site and the model-router dispatcher.
+ */
+export type ProviderName = 'claude' | 'openai' | 'gemini' | 'openrouter' | 'ollama' | 'gemini-cli' | 'adk' | 'opencode';
+export type ProviderTier = 'agentic' | 'function-calling' | 'text-only';
+export interface ProviderCapabilities {
+    tier: ProviderTier;
+    streaming: boolean;
+    toolUse: boolean;
+    fileSystem: boolean;
+    shellExecution: boolean;
+    sessionResume: boolean;
+    /** Whether the provider supports prompt caching (e.g. Anthropic ephemeral cache). */
+    promptCaching?: boolean;
+    /**
+     * Prompt-cache marker semantics:
+     *   - 'auto'     — provider caches stable prefixes silently (e.g. OpenAI ≥1024 tok).
+     *   - 'explicit' — caller must place markers (e.g. Anthropic cache_control).
+     *   - 'none'     — no caching benefit; markers are no-ops.
+     * `undefined` means the adapter has not declared a stance — treat as 'none'.
+     */
+    cache?: 'auto' | 'explicit' | 'none';
+    /** Cache TTL in seconds when `cache !== 'none'`. Informational only. */
+    cacheTtlSeconds?: number;
+    /**
+     * Adapter honors `ModelAdapterConfig.maxOutputTokens` and forwards it to the
+     * provider. When false, callers may still pass it but the adapter ignores it.
+     */
+    maxOutputTokens?: boolean;
+    /**
+     * Structured-output (JSON-schema-constrained generation) support level.
+     *   - 'strict'      — provider enforces the schema server-side.
+     *   - 'tool-shim'   — caller emulates via tool calls (e.g. Claude's tool-use trick).
+     *   - 'best-effort' — prompt-only; provider doesn't constrain output.
+     *   - 'none'        — not supported.
+     */
+    structuredOutput?: 'strict' | 'tool-shim' | 'best-effort' | 'none';
+}
+export interface LanguageModelMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    content: string;
+    toolCallId?: string;
+    toolCalls?: ToolCall[];
+}
+export interface ToolCall {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+}
+export interface ToolSchema {
+    name: string;
+    description: string;
+    inputSchema: Record<string, unknown>;
+}
+export interface LanguageModelInvokeOptions {
+    model: string;
+    messages: LanguageModelMessage[];
+    tools?: ToolSchema[];
+    maxTokens?: number;
+    temperature?: number;
+    /** Index in `messages[]` where a cache breakpoint should be inserted (Anthropic-style). */
+    cacheBreakpoint?: number;
+    /** Escape hatch for provider-specific knobs (e.g., `topP`, `responseFormat`). */
+    providerOptions?: Record<string, unknown>;
+    signal?: AbortSignal;
+}
+export type StreamEvent = {
+    type: 'text-delta';
+    text: string;
+} | {
+    type: 'tool-call';
+    call: ToolCall;
+} | {
+    type: 'reasoning-delta';
+    text: string;
+} | {
+    type: 'usage';
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+} | {
+    type: 'finish';
+    reason: 'end' | 'tool-use' | 'length' | 'error';
+    error?: string;
+};
+export interface InvokeUsage {
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens?: number;
+    cacheWriteTokens?: number;
+}
+export interface InvokeResult {
+    text: string;
+    toolCalls: ToolCall[];
+    usage: InvokeUsage;
+    costUsd: number;
+    durationMs: number;
+    provider: ProviderName;
+    model: string;
+    /** Reason the stream finished. Mirrors the final `finish` event. */
+    finishReason: 'end' | 'tool-use' | 'length' | 'error';
+}
+export interface LanguageModel {
+    readonly provider: ProviderName;
+    readonly capabilities: ProviderCapabilities;
+    supportsModel(modelId: string): boolean;
+    /** `[inputPer1M, outputPer1M]` pricing in USD, or `null` if unknown. */
+    getModelPricing(modelId: string): [number, number] | null;
+    checkAvailability(): Promise<{
+        available: boolean;
+        version?: string;
+        error?: string;
+    }>;
+    /** Streaming surface — yields events as the provider produces them. */
+    invokeStream(opts: LanguageModelInvokeOptions): AsyncIterable<StreamEvent>;
+    /** Single-shot surface — drains the stream and returns the final block. */
+    invoke(opts: LanguageModelInvokeOptions): Promise<InvokeResult>;
+}
+export interface ModelAdapterConfig {
+    userPrompt: string;
+    projectPrompt?: string;
+    model: string;
+    workingDir: string;
+    stage: string;
+    persona: string;
+    sessionId?: string;
+    resume?: boolean;
+    permissionMode?: string;
+    allowedTools?: string[];
+    disallowedTools?: string[];
+    timeout?: number;
+    /**
+     * Cap on the number of output tokens the provider should emit for this
+     * call. Adapters whose `capabilities.maxOutputTokens === true` honor it
+     * (set the provider's `max_tokens` knob); others ignore it.
+     */
+    maxOutputTokens?: number;
+    /**
+     * Routes the call through the process-local FIFO single-slot executor
+     * (`@esankhan3/anvil-agent-core/router/local-executor`). Set true ONLY for local
+     * GPU-resident models that cannot co-reside (Qwen 14B / Gemma class).
+     * Other adapters ignore this flag. Default false = bypass queue.
+     */
+    exclusiveSlot?: boolean;
+    /**
+     * Optional tool executor for adapters that drive their own agentic
+     * loop (Ollama, future OpenAI/Gemini agentic paths). When set, the
+     * adapter advertises the executor's filtered schemas to the model
+     * and feeds back tool results in-loop. Claude CLI ignores it — it
+     * ships its own tool runtime.
+     */
+    toolExecutor?: ToolExecutorLike;
+    /**
+     * Cap on agentic-loop iterations. Default 32. Adapters that don't
+     * loop ignore the field. Hitting the cap surfaces as
+     * `stopReason: 'iteration_limit'` in the result.
+     */
+    maxToolIterations?: number;
+    /**
+     * Provider-side context-window cap (Ollama `num_ctx`). Bounds VRAM
+     * cost of the conversation history. Adapters that don't expose
+     * this knob ignore the field.
+     */
+    contextWindow?: number;
+    /**
+     * Path to an `mcp.json` config the adapter should forward to its
+     * underlying tool runtime. Today only the Claude CLI path consumes
+     * this (passes `--mcp-config <path>`); other adapters ignore it.
+     * Populated by `defaultAdapterFactory` when a `workspaceDir` is set
+     * and an MCP config is discovered. Per AGENT-PROCESS-CONSOLIDATION-
+     * ADR §C5.
+     */
+    mcpConfigPath?: string;
+}
+export interface ToolExecutorLike {
+    listSchemas(): ToolSchema[];
+    execute(call: ToolCall, ctx: {
+        workingDir: string;
+        abortSignal: AbortSignal;
+    }): Promise<{
+        content: string;
+        isError: boolean;
+    }>;
+}
+export interface ModelAdapterResult {
+    output: string;
+    inputTokens: number;
+    outputTokens: number;
+    costUsd: number;
+    durationMs: number;
+    sessionId?: string;
+    provider: ProviderName;
+    model: string;
+    /** Tokens served from a prompt cache (Anthropic cache_read, OpenAI cached_tokens, Gemini cachedContentTokenCount). */
+    cacheReadTokens?: number;
+    /** Tokens written to the prompt cache (Anthropic cache_creation; OpenAI/Gemini do not bill cache writes separately). */
+    cacheWriteTokens?: number;
+    /** Tokens spent on extended thinking / reasoning blocks (Anthropic ThinkingBlock, OpenAI o-series reasoning, Gemini thoughtsTokenCount). */
+    reasoningTokens?: number;
+    /** Count of tool_use / function-call invocations in this turn. */
+    toolCallCount?: number;
+    /**
+     * Provider-reported reason the call ended. Common values:
+     *   - 'end_turn' / 'stop'     — natural completion
+     *   - 'max_tokens' / 'length' — output ceiling hit (truncation)
+     *   - 'tool_use'              — paused for a tool call
+     * Adapters that don't surface a reason leave it undefined. OpenAI-shape
+     * adapters normalize 'length' → 'max_tokens' so callers can detect
+     * truncation provider-agnostically.
+     */
+    stopReason?: string;
+}
+export interface ModelAdapter {
+    readonly provider: ProviderName;
+    readonly capabilities: ProviderCapabilities;
+    /** Check whether this adapter handles the given model identifier. */
+    supportsModel(modelId: string): boolean;
+    /** Return [inputPer1M, outputPer1M] pricing, or null if unknown. */
+    getModelPricing(modelId: string): [number, number] | null;
+    /** Verify the provider CLI / API is reachable and report its version. */
+    checkAvailability(): Promise<{
+        available: boolean;
+        version?: string;
+        error?: string;
+    }>;
+    /** Run agent. Write Anvil Stream Format NDJSON to `output`. */
+    run(config: ModelAdapterConfig, output: NodeJS.WritableStream): Promise<ModelAdapterResult>;
+    /** Kill running process if applicable. */
+    kill?(): void;
+}
+//# 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/types.js

@@ -0,0 +1,22 @@
+/**
+ * `@esankhan3/anvil-agent-core` — public type surface.
+ *
+ * Two interfaces live here, intentionally:
+ *
+ *   1. `LanguageModel` — the new, forward-looking shape. Vendor-agnostic
+ *      streaming/single-shot interface that future code (Phase 5+ of the
+ *      agent-core extract) wires against. Yields typed events; analytical
+ *      callers drain the stream via the default `invoke()` impl.
+ *
+ *   2. `ModelAdapter` — the legacy interface inherited from cli/src/providers.
+ *      Kept verbatim (same field names, same signatures) so the seven existing
+ *      adapters keep compiling unchanged when they move into this package in
+ *      Phase 3+4. New code should not import these — they are bridged into
+ *      `LanguageModel` via `legacyAdapterToLanguageModel()` (Phase 3).
+ *
+ * `ProviderName` is shared between the two interfaces and uses the EXISTING
+ * values (`'claude' | 'openai' | …`) — see ADR D15. Renaming would cascade
+ * through every `ProviderRegistry.get()` site and the model-router dispatcher.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/upstream-error.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Shared upstream-error contract for all `ModelAdapter` implementations.
+ *
+ * The dashboard's `runStageWithFallback` (in
+ * `packages/dashboard/server/pipeline-runner.ts`) duck-types this shape
+ * — `name === 'UpstreamError' && retryable === true` — to decide whether
+ * to burn the current model and re-resolve the chain. Adapters that
+ * throw plain `Error` lose chain-fallback even when the failure is
+ * obviously transient (429 quota, 503 outage).
+ *
+ * The class is provider-agnostic on purpose. CLI adapters (claude,
+ * gemini-cli) don't get an HTTP status — pass `synthesizeStatusFromCli`
+ * the stderr text and we'll map known vendor patterns to a synthetic
+ * status code that callers can switch on the same way they switch on
+ * real HTTP status codes.
+ */
+export declare class UpstreamError extends Error {
+    readonly status: number;
+    readonly body: string;
+    /**
+     * True when the failure class warrants chain-fallback (insufficient
+     * quota, rate limited, upstream outage). Auth / bad-request errors
+     * are NOT retryable — they need a config fix, not a different model.
+     */
+    readonly retryable: boolean;
+    constructor(status: number, body: string, opts?: {
+        provider?: string;
+        retryable?: boolean;
+    });
+}
+/**
+ * Default retryable-status map. Matches what the dashboard's
+ * `runStageWithFallback` checks. Adapters can pass an explicit
+ * `retryable` override when they need finer control (e.g. Anthropic's
+ * "Credit balance too low" is 400 with a specific body — not
+ * retryable to a different model from the SAME provider, but the
+ * dashboard should still fall back to a DIFFERENT provider in the
+ * chain, so we mark it retryable=true with a synthetic 402).
+ */
+export declare function isRetryableStatus(status: number): boolean;
+/**
+ * Body-pattern matcher for cases where the upstream returns 200/400
+ * but the body indicates a transient condition. Common with Anthropic
+ * (`overloaded_error`) and OpenRouter's wrapped-provider errors.
+ */
+export declare function bodyLooksRetryable(body: string): boolean;
+/**
+ * For CLI subprocess adapters (claude, gemini-cli) — map stderr text
+ * patterns to a synthetic HTTP-style status code. Returns `undefined`
+ * when the stderr doesn't look like a known transient condition; the
+ * adapter should then throw a plain (non-retryable) `Error`.
+ *
+ * Patterns curated from observed stderr output:
+ *   - Anthropic Claude CLI: "rate_limit_error", "overloaded_error",
+ *     "Credit balance is too low" (the last is a hard block — but we
+ *     mark it retryable so the chain hops to another provider).
+ *   - Google Gemini CLI: "RESOURCE_EXHAUSTED", "Quota exceeded",
+ *     "rate limit exceeded", "429".
+ */
+export declare function synthesizeStatusFromCli(stderr: string): {
+    status: number;
+    retryable: boolean;
+} | undefined;
+//# sourceMappingURL=upstream-error.d.ts.map

package/dist/upstream-error.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream-error.d.ts","sourceRoot":"","sources":["../src/upstream-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,qBAAa,aAAc,SAAQ,KAAK;IACtC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE;QAAE,QAAQ,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAO;CAQhG;AAED;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAQzD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAGxD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,GAAG,SAAS,CAuB1G"}

package/dist/upstream-error.js

@@ -0,0 +1,105 @@
+/**
+ * Shared upstream-error contract for all `ModelAdapter` implementations.
+ *
+ * The dashboard's `runStageWithFallback` (in
+ * `packages/dashboard/server/pipeline-runner.ts`) duck-types this shape
+ * — `name === 'UpstreamError' && retryable === true` — to decide whether
+ * to burn the current model and re-resolve the chain. Adapters that
+ * throw plain `Error` lose chain-fallback even when the failure is
+ * obviously transient (429 quota, 503 outage).
+ *
+ * The class is provider-agnostic on purpose. CLI adapters (claude,
+ * gemini-cli) don't get an HTTP status — pass `synthesizeStatusFromCli`
+ * the stderr text and we'll map known vendor patterns to a synthetic
+ * status code that callers can switch on the same way they switch on
+ * real HTTP status codes.
+ */
+export class UpstreamError extends Error {
+    status;
+    body;
+    /**
+     * True when the failure class warrants chain-fallback (insufficient
+     * quota, rate limited, upstream outage). Auth / bad-request errors
+     * are NOT retryable — they need a config fix, not a different model.
+     */
+    retryable;
+    constructor(status, body, opts = {}) {
+        const provider = opts.provider ?? 'upstream';
+        super(`${provider} ${status}: ${truncate(body, 400)}`);
+        this.name = 'UpstreamError';
+        this.status = status;
+        this.body = body;
+        this.retryable = opts.retryable ?? (isRetryableStatus(status) || bodyLooksRetryable(body));
+    }
+}
+/**
+ * Default retryable-status map. Matches what the dashboard's
+ * `runStageWithFallback` checks. Adapters can pass an explicit
+ * `retryable` override when they need finer control (e.g. Anthropic's
+ * "Credit balance too low" is 400 with a specific body — not
+ * retryable to a different model from the SAME provider, but the
+ * dashboard should still fall back to a DIFFERENT provider in the
+ * chain, so we mark it retryable=true with a synthetic 402).
+ */
+export function isRetryableStatus(status) {
+    return status === 408 || // Request Timeout
+        status === 425 || // Too Early
+        status === 429 || // Too Many Requests / quota
+        status === 502 || // Bad Gateway
+        status === 503 || // Service Unavailable
+        status === 504 || // Gateway Timeout
+        status === 0; // network / empty body / DNS
+}
+/**
+ * Body-pattern matcher for cases where the upstream returns 200/400
+ * but the body indicates a transient condition. Common with Anthropic
+ * (`overloaded_error`) and OpenRouter's wrapped-provider errors.
+ */
+export function bodyLooksRetryable(body) {
+    if (!body)
+        return false;
+    return /insufficient[\s_-]?quota|rate[\s_-]?limit|overloaded[\s_-]?error|resource[\s_-]?exhausted|quota[\s_-]?exceeded|server\s+(?:is\s+)?busy|temporarily\s+(?:un)?available|temporarily\s+rate-?limited|too\s+many\s+requests/i.test(body);
+}
+/**
+ * For CLI subprocess adapters (claude, gemini-cli) — map stderr text
+ * patterns to a synthetic HTTP-style status code. Returns `undefined`
+ * when the stderr doesn't look like a known transient condition; the
+ * adapter should then throw a plain (non-retryable) `Error`.
+ *
+ * Patterns curated from observed stderr output:
+ *   - Anthropic Claude CLI: "rate_limit_error", "overloaded_error",
+ *     "Credit balance is too low" (the last is a hard block — but we
+ *     mark it retryable so the chain hops to another provider).
+ *   - Google Gemini CLI: "RESOURCE_EXHAUSTED", "Quota exceeded",
+ *     "rate limit exceeded", "429".
+ */
+export function synthesizeStatusFromCli(stderr) {
+    if (!stderr)
+        return undefined;
+    const s = stderr.toLowerCase();
+    // Quota / billing — provider-side. Hop to another provider's chain entry.
+    if (/credit\s+balance\s+is\s+too\s+low|insufficient[\s_-]?credit|insufficient[\s_-]?quota|quota[\s_-]?exceeded|resource[\s_-]?exhausted/.test(s)) {
+        return { status: 429, retryable: true };
+    }
+    // Rate-limit / overload — usually transient. Other models help.
+    if (/rate[\s_-]?limit|too\s+many\s+requests|overloaded_error|server\s+(?:is\s+)?busy|\b429\b/.test(s)) {
+        return { status: 429, retryable: true };
+    }
+    // Outage signals.
+    if (/internal\s+server\s+error|\b503\b|\b502\b|\b504\b|service\s+unavailable|gateway\s+timeout|temporarily\s+unavailable/.test(s)) {
+        return { status: 503, retryable: true };
+    }
+    // Auth / config errors — terminal. The chain-fallback would just hit
+    // the same wall on the next model from the same provider.
+    if (/invalid\s+api\s+key|api\s+key\s+not\s+valid|unauthorized|\b401\b|\b403\b|permission[\s_-]?denied/.test(s)) {
+        return { status: 401, retryable: false };
+    }
+    // Default: caller should treat as terminal.
+    return undefined;
+}
+function truncate(s, n) {
+    if (s.length <= n)
+        return s;
+    return s.slice(0, n) + '…';
+}
+//# sourceMappingURL=upstream-error.js.map

package/dist/upstream-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"upstream-error.js","sourceRoot":"","sources":["../src/upstream-error.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,MAAM,OAAO,aAAc,SAAQ,KAAK;IAC7B,MAAM,CAAS;IACf,IAAI,CAAS;IACtB;;;;OAIG;IACM,SAAS,CAAU;IAE5B,YAAY,MAAc,EAAE,IAAY,EAAE,OAAmD,EAAE;QAC7F,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,IAAI,UAAU,CAAC;QAC7C,KAAK,CAAC,GAAG,QAAQ,IAAI,MAAM,KAAK,QAAQ,CAAC,IAAI,EAAE,GAAG,CAAC,EAAE,CAAC,CAAC;QACvD,IAAI,CAAC,IAAI,GAAG,eAAe,CAAC;QAC5B,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;QACrB,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC,SAAS,IAAI,CAAC,iBAAiB,CAAC,MAAM,CAAC,IAAI,kBAAkB,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7F,CAAC;CACF;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,iBAAiB,CAAC,MAAc;IAC9C,OAAO,MAAM,KAAK,GAAG,IAAK,kBAAkB;QACrC,MAAM,KAAK,GAAG,IAAK,YAAY;QAC/B,MAAM,KAAK,GAAG,IAAK,4BAA4B;QAC/C,MAAM,KAAK,GAAG,IAAK,cAAc;QACjC,MAAM,KAAK,GAAG,IAAK,sBAAsB;QACzC,MAAM,KAAK,GAAG,IAAK,kBAAkB;QACrC,MAAM,KAAK,CAAC,CAAC,CAAM,6BAA6B;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,IAAY;IAC7C,IAAI,CAAC,IAAI;QAAE,OAAO,KAAK,CAAC;IACxB,OAAO,0NAA0N,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/O,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,MAAM,UAAU,uBAAuB,CAAC,MAAc;IACpD,IAAI,CAAC,MAAM;QAAE,OAAO,SAAS,CAAC;IAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,WAAW,EAAE,CAAC;IAE/B,0EAA0E;IAC1E,IAAI,oIAAoI,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACjJ,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,gEAAgE;IAChE,IAAI,yFAAyF,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QACtG,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,kBAAkB;IAClB,IAAI,qHAAqH,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAClI,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAC1C,CAAC;IACD,qEAAqE;IACrE,0DAA0D;IAC1D,IAAI,kGAAkG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/G,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAC3C,CAAC;IACD,4CAA4C;IAC5C,OAAO,SAAS,CAAC;AACnB,CAAC;AAED,SAAS,QAAQ,CAAC,CAAS,EAAE,CAAS;IACpC,IAAI,CAAC,CAAC,MAAM,IAAI,CAAC;QAAE,OAAO,CAAC,CAAC;IAC5B,OAAO,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,GAAG,GAAG,CAAC;AAC7B,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.0.1";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAC"}

package/dist/version.js

@@ -0,0 +1,2 @@
+export const VERSION = '0.0.1';
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,OAAO,GAAG,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@esankhan3/anvil-agent-core",
+  "version": "0.1.0",
+  "description": "Shared LLM stack — unified LanguageModel interface, provider adapters, agent subprocess machinery, and cost calculation for cli + knowledge-core + headless runners.",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./*.js": {
+      "types": "./dist/*.d.ts",
+      "default": "./dist/*.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc -b && mkdir -p dist/data && cp src/data/model-prices.json dist/data/",
+    "dev": "tsc -b --watch",
+    "test": "tsc -b && mkdir -p dist/data && cp src/data/model-prices.json dist/data/ && node --test dist/__tests__/*.test.js dist/agent/session/__tests__/*.test.js dist/checkpoint/__tests__/*.test.js",
+    "refresh-cost-table": "node scripts/refresh-cost-table.mjs"
+  },
+  "dependencies": {
+    "@opentelemetry/api": "^1.9.0",
+    "@opentelemetry/exporter-metrics-otlp-http": "^0.200.0",
+    "@opentelemetry/exporter-trace-otlp-http": "^0.200.0",
+    "@opentelemetry/resources": "^2.0.0",
+    "@opentelemetry/sdk-metrics": "^2.0.0",
+    "@opentelemetry/sdk-trace-base": "^2.0.0",
+    "@opentelemetry/sdk-trace-node": "^2.0.0",
+    "@opentelemetry/semantic-conventions": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "better-sqlite3": "^11.7.0",
+    "yaml": "^2.8.3"
+  },
+  "optionalDependencies": {
+    "@google/adk": "^1.1.0",
+    "@google/genai": "^1.37.0"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.12",
+    "@types/node": "^22.15.2"
+  }
+}