@kasenri/dsh-orbit 0.5.1

package/lib/pipeline-guard.js

@@ -0,0 +1,75 @@
+import { guardBashCommand, guardReason, guardToolPath } from "./guard.js";
+const WRITE_PATH_TOOLS = new Set(['write', 'edit', 'str_replace_editor']);
+/** Top-level autonomous mutation drivers that must not run beside an active Orbit run. */
+export const MUTATION_DRIVER_TOOLS = new Set(['create_goal', 'ralph', 'workflow']);
+/** Canonical and legacy controller tool names. */
+export const ORBIT_CONTROLLER_TOOLS = new Set(['orbit_controller', 'cx_controller']);
+/**
+ * The Orbit recoverable tool guard plus mutation-driver mutual exclusion.
+ *
+ * Recovery contract: a denial blocks only this one tool call; the agent turn and
+ * the Orbit phase continue. Mutation exclusion, by contrast, is an ownership fence:
+ * Orbit and another top-level autonomous driver must never run in the same project.
+ */
+export function createOrbitPreExecuteHandler(service, options = {}) {
+    return async function orbitPreExecute(exec, next) {
+        const cwd = exec.agent?.session?.header?.cwd ?? process.cwd();
+        const active = service.hasActiveRun(cwd);
+        const args = (exec.arguments ?? {});
+        // Orbit owns the workspace: refuse to start another top-level mutation driver.
+        if (active && MUTATION_DRIVER_TOOLS.has(exec.name)) {
+            return {
+                kind: 'deny',
+                reason: `ORBIT_MUTATION_DRIVER_CONFLICT: an active Orbit run owns this workspace, so ${exec.name} must not start. ` +
+                    'Resume or stop the Orbit run first, or continue through orbit_controller.',
+            };
+        }
+        // Another driver already owns the workspace: refuse to start Orbit.
+        if (!active && ORBIT_CONTROLLER_TOOLS.has(exec.name)) {
+            const action = typeof args['action'] === 'string' ? args['action'] : '';
+            if (action === 'run' || action === 'start') {
+                const competing = options.competingDriver?.(exec.agent);
+                if (competing) {
+                    return {
+                        kind: 'deny',
+                        reason: `ORBIT_MUTATION_DRIVER_CONFLICT: ${competing} already owns mutation in this workspace; stop it before starting Orbit.`,
+                    };
+                }
+            }
+        }
+        if (!active)
+            return next();
+        if (exec.name === 'bash') {
+            const command = typeof args['command'] === 'string' ? args['command'] : '';
+            const decision = guardBashCommand(command, { github_allowed: service.githubAllowed(cwd) });
+            if (!decision.allowed) {
+                const outcome = await service.recordGuardBlock(decision.code, decision.reason, cwd);
+                return { kind: 'deny', reason: `${guardReason(decision)} ${outcome.instruction}` };
+            }
+            return next();
+        }
+        if (WRITE_PATH_TOOLS.has(exec.name)) {
+            const target = args['path'] ?? args['file_path'] ?? args['filePath'];
+            const decision = guardToolPath(exec.name, target, { cwd });
+            if (!decision.allowed) {
+                const outcome = await service.recordGuardBlock(decision.code, decision.reason, cwd);
+                return { kind: 'deny', reason: `${guardReason(decision)} ${outcome.instruction}` };
+            }
+            return next();
+        }
+        // The browser tool can write its structured result to a caller path; route
+        // that path through the same durable-state policy instead of a second copy.
+        if (exec.name === 'agent_browser') {
+            const outputPath = args['outputPath'];
+            if (typeof outputPath === 'string' && outputPath.length > 0) {
+                const decision = guardToolPath('write', outputPath, { cwd });
+                if (!decision.allowed) {
+                    const outcome = await service.recordGuardBlock(decision.code, decision.reason, cwd);
+                    return { kind: 'deny', reason: `${guardReason(decision)} ${outcome.instruction}` };
+                }
+            }
+            return next();
+        }
+        return next();
+    };
+}

