spexcode 0.6.2 → 0.6.5

package/node_modules/@spexcode/spec-cli/dist/hook-prompts.js

@@ -0,0 +1,122 @@
+export const HOOK_PROMPT_SOURCE = 'spec-cli/src/hook-prompts.ts';
+function interpolate(template, params) {
+    return template.replace(/\{([a-z][a-z0-9-]*)\}/gi, (whole, key) => {
+        const value = params[key];
+        if (value === undefined)
+            throw new Error(`hook prompt requires '${key}'`);
+        return String(value);
+    });
+}
+const SPEC_FIRST = [
+    'Before accessing governed source {path}, read its governing spec FIRST: {owner}. Read the relevant NEIGHBORS too: the parent that scopes it, the siblings it borders, and the children that refine it. Then reconcile deliberately: change the spec if the intent is changing, or make the code honor it. The one forbidden move is code that silently diverges from its spec. (Fires once per session, at the first governed code read.)',
+].join('\n');
+const SPEC_OF_FILE = 'Contract context for this edit:\n{details}';
+const STOP_GATE_VARIANTS = Object.freeze({
+    full: [
+        'Your session state is a CLAIM the graph, your supervisor, and other agents act on — not a box to tick to end the turn. Stopping undeclared makes your outcome a guess. Pick the ONE that is TRUE right now and run `{cli} session <choice>`, choosing the <choice> whose condition holds:',
+        '  • done --propose merge  — spec+code COMMITTED on the branch and genuinely ready for human review. It declares REVIEW and is the ONLY proposal that offers a clickable merge.',
+        '  • done --propose nothing — TRAP: records no state. Choose merge, close, ask, or park below.',
+        '  • done --propose close — task genuinely settled, work landed (or none to merge), worktree no longer needed, and no human decision, follow-up, or posted artifact awaits inspection: propose human close. It declares CLOSE-PENDING, not merge. Never run `session close` on your own id.',
+        '  • ask --note <what-you-await> — a human reply, direction, or decision is needed, including a reported finding/recommendation, handoff, or posted-artifact inspection. It declares ASKING and resumes only when they reply.',
+        '  • park --note <what-you-await> — ONLY when a real wake-up will resume a named next action: a managed watch delivery or background task. A watch on terminal children is not a wake-up. It declares PARKED and self-resumes.',
+        '',
+        'DECLARE LAST, THEN STOP: finish everything else in the turn first — speak, send your messages, establish managed watches or arm background waits — and make the declaration your FINAL call. Any tool call AFTER it flips your record back to active (mark-active, by design: activity is activity), so the next stop re-blocks and demands a fresh declaration; declaring last kills that loop at its source.',
+        '',
+        '(This full explanation shows once per session; later undeclared stops get a one-line reminder. `{cli} help session` re-explains the choices any time.)',
+    ].join('\n'),
+    terse: 'undeclared stop — declare the ONE true state as your LAST call: `{cli} session <done --propose merge (review; ONLY clickable merge)|close (close-pending; settled, no human decision/follow-up or posted artifact waiting)|park (parked; real wake-up + next action) / ask (asking; human reply/direction/decision, including reported finding/recommendation or handoff)>`. `done --propose nothing` is a trap: it writes no state and names these choices. Conditions: `{cli} help session`.',
+    artifact: 'a posted file/web artifact still needs human inspection; declare `spex session ask --note ...`, and declare it last.',
+    commit: 'Not ready to declare done: {reason}. The dogfood ritual lands every change as a git commit on your node branch BEFORE you propose. Commit your spec.md + code on this node branch (spec: <id> — <reason>, with a Session: trailer), then re-run `{cli} session done --propose {proposal}`.',
+    eval: 'eval — the loss signal the optimizer reads — flags {count} gap(s) in nodes you changed: {ids}. A node whose score went stale/unmeasured: re-measure it — PRODUCE the measurement YOURSELF with a real run of the scenario\'s actual surface (its tag on the `spex eval lint --changed` line tells you WHICH surface to run), compare to expected, and file it with `spex eval add <node>`; don\'t desk-check it, and don\'t defer to reviewing a recording after the fact. A FRONTEND node with no eval.md: give it one (a scenario — description + expected), since an obvious UI change should carry a loss signal. `spex eval lint --changed` lists them. (Advisory — fires once, not a gate.)',
+});
+const STOP_GATE_CONTENT = Object.entries(STOP_GATE_VARIANTS)
+    .map(([name, template]) => `## ${name}\n${template}`)
+    .join('\n\n');
+const NO_PROMPT = (name, effect) => `No prompt text is injected by ${name}. ${effect}`;
+const DEFINITIONS = Object.freeze([
+    {
+        name: 'idle',
+        title: 'idle',
+        description: 'Lifecycle signal only; no agent-facing text is emitted.',
+        role: 'signal',
+        content: NO_PROMPT('idle', 'It records an undeclared idle session in the session list.'),
+        render: () => '',
+    },
+    {
+        name: 'mark-active',
+        title: 'mark-active',
+        description: 'Freshness signal only; no agent-facing text is emitted.',
+        role: 'signal',
+        content: NO_PROMPT('mark-active', 'It updates the session lifecycle record before the tool runs.'),
+        render: () => '',
+    },
+    {
+        name: 'session-fail',
+        title: 'session-fail',
+        description: 'Failure signal only; no agent-facing text is emitted.',
+        role: 'signal',
+        content: NO_PROMPT('session-fail', 'It records a failed governed turn as error.'),
+        render: () => '',
+    },
+    {
+        name: 'spec-first',
+        title: 'spec-first',
+        description: 'Blocking prompt injected once before the first governed code read.',
+        role: 'prompt',
+        content: SPEC_FIRST,
+        render: (params) => interpolate(SPEC_FIRST, params),
+    },
+    {
+        name: 'spec-of-file',
+        title: 'spec-of-file',
+        description: 'Non-blocking context injected when an actionable edited file needs attention.',
+        role: 'prompt',
+        content: SPEC_OF_FILE,
+        render: (params) => interpolate(SPEC_OF_FILE, params),
+    },
+    {
+        name: 'stop-gate',
+        title: 'stop-gate',
+        description: 'Blocking and advisory prompt variants emitted at the stop boundary.',
+        role: 'prompt',
+        content: STOP_GATE_CONTENT,
+        render: (params) => {
+            const variant = String(params.variant ?? '');
+            const template = STOP_GATE_VARIANTS[variant];
+            if (!template)
+                throw new Error(`unknown stop-gate prompt variant '${variant}'`);
+            return interpolate(template, params);
+        },
+    },
+]);
+function freeze(value) {
+    if (!value || typeof value !== 'object' || Object.isFrozen(value))
+        return value;
+    for (const child of Object.values(value))
+        freeze(child);
+    return Object.freeze(value);
+}
+/** The single authoring registry for text emitted by runtime hooks and published prompt catalogs. */
+export class HookPromptCatalog {
+    entries;
+    definitions;
+    constructor() {
+        this.entries = freeze(DEFINITIONS.map(({ render: _render, ...entry }) => ({ ...entry })));
+        this.definitions = new Map(DEFINITIONS.map((entry) => [entry.name, entry]));
+    }
+    entry(name) {
+        const entry = this.definitions.get(name);
+        if (!entry)
+            throw new Error(`surface:hook node '${name}' has no HookPromptCatalog entry`);
+        const { render: _render, ...publicEntry } = entry;
+        return publicEntry;
+    }
+    render(name, params = {}) {
+        const entry = this.definitions.get(name);
+        if (!entry)
+            throw new Error(`surface:hook node '${name}' has no HookPromptCatalog entry`);
+        if (entry.role !== 'prompt')
+            throw new Error(`surface:hook node '${name}' does not emit prompt text`);
+        return entry.render(params);
+    }
+}

