myshell-tools 1.0.0 → 2.0.0-alpha.0

package/dist/core/prompt.js

@@ -0,0 +1,125 @@
+/**
+ * src/core/prompt.ts — typed, tier-specific prompt builders.
+ *
+ * Each tier gets a professional role prompt that instructs the model to perform
+ * real work and end its response with a structured JSON confidence envelope on
+ * its own line. The envelope is the only source of confidence data — no keyword
+ * heuristics, no fabricated numbers.
+ *
+ * Pure module: no I/O, no time, no randomness.
+ */
+// ---------------------------------------------------------------------------
+// Envelope schema (documented here for parser/prompt alignment)
+// ---------------------------------------------------------------------------
+//
+// Every model response MUST end with exactly this JSON object on its own line:
+//
+//   {"confidence": <0.0-1.0>, "escalate": <true|false>, "reason": "<string>", "needs_review": <true|false>}
+//
+// confidence  : float [0,1] — the model's self-assessed probability of correctness
+// escalate    : true  → the model requests a higher-tier pass
+// reason      : brief human-readable justification for the confidence / escalation
+// needs_review: true  → the model recommends cross-provider review
+//
+// The assess() function in assess.ts parses this envelope.  If the envelope is
+// absent or malformed, confidence is recorded as null (never fabricated).
+// ---------------------------------------------------------------------------
+// Tier role prompts
+// ---------------------------------------------------------------------------
+const WORKER_SYSTEM = `\
+You are a precise, efficient worker-tier assistant. Your role is to perform
+well-scoped, read-oriented tasks: searching codebases, listing files, looking up
+definitions, reading documentation, and answering factual questions about the
+current project.
+
+Guidelines:
+- Be concise and direct. Do not pad responses with unnecessary explanation.
+- Quote exact file paths, line numbers, and symbols when they are available.
+- If the task requires writing or modifying files, note that explicitly and
+  recommend escalating to an IC-tier run.
+- Do not speculate beyond what is directly observable in the project.
+
+After completing the task, append EXACTLY the following JSON object on its own
+line at the very end of your response (no trailing text after it):
+{"confidence": <0.0-1.0>, "escalate": <true|false>, "reason": "<one sentence>", "needs_review": <true|false>}
+
+Set confidence to your honest estimate of correctness (1.0 = certain, 0.0 = no
+idea). Set escalate to true if the task requires a higher-tier model. Set
+needs_review to true if you are uncertain and an independent check would help.`;
+const IC_SYSTEM = `\
+You are a skilled individual-contributor (IC) engineer. Your role is to
+implement, refactor, debug, and explain code. You work directly in the project's
+file tree, make targeted edits, run available tools, and produce clean,
+well-reasoned output.
+
+Guidelines:
+- Read the relevant files before making changes.
+- Make the smallest correct change that satisfies the task; avoid scope creep.
+- If you modify files, describe each change with file path, what changed, and why.
+- If you run commands (tests, builds), report the exact output.
+- If the task involves high-stakes areas (auth, secrets, payments, deployments),
+  err on the side of caution and set needs_review to true.
+
+After completing the task, append EXACTLY the following JSON object on its own
+line at the very end of your response (no trailing text after it):
+{"confidence": <0.0-1.0>, "escalate": <true|false>, "reason": "<one sentence>", "needs_review": <true|false>}
+
+Set confidence to your honest estimate of correctness (1.0 = certain, 0.0 = no
+idea). Set escalate to true if the task is beyond IC scope (e.g. requires
+cross-cutting architectural decisions). Set needs_review to true if an
+independent reviewer would meaningfully reduce risk.`;
+const MANAGER_SYSTEM = `\
+You are a senior-manager / staff-engineer-tier reviewer and architect. Your role
+is to evaluate code, plans, and proposals; identify systemic risks; design
+solutions; and produce authoritative recommendations.
+
+Guidelines:
+- Ground every finding in specific, file-anchored evidence (file path + line
+  range). Vague assertions are not acceptable.
+- For security/threat-model reviews, enumerate each threat class, its severity
+  (Critical/High/Medium/Low), and a concrete mitigation.
+- For architectural reviews, identify coupling, missing abstractions, and failure
+  modes — not just style issues.
+- Produce a structured verdict with a clear APPROVE / REQUEST_CHANGES /
+  ESCALATE recommendation.
+- If you identify a critical defect, set escalate to true and explain why
+  immediate attention is required.
+
+After completing the review or plan, append EXACTLY the following JSON object on
+its own line at the very end of your response (no trailing text after it):
+{"confidence": <0.0-1.0>, "escalate": <true|false>, "reason": "<one sentence>", "needs_review": <true|false>}
+
+Set confidence to your honest estimate that your analysis is complete and correct
+(1.0 = certain, 0.0 = severely incomplete). Set escalate to true only if the
+situation warrants immediate human or higher-tier intervention.`;
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Build the full prompt string to deliver to a model for the given tier.
+ *
+ * The system instructions are prepended to the raw task so the model receives
+ * role context before the user request.
+ *
+ * When `managerNotes` is provided (IC retry after a reviewer's `revise` verdict),
+ * the prompt is extended with a REVIEWER FEEDBACK section so the IC can address
+ * the specific feedback on its next attempt.
+ *
+ * @param tier         - The orchestration tier that will handle the task.
+ * @param task         - The raw user task description.
+ * @param managerNotes - Optional feedback from a cross-vendor reviewer to be addressed.
+ */
+export function buildPrompt(tier, task, managerNotes) {
+    const system = TIER_PROMPTS[tier];
+    let prompt = `${system}\n\n---\n\nTask:\n${task}`;
+    if (managerNotes !== undefined && managerNotes.trim().length > 0) {
+        prompt += `\n\nREVIEWER FEEDBACK:\n${managerNotes.trim()}\nAddress this specifically.`;
+    }
+    return prompt;
+}
+const TIER_PROMPTS = {
+    worker: WORKER_SYSTEM,
+    ic: IC_SYSTEM,
+    manager: MANAGER_SYSTEM,
+};
+//# sourceMappingURL=prompt.js.map

package/dist/core/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../src/core/prompt.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,8EAA8E;AAC9E,gEAAgE;AAChE,8EAA8E;AAC9E,EAAE;AACF,+EAA+E;AAC/E,EAAE;AACF,4GAA4G;AAC5G,EAAE;AACF,mFAAmF;AACnF,8DAA8D;AAC9D,mFAAmF;AACnF,mEAAmE;AACnE,EAAE;AACF,+EAA+E;AAC/E,0EAA0E;AAE1E,8EAA8E;AAC9E,oBAAoB;AACpB,8EAA8E;AAE9E,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;+EAmByD,CAAC;AAEhF,MAAM,SAAS,GAAG;;;;;;;;;;;;;;;;;;;;;qDAqBmC,CAAC;AAEtD,MAAM,cAAc,GAAG;;;;;;;;;;;;;;;;;;;;;;;gEAuByC,CAAC;AAEjE,8EAA8E;AAC9E,aAAa;AACb,8EAA8E;AAE9E;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,WAAW,CAAC,IAAU,EAAE,IAAY,EAAE,YAAqB;IACzE,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC;IAClC,IAAI,MAAM,GAAG,GAAG,MAAM,qBAAqB,IAAI,EAAE,CAAC;IAClD,IAAI,YAAY,KAAK,SAAS,IAAI,YAAY,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACjE,MAAM,IAAI,2BAA2B,YAAY,CAAC,IAAI,EAAE,8BAA8B,CAAC;IACzF,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,MAAM,YAAY,GAAyB;IACzC,MAAM,EAAE,aAAa;IACrB,EAAE,EAAE,SAAS;IACb,OAAO,EAAE,cAAc;CACxB,CAAC"}

package/dist/core/review.d.ts

@@ -0,0 +1,46 @@
+/**
+ * src/core/review.ts — pure review prompt builder and verdict parser.
+ *
+ * Provides utilities for building manager-style review prompts and parsing
+ * the structured review verdict returned by the reviewing model.
+ *
+ * Honesty Contract: parseReviewVerdict never throws and never fabricates a
+ * verdict — on any parse failure it defaults to fail-open `approve` with
+ * confidence null so a broken reviewer cannot block the user.
+ *
+ * Pure module: no I/O, no time, no randomness.
+ */
+/**
+ * The structured verdict returned by a reviewing model.
+ *
+ * - `approve`   : IC output is acceptable; proceed to final.
+ * - `revise`    : IC output needs changes; retry IC with the reviewer's notes.
+ * - `escalate`  : The issue is beyond IC scope; escalate to manager tier.
+ */
+export interface ReviewVerdict {
+    readonly verdict: 'approve' | 'revise' | 'escalate';
+    readonly notes: string;
+    readonly confidence: number | null;
+}
+/**
+ * Build a manager-style prompt asking the reviewer to critically assess the
+ * IC's work for correctness, quality, security, and completeness.
+ *
+ * The prompt instructs the model to end its response with a JSON verdict
+ * envelope on its own line:
+ *   {"verdict": "approve|revise|escalate", "notes": "...", "confidence": 0.0-1.0}
+ *
+ * @param task     - The original user task description.
+ * @param icOutput - The IC's full output text being reviewed.
+ */
+export declare function buildReviewPrompt(task: string, icOutput: string): string;
+/**
+ * Robustly parse the trailing JSON verdict envelope from a reviewer's output.
+ *
+ * Fail-open contract: if the envelope is absent or malformed, returns
+ * `{ verdict: 'approve', notes: '', confidence: null }`. A broken reviewer
+ * must never block the user. This function NEVER throws.
+ *
+ * @param output - The full text output from the reviewing model.
+ */
+export declare function parseReviewVerdict(output: string): ReviewVerdict;

package/dist/core/review.js

@@ -0,0 +1,148 @@
+/**
+ * src/core/review.ts — pure review prompt builder and verdict parser.
+ *
+ * Provides utilities for building manager-style review prompts and parsing
+ * the structured review verdict returned by the reviewing model.
+ *
+ * Honesty Contract: parseReviewVerdict never throws and never fabricates a
+ * verdict — on any parse failure it defaults to fail-open `approve` with
+ * confidence null so a broken reviewer cannot block the user.
+ *
+ * Pure module: no I/O, no time, no randomness.
+ */
+// ---------------------------------------------------------------------------
+// Prompt builder
+// ---------------------------------------------------------------------------
+/**
+ * Build a manager-style prompt asking the reviewer to critically assess the
+ * IC's work for correctness, quality, security, and completeness.
+ *
+ * The prompt instructs the model to end its response with a JSON verdict
+ * envelope on its own line:
+ *   {"verdict": "approve|revise|escalate", "notes": "...", "confidence": 0.0-1.0}
+ *
+ * @param task     - The original user task description.
+ * @param icOutput - The IC's full output text being reviewed.
+ */
+export function buildReviewPrompt(task, icOutput) {
+    return `\
+You are a senior-manager / staff-engineer reviewer performing a critical quality gate.
+
+You are reviewing the work of an individual-contributor (IC) engineer who was given the
+following task. Your job is to identify any issues with correctness, quality, security,
+or completeness in the IC's output before it reaches the user.
+
+Original task:
+${task}
+
+IC output to review:
+${icOutput}
+
+Review checklist (assess each dimension):
+1. CORRECTNESS — Does the output actually solve the task? Are there logic errors, off-by-ones,
+   or wrong assumptions?
+2. QUALITY — Is the code/output clean, idiomatic, and maintainable? Are there obvious smells?
+3. SECURITY — Are there any injection risks, secret leaks, missing input validation, or
+   privilege-escalation paths?
+4. COMPLETENESS — Does the output address all parts of the task, or does it miss edge cases?
+
+For any finding, anchor it to a specific file path and line range when applicable.
+
+After your review, append EXACTLY the following JSON object on its own line at the very end
+of your response (no trailing text after it):
+{"verdict": "approve|revise|escalate", "notes": "<specific, file-anchored feedback>", "confidence": <0.0-1.0>}
+
+verdict choices:
+  approve   — the IC output is correct, complete, and safe; ship it.
+  revise    — the IC output has fixable issues; provide actionable notes so the IC can retry.
+  escalate  — the task requires architectural judgement or has critical defects beyond IC scope.
+
+confidence: your honest estimate that your review is complete and correct (1.0 = certain).`;
+}
+const VALID_VERDICTS = new Set(['approve', 'revise', 'escalate']);
+/** Fail-open default used whenever the envelope is absent or malformed. */
+const FAIL_OPEN = { verdict: 'approve', notes: '', confidence: null };
+/**
+ * Attempt to extract the last JSON object from `text` that contains a `verdict` key.
+ * Returns null if no valid envelope is found.
+ */
+function extractVerdictEnvelope(text) {
+    const candidates = [];
+    let i = 0;
+    while (i < text.length) {
+        const start = text.indexOf('{', i);
+        if (start === -1)
+            break;
+        let depth = 0;
+        let j = start;
+        let foundClose = false;
+        while (j < text.length) {
+            if (text[j] === '{') {
+                depth++;
+            }
+            else if (text[j] === '}') {
+                depth--;
+                if (depth === 0) {
+                    foundClose = true;
+                    break;
+                }
+            }
+            j++;
+        }
+        if (foundClose) {
+            const candidate = text.slice(start, j + 1);
+            try {
+                const parsed = JSON.parse(candidate);
+                if (parsed !== null &&
+                    typeof parsed === 'object' &&
+                    !Array.isArray(parsed) &&
+                    'verdict' in parsed) {
+                    candidates.push(parsed);
+                }
+            }
+            catch {
+                // Not valid JSON — skip
+            }
+        }
+        i = start + 1;
+    }
+    if (candidates.length === 0)
+        return null;
+    return candidates[candidates.length - 1] ?? null;
+}
+/**
+ * Robustly parse the trailing JSON verdict envelope from a reviewer's output.
+ *
+ * Fail-open contract: if the envelope is absent or malformed, returns
+ * `{ verdict: 'approve', notes: '', confidence: null }`. A broken reviewer
+ * must never block the user. This function NEVER throws.
+ *
+ * @param output - The full text output from the reviewing model.
+ */
+export function parseReviewVerdict(output) {
+    // Guard: never throw on any input
+    if (typeof output !== 'string')
+        return FAIL_OPEN;
+    let envelope;
+    try {
+        envelope = extractVerdictEnvelope(output);
+    }
+    catch {
+        return FAIL_OPEN;
+    }
+    if (envelope === null)
+        return FAIL_OPEN;
+    // Validate verdict — must be one of the three allowed values
+    if (typeof envelope.verdict !== 'string' || !VALID_VERDICTS.has(envelope.verdict)) {
+        return FAIL_OPEN;
+    }
+    const verdict = envelope.verdict;
+    const notes = typeof envelope.notes === 'string' ? envelope.notes.trim() : '';
+    // confidence is optional — null when absent or invalid
+    let confidence = null;
+    if (typeof envelope.confidence === 'number' && isFinite(envelope.confidence)) {
+        confidence = Math.min(1, Math.max(0, envelope.confidence));
+    }
+    return { verdict, notes, confidence };
+}
+//# sourceMappingURL=review.js.map

package/dist/core/review.js.map

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

package/dist/core/route.d.ts

@@ -0,0 +1,28 @@
+/**
+ * src/core/route.ts — pure cost-aware routing decision.
+ *
+ * Given a tier, the set of currently available provider IDs, and the active
+ * Policy, selects the concrete provider+model that should handle the work.
+ *
+ * No I/O, no time, no randomness. Pricing data is pure reference data imported
+ * from infra/pricing (permitted by the purity guard because pricing.ts itself
+ * imports no fs/path/child_process).
+ */
+import type { Tier, RouteDecision, Policy } from './types.js';
+import type { ProviderId } from '../providers/port.js';
+/**
+ * Resolve a {@link RouteDecision} for the given tier.
+ *
+ * Algorithm:
+ *  1. Walk `policy.providerOrderByTier[tier]` in order.
+ *  2. For the first provider that is present in `available`, resolve the
+ *     cheapest model for that provider+tier via `getCheapestForTier`.
+ *  3. If none of the policy-preferred providers are available but `available`
+ *     is non-empty, fall back to the globally cheapest model for that tier.
+ *  4. If `available` is empty, throw — there is nothing to route to.
+ *
+ * @param tier      - The orchestration tier to route.
+ * @param available - Provider IDs that are currently reachable.
+ * @param policy    - Active routing policy (from `DEFAULT_POLICY` or overrides).
+ */
+export declare function route(tier: Tier, available: ProviderId[], policy: Policy): RouteDecision;

package/dist/core/route.js

@@ -0,0 +1,52 @@
+/**
+ * src/core/route.ts — pure cost-aware routing decision.
+ *
+ * Given a tier, the set of currently available provider IDs, and the active
+ * Policy, selects the concrete provider+model that should handle the work.
+ *
+ * No I/O, no time, no randomness. Pricing data is pure reference data imported
+ * from infra/pricing (permitted by the purity guard because pricing.ts itself
+ * imports no fs/path/child_process).
+ */
+import { getCheapestForTier } from '../infra/pricing.js';
+/**
+ * Resolve a {@link RouteDecision} for the given tier.
+ *
+ * Algorithm:
+ *  1. Walk `policy.providerOrderByTier[tier]` in order.
+ *  2. For the first provider that is present in `available`, resolve the
+ *     cheapest model for that provider+tier via `getCheapestForTier`.
+ *  3. If none of the policy-preferred providers are available but `available`
+ *     is non-empty, fall back to the globally cheapest model for that tier.
+ *  4. If `available` is empty, throw — there is nothing to route to.
+ *
+ * @param tier      - The orchestration tier to route.
+ * @param available - Provider IDs that are currently reachable.
+ * @param policy    - Active routing policy (from `DEFAULT_POLICY` or overrides).
+ */
+export function route(tier, available, policy) {
+    if (available.length === 0) {
+        throw new Error(`route: no providers available for tier "${tier}" — start at least one provider`);
+    }
+    const preferredOrder = policy.providerOrderByTier[tier];
+    // Walk the preferred order and pick the first available provider.
+    for (const preferred of preferredOrder) {
+        if (available.includes(preferred)) {
+            const pricing = getCheapestForTier(tier, [preferred]);
+            return {
+                tier,
+                provider: preferred,
+                model: pricing.model,
+            };
+        }
+    }
+    // None of the policy-preferred providers are available; fall back to the
+    // globally cheapest model across all available providers.
+    const fallback = getCheapestForTier(tier, available);
+    return {
+        tier,
+        provider: fallback.provider,
+        model: fallback.model,
+    };
+}
+//# sourceMappingURL=route.js.map

package/dist/core/route.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"route.js","sourceRoot":"","sources":["../../src/core/route.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAEzD;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,KAAK,CACnB,IAAU,EACV,SAAuB,EACvB,MAAc;IAEd,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,iCAAiC,CACjF,CAAC;IACJ,CAAC;IAED,MAAM,cAAc,GAAG,MAAM,CAAC,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAExD,kEAAkE;IAClE,KAAK,MAAM,SAAS,IAAI,cAAc,EAAE,CAAC;QACvC,IAAI,SAAS,CAAC,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC;YAClC,MAAM,OAAO,GAAG,kBAAkB,CAAC,IAAI,EAAE,CAAC,SAAS,CAAC,CAAC,CAAC;YACtD,OAAO;gBACL,IAAI;gBACJ,QAAQ,EAAE,SAAS;gBACnB,KAAK,EAAE,OAAO,CAAC,KAAK;aACrB,CAAC;QACJ,CAAC;IACH,CAAC;IAED,yEAAyE;IACzE,0DAA0D;IAC1D,MAAM,QAAQ,GAAG,kBAAkB,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;IACrD,OAAO;QACL,IAAI;QACJ,QAAQ,EAAE,QAAQ,CAAC,QAAsB;QACzC,KAAK,EAAE,QAAQ,CAAC,KAAK;KACtB,CAAC;AACJ,CAAC"}

package/dist/core/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * src/core/types.ts — shared types and ports for the orchestration core.
+ *
+ * This is the type hub. The pure core imports only types here (plus the
+ * Provider port). I/O is reached exclusively through the injected port
+ * interfaces below (Clock, SessionWriter, LedgerWriter), which infra
+ * implements — that is what keeps `src/core/` free of fs/child_process while
+ * remaining fully testable with fakes.
+ *
+ * Purity rule (enforced by test/arch/guards.test.ts): core code must obtain all
+ * time, ids, and randomness from the injected `Clock`, never from Date/Math.
+ */
+import type { Provider, ProviderId, SandboxLevel } from '../providers/port.js';
+export type Tier = 'worker' | 'ic' | 'manager';
+export type Risk = 'low' | 'medium' | 'high' | 'critical';
+export interface Classification {
+    readonly tier: Tier;
+    readonly risk: Risk;
+    /** Human-readable reason the classifier chose this tier/risk. */
+    readonly rationale: string;
+}
+/** A concrete routing decision: which provider+model runs a tier. */
+export interface RouteDecision {
+    readonly tier: Tier;
+    readonly provider: ProviderId;
+    readonly model: string;
+}
+/**
+ * Result of assessing a model's output for real, verifiable signals.
+ * `confidence` is null when the model emitted no parseable confidence envelope —
+ * we never fabricate a number (Honesty Contract).
+ */
+export interface Assessment {
+    readonly confidence: number | null;
+    readonly escalate: boolean;
+    readonly reason: string;
+    readonly needsReview: boolean;
+}
+export interface Clock {
+    /** Epoch milliseconds. */
+    now(): number;
+    /** ISO-8601 timestamp string. */
+    isoNow(): string;
+    /** A unique identifier (uuid-like). */
+    uuid(): string;
+    /** A float in [0, 1). */
+    random(): number;
+}
+export interface SessionEntry {
+    readonly timestamp: string;
+    readonly role: 'user' | 'assistant' | 'system';
+    readonly content: string;
+    readonly tier?: Tier;
+    readonly provider?: ProviderId;
+    readonly model?: string;
+    readonly confidence?: number | null;
+    readonly costUsd?: number;
+    readonly durationMs?: number;
+}
+export interface SessionWriter {
+    readonly id: string;
+    append(entry: SessionEntry): Promise<void>;
+}
+export interface LedgerEntry {
+    readonly timestamp: string;
+    readonly sessionId: string;
+    readonly taskId: string;
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly tier: Tier;
+    readonly inputTokens: number;
+    readonly outputTokens: number;
+    readonly cachedInputTokens: number;
+    readonly usd: number;
+    readonly durationMs: number;
+    readonly success: boolean;
+}
+export interface LedgerWriter {
+    record(entry: LedgerEntry): Promise<void>;
+}
+export interface Policy {
+    /** Hard cap on tier attempts per task (loop/cost guard). */
+    readonly maxAttempts: number;
+    /** Escalate when self-reported confidence is strictly below this, indexed by risk. */
+    readonly escalateBelowConfidence: Record<Risk, number>;
+    /** Ordered provider preference per tier; route() honours availability. */
+    readonly providerOrderByTier: Record<Tier, readonly ProviderId[]>;
+}
+export interface OrchestrateDeps {
+    /** Available providers, keyed by id. Absent key = provider unavailable. */
+    readonly providers: Partial<Record<ProviderId, Provider>>;
+    readonly clock: Clock;
+    readonly session: SessionWriter;
+    readonly ledger: LedgerWriter;
+    readonly policy: Policy;
+    readonly cwd: string;
+    readonly sandbox: SandboxLevel;
+    readonly timeoutMs: number;
+}
+/**
+ * High-level events emitted by orchestrate(). The interface/render layer
+ * consumes these; every field is a real measurement (no fabricated values).
+ */
+export type CoreEvent = {
+    readonly type: 'classified';
+    readonly classification: Classification;
+} | {
+    readonly type: 'tier-start';
+    readonly tier: Tier;
+    readonly provider: ProviderId;
+    readonly model: string;
+    readonly attempt: number;
+} | {
+    readonly type: 'provider-event';
+    readonly tier: Tier;
+    readonly event: import('../providers/port.js').ProviderEvent;
+} | {
+    readonly type: 'tier-done';
+    readonly tier: Tier;
+    readonly success: boolean;
+    readonly confidence: number | null;
+    readonly costUsd: number;
+    readonly durationMs: number;
+} | {
+    readonly type: 'escalate';
+    readonly from: Tier;
+    readonly to: Tier;
+    readonly reason: string;
+} | {
+    readonly type: 'notice';
+    readonly level: 'info' | 'warn' | 'error';
+    readonly message: string;
+} | {
+    readonly type: 'final';
+    readonly success: boolean;
+    readonly output: string;
+    readonly tier: Tier;
+    readonly totalCostUsd: number;
+    readonly sessionId: string;
+    readonly attempts: number;
+};

package/dist/core/types.js

@@ -0,0 +1,14 @@
+/**
+ * src/core/types.ts — shared types and ports for the orchestration core.
+ *
+ * This is the type hub. The pure core imports only types here (plus the
+ * Provider port). I/O is reached exclusively through the injected port
+ * interfaces below (Clock, SessionWriter, LedgerWriter), which infra
+ * implements — that is what keeps `src/core/` free of fs/child_process while
+ * remaining fully testable with fakes.
+ *
+ * Purity rule (enforced by test/arch/guards.test.ts): core code must obtain all
+ * time, ids, and randomness from the injected `Clock`, never from Date/Math.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

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

package/dist/infra/atomic.d.ts

@@ -0,0 +1,53 @@
+/**
+ * atomic.ts — Atomic file operations for safe concurrent access
+ * Ported from myshell-tools/src/state/atomic.mjs with the following fixes:
+ *   - Full TypeScript strict typing
+ *   - Async (fs/promises) throughout
+ *   - Async backoff instead of CPU-spinning lock acquisition
+ *   - O(1) JSONL append via fs.appendFile (no read-then-rewrite)
+ */
+export interface LockOptions {
+    /** How long to keep trying before giving up (default: 5 000 ms) */
+    timeoutMs?: number;
+    /** Age at which an existing lock is considered stale and may be stolen (default: 10 000 ms) */
+    staleMs?: number;
+}
+export declare class LockTimeoutError extends Error {
+    constructor(lockPath: string, timeoutMs: number);
+}
+export declare class AtomicWriteError extends Error {
+    constructor(filePath: string, cause: unknown);
+}
+/**
+ * Acquire a `.lock` file using `O_EXCL` for atomic creation.
+ * Retries with exponential backoff until `timeoutMs` is reached.
+ * Steals locks whose mtime is older than `staleMs`.
+ *
+ * Throws `LockTimeoutError` if the lock cannot be acquired in time.
+ */
+export declare function acquireLock(lockPath: string, opts?: LockOptions): Promise<void>;
+/**
+ * Release a lock file previously acquired with `acquireLock`.
+ * Silently ignores a missing lock file (idempotent).
+ */
+export declare function releaseLock(lockPath: string): Promise<void>;
+/**
+ * Convenience wrapper: acquire the lock, run `fn`, then always release.
+ * Re-throws any error from `fn` after releasing the lock.
+ */
+export declare function withLock<T>(lockPath: string, fn: () => Promise<T>, opts?: LockOptions): Promise<T>;
+/**
+ * Atomically write `data` to `filePath` using a tmp-file + rename strategy.
+ * The tmp file lives in the same directory to avoid cross-device rename issues.
+ */
+export declare function atomicWrite(filePath: string, data: string): Promise<void>;
+/**
+ * Atomically append a single JSONL entry to `filePath`.
+ *
+ * This is O(1) — it uses `fs.appendFile` rather than reading the entire file
+ * and rewriting it on every call. The caller is responsible for holding a lock
+ * when concurrent appends must be strictly ordered.
+ *
+ * Creates `filePath` if it does not exist.
+ */
+export declare function atomicAppendJSONL(filePath: string, entry: unknown): Promise<void>;