@jinn-network/client 0.1.6 → 0.1.7-canary.08ebd916

package/dist/harnesses/cost-estimates.js

@@ -0,0 +1,297 @@
+/**
+ * Per-task cost estimates for paid-API-key harnesses.
+ *
+ * Background — Issue #331 (Run-mode `feat`, P0 tier under release-feedback
+ * umbrella #328). The operator dashboard surfaces a harness/model selection
+ * at SolverNet-join time and again in Settings. Operators routing a paid
+ * API key (Anthropic, OpenAI, OpenRouter, Nous Portal) through the Hermes
+ * harness — or a "raw API key" Claude Code variant if we ever add one —
+ * have **no UI nudge** at join-time about per-task cost. The v0.1.6 dogfood
+ * surfaced the concrete worry: a first-run operator could pick Opus 4.7 +
+ * SWE-rebench v2 and burn $100s/hr before they figure out what Jinn does.
+ *
+ * This module captures the heuristic the SPA uses to render that estimate
+ * and to gate the Save & Join action when the estimate exceeds a
+ * configurable per-task threshold (default $1).
+ *
+ * Heuristic shape per the spec:
+ *   per-1k-token rate × typical task length, by model id.
+ *
+ * Subscription harnesses (Claude Code, Codex) are flagged via
+ * `subscriptionPath: true` on the harness; in that case the surface shows
+ * "Included in subscription, no per-task API cost" and **does not** trigger
+ * the confirmation gate, regardless of the model selected.
+ *
+ * To add a new model: append an entry to `MODEL_COST_TABLE`. The id is the
+ * exact `model` string persisted to `joinedSolverNets[<cid>].model`. To
+ * shape a new harness: append to `HARNESS_BILLING`. Keep the units
+ * consistent: token counts in tokens, rates in USD-per-1k-tokens.
+ *
+ * Units note: Anthropic + OpenAI publish prices per million tokens; we
+ * convert to per-1k-tokens here so the multiplication reads as
+ * `(tokens / 1000) * pricePer1k`. Avoids floating-point surprises when the
+ * dashboard renders cents.
+ *
+ * Pricing references captured at the time of this commit (see PR body):
+ *   - Anthropic Claude Opus 4.7: $15/M input, $75/M output (≈ $0.015 / 1k
+ *     input, $0.075 / 1k output). Typical SWE-rebench v2 task estimated at
+ *     ~50k input + 20k output → ~$2.25/task. Anthropic public pricing.
+ *   - Anthropic Claude Sonnet 4.6: $3/M input, $15/M output.
+ *   - OpenAI GPT-5.4: $1.25/M input, $10/M output (OpenAI public pricing).
+ *   - OpenAI GPT-5.4 Mini: $0.25/M input, $2/M output.
+ *
+ * These are heuristics. Provider-API reconciliation (actual usage) is
+ * deferred to the P1 follow-up tracked in #331.
+ */
+import { CLAUDE_CODE_HARNESS, CODEX_HARNESS, HERMES_AGENT_HARNESS, canonicalHarnessName, } from './names.js';
+/**
+ * Per-model cost entries. Keyed by the exact `model` id persisted to
+ * `joinedSolverNets[<cid>].model`. The dashboard model dropdown in
+ * `claudeModels.ts` is the source of truth for which ids appear here.
+ */
+export const MODEL_COST_TABLE = {
+    // ---------- Anthropic family (direct + via OpenRouter) ----------
+    'claude-opus-4-7': {
+        provider: 'anthropic',
+        inputPer1kTokens: 0.015,
+        outputPer1kTokens: 0.075,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'claude-sonnet-4-6': {
+        provider: 'anthropic',
+        inputPer1kTokens: 0.003,
+        outputPer1kTokens: 0.015,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'claude-haiku-4-5-20251001': {
+        provider: 'anthropic',
+        inputPer1kTokens: 0.001,
+        outputPer1kTokens: 0.005,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    // OpenRouter routing of the same families (Hermes harness uses these).
+    'anthropic/claude-opus-4.7': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.015,
+        outputPer1kTokens: 0.075,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'anthropic/claude-sonnet-4.6': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.003,
+        outputPer1kTokens: 0.015,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    // ---------- OpenAI family ----------
+    'gpt-5.4': {
+        provider: 'openai',
+        inputPer1kTokens: 0.00125,
+        outputPer1kTokens: 0.01,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'gpt-5.4-mini': {
+        provider: 'openai',
+        inputPer1kTokens: 0.00025,
+        outputPer1kTokens: 0.002,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'gpt-5.5': {
+        provider: 'openai',
+        // Newer flagship; public pricing not confirmed at heuristic-capture
+        // time, so use Opus-4.7-class rates as a conservative upper bound
+        // until we get a verified figure.
+        inputPer1kTokens: 0.015,
+        outputPer1kTokens: 0.06,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'gpt-5.3-codex': {
+        provider: 'openai',
+        inputPer1kTokens: 0.00125,
+        outputPer1kTokens: 0.01,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'gpt-5.3-codex-spark': {
+        provider: 'openai',
+        inputPer1kTokens: 0.00125,
+        outputPer1kTokens: 0.01,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    // ---------- OpenRouter long-tail (Hermes) ----------
+    // These rates are coarse — OpenRouter's effective price depends on the
+    // route picked. We pick the published list-price upper bound so the
+    // estimate biases toward over-warning rather than under-warning.
+    'tencent/hy3-preview': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.003,
+        outputPer1kTokens: 0.015,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'deepseek/deepseek-v4-pro': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0014,
+        outputPer1kTokens: 0.0028,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'deepseek/deepseek-v4-flash': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0001,
+        outputPer1kTokens: 0.0004,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'google/gemini-3.1-flash-lite': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0001,
+        outputPer1kTokens: 0.0004,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'moonshotai/kimi-k2.6': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0006,
+        outputPer1kTokens: 0.0025,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'openrouter/owl-alpha': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.002,
+        outputPer1kTokens: 0.008,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'minimax/minimax-m2.7': {
+        provider: 'openrouter',
+        inputPer1kTokens: 0.0008,
+        outputPer1kTokens: 0.0032,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+    'nousresearch/hermes-4-405b': {
+        provider: 'nous',
+        inputPer1kTokens: 0.0009,
+        outputPer1kTokens: 0.0009,
+        typicalInputTokens: 50_000,
+        typicalOutputTokens: 20_000,
+    },
+};
+/**
+ * Harness-level billing classification.
+ *
+ * `subscriptionPath: true` means the harness shells out to a
+ * subscription-billed CLI (Claude Code, Codex) and the operator does NOT
+ * incur per-task API charges — the cost surface is suppressed entirely
+ * and the confirmation gate is never triggered.
+ *
+ * `subscriptionPath: false` means the harness routes to a paid API key
+ * (Hermes via OpenRouter / Anthropic API / Nous Portal). The cost surface
+ * is shown and the gate fires above the configured threshold.
+ */
+export const HARNESS_BILLING = {
+    [CLAUDE_CODE_HARNESS]: { subscriptionPath: true },
+    [CODEX_HARNESS]: { subscriptionPath: true },
+    [HERMES_AGENT_HARNESS]: { subscriptionPath: false },
+};
+/** Default per-task USD threshold above which the confirmation gate fires. */
+export const DEFAULT_HIGH_COST_THRESHOLD_USD = 1;
+/**
+ * Compute the per-task cost estimate for a given model id. Returns `null`
+ * when the id has no entry in `MODEL_COST_TABLE` — callers should treat
+ * that as "unknown, don't surface a number" rather than rendering $0.
+ */
+export function estimateModelCost(modelId) {
+    const entry = MODEL_COST_TABLE[modelId];
+    if (!entry)
+        return null;
+    const inputUsd = (entry.typicalInputTokens / 1000) * entry.inputPer1kTokens;
+    const outputUsd = (entry.typicalOutputTokens / 1000) * entry.outputPer1kTokens;
+    return {
+        usd: inputUsd + outputUsd,
+        inputUsd,
+        outputUsd,
+        typicalInputTokens: entry.typicalInputTokens,
+        typicalOutputTokens: entry.typicalOutputTokens,
+        entry,
+    };
+}
+/**
+ * `true` when the harness routes through a paid API key. Subscription
+ * harnesses (Claude Code, Codex) return `false`; unknown harnesses
+ * conservatively return `true` so a misnamed harness doesn't silently
+ * skip the cost surface.
+ */
+export function harnessUsesPaidApiKey(harness) {
+    if (!harness)
+        return false;
+    const canonical = canonicalHarnessName(harness);
+    const billing = HARNESS_BILLING[canonical];
+    if (!billing)
+        return true;
+    return !billing.subscriptionPath;
+}
+/**
+ * Decide what the cost surface should render for a given harness + model
+ * combination, plus whether the confirmation gate fires.
+ *
+ * Defaults:
+ *   - threshold: $1 / task (see DEFAULT_HIGH_COST_THRESHOLD_USD).
+ *   - subscription harness → suppress surface + skip gate.
+ *   - unknown model on a paid harness → show estimate slot (caller may
+ *     render "estimate unavailable") but DO NOT trigger the gate.
+ */
+export function decideCostSurface(harness, modelId, thresholdUsd = DEFAULT_HIGH_COST_THRESHOLD_USD) {
+    if (!harnessUsesPaidApiKey(harness)) {
+        return {
+            showEstimate: false,
+            estimate: null,
+            requiresConfirmation: false,
+            suppressedReason: 'Included in subscription, no per-task API cost.',
+        };
+    }
+    const estimate = modelId ? estimateModelCost(modelId) : null;
+    const modelOverridesSubscription = estimate?.entry.subscriptionPath === true;
+    if (modelOverridesSubscription) {
+        return {
+            showEstimate: false,
+            estimate: null,
+            requiresConfirmation: false,
+            suppressedReason: 'Included in subscription, no per-task API cost.',
+        };
+    }
+    return {
+        showEstimate: true,
+        estimate,
+        requiresConfirmation: estimate !== null && estimate.usd > thresholdUsd,
+        suppressedReason: null,
+    };
+}
+/**
+ * Format a USD amount for compact display in the dashboard. Picks the
+ * smallest fraction count that still distinguishes the value from $0.
+ */
+export function formatUsd(amount) {
+    if (!Number.isFinite(amount))
+        return '—';
+    if (amount === 0)
+        return '$0';
+    if (amount < 0.01)
+        return `<$0.01`;
+    if (amount < 1)
+        return `$${amount.toFixed(2)}`;
+    if (amount < 10)
+        return `$${amount.toFixed(2)}`;
+    return `$${amount.toFixed(2)}`;
+}
+//# sourceMappingURL=cost-estimates.js.map

package/dist/harnesses/cost-estimates.js.map

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

package/dist/harnesses/engine/engine.d.ts

@@ -8,6 +8,7 @@
  */
 import { TaskRunPersistence, type PersistedTaskRun, type PersistedTaskRunInput } from './persistence.js';
 import type { Store } from '../../store/store.js';
+import { type ReapWorkDirsReport } from './work-dir-reaper.js';
 import { type PackagingDeps } from './packaging.js';
 import { type EnvelopeAssemblyDeps } from './envelope-assembly.js';
 import { type DeliveryDeps } from './delivery.js';
@@ -240,6 +241,28 @@ export interface TaskEngineOptions {
      * Spec: docs/superpowers/specs/2026-05-06-agent-harness-solvernet-design.md §6.3
      */
     harnessMode?: 'train' | 'frozen';
+    /**
+     * Working-directory reaper tuning (issue #320). Each task run provisions a
+     * heavy scratch directory under `paths.workingDirRoot`; without cleanup an
+     * operator accumulates hundreds of dirs / tens of GB. The engine reaps a
+     * task's directory once it reaches a terminal state (COMPLETE / FAILED),
+     * and periodically sweeps the root for crash-orphaned dirs.
+     *
+     * Optional — sensible defaults apply when absent.
+     */
+    workDirReaper?: {
+        /**
+         * Age above which a directory with no DB row (orphaned by a crash or an
+         * older daemon) is removed. Defaults to {@link DEFAULT_ORPHAN_MAX_AGE_MS}
+         * (24h). Set to a large value to keep orphans for forensic inspection.
+         */
+        orphanMaxAgeMs?: number;
+        /**
+         * Disable the reaper entirely (escape hatch for debugging a stuck task).
+         * Defaults to false — the reaper runs.
+         */
+        disabled?: boolean;
+    };
 }
 /** Per-task outcome from a recovery pass. */
 export interface RecoveryReport {
@@ -289,12 +312,44 @@ export declare class TaskEngine {
     private stopped;
     private stopResolve?;
     private readonly stopPromise;
+    /** Working-dir reaper tuning (issue #320). */
+    protected readonly workDirReaperOpts: {
+        orphanMaxAgeMs: number;
+        disabled: boolean;
+    };
     constructor(opts: TaskEngineOptions);
     /**
      * Called when an task is observed from an on-chain event.
      * Persists a DISCOVERED row. Idempotent: if the row already exists, no-op.
      */
     observe(input: PersistedTaskRunInput): Promise<void>;
+    /**
+     * Pre-claim acceptance check used by the daemon's engine-watcher loop.
+     *
+     * Performance contract (issue #398): this runs once per task announcement,
+     * on the engine-watcher hot path, for every observed task. It MUST NOT
+     * perform per-task blocking I/O. In particular it does not probe
+     * `impl.isReady()` — historically the Hermes harness ran child processes
+     * inside its readiness probe, so a backlog would pay per-task blocking
+     * spawns and starve the daemon event loop. (#778 converted the matching
+     * post-execution `git diff` wedge in harvest.ts to async + 60s timeout;
+     * the #778 follow-up converted the readiness-probe spawns themselves —
+     * Hermes `doctor` / `auth list` and the codex-doctor `--version` probe —
+     * to async, so the registry's background refresh loop no longer blocks the
+     * main thread either. The readiness path remains O(1) here via the cache
+     * below.)
+     *
+     * Harness readiness for the claim gate is instead served O(1) from the
+     * daemon's cached `HarnessReadinessRegistry` snapshot: the engine-watcher
+     * loop calls `gateClaimByReadiness(...)` immediately after `canAcceptTask`
+     * returns. A ~tickIntervalMs-stale snapshot is acceptable — harness
+     * readiness changes on a minutes scale (auth/config) and the daemon
+     * already trusts that cached registry for its post-`canAcceptTask` gate.
+     *
+     * `claim()` (the DISCOVERED → CLAIMED transition) still probes
+     * `impl.isReady()` directly — it runs once per claimed task, not per
+     * announcement, and is the authoritative pre-execution gate.
+     */
     canAcceptTask(input: {
         solverType?: string;
         taskRole?: 'restoration' | 'evaluation';
@@ -320,6 +375,18 @@ export declare class TaskEngine {
      * Errors from individual tasks are logged but do not stop the loop.
      */
     tick(options?: TickOptions): Promise<void>;
+    /**
+     * Reap on-disk per-task working directories (issue #320).
+     *
+     * Removes the scratch directory of every task in a terminal state
+     * (COMPLETE / FAILED) and any crash-orphaned directory older than the
+     * configured max age. In-flight tasks are never touched. Safe to call at
+     * any time; never throws (filesystem errors are collected into the report).
+     *
+     * Called automatically every `tick()`; also exposed for the one-shot
+     * cleanup script and for tests.
+     */
+    reapWorkDirsNow(): ReapWorkDirsReport;
     /**
      * Drive `tick()` on a fixed interval until `stop()` is called.
      * Errors thrown by tick() itself are logged and do not stop the loop.
@@ -390,6 +457,17 @@ export declare class TaskEngine {
      * `task` non-null.
      */
     private evaluateJoinedEligibility;
+    /**
+     * Shared eligibility evaluation behind both `canAcceptTask` and `claim`.
+     *
+     * `opts.skipReadinessProbe` (issue #398): when true, the per-task
+     * `impl.isReady()` probe is skipped. The engine-watcher's `canAcceptTask`
+     * sets this — it relies on the daemon's cached `HarnessReadinessRegistry`
+     * (via `gateClaimByReadiness`) for the readiness gate instead of a
+     * blocking per-announcement probe. `claim()` leaves it false so the
+     * DISCOVERED → CLAIMED transition still runs the authoritative readiness
+     * probe (once per claimed task, not per announcement).
+     */
     private runnableFailureReason;
     /**
      * PRE_SNAPSHOT transition: provision workingDir + implStateDir, write