productfoo 0.0.0-stage → 1.0.1

package/dist-public/src/agentAdapters.js

@@ -0,0 +1,178 @@
+// Cross-agent runtime registry for portable routines (portable-routines-v0).
+//
+// A routine's *contract* is canonical and runtime-neutral (purpose, observation
+// source, allowed actions, verification check, terminal states, approval
+// boundaries — see routines.ts). What differs per coding agent is only the
+// *binding*: how a schedule is armed, and how that agent is invoked headless for
+// one pass. This registry is that binding, kept in one place so adding a runtime
+// is a data edit, not a code change.
+//
+// productfoo never runs a scheduler itself. It validates the canonical contract and
+// emits the per-runtime binding artifact (a crontab line, a CI workflow, a
+// `.claude`/`.codex` descriptor). The runtime's own scheduler fires it; each
+// pass writes its iteration record back into the packet ledger, so the loop's
+// output stays runtime-neutral no matter who ran it.
+export function resolveHarnessCommandTarget(adapter, scope) {
+    if (adapter.support === "planned") {
+        return { supported: false, reason: adapter.unsupportedReason ?? `${adapter.label} command surface not yet supported` };
+    }
+    const dir = scope === "global" ? adapter.commandsDir.global : adapter.commandsDir.project;
+    if (dir == null) {
+        return { supported: false, reason: `${adapter.label} has no ${scope}-scope command directory` };
+    }
+    return { supported: true, dir, extension: adapter.commandExtension, format: adapter.commandFormat, prefix: adapter.commandPrefix ?? "" };
+}
+// Claude and Codex are the two supported runtimes for V0; the rest are mapped
+// with the concrete gap so "what else we'd want to fit for" is explicit, not lost.
+export const AGENT_ADAPTERS = {
+    claude: {
+        id: "claude",
+        label: "Claude Code",
+        support: "supported",
+        config_dir: ".claude",
+        can_run_headless: true,
+        trigger_mechanisms: ["manual", "schedule", "event"],
+        // Headless one-shot, least-privilege by default: -p runs non-interactively
+        // and exits, with normal permission prompts intact. Raising autonomy
+        // (acceptEdits / skip-permissions) for an unattended routine is a deliberate
+        // opt-in, never the emitted default (foo-roast Agent-Safety finding).
+        invoke_template: 'claude -p "{prompt}"',
+        notes: "Schedule via the harness scheduler (cron) or the /loop skill; events via hooks. Pass --output-format json to capture the iteration record for the ledger. Raise autonomy explicitly if a routine truly needs unattended edits.",
+    },
+    codex: {
+        id: "codex",
+        label: "Codex CLI",
+        support: "supported",
+        config_dir: ".codex",
+        can_run_headless: true,
+        trigger_mechanisms: ["manual", "schedule"],
+        // `codex exec` is Codex's non-interactive one-shot.
+        invoke_template: 'codex exec "{prompt}"',
+        notes: "Headless via `codex exec`. No first-party scheduler yet — arm the schedule with system cron or github-actions and let the binding invoke `codex exec`.",
+    },
+    cursor: {
+        id: "cursor",
+        label: "Cursor",
+        // A headless CLI now EXISTS — `cursor-agent -p "<prompt>"` — so the gap is no
+        // longer "no CLI"; it is RELIABILITY. `-p` has documented hang / terminal-not-
+        // released bugs (community reports, early 2026), which is precisely the B4
+        // failure mode: an unattended loop that never returns. So `can_run_headless`
+        // stays false until `-p` reliability is confirmed on a pinned version. First-
+        // class on the command surface (HARNESS_COMMAND_ADAPTERS); gated as an
+        // UNATTENDED runtime on purpose. (cursor.com/docs/cli/headless)
+        support: "planned",
+        config_dir: ".cursor",
+        can_run_headless: false,
+        trigger_mechanisms: ["manual"],
+        invoke_template: null,
+        notes: "Headless CLI exists (`cursor-agent -p`), but `-p` has reported reliability issues (hangs / does not release the terminal) that make it unsafe to arm for unattended loops today. Promote `can_run_headless` once `-p` is confirmed reliable on a pinned version; until then run a watched one-shot manually, or arm via github-actions running a supported runtime.",
+    },
+    "github-actions": {
+        id: "github-actions",
+        label: "GitHub Actions",
+        support: "planned",
+        config_dir: ".github/workflows",
+        can_run_headless: true,
+        // CI is the strongest portable *scheduling substrate*: it can arm a cron and
+        // then invoke ANY of the runtimes above in a job step.
+        trigger_mechanisms: ["schedule", "event"],
+        invoke_template: null,
+        notes: "Meta-adapter: `on: schedule` (cron) or `on:` events host any runtime's headless invocation in a step. Best path to arm Codex on a cadence today; needs secrets handling and a committed workflow.",
+    },
+};
+// Human command surfaces for `foo agent setup`. The canonical behavior lives in
+// `commands/*.md` and the CLI; these descriptors only adapt that portable
+// payload to a harness filesystem convention.
+export const HARNESS_COMMAND_ADAPTERS = {
+    "claude-code": {
+        id: "claude-code",
+        label: "Claude Code",
+        // Claude Code namespaces slash commands by SUBDIRECTORY of its native
+        // commands dir: .claude/commands/foo/spec.md is typed /foo:spec, loaded in
+        // every session with zero registration. The earlier plugin install
+        // (.claude/skills/foo/ + .claude-plugin/plugin.json) is retired: Claude
+        // Code only loads plugins registered in its plugin manager or passed via
+        // --plugin-dir, so the unregistered directory silently loaded nothing and
+        // fresh sessions had no /foo:* commands at all.
+        commandsDir: { global: ".claude/commands/foo", project: ".claude/commands/foo" },
+        commandExtension: ".md",
+        commandFormat: "markdown",
+        support: "supported",
+        commandNamespace: "foo",
+        projectPath: ".claude/commands",
+        legacyPaths: [".claude/skills"],
+        legacyCommandsDir: ".claude/skills/foo/commands",
+        legacyPluginDir: ".claude/skills/foo",
+    },
+    codex: {
+        id: "codex",
+        label: "Codex",
+        // Current Codex App + CLI share the plugin substrate. A personal plugin is
+        // the verified way to expose the SAME /foo:* namespace in both.
+        commandsDir: { global: "plugins/foo/skills", project: null },
+        commandExtension: ".md",
+        commandFormat: "markdown",
+        commandLayout: "skills",
+        support: "supported",
+        plugin: { dir: "plugins/foo", name: "foo", manifestRelPath: ".codex-plugin/plugin.json" },
+        marketplace: { manifestRelPath: ".agents/plugins/marketplace.json", name: "personal" },
+        projectPath: "plugins/foo",
+        legacyPaths: [".agents/skills"],
+    },
+    opencode: {
+        id: "opencode",
+        label: "OpenCode",
+        // ~/.config/opencode/commands (global) + .opencode/commands (project) — NOT .agents/.
+        commandsDir: { global: ".config/opencode/commands", project: ".opencode/commands" },
+        commandExtension: ".md",
+        commandFormat: "markdown",
+        support: "supported",
+        commandPrefix: "foo-",
+        projectPath: ".opencode/commands",
+        legacyPaths: [".agents/skills"],
+        legacyCommandsDir: ".agents/commands",
+    },
+    cursor: {
+        id: "cursor",
+        label: "Cursor",
+        // ~/.cursor/commands (global) + .cursor/commands (project); markdown, /-invoked.
+        commandsDir: { global: ".cursor/commands", project: ".cursor/commands" },
+        commandExtension: ".md",
+        commandFormat: "markdown",
+        support: "supported",
+        commandPrefix: "foo-",
+        projectPath: ".cursor/commands",
+        legacyPaths: [".agents/skills"],
+        legacyCommandsDir: ".agents/commands",
+    },
+    grok: {
+        id: "grok",
+        label: "Grok Bot",
+        // Grok Bot command directory follows the common .grok/commands pattern.
+        // D-001 (embedded invocation): bot skills embed command contract and call `foo <command>`.
+        // D-002: eight commands only (init, spec, ideate, pitch, research, preview, roast, discovery) — bug excluded.
+        commandsDir: { global: ".grok/commands", project: ".grok/commands" },
+        commandExtension: ".md",
+        commandFormat: "markdown",
+        support: "supported",
+        commandPrefix: "foo-",
+        projectPath: ".grok/commands",
+        excludedCommands: ["bug"], // D-002: exclude bug from third-party Grok Bot
+        legacyPaths: [],
+    },
+};
+export function getAdapter(id) {
+    return AGENT_ADAPTERS[id];
+}
+export function supportedRuntimes() {
+    return Object.keys(AGENT_ADAPTERS).filter((id) => AGENT_ADAPTERS[id].support === "supported");
+}
+export function knownRuntimes() {
+    return Object.keys(AGENT_ADAPTERS);
+}
+export function knownHarnessCommandAdapters() {
+    return Object.keys(HARNESS_COMMAND_ADAPTERS);
+}
+export function getHarnessCommandAdapter(id) {
+    return HARNESS_COMMAND_ADAPTERS[id];
+}

