@agent-relay/factory 0.0.0 → 0.1.2

package/README.md

@@ -1,30 +1,189 @@
-# @agent-relay/factory
+# Agent Workforce Factory
 
-Autonomous Linear-issue → triage → PR factory. **This is currently a placeholder
-reservation** — the real package (orchestrator, triage engine, GitHub merge-gate,
-fleet client, StateStore, config) is extracted here from `pear/packages/factory-sdk`
-by the **p4** workflow in the factory build-out stack.
+**Turn issues into reviewed pull requests, automatically.**
 
-See the planning + epic under [`planning/`](./planning/) (especially
-`factory-cloud-watches-local-node-linear-issue.md`).
+Point the factory at your ticketing system (Linear, GitHub, Shortcut, Asana etc) and it does the loop a human
+otherwise babysits: it discovers the issues that are ready, decides how to tackle
+each one, spawns coding agents to implement and review the change, opens a PR,
+drives it through a merge gate, and closes the issue — all inside a safety scope
+you define, so it only ever acts on work you've explicitly opted in.
 
-## Publishing
+## Why use it
 
-Releases use npm **OIDC trusted-publisher provenance** (no `NPM_TOKEN`), via
-`.github/workflows/publish.yml` — `npm publish --provenance` under
-`id-token: write`. Register this repo/workflow as a trusted publisher for
-`@agent-relay/factory` on npmjs.com before the first CI publish.
+- **Clear the small-but-real backlog.** The well-scoped fixes and chores that pile
+  up get done without a person shepherding each one.
+- **It only touches what you allow.** A safety gate (title prefix + team) means
+  the factory dispatches *exactly* the issues you mark for it and ignores
+  everything else — opt-in by construction.
+- **Real PRs, not blind merges.** Every change goes through an implement → review
+  → merge-gate flow and lands as a normal PR. It defaults to *never* auto-merging
+  until you turn that on.
+- **You stay in the loop.** It posts threaded status to Slack and can ask a human
+  for clarification mid-task when an issue is ambiguous.
+- **Drop in by label.** Hand it new work just by labeling a Linear or GitHub
+  issue — no new tooling in your day-to-day.
+
+A good fit when you have a steady stream of scoped issues and want them turned
+into PRs without standing up your own agent orchestration.
+
+## How it works
+
+```
+discover ready issues → triage (how to do it) → dispatch agents (implement + review)
+        → open PR → merge gate → close issue
+```
+
+Each step is gated by your config and the safety scope. Issues outside the scope
+are pulled but never dispatched.
+
+## Install
+
+```bash
+npm install @agent-relay/factory
+```
+
+The factory talks to a relay broker through the **`agent-relay`** sidecar; install
+and sign in to that separately (it's a peer of this package). Once installed, the
+CLI is available as `factory`:
+
+```bash
+factory factory run-once --config ./factory.config.json --dry-run
+```
+
+> Yes, `factory factory` — the `factory` CLI groups its commands under a `factory`
+> subcommand. From a source checkout instead of an npm install, run
+> `npm ci && npm run build` first, then `node bin/factory.mjs factory <action> …`.
+
+## Quick start
+
+1. **Write a minimal config** (`factory.config.json`). Only `workspaceId` and a
+   repo route are required:
+
+   ```json
+   {
+     "workspaceId": "your-workspace-id",
+     "repos": {
+       "byLabel": { "pear": "AgentWorkforce/pear" },
+       "clonePaths": { "AgentWorkforce/pear": "/path/to/your/pear/checkout" },
+       "default": "AgentWorkforce/pear"
+     }
+   }
+   ```
+
+   `workspaceId` is your relay workspace; `repos.byLabel` maps a Linear label to a
+   repo; `clonePaths` tells the agent where that repo lives locally so it has
+   somewhere to make changes.
+
+2. **Plan a cycle without touching anything** — `--dry-run` discovers and triages
+   but writes nothing and spawns no agents:
+
+   ```bash
+   factory factory run-once --config ./factory.config.json --dry-run
+   ```
+
+3. **Let it work for real:**
+
+   ```bash
+   # One discovery→dispatch cycle, then exit.
+   factory factory run-once --config ./factory.config.json
+
+   # Or run continuously as a daemon (the production form).
+   factory factory start --mode live --config ./factory.config.json
+   ```
+
+> **Pulled some issues but dispatched none?** That's the safety gate doing its
+> job — the issues are real but outside your scope. See
+> [Tell it what to work on](#tell-it-what-to-work-on).
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `factory run-once` | One discover→triage→dispatch cycle, then exit. Honors `--dry-run`. |
+| `factory loop` | A bounded multi-iteration loop, then exit. |
+| `factory start --mode live` | Long-lived daemon — the production entrypoint. Runs until you stop it. |
+| `factory status` | Print current factory status as JSON. |
+| `factory triage <KEY\|path>` | Triage one issue and print the decision. |
+| `factory dispatch <KEY\|path>` | Triage + dispatch one issue. Honors `--dry-run`. |
+| `factory canary <KEY\|path>` | Assert a known "Ready for Agent" issue is dispatch-ready by the real dry-run triage path. Prints `{ok,issue,status,reason}`; exits non-zero (with the skip reason) if it isn't. |
+
+Global options work anywhere in the args: `--config <path>`, `--dry-run`,
+`--backend <internal|relay>`. The internal backend reuses a relay broker that's
+already running for your workspace, and starts one if none is.
+
+(There are a few more operational commands — `loop-status`, `kill-loop`,
+`reap-orphans`, `close-probe` — for running the daemon in production.)
+
+### Scheduled sync-fidelity canary
+
+`factory canary` is the regression detector for upstream sync drift: if a synced
+issue stops carrying enough state to be dispatchable (e.g. the Linear sync
+regresses to records without `state.id`), a known-good issue flips from
+dispatch-ready to skipped. Run it on a schedule against a standing "Ready for
+Agent" canary issue and alert on failure.
+
+`scripts/factory-canary.sh` wraps the command for cron/launchd: it runs from your
+deployment dir (reusing the running relay broker), bounds a hung run, and posts a
+Slack alert via `FACTORY_CANARY_SLACK_WEBHOOK` on failure. See
+`scripts/com.agentrelay.factory-canary.plist.example` for an every-6h launchd
+template.
+
+## Tell it what to work on
+
+Two ways to hand the factory an issue — both are just labeling/titling, nothing
+to install:
+
+| Source | What you do | Result |
+|---|---|---|
+| **Linear** | Title it `[factory] <task>`, set the team + a repo label, move it to **Ready for Agent** | dispatched directly |
+| **GitHub** | Add the **`factory`** label to the issue | mirrored into a `[factory]` Linear issue, then dispatched |
+
+The **safety gate** is what keeps this opt-in: by default the factory only
+dispatches an issue whose **title starts with your configured prefix** *and* whose
+**team matches** your configured team. Everything else is ignored. Loosen it
+deliberately — it's the main guardrail.
+
+> Tip: `[factory-e2e]` is reserved for the factory's own self-test soak (its PRs
+> auto-close). For real work you want to keep, use the `[factory]` prefix.
+
+## Run it as a fleet node (optional)
+
+The package also ships a fleet **node definition** so a machine can advertise
+`spawn:claude` / `spawn:codex` / `workflow:run` to the cloud and run agents in the
+checkouts it owns:
 
-**Reserve the name now (manual, no provenance — that's fine for a reservation):**
 ```bash
-cd factory
-npm publish --access public      # publishes 0.0.0, reserves @agent-relay/factory
+agent-relay fleet serve @agent-relay/factory/node
+```
+
+It reads its node config from `./factory.node.json` (or `$FACTORY_NODE_CONFIG`).
+Prefer to build the definition yourself?
+
+```ts
+import { createFactoryNodeDefinition, readFactoryNodeConfigSync } from '@agent-relay/factory'
+
+export default createFactoryNodeDefinition({ config: readFactoryNodeConfigSync() })
 ```
-Then the p4 extraction lands the real code and the **first real release is 0.1.0**
-via the publish workflow (`workflow_dispatch` → `custom_version: 0.1.0`), with
-provenance.
-
-> When p4 extracts `factory-sdk` into this repo, it must **preserve** this
-> `package.json`'s `repository` + `publishConfig` fields and
-> `.github/workflows/publish.yml`, and replace the placeholder `index.js` /
-> `index.d.ts` with the real package entrypoints.
+
+## Configuration
+
+Pass a JSON file via `--config`. Beyond the two required fields above, useful
+knobs include issue **routing** (`repos.byLabel` / `byProject` / `keywordRules` /
+`default`), the **safety gate** (`safety.requireTitlePrefix`, `safety.requireTeamKey`),
+`mergePolicy` (defaults to `never`), per-role **model** overrides, and an optional
+**Slack** channel for status threads.
+
+The full schema — every field and default — is validated by Zod at load time, so
+an invalid config fails fast with a field-level error. See
+[`src/config/schema.ts`](src/config/schema.ts) for the authoritative reference,
+and [`test/fixtures/factory.config.json`](test/fixtures/factory.config.json) for a
+worked example (including offline fixture mode).
+
+## Notes
+
+- The daemon is headless by design; tools like Pear can consume this package and
+  wrap it, but the published CLI is `factory`.
+- The published `dist/` is plain ESM, runnable directly by Node (`node bin/factory.mjs`)
+  and importable by ESM consumers.
+- For production operation (the live-daemon + reaper backstop model, heartbeats,
+  and `gh`-auth preconditions), see the operations notes alongside the config schema.

package/bin/factory.mjs

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+const here = dirname(fileURLToPath(import.meta.url))
+const entry = join(here, '..', 'dist', 'cli', 'fleet.js')
+const mod = await import(pathToFileURL(entry).href)
+await mod.main(process.argv.slice(2))

package/dist/cli/fleet.d.ts

@@ -0,0 +1,81 @@
+import { createFactory, createFleet, ensureRelayBroker, type Capability, type Factory, type FactoryConfig, type FleetBackend, type FleetClient, type GhRunner, type FactoryStateResolution, type MountClient, type ProbeCloser, type RelayfileCloudMountClientConfig, type ResolvedFactoryWorkspace } from '../index.js';
+interface FleetCliDeps {
+    fleet?: FleetClient;
+    mount?: MountClient;
+    createFactory?: typeof createFactory;
+    createFleet?: typeof createFleet;
+    ensureRelayBroker?: typeof ensureRelayBroker;
+    cloudMountFromConfig?: (config?: RelayfileCloudMountClientConfig) => Promise<MountClient>;
+    resolveWorkspace?: () => Promise<ResolvedFactoryWorkspace>;
+    resolveStates?: (mount: MountClient, config: FactoryConfig) => Promise<FactoryStateResolution>;
+    ensureLocalMount?: (workspaceId: string, startDir: string, options?: {
+        acceptableWorkspaceIds?: readonly string[];
+    }) => Promise<void>;
+    waitForStopSignal?: () => Promise<number | void>;
+    stdout?: Pick<NodeJS.WriteStream, 'write'>;
+    stderr?: Pick<NodeJS.WriteStream, 'write'>;
+    probeCloser?: ProbeCloser;
+    probePrGhRunner?: GhRunner;
+    now?: () => number;
+    stopSignalProcessLike?: Pick<NodeJS.Process, 'once' | 'off'>;
+    daemonExit?: (code: number) => void;
+    flushDaemonOutput?: () => Promise<void>;
+}
+interface GlobalOptions {
+    backend: FleetBackend;
+    config?: string;
+    dryRun: boolean;
+}
+type ParsedCommand = {
+    kind: 'spawn';
+    input: {
+        capability: Capability;
+        name?: string;
+        node?: 'self' | string;
+        task?: string;
+        model?: string;
+        sessionRef?: string;
+        cwd?: string;
+    };
+} | {
+    kind: 'roster';
+} | {
+    kind: 'release';
+    name: string;
+    reason?: string;
+} | {
+    kind: 'factory';
+    action: 'run-once' | 'loop' | 'status' | 'loop-status' | 'kill-loop' | 'reap-orphans';
+} | {
+    kind: 'factory';
+    action: 'start';
+    mode?: 'live';
+} | {
+    kind: 'factory-canary';
+    issue: string;
+} | {
+    kind: 'factory-triage';
+    issue: string;
+} | {
+    kind: 'factory-dispatch';
+    issue: string;
+} | {
+    kind: 'factory-close-probe';
+    prNumber: number;
+    repo: string;
+    issue: string;
+};
+export declare function runFleetCli(argv: string[], deps?: FleetCliDeps): Promise<number>;
+export declare function parseFleetCommand(args: string[]): ParsedCommand;
+export declare function parseGlobalOptions(argv: string[]): {
+    globals: GlobalOptions;
+    args: string[];
+};
+export declare function resolveBrokerConnectionPath(startCwd?: string): string | undefined;
+export declare function installFactoryStopSignalHandlers(factory: Factory, opts?: {
+    exit?: (code: number) => void;
+    processLike?: Pick<NodeJS.Process, 'once' | 'off'>;
+}): () => void;
+export declare function main(argv?: string[]): Promise<void>;
+export {};
+//# sourceMappingURL=fleet.d.ts.map

package/dist/cli/fleet.d.ts.map

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