@ashlr/hub 2.2.0

package/dist/core/readiness.js

@@ -0,0 +1,431 @@
+/**
+ * readiness.ts — SHARED, READ-ONLY first-activation readiness model (H7).
+ *
+ * Single source of truth consumed by BOTH `ashlr preflight` (src/cli/preflight.ts)
+ * AND the five new read-only `ashlr doctor` probes (src/core/doctor.ts), so there
+ * is no drift and no double maintenance. See docs/contracts/CONTRACT-H7.md
+ * (BUILD ITEM 1 + BUILD ITEM 2).
+ *
+ * H7 ABSOLUTE RULES (proven by test/h7.*):
+ *  - READ-ONLY: composes only read-only primitives — probeEndpoint (local GET,
+ *    never throws), listEnrolled, killSwitchOn, loadDaemonState (H5 self-heal),
+ *    listSandboxes. It MUTATES NOTHING and adds NO outward capability.
+ *  - The ONE write is the `~/.ashlr` writeable probe — it writes then UNLINKS a
+ *    private sentinel under the (HOME-relative, isolated-in-tests) ~/.ashlr dir;
+ *    it touches no repo, no enrollment, no kill, no daemon state, and leaves no
+ *    persistent artifact.
+ *  - NEVER throws — every facet degrades to a typed result on error.
+ *  - No new runtime deps; node builtins + existing core modules only.
+ *
+ * NOTE: paths are resolved at CALL TIME via homedir() (matching policy.ts /
+ * daemon/state.ts) so a test that relocates process.env.HOME gets an ISOLATED
+ * ~/.ashlr — never the real one. (config.ts CONFIG_DIR is captured at import
+ * time, so we do NOT use it here for the writeable sentinel.)
+ */
+import { spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, writeFileSync, unlinkSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { probeEndpoint } from './providers.js';
+import { listEnrolled, killSwitchOn } from './sandbox/policy.js';
+import { loadDaemonState, daemonStatePath } from './daemon/state.js';
+import { listSandboxes, ORPHAN_STALE_MS } from './sandbox/worktree.js';
+import { getPhantomStatus } from './phantom.js';
+// ---------------------------------------------------------------------------
+// Internal: call-time ~/.ashlr resolution (HOME-relative, isolated in tests)
+// ---------------------------------------------------------------------------
+/** Call-time ~/.ashlr dir (matches policy.ts / daemon/state.ts — NOT config.ts). */
+function ashlrDir() {
+    return join(homedir(), '.ashlr');
+}
+/** Orphan-sandbox count threshold at/above which sandbox health warns. */
+export const SANDBOX_ORPHAN_WARN_THRESHOLD = 3;
+// ---------------------------------------------------------------------------
+// Per-facet read-only helpers (each NEVER throws)
+// ---------------------------------------------------------------------------
+/**
+ * READ-ONLY writeable probe for ~/.ashlr. Writes then immediately UNLINKS a
+ * private sentinel under the (call-time, HOME-relative) ~/.ashlr dir. Returns
+ * true when writeable, false otherwise. Leaves NO persistent artifact. Never
+ * throws.
+ */
+export function checkAshlrWriteable() {
+    const dir = ashlrDir();
+    // A unique sentinel name so concurrent probes never collide and a leftover
+    // (should an unlink ever be skipped) is unmistakably transient.
+    const sentinel = join(dir, `.ashlr-preflight-${process.pid}-${Date.now()}.tmp`);
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        writeFileSync(sentinel, '', 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        // ALWAYS attempt to remove the sentinel — leave no persistent artifact.
+        try {
+            if (existsSync(sentinel))
+                unlinkSync(sentinel);
+        }
+        catch {
+            /* idempotent — never throw from the cleanup */
+        }
+    }
+}
+/** READ-ONLY enrollment snapshot: { count } via listEnrolled(). Never throws. */
+export function readEnrollmentState() {
+    try {
+        return { count: listEnrolled().length };
+    }
+    catch {
+        return { count: 0 };
+    }
+}
+/** READ-ONLY kill-switch snapshot: { on } via killSwitchOn(). Never throws. */
+export function readKillState() {
+    try {
+        return { on: killSwitchOn() };
+    }
+    catch {
+        return { on: false };
+    }
+}
+/**
+ * READ-ONLY daemon-health snapshot via loadDaemonState() (which applies the H5
+ * reconcileDaemonState self-heal at the load chokepoint). Returns whether the
+ * daemon is reported running, its recorded pid, and whether the recorded pid is
+ * still alive (a still-running flag with a live pid is a healthy live daemon; a
+ * dead-pid running flag is already self-healed to running:false by the load).
+ * Never throws.
+ */
+export function readDaemonHealth() {
+    try {
+        // Peek at the RAW persisted flag BEFORE loadDaemonState() applies the H5
+        // reconcileDaemonState self-heal, so we can report whether a stale dead-pid
+        // `running:true` flag was healed at the load chokepoint. This peek is a pure
+        // read — it never writes.
+        let rawRunning = false;
+        let rawPid = null;
+        try {
+            const p = daemonStatePath();
+            if (existsSync(p)) {
+                const parsed = JSON.parse(readFileSync(p, 'utf8'));
+                if (typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed)) {
+                    const obj = parsed;
+                    rawRunning = obj['running'] === true;
+                    rawPid = typeof obj['pid'] === 'number' ? obj['pid'] : null;
+                }
+            }
+        }
+        catch {
+            rawRunning = false;
+            rawPid = null;
+        }
+        // loadDaemonState() applies the self-heal: a dead-pid running flag becomes
+        // running:false. The post-load `running` is therefore the truthful state.
+        const state = loadDaemonState();
+        // selfHealed iff the RAW file claimed running with a pid that is NOT alive
+        // and the post-load state is now stopped (the reconcile flipped it).
+        let selfHealed = false;
+        if (rawRunning && !state.running) {
+            let rawPidAlive = false;
+            if (typeof rawPid === 'number' && rawPid > 0) {
+                try {
+                    process.kill(rawPid, 0);
+                    rawPidAlive = true;
+                }
+                catch {
+                    rawPidAlive = false;
+                }
+            }
+            selfHealed = !rawPidAlive;
+        }
+        // pidAlive: whether the POST-load (self-healed) running flag is backed by a
+        // live pid — a healthy live daemon. (A dead-pid flag is already healed to
+        // running:false above, so this is only true for a genuinely live daemon.)
+        let pidAlive = false;
+        if (state.running && typeof state.pid === 'number' && state.pid > 0) {
+            try {
+                process.kill(state.pid, 0);
+                pidAlive = true;
+            }
+            catch {
+                pidAlive = false;
+            }
+        }
+        return { running: state.running, pid: state.pid, selfHealed, pidAlive };
+    }
+    catch {
+        return { running: false, pid: null, selfHealed: false, pidAlive: false };
+    }
+}
+/**
+ * READ-ONLY sandbox-health snapshot via listSandboxes(): total on-disk sandboxes
+ * + an orphan estimate. A sandbox is counted as an orphan when its owner pid is
+ * no longer alive AND it is older than ORPHAN_STALE_MS (mirrors the sweep's two
+ * guards — a LIVE owner pid is NEVER counted as an orphan regardless of age).
+ * Read-only; removes NOTHING. Never throws.
+ */
+export function readSandboxHealth() {
+    try {
+        const sandboxes = listSandboxes();
+        const now = Date.now();
+        let orphans = 0;
+        for (const sb of sandboxes) {
+            // Guard 1 — POSITIVE liveness: a live owner pid is never an orphan.
+            const pid = sb.ownerPid;
+            if (typeof pid === 'number' && Number.isInteger(pid) && pid > 0) {
+                let alive = false;
+                try {
+                    process.kill(pid, 0);
+                    alive = true;
+                }
+                catch {
+                    alive = false;
+                }
+                if (alive)
+                    continue;
+            }
+            // Guard 2 — AGE fallback: no usable live owner; count only when stale.
+            const created = Date.parse(sb.createdAt);
+            if (Number.isFinite(created) && now - created >= ORPHAN_STALE_MS) {
+                orphans++;
+            }
+        }
+        return { total: sandboxes.length, orphans };
+    }
+    catch {
+        return { total: 0, orphans: 0 };
+    }
+}
+/** READ-ONLY presence check for git (`git --version`). Never throws. */
+function gitPresent() {
+    try {
+        const r = spawnSync('git', ['--version'], { encoding: 'utf8', timeout: 5000 });
+        return !r.error && r.status === 0;
+    }
+    catch {
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+// buildReadiness — composes the facets into a ReadinessReport
+// ---------------------------------------------------------------------------
+/**
+ * Build the full first-activation readiness report (READ-ONLY).
+ *
+ * Composes (all read-only, all degrade gracefully):
+ *  - local model reachable via probeEndpoint (down => WARNING, never a blocker)
+ *  - enrollment count via readEnrollmentState (0 => INFO, never a blocker)
+ *  - kill-switch via readKillState (on => WARNING)
+ *  - daemon not stuck via readDaemonHealth (self-heal already applied)
+ *  - ~/.ashlr writeable via checkAshlrWriteable (not writeable => BLOCKER)
+ *  - sandbox health via readSandboxHealth (high orphan count => WARNING)
+ *  - git present (absent => BLOCKER); phantom present (absent => WARNING)
+ *
+ * `ready` is true iff blockers.length === 0. Never throws.
+ *
+ * MUST NOT mutate any enrollment/kill/daemon/sandbox/repo state; the ONLY write
+ * is the self-cleaning sentinel inside checkAshlrWriteable.
+ */
+export async function buildReadiness(cfg) {
+    const blockers = [];
+    const warnings = [];
+    const info = [];
+    // -- local model reachable (down => warning, never a blocker, never throws) --
+    {
+        const models = cfg?.models;
+        const lmUrl = typeof models?.lmstudio === 'string' ? models.lmstudio : '';
+        const olUrl = typeof models?.ollama === 'string' ? models.ollama : '';
+        const probes = [];
+        if (lmUrl)
+            probes.push(probeEndpoint('lmstudio', lmUrl));
+        if (olUrl)
+            probes.push(probeEndpoint('ollama', olUrl));
+        if (probes.length === 0) {
+            warnings.push({
+                id: 'model',
+                severity: 'warning',
+                detail: 'no local model endpoint configured (cfg.models.lmstudio / cfg.models.ollama)',
+                fix: 'Configure a local model in ~/.ashlr/config.json or run `ashlr models`.',
+            });
+        }
+        else {
+            let anyUp = false;
+            const downDetails = [];
+            // probeEndpoint never throws, but stay defensive — a single rejection must
+            // not abort the whole readiness report.
+            const results = await Promise.allSettled(probes);
+            for (const r of results) {
+                if (r.status === 'fulfilled') {
+                    if (r.value.up)
+                        anyUp = true;
+                    else
+                        downDetails.push(`${r.value.id} down (${r.value.error ?? 'no response'})`);
+                }
+                else {
+                    downDetails.push('probe failed');
+                }
+            }
+            if (anyUp) {
+                info.push({
+                    id: 'model',
+                    severity: 'info',
+                    detail: 'local model reachable',
+                });
+            }
+            else {
+                warnings.push({
+                    id: 'model',
+                    severity: 'warning',
+                    detail: `local model unreachable — ${downDetails.join('; ')}`,
+                    fix: 'Start LM Studio / Ollama, or proceed (autonomy needs a local model to run).',
+                });
+            }
+        }
+    }
+    // -- enrollment state (empty is FINE — info, never a blocker) ---------------
+    {
+        const { count } = readEnrollmentState();
+        if (count === 0) {
+            info.push({
+                id: 'enrollment',
+                severity: 'info',
+                detail: 'no repos enrolled yet (a fresh install is legitimately empty)',
+                fix: 'Run `ashlr onboard` to safely enroll your first repo.',
+            });
+        }
+        else {
+            info.push({
+                id: 'enrollment',
+                severity: 'info',
+                detail: `${count} repo(s) enrolled`,
+            });
+        }
+    }
+    // -- kill-switch (on => warning: nothing will run) --------------------------
+    {
+        const { on } = readKillState();
+        if (on) {
+            warnings.push({
+                id: 'kill-switch',
+                severity: 'warning',
+                detail: 'kill switch is ON — all autonomy is paused (nothing will run)',
+                fix: 'Clear it with `ashlr kill off` when you are ready to resume.',
+            });
+        }
+        else {
+            info.push({
+                id: 'kill-switch',
+                severity: 'info',
+                detail: 'kill switch is OFF',
+            });
+        }
+    }
+    // -- daemon not stuck (H5 self-heal already applied at load) -----------------
+    {
+        const { running, pid, selfHealed } = readDaemonHealth();
+        if (selfHealed) {
+            info.push({
+                id: 'daemon',
+                severity: 'info',
+                detail: 'daemon stopped (a stale dead-pid running flag was self-healed)',
+            });
+        }
+        else if (running) {
+            info.push({
+                id: 'daemon',
+                severity: 'info',
+                detail: `daemon running (pid ${pid ?? '?'})`,
+            });
+        }
+        else {
+            info.push({
+                id: 'daemon',
+                severity: 'info',
+                detail: 'daemon not running',
+            });
+        }
+    }
+    // -- ~/.ashlr writeable (not writeable => BLOCKER — nothing can persist) -----
+    {
+        if (checkAshlrWriteable()) {
+            info.push({
+                id: 'ashlr-writeable',
+                severity: 'info',
+                detail: '~/.ashlr is writeable',
+            });
+        }
+        else {
+            blockers.push({
+                id: 'ashlr-writeable',
+                severity: 'blocker',
+                detail: '~/.ashlr is NOT writeable — no state can be persisted',
+                fix: 'Fix permissions on ~/.ashlr (e.g. `chmod u+rwx ~/.ashlr`).',
+            });
+        }
+    }
+    // -- sandbox health (high orphan count => warning; never a blocker) ---------
+    {
+        const { total, orphans } = readSandboxHealth();
+        if (orphans >= SANDBOX_ORPHAN_WARN_THRESHOLD) {
+            warnings.push({
+                id: 'sandbox',
+                severity: 'warning',
+                detail: `${orphans} orphaned sandbox(es) of ${total} on disk`,
+                fix: 'Reclaim them with `ashlr sandbox gc`.',
+            });
+        }
+        else {
+            info.push({
+                id: 'sandbox',
+                severity: 'info',
+                detail: total === 0 ? 'no sandboxes on disk' : `${total} sandbox(es) on disk, ${orphans} orphan(s)`,
+            });
+        }
+    }
+    // -- git present (absent => BLOCKER) ----------------------------------------
+    {
+        if (gitPresent()) {
+            info.push({ id: 'git', severity: 'info', detail: 'git is installed' });
+        }
+        else {
+            blockers.push({
+                id: 'git',
+                severity: 'blocker',
+                detail: 'git not found on PATH — the autonomous chain cannot run',
+                fix: 'Install git: https://git-scm.com',
+            });
+        }
+    }
+    // -- phantom present (optional; absent => warning) --------------------------
+    {
+        let installed = false;
+        try {
+            installed = getPhantomStatus().installed;
+        }
+        catch {
+            installed = false;
+        }
+        if (installed) {
+            info.push({ id: 'phantom', severity: 'info', detail: 'phantom is installed' });
+        }
+        else {
+            warnings.push({
+                id: 'phantom',
+                severity: 'warning',
+                detail: 'phantom not installed (optional — secret scrubbing still applies)',
+            });
+        }
+    }
+    return {
+        ready: blockers.length === 0,
+        blockers,
+        warnings,
+        info,
+        generatedAt: new Date().toISOString(),
+    };
+}
+//# sourceMappingURL=readiness.js.map

package/dist/core/readiness.js.map

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

package/dist/core/run/agent-loop.d.ts

@@ -0,0 +1,40 @@
+/**
+ * agent-loop.ts — bounded ReAct-style loop for a single RunTask.
+ *
+ * Runs the task against a ProviderClient, handling tool calls when supported,
+ * enforcing the hard budget ceiling, and emitting RunStep events per step.
+ * Never throws out of runTask — all errors are captured into task.status/error.
+ *
+ * M11: accepts an optional StreamSink in ctx for live progress streaming.
+ * Emits model-delta events via client.chatStream() when available (falls back
+ * to client.chat() with a single delta of the full content). Also emits
+ * tool-call events per tool execution.
+ */
+import type { RunTask, RunStep, RunBudget, RunUsage, ProviderClient } from '../types.js';
+import type { StreamSink } from './streaming.js';
+/**
+ * Execute a single RunTask to completion using `client`.
+ *
+ * - Runs a bounded chat loop (ReAct-style).
+ * - When ctx.tools is present AND client.supportsTools, may issue tool calls
+ *   and feed results back as role:'tool' messages.
+ * - Accumulates per-step usage into ctx.usage (mutated in place via addUsage).
+ * - Emits one RunStep per model call (kind:'model') and per tool execution
+ *   batch (kind:'tool') via ctx.onStep.
+ * - M11: emits RunStreamEvents via ctx.sink for live CLI progress:
+ *     model-delta (via chatStream if available, else single onDelta of full content),
+ *     tool-call per tool execution.
+ * - HARD STOP: if overBudget(ctx.usage, ctx.budget) at any point, stops the
+ *   loop. Sets task.status='failed' (no result) or 'done' (partial result).
+ * - On success: task.status='done', task.result=<text>, task.usage=<delta>.
+ * - On error: task.status='failed', task.error=<message>.
+ * - Returns the SAME task object (mutated) for caller convenience.
+ */
+export declare function runTask(task: RunTask, client: ProviderClient, ctx: {
+    tools?: unknown[];
+    budget: RunBudget;
+    usage: RunUsage;
+    /** M11: optional StreamSink for live progress events. Defaults to nullSink. */
+    sink?: StreamSink;
+    onStep: (s: RunStep) => void;
+}): Promise<RunTask>;