package/dist-public/src/agentState.d.ts

@@ -0,0 +1,43 @@
+export type AgentTelemetryConfig = {
+    enabled: boolean;
+    testerId?: string;
+};
+export type CliUsageEvent = {
+    schema_version: "0.1";
+    event_type: "cli_usage";
+    id: string;
+    timestamp: string;
+    domain: string;
+    command: string;
+    exit_code: number;
+    error_class: string;
+    error_code?: string;
+    duration_ms: number;
+    version: string;
+    tester_id?: string;
+    packet_slug?: string;
+    attributes?: {
+        interactive: boolean;
+        fingerprint?: string;
+    };
+};
+export declare function agentLogPath(_root?: string): string;
+export declare const LEDGER_MAX_BYTES: number;
+export declare function appendLedgerEvent(logPath: string, line: string, maxBytes?: number): void;
+export declare function agentTelemetryConfigPath(root: string): string;
+export declare function machineTelemetryConfigPath(): string;
+export declare function nextAgentEventId(): string;
+export declare function readTelemetryFile(configPath: string): {
+    config: Partial<AgentTelemetryConfig>;
+    exists: boolean;
+};
+export declare function readAgentTelemetryConfig(root: string): {
+    config: AgentTelemetryConfig;
+    exists: boolean;
+};
+export declare function writeAgentTelemetryConfig(root: string, config: AgentTelemetryConfig): void;
+export declare function writeMachineTesterId(testerId: string): void;
+export declare function generateTesterId(): string;
+export declare function resolveTesterId(root: string): string | undefined;
+export declare function autoWireEligibleDomain(domain: string | undefined): boolean;
+export declare function isFlagOnlyDomain(domain: string): boolean;