package/lib/routes.js

@@ -0,0 +1,52 @@
+/**
+ * Effective route resolution for a new Orbit run.
+ *
+ * Orbit stores only Commander and Watchdog itself (`orbit` settings namespace,
+ * falling back to the composition `config.routes`). The Executor follows the
+ * initiating Session's current model selection, read through the public
+ * request-header seam, and falls back to `config.routes.executor` on surfaces
+ * without one (headless, CLI, minimal profiles, tests). Resolution happens
+ * exactly once per new run and is frozen into `state.routes`.
+ */
+/**
+ * Normalize one provider/model/effort candidate into a complete route.
+ * @param selection - candidate fields from settings, the session header, or tests.
+ * @returns the complete route, or undefined when provider/model are unusable.
+ */
+export function routeFromSelection(selection) {
+    if (selection === undefined)
+        return undefined;
+    const { provider, model, reasoningEffort } = selection;
+    if (typeof provider !== 'string' || provider === '')
+        return undefined;
+    if (typeof model !== 'string' || model === '')
+        return undefined;
+    return {
+        provider,
+        model,
+        ...(typeof reasoningEffort === 'string' && reasoningEffort !== '' ? { reasoningEffort } : {}),
+    };
+}
+/**
+ * Resolve the three role routes for a NEW run:
+ * Commander = settings (base = config) → config; Executor = session selection
+ * → config; Watchdog = settings (base = config) → config.
+ * @param input - config fallback, settings section, and session selection.
+ * @returns the complete frozen route set.
+ */
+export function resolveEffectiveRoutes(input) {
+    return {
+        commander: routeFromSelection(input.settings?.commander) ?? input.configRoutes.commander,
+        executor: routeFromSelection(input.sessionSelection) ?? input.configRoutes.executor,
+        watchdog: routeFromSelection(input.settings?.watchdog) ?? input.configRoutes.watchdog,
+    };
+}
+/**
+ * Read the initiating Session's current model selection from the public
+ * request-header seam (`Agent.session.requestHeader().config`).
+ * @param agent - initiating agent, or undefined outside a boundary.
+ * @returns the selection route, or undefined when no header exists.
+ */
+export function sessionSelectionOf(agent) {
+    return routeFromSelection(agent?.session?.requestHeader?.()?.config);
+}

package/lib/sanitize.js

@@ -0,0 +1,39 @@
+/** Secret redaction shared by Orbit state, logs, and watchdog prompts. */
+const SECRET_PATTERNS = [
+    /(authorization\s*:\s*(?:bearer\s+)?)[^\s,;]+/gi,
+    /((?:api[_-]?key|access[_-]?token|refresh[_-]?token|password|passwd|cookie|secret|private[_-]?key)\s*[=:]\s*)[^\s,;]+/gi,
+    /(\b(?:sk|pk|ghp|github_pat)_[A-Za-z0-9_-]{8,})/g,
+    /(\bBearer\s+)[A-Za-z0-9._-]+/gi,
+];
+const SENSITIVE_KEY = /^(?:password|passwd|cookie|secret|authorization|bearer|private[_-]?key|api[_-]?key|access[_-]?token|refresh[_-]?token|token|github[_-]?token|gh[_-]?token|credential)$/i;
+export function redactText(value) {
+    let result = value;
+    for (const pattern of SECRET_PATTERNS)
+        result = result.replace(pattern, '$1[REDACTED]');
+    return result;
+}
+export function redactValue(value, key) {
+    if (key !== undefined && SENSITIVE_KEY.test(key))
+        return '[REDACTED]';
+    if (Array.isArray(value))
+        return value.map((item) => redactValue(item));
+    if (value !== null && typeof value === 'object') {
+        const out = {};
+        for (const [childKey, childValue] of Object.entries(value)) {
+            out[childKey] = redactValue(childValue, childKey);
+        }
+        return out;
+    }
+    if (typeof value === 'string')
+        return redactText(value);
+    return value;
+}
+export function truncateSafe(value, max = 4000) {
+    const redacted = redactText(value);
+    if (redacted.length <= max)
+        return redacted;
+    return `${redacted.slice(0, max)}\n...[truncated]`;
+}
+export function looksLikeSecretKey(key) {
+    return SENSITIVE_KEY.test(key);
+}