package/node_modules/@spexcode/spec-cli/dist/hooks.d.ts

@@ -0,0 +1 @@
+export declare function compileManifest(cfgs?: import("@spexcode/spec-core").ConfigPreset[]): string;

package/{spec-cli/src/hooks.ts → node_modules/@spexcode/spec-cli/dist/hooks.js}

@@ -1,5 +1,4 @@
-import { loadHookConfig } from './specs.js'
-
+import { loadHookConfig } from '@spexcode/spec-core';
 // @@@ hook manifest - the harness-agnostic hook system has THREE parts: (1) the discovered handlers —
 // `surface: hook` nodes under .plugins/core/* (spec-governed content, each shipping one co-located .sh);
 // (2) this COMPILER, which flattens them into a flat per-session manifest; (3) a pure-shell dispatcher
@@ -11,17 +10,18 @@ import { loadHookConfig } from './specs.js'
 // sorted by event, then order, then script — the DETERMINISTIC run order the native multi-hook model (which
 // runs matching hooks in parallel on BOTH Claude Code and Codex) cannot guarantee. One node binds many
 // events (mark-active → UserPromptSubmit+PreToolUse) → one manifest line per (node × event).
-export function compileManifest(cfgs = loadHookConfig()): string {
-  const lines: string[] = []
-  for (const h of cfgs) {
-    const script = h.files.find((f) => f.endsWith('.sh'))
-    if (!script) throw new Error(`surface:hook node '${h.name}' ships no .sh script (one co-located .sh required)`)
-    for (const ev of h.events) lines.push(`${ev}\t${h.order}\t${h.block}\t${script}`)
-  }
-  lines.sort((a, b) => {
-    const A = a.split('\t'), B = b.split('\t')
-    return A[0].localeCompare(B[0]) || Number(A[1]) - Number(B[1]) || (a < b ? -1 : a > b ? 1 : 0)
-  })
-  return lines.length ? lines.join('\n') + '\n' : ''
+export function compileManifest(cfgs = loadHookConfig()) {
+    const lines = [];
+    for (const h of cfgs) {
+        const script = h.files.find((f) => f.endsWith('.sh'));
+        if (!script)
+            throw new Error(`surface:hook node '${h.name}' ships no .sh script (one co-located .sh required)`);
+        for (const ev of h.events)
+            lines.push(`${ev}\t${h.order}\t${h.block}\t${script}`);
+    }
+    lines.sort((a, b) => {
+        const A = a.split('\t'), B = b.split('\t');
+        return A[0].localeCompare(B[0]) || Number(A[1]) - Number(B[1]) || (a < b ? -1 : a > b ? 1 : 0);
+    });
+    return lines.length ? lines.join('\n') + '\n' : '';
 }
-

package/node_modules/@spexcode/spec-cli/dist/host-resources.d.ts

@@ -0,0 +1,97 @@
+import { type HarnessLivenessRecord } from './harness.js';
+import { type ProcessIdentity } from '@spexcode/spec-core';
+export type ResourceReference = {
+    sessionId: string | null;
+    threadId: string | null;
+    status: string | null;
+    ownerState: 'governed' | 'unowned' | 'ambiguous';
+    referenceState: 'loaded' | 'record-only' | 'queued-no-thread';
+    turnPresence: 'active' | 'idle' | 'unknown' | 'none';
+    protectsControlPlane: boolean;
+    liveness?: 'offline' | 'unknown';
+};
+export type ResourceOwner = {
+    kind: 'session' | 'shared-runtime' | 'backend' | 'orphan' | 'unattributed';
+    id: string;
+    label: string;
+    status?: string;
+    liveness?: 'offline' | 'unknown';
+    proposal?: string | null;
+    note?: string | null;
+    worktreePath?: string;
+    branch?: string | null;
+    stopped?: boolean;
+    archived?: boolean;
+    processes: Array<ProcessIdentity & {
+        command: string;
+        rssMiB: number;
+        pssMiB: number | null;
+        cpuPercent: number;
+    }>;
+    rssMiB: number;
+    pssMiB: number | null;
+    cpuPercent: number;
+    budget: {
+        rssMiB: number | null;
+        idleCpuPercent: number | null;
+    };
+    controlPlane?: {
+        healthy: boolean;
+        refCount: number | null;
+        error?: string;
+    };
+    references?: ResourceReference[];
+    findings: string[];
+    reclaim?: {
+        eligible: boolean;
+        reason: string;
+    };
+};
+export type ResourceReport = {
+    version: 1;
+    measuredAt: string;
+    projectRoot: string;
+    platform: string;
+    available: boolean;
+    unavailableReason?: string;
+    host: {
+        memoryTotalMiB: number | null;
+        memoryUsedMiB: number | null;
+        memoryAvailableMiB: number | null;
+        swapTotalMiB: number | null;
+        swapUsedMiB: number | null;
+        cpuPercent: number | null;
+    };
+    budgets: ResourceBudgets;
+    owners: ResourceOwner[];
+    totals: {
+        rssMiB: number;
+        pssMiB: number | null;
+        cpuPercent: number;
+    };
+    findings: number;
+};
+export type ResourceBudgets = {
+    sessionRssMiB: number;
+    backendRssMiB: number;
+    idleCpuPercent: number;
+    sampleMs: number;
+    reportIntervalMs: number;
+};
+export declare class ResourceConflict extends Error {
+    readonly code: string;
+    constructor(message: string, code?: string);
+}
+export declare function resourceBudgets(root?: string): ResourceBudgets;
+export declare function assertSessionOwnerSafe(id: string, harnessId: string): void;
+export declare function collectResourceReport(opts?: {
+    procRoot?: string;
+    persist?: boolean;
+}): Promise<ResourceReport>;
+export declare function assertSessionStopSafe(id: string, rec: (HarnessLivenessRecord & {
+    harness?: string;
+}) | null, opts?: {
+    coldReceipt?: unknown;
+}): Promise<void>;
+export declare function formatResourceReport(report: ResourceReport): string;
+export declare function startResourceMonitor(): void;