package/dist-public/src/agentState.js

@@ -0,0 +1,177 @@
+// Light, boot-path agent state: the ledger/event primitives, telemetry config,
+// tester identity, and the auto-wire eligibility predicate that cli.ts's
+// per-invocation spine uses. This module exists so the every-invocation code
+// path (usage telemetry, event ids, log path) does not pull the heavy `agent`
+// command domain (harness adapters, redaction, agent setup) into the static
+// import graph — cli_performance-v0 R-002 lazy dispatch. The functions are
+// moved verbatim from commands/agent.ts, which re-exports them.
+import { appendFileSync, mkdirSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { randomBytes } from "node:crypto";
+import path from "node:path";
+import { readJson } from "./jsonFile.js";
+import { machineStateDir } from "./machineState.js";
+import { fileStatKey, readMemoized, writeMemoized } from "./processMemo.js";
+// The event ledger is MACHINE state, not project state — the same argument that
+// already moved the tester id out of the project dir (see machineTelemetryConfigPath
+// below). It used to be `<cwd>/.foo/agent-events.jsonl`: foo wrote telemetry INTO
+// the user's git repo, on every invocation, and nothing gitignored it. An alpha
+// tester found it as an untracked file she had to clean up herself.
+//
+// It never bit in dogfood for one reason: productfoo's OWN .gitignore has `.foo/`. productfoo
+// was the only repo in the world where the bug was invisible.
+//
+// The other exit — writing `.foo/` into the user's .gitignore for them — is the
+// same sin in a different file: editing a tracked project file nobody asked us to
+// touch (R-004 says this out loud about shell profiles; a .gitignore is no
+// different). So foo writes under its own home instead, and leaves the user's repo
+// exactly as it found it. FOO_STATE_DIR overrides for tests. (R-005)
+export function agentLogPath(_root) {
+    return path.join(machineStateDir(), "agent-events.jsonl");
+}
+// The ledger is read back whole (`foo agent logs|rate|telemetry` parse every
+// line), so an unbounded file would make those reads grow with history. At
+// the cap the current file rotates to `<name>.1` — one backup generation, the
+// oldest events falling off first (cli-performance-v0 R-004, audit F7).
+export const LEDGER_MAX_BYTES = 5 * 1024 * 1024;
+// Single append per event, with size-cap rotation: every ledger write goes
+// through here so no site can rewrite the file. Rotation is one rename (the
+// live file becomes the backup, replaced in turn by the next rotation) —
+// never a read-and-rewrite of the corpus. The cap is a parameter so tests can
+// exercise the boundary without materializing megabytes.
+export function appendLedgerEvent(logPath, line, maxBytes = LEDGER_MAX_BYTES) {
+    mkdirSync(path.dirname(logPath), { recursive: true });
+    if (maxBytes > 0) {
+        try {
+            if (statSync(logPath).size >= maxBytes)
+                renameSync(logPath, `${logPath}.1`);
+        }
+        catch (error) {
+            // No ledger yet is the normal first-append case, not a failure; any
+            // other stat error (permissions, EACCES) is real and must surface.
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    }
+    appendFileSync(logPath, line);
+}
+export function agentTelemetryConfigPath(root) {
+    return path.join(root, ".foo", "telemetry.json");
+}
+// The tester id is a PER-MACHINE identity (one human, one id), so it lives
+// under the home dir — never the project dir. Persisting it per-project minted
+// a fresh id (and fired a fresh activation event) in every directory a tester
+// ran foo from, inflating install counts. FOO_STATE_DIR overrides for tests.
+export function machineTelemetryConfigPath() {
+    return path.join(machineStateDir(), "telemetry.json");
+}
+export function nextAgentEventId() {
+    return `evt_${Date.now().toString(36)}_${Math.random().toString(36).slice(2, 8)}`;
+}
+// Per-process memo (cli_performance-v0 R-002): telemetry config is read 3× per
+// invocation today (cli.ts usage path ×2 + resolveTesterId). Keyed on
+// (mtime, size) so an external write between reads — a test fixture, another
+// process — invalidates naturally; every in-process write deletes its entry.
+const telemetryFileCache = new Map();
+export function readTelemetryFile(configPath) {
+    const key = fileStatKey(configPath);
+    const cached = readMemoized(telemetryFileCache, configPath, key);
+    if (cached !== undefined)
+        return { exists: cached.exists, config: { ...cached.config } };
+    let value;
+    if (key === "absent")
+        value = { config: {}, exists: false };
+    else {
+        try {
+            value = { config: readJson(configPath), exists: true };
+        }
+        catch {
+            value = { config: {}, exists: false };
+        }
+    }
+    writeMemoized(telemetryFileCache, configPath, key, value);
+    return { exists: value.exists, config: { ...value.config } };
+}
+// Merged view: the tester id comes from the machine config first (project as a
+// pre-fix fallback, adopted upward by resolveTesterId); the opt-out honors a
+// `false` at EITHER scope, so a disable always holds.
+export function readAgentTelemetryConfig(root) {
+    const project = readTelemetryFile(agentTelemetryConfigPath(root));
+    const machine = readTelemetryFile(machineTelemetryConfigPath());
+    const testerId = machine.config.testerId ?? project.config.testerId;
+    return {
+        config: {
+            enabled: project.config.enabled !== false && machine.config.enabled !== false,
+            ...(testerId ? { testerId } : {}),
+        },
+        exists: project.exists || machine.exists,
+    };
+}
+function writeTelemetryFile(configPath, config) {
+    mkdirSync(path.dirname(configPath), { recursive: true });
+    writeFileSync(configPath, `${JSON.stringify({ schema_version: "0.1", ...config }, null, 2)}\n`);
+    // Same-process reads must observe the write (enable/disable then read).
+    telemetryFileCache.delete(configPath);
+}
+// Per-repo settings (the enable/disable opt-out) stay in the project config.
+export function writeAgentTelemetryConfig(root, config) {
+    writeTelemetryFile(agentTelemetryConfigPath(root), config);
+}
+// Identity writes go to the machine config — one id per human per machine.
+export function writeMachineTesterId(testerId) {
+    const { config } = readTelemetryFile(machineTelemetryConfigPath());
+    writeTelemetryFile(machineTelemetryConfigPath(), { ...config, enabled: config.enabled !== false, testerId });
+}
+export function generateTesterId() {
+    return `t_${randomBytes(6).toString("hex")}`;
+}
+// Local installation identifier. Precedence:
+// FOO_TESTER_ID env (maintainer-issued at invite) > machine config > project
+// config (pre-fix installs; adopted upward once) > freshly generated. Opaque
+// token, never a name; it attributes metadata-only usage and count-only
+// Firecrawl bridge metering. The bridge is untrusted transport; sealing and
+// exact-byte receipt validation are separate, and there is no multi-model panel.
+// Returns undefined when telemetry is opted out — no id is minted
+// or emitted in that case.
+export function resolveTesterId(root) {
+    const { config } = readAgentTelemetryConfig(root);
+    if (!config.enabled)
+        return undefined;
+    const machine = readTelemetryFile(machineTelemetryConfigPath()).config;
+    const fromEnv = process.env.FOO_TESTER_ID?.trim();
+    if (fromEnv) {
+        if (machine.testerId !== fromEnv)
+            writeMachineTesterId(fromEnv);
+        return fromEnv;
+    }
+    if (machine.testerId)
+        return machine.testerId;
+    // Pre-fix installs persisted the id per-project: adopt it upward once so the
+    // tester keeps their identity and no duplicate activation fires.
+    if (config.testerId) {
+        writeMachineTesterId(config.testerId);
+        return config.testerId;
+    }
+    const generated = generateTesterId();
+    writeMachineTesterId(generated);
+    return generated;
+}
+// Which invocations may trigger the install-once-wire-all self-wiring
+// (maybeAutoWireHarnesses, commands/agent.ts). Trivial meta commands are
+// exempt, and so is the BARE invocation (no domain at all): a stranger's
+// first-ever `foo` must answer before it writes — the front door used to wire
+// `~/.claude/commands/*` and stamp `~/.foo` on the way to printing
+// "domain missing" (FTUX defect: mutate-before-hello). Lives here (not the
+// heavy agent domain) because dispatch consults it on every invocation.
+export function autoWireEligibleDomain(domain) {
+    if (domain === undefined)
+        return false;
+    return !["--version", "-v", "version", "help", "--help", "-h"].includes(domain);
+}
+// Flag-only invocations (`--version`, `help`) carry no usage signal worth a
+// ledger line: appending one trained a spurious event into every machine's
+// ledger on every boot (cli-performance-v0 R-004, audit F7). Derived-domain
+// form — deriveCliCommand normalizes --version/-v and --help/-h before this
+// sees them. The keyed auto-report is a separate egress flow and is unaffected.
+export function isFlagOnlyDomain(domain) {
+    return domain === "version" || domain === "help";
+}

package/dist-public/src/bugCapsule.d.ts

@@ -0,0 +1,94 @@
+import type { ErrorClass, ErrorCode } from "./errorTaxonomy.js";
+export type FieldValue = {
+    state: "collected";
+    value: string;
+} | {
+    state: "not_collected" | "withheld" | "unavailable";
+    reason: string;
+};
+export type BugCapsule = {
+    schema_version: "0.1";
+    capsule_id: string;
+    occurred_at: string;
+    producer: {
+        name: string;
+        version: string;
+    };
+    product: {
+        name: string;
+        component: string;
+        version: string;
+    };
+    invocation: {
+        command: string;
+        runtime: {
+            node: string;
+            platform: string;
+            arch: string;
+        };
+    };
+    failure: {
+        class: ErrorClass;
+        code: ErrorCode;
+        classifier_version: "0.1";
+        classification: "known" | "fallback";
+        message: FieldValue;
+        stack: FieldValue;
+    };
+    report: {
+        expected: FieldValue;
+        actual: FieldValue;
+        reproduction: FieldValue;
+    };
+    evidence: Array<{
+        kind: "diagnostic" | "user_report";
+        state: FieldValue["state"];
+        content_type: string;
+    }>;
+    similarity: {
+        version: "0.1";
+        signals: Array<{
+            kind: "error_fingerprint";
+            value: string;
+        }>;
+    };
+    links: Array<{
+        relation: string;
+        provider: string;
+        external_id: string;
+        provenance: "reporter_observed";
+        authority: "reference";
+    }>;
+    extensions: Record<string, unknown> & {
+        foo?: {
+            spec_context?: {
+                spec_id: string;
+                packet_path: string;
+                revision?: string;
+                requirement_ids: string[];
+                task_ids: string[];
+                provenance: "reporter_observed";
+            };
+        };
+    };
+};
+/** Historical delivery metadata retained so existing local archives remain readable. */
+export type DeliveryReceipt = {
+    schema_version: "0.1";
+    receipt_id: string;
+    capsule_id: string;
+    payload_digest: string;
+    accepted_at: string;
+    destination: string;
+    status: "accepted" | "rejected" | "retryable";
+    error: null | {
+        code: string;
+        message: string;
+        retry_after?: string;
+    };
+};
+export declare function canonicalBytes(capsule: BugCapsule): Buffer;
+export declare function payloadDigest(capsule: BugCapsule): string;
+export declare function uuidV7(nowMs?: number, entropy?: Buffer): string;
+export declare function parseBugCapsule(value: unknown): BugCapsule;
+export declare function parseDeliveryReceipt(value: unknown): DeliveryReceipt;