package/lib/service.js

@@ -0,0 +1,104 @@
+import { accessSync, constants, mkdirSync } from 'node:fs';
+import { Service } from '@deepseek-ai/cordis';
+import { DshOrbitHost } from "./dsh-host.js";
+import { OrbitStateStore } from "./state-store.js";
+import { OrbitSupervisor } from "./supervisor.js";
+export class OrbitService extends Service {
+    host;
+    config;
+    constructor(ctx, config) {
+        super(ctx, 'orbit');
+        this.host = new DshOrbitHost(ctx);
+        this.config = config;
+    }
+    supervisorFor(projectDir) {
+        return new OrbitSupervisor(new OrbitStateStore(projectDir), this.host, {
+            defaultRoutes: this.config.routes,
+            ...(this.config.resolveRoutes ? { resolveRoutes: this.config.resolveRoutes } : {}),
+            browserTools: this.config.browserTools,
+            commanderReadOnlyTools: this.config.commanderReadOnlyTools,
+            watchdogTools: this.config.watchdogTools,
+            executorTools: this.config.executorTools,
+            ...(this.config.executorTimeoutMs ? { executorTimeoutMs: this.config.executorTimeoutMs } : {}),
+        });
+    }
+    resolveProjectDir(projectDir) {
+        return projectDir ?? this.config.projectDir ?? process.cwd();
+    }
+    run(input, projectDir, signal) {
+        return this.supervisorFor(this.resolveProjectDir(projectDir)).bootstrap(input, signal);
+    }
+    async resume(input, projectDir, signal) {
+        const dir = this.resolveProjectDir(projectDir);
+        const state = new OrbitStateStore(dir).readState();
+        if (!state)
+            return { ok: false, action: 'resume', message: 'ORBIT_RUN_NOT_FOUND: no durable run to resume.' };
+        const supervisor = this.supervisorFor(dir);
+        return supervisor.run(state, signal);
+    }
+    stop(runId, projectDir) {
+        return this.supervisorFor(this.resolveProjectDir(projectDir)).stop('stop', runId);
+    }
+    status(projectDir) {
+        return this.supervisorFor(this.resolveProjectDir(projectDir)).status();
+    }
+    recordGuardBlock(code, reason, projectDir) {
+        return this.supervisorFor(this.resolveProjectDir(projectDir)).recordGuardBlock(code, reason);
+    }
+    hasActiveRun(projectDir) {
+        const state = new OrbitStateStore(this.resolveProjectDir(projectDir)).readState();
+        return state !== null && state.driver_ownership !== 'CLOSED';
+    }
+    githubAllowed(projectDir) {
+        const state = new OrbitStateStore(this.resolveProjectDir(projectDir)).readState();
+        return state?.github_allowed === true;
+    }
+    async doctor(projectDir) {
+        const dir = this.resolveProjectDir(projectDir);
+        const checks = [];
+        try {
+            mkdirSync(`${dir}/.cx`, { recursive: true, mode: 0o700 });
+            accessSync(`${dir}/.cx`, constants.W_OK);
+            checks.push({ name: 'state-storage', status: 'pass', detail: `${dir}/.cx is writable` });
+        }
+        catch (error) {
+            checks.push({ name: 'state-storage', status: 'fail', detail: String(error) });
+        }
+        checks.push({ name: 'subagent-service', status: this.ctx.subagents ? 'pass' : 'fail', detail: this.ctx.subagents ? 'ctx.subagents available' : 'ctx.subagents missing' });
+        checks.push({ name: 'tools-service', status: this.ctx.tools ? 'pass' : 'fail', detail: this.ctx.tools ? 'ctx.tools available' : 'ctx.tools missing' });
+        const browserTool = this.config.browserTools[0] ?? 'agent_browser';
+        const browserAvailable = this.host.hasTool(browserTool);
+        checks.push({
+            name: 'browser-capability',
+            status: browserAvailable ? 'pass' : 'warn',
+            detail: browserAvailable ? `${browserTool} registered` : `${browserTool} unavailable; browser steps will fail with BROWSER_CAPABILITY_UNAVAILABLE`,
+        });
+        const executorRegistered = this.config.executorTools.filter((tool) => this.host.hasTool(tool));
+        checks.push({
+            name: 'executor-writer-scope',
+            status: executorRegistered.length > 0 ? 'pass' : 'fail',
+            detail: executorRegistered.length > 0 ? `executor allowlist: ${executorRegistered.join(', ')}` : 'no configured executor tool is registered',
+        });
+        const driverTools = ['create_goal', 'ralph', 'workflow'].filter((tool) => this.host.hasTool(tool));
+        checks.push({
+            name: 'mutation-driver-hook',
+            status: 'pass',
+            detail: driverTools.length > 0
+                ? `Orbit mutation guard will deny ${driverTools.join(', ')} while a run is active`
+                : 'no top-level mutation driver tool is registered in this profile',
+        });
+        checks.push({
+            name: 'host-adapter-lifecycle',
+            status: 'pass',
+            detail: 'DshOrbitHost provides cancel/dispose/runtimeSnapshot for every role handle',
+        });
+        checks.push({
+            name: 'role-routes',
+            status: this.config.routes.commander.model && this.config.routes.executor.model ? 'pass' : 'fail',
+            detail: `commander=${this.config.routes.commander.model} executor=${this.config.routes.executor.model} watchdog=${this.config.routes.watchdog.model}`,
+        });
+        checks.push({ name: 'tested-dsh-version', status: 'pass', detail: 'tested against @deepseek-ai/dsh 0.1.5-rc.2' });
+        const status = checks.some((check) => check.status === 'fail') ? 'fail' : checks.some((check) => check.status === 'warn') ? 'warn' : 'pass';
+        return { status, generatedAt: new Date().toISOString(), checks };
+    }
+}

package/lib/settlement.js

@@ -0,0 +1,33 @@
+/**
+ * Settlement classification for Orbit executor/commander children.
+ *
+ * The durable seam is the session `turn/end` event: its `data.reason.kind` is
+ * `completed | aborted | error | blocked | max-tokens` (`interrupted` only
+ * appears on cold-read synthesis). A child that is merely `idle` is NOT success.
+ */
+export function classifyTurnSettlement(events) {
+    let end;
+    for (let index = events.length - 1; index >= 0; index -= 1) {
+        if (events[index]?.type === 'turn/end') {
+            end = events[index];
+            break;
+        }
+    }
+    if (!end)
+        return { settlement: 'open' };
+    const reason = end.data?.reason;
+    switch (reason?.kind) {
+        case 'completed':
+            return { settlement: 'completed' };
+        case 'aborted':
+            return { settlement: 'aborted', ...(reason.reason?.kind ? { cancelCause: reason.reason.kind } : {}) };
+        case 'error':
+            return { settlement: 'error', ...(reason.error?.message ? { errorMessage: reason.error.message } : {}) };
+        case 'blocked':
+            return { settlement: 'blocked' };
+        case 'max-tokens':
+            return { settlement: 'max-tokens' };
+        default:
+            return { settlement: 'open' };
+    }
+}

package/lib/state-store.js

@@ -0,0 +1,128 @@
+import { mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { hostname } from 'node:os';
+import { dirname, join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { redactValue } from "./sanitize.js";
+import { ORBIT_SCHEMA_VERSION } from "./types.js";
+const LOCK_TIMEOUT_MS = 5_000;
+const LOCK_STALE_MS = 30_000;
+const LOCK_SPIN_MS = 20;
+export function driverOwnershipFor(phase, status) {
+    if (['SUCCESS', 'STOPPED', 'BUDGET_EXHAUSTED'].includes(phase) || ['success', 'stopped', 'budget_exhausted'].includes(status)) {
+        return 'CLOSED';
+    }
+    return phase === 'NEEDS_USER' || status === 'needs_user' ? 'AWAITING_USER' : 'ACTIVE';
+}
+function nowIso() {
+    return new Date().toISOString();
+}
+/**
+ * Project-scoped durable store for `.cx/state.json`.
+ * Atomic write + short-transaction directory lock + monotonic revision.
+ */
+export class OrbitStateStore {
+    stateDir;
+    lockDepth = 0;
+    constructor(projectDir) {
+        this.stateDir = join(projectDir, '.cx');
+    }
+    get statePath() {
+        return join(this.stateDir, 'state.json');
+    }
+    transact(operation) {
+        if (this.lockDepth > 0)
+            return operation();
+        mkdirSync(this.stateDir, { recursive: true, mode: 0o700 });
+        const lock = join(this.stateDir, 'controller.lock');
+        const deadline = Date.now() + LOCK_TIMEOUT_MS;
+        for (;;) {
+            try {
+                mkdirSync(lock, { mode: 0o700 });
+                writeFileSync(join(lock, 'owner.json'), JSON.stringify({ pid: process.pid, hostname: hostname(), acquired_at: nowIso() }), { mode: 0o600 });
+                break;
+            }
+            catch (error) {
+                if (error?.code !== 'EEXIST')
+                    throw error;
+                if (isStale(lock) || Date.now() > deadline) {
+                    if (Date.now() > deadline && !isStale(lock))
+                        throw new Error('ORBIT_STATE_LOCK_TIMEOUT: another controller transaction is active');
+                    rmSync(lock, { recursive: true, force: true });
+                    continue;
+                }
+                sleepSync(LOCK_SPIN_MS);
+            }
+        }
+        this.lockDepth += 1;
+        try {
+            return operation();
+        }
+        finally {
+            this.lockDepth -= 1;
+            rmSync(lock, { recursive: true, force: true });
+        }
+    }
+    readRawState() {
+        try {
+            const parsed = JSON.parse(readFileSync(this.statePath, 'utf8'));
+            if (parsed !== null && typeof parsed === 'object')
+                return parsed;
+            return null;
+        }
+        catch {
+            return null;
+        }
+    }
+    readState() {
+        const raw = this.readRawState();
+        if (raw === null)
+            return null;
+        return raw;
+    }
+    writeState(state) {
+        return this.transact(() => {
+            const current = this.readRawState();
+            const revision = Number(current?.['state_revision'] ?? 0) + 1;
+            const next = {
+                ...state,
+                schema_version: ORBIT_SCHEMA_VERSION,
+                state_revision: revision,
+                driver_ownership: driverOwnershipFor(state.phase, state.status),
+                updated_at: nowIso(),
+            };
+            Object.assign(state, next);
+            this.writeJson(this.statePath, next);
+            return next;
+        });
+    }
+    writeJson(filePath, value) {
+        mkdirSync(dirname(filePath), { recursive: true, mode: 0o700 });
+        const temp = `${filePath}.${randomUUID()}.tmp`;
+        writeFileSync(temp, `${JSON.stringify(redactValue(value), null, 2)}\n`, { encoding: 'utf8', mode: 0o600 });
+        renameSync(temp, filePath);
+    }
+}
+function isStale(lock) {
+    try {
+        const owner = JSON.parse(readFileSync(join(lock, 'owner.json'), 'utf8'));
+        if (typeof owner.pid === 'number') {
+            try {
+                process.kill(owner.pid, 0);
+            }
+            catch {
+                return true;
+            }
+        }
+        const acquired = Date.parse(owner.acquired_at ?? '');
+        if (!Number.isNaN(acquired) && Date.now() - acquired > LOCK_STALE_MS)
+            return true;
+        statSync(lock);
+        return false;
+    }
+    catch {
+        return true;
+    }
+}
+function sleepSync(ms) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+}