@agentproto/worktree 0.4.1 → 0.4.3

package/routines/README.md

@@ -0,0 +1,113 @@
+# Routines here have no runtime yet — a bridge proposal (DESIGN ONLY)
+
+`worktree-gc/ROUTINE.md` in this directory is a real, schema-valid AIP-41
+routine manifest (`schema: routine/v1`), shipped `enabled: false` since PR
+#626. Nothing in this repo turns it into a scheduled fire. This note records
+the gap precisely and sketches a bridge — **not built, not decided**; the
+call on whether/how to build it belongs to Jeremy.
+
+## The gap, precisely
+
+- `@agentproto/routine` (`packages/routine/src`) parses and validates a
+  `ROUTINE.md` — `parseRoutineManifest` → `routineFromManifest` →
+  `defineRoutine` (`define-routine.ts`) — into a frozen `RoutineHandle`. That
+  handle is **pure data**. `defineRoutine`'s `build()` just spreads the
+  validated definition into a new object; there is no `execute()`, no
+  scheduling hook, nothing that fires anything.
+- Nothing scans a workspace's `.routines/` directory. `grep`ing the whole
+  `packages/` tree for a reader of `.routines/*/ROUTINE.md` outside this
+  package's own manifest parser and its tests turns up nothing.
+- The one LIVE scheduling primitive in the daemon is
+  `packages/runtime/src/cron-scheduler.ts`'s `CronScheduler` — persisted,
+  ticks every 20s, fires a `CronAction`. Its `CronAction` union
+  (`cron-scheduler.ts:50-72`) has exactly three kinds: `command` (spawn a
+  shell command), `agent` (spawn a fresh agent session), `prompt-session`
+  (reprompt an existing one). **None of them is "call an in-process
+  AIP-14 tool by id."**
+- AIP-41's own `TargetTool` (`packages/routine/src/types.ts:163-171`) is
+  exactly that: `{ tool: string, inputs?: {...} }` — a TOOL ref, not a shell
+  command or an agent prompt. There is no `CronAction` shape it maps onto
+  today.
+
+That mismatch is why the daily worktree-gc sweep operationalized today as a
+`kind:"command"` cron job (`worktree-janitor-daily`) that shells out to
+`agentproto worktree gc --apply` — a subprocess, re-spawning a whole CLI
+process, re-resolving `git` from scratch — instead of the daemon just
+calling its own already-registered `worktree_gc` tool in-process, the way
+`worktree_gc` MCP calls do it today. That subprocess indirection is exactly
+where Fix A's `spawn git ENOENT` (a narrow inherited PATH baked into the
+launchd plist) came from. A `kind:"tool"` bridge doesn't just close the
+routine-runtime gap — it removes the entire class of "spawn a CLI to call a
+tool the daemon already hosts" bugs for anything wired through it.
+
+## Proposed bridge (not built)
+
+1. **New `CronAction` kind: `"tool"`.**
+   ```ts
+   | { kind: "tool"; tool: string; inputs?: Record<string, unknown> }
+   ```
+   Dispatched in-process against the same tool registry the daemon's MCP
+   surface already calls `worktree_gc` through — no subprocess, so no PATH
+   to get wrong. Whether an argv-prefix-style allowlist (mirroring
+   `command-tools.ts`'s `AllowlistEntry`) should gate which tool ids a cron
+   job may target is an open question below, not resolved here.
+
+2. **A registrar** — a new module, e.g.
+   `packages/runtime/src/routine-cron-bridge.ts` — that:
+   - Scans `<workspace>/.routines/*/ROUTINE.md` (the path the existing
+     `worktree-gc/ROUTINE.md` doc already documents as the install target).
+   - Parses each with `@agentproto/routine`'s existing
+     `parseRoutineManifest` / `routineFromManifest` — reuse, not a second
+     parser.
+   - Keeps only `enabled: true` entries whose `schedule.kind === "cron"`
+     (interval/calendar/manual/event schedules are out of scope for a
+     *cron*-scheduler bridge by construction; see open questions).
+   - Maps `target`: a `TargetTool` becomes `{kind:"tool", tool, inputs}`
+     directly. A `TargetAction` or `TargetWorkflow` target has no obvious
+     `CronAction` mapping yet — v1 logs "unsupported target kind" and skips
+     rather than guessing.
+   - Calls `cronScheduler.create(...)`, keyed so a re-scan **upserts**
+     rather than accumulates duplicates — needs a stable identifier
+     (e.g. a `sourceRoutineId` field added to `CronJob`, or a deterministic
+     `label: "routine:<id>"` the registrar diffs against) so editing or
+     removing a `ROUTINE.md` is reflected, not just additive.
+   - `@agentproto/routine`'s only deps are `gray-matter` + `zod` (checked:
+     `packages/routine/package.json`) — light enough that `@agentproto/runtime`
+     can depend on it directly, unlike `@agentproto/worktree`, which
+     `worktree-gc.ts`'s own docblock deliberately keeps out of the runtime's
+     dependency graph as "the heavy dependency."
+
+3. **Trigger points**: run the scan once at daemon boot (`serve.ts`, next to
+   where `cron-scheduler.ts` is already constructed), plus a new explicit
+   verb (`agentproto routine reload` / a `routines_reload` MCP tool,
+   mirroring the existing `cron_list`/`cron_create` surface) so editing a
+   `.routines/*.md` doesn't require a daemon restart to take effect.
+
+## Open questions (Jeremy's call, not resolved here)
+
+- **Retry / failure routing.** `CronJob` has no `retry` or `on_failure`
+  fields today (`cron-scheduler.ts:74-88`) — a fire either succeeds or
+  throws once. AIP-41's `retry.max_attempts` / `on_failure.create_work_item`
+  / `fires_events` (AIP-37 vocabulary) have no home on the cron side yet.
+  `worktree-gc/ROUTINE.md`'s own `retry.max_attempts: 1` happens to already
+  match cron's today-single-attempt behavior, which is why this particular
+  routine doesn't surface the gap — a routine that actually wants retries
+  or `fires_events` would.
+- **Allowlisting `kind:"tool"` cron jobs.** `kind:"command"` gates through
+  `.agentproto/allowed-commands.json`. Should an in-process tool call get an
+  analogous allowlist, or is "the tool is already registered on this
+  daemon" sufficient authorization? Registered tools can mutate a lot
+  (`worktree_gc --apply` deletes branches and directories) — this deserves
+  its own decision, not a default inherited from the command-allowlist
+  model by accident.
+- **Where the bridge module lives.** Proposed above as
+  `packages/runtime/src/routine-cron-bridge.ts`, but it could equally live
+  in the CLI host (next to `makeWorktreeGcRunner`) if the intent is to keep
+  `packages/runtime` free of anything that isn't a pure port/injection
+  boundary.
+- **Non-cron schedules** (`interval`, `calendar`, `manual`, `event`) aren't
+  addressed at all — this proposal only closes the `schedule.kind: "cron"`
+  case, which is what `worktree-gc/ROUTINE.md` uses.
+- **Multi-workspace scope.** v1 above only scans the active workspace's
+  `.routines/`, matching how `worktree_status` / `worktree_gc` themselves
+  resolve a repo today (`resolveWorktreeQueryRoot` → `getActiveWorkspace`).

package/routines/worktree-gc/ROUTINE.md

@@ -0,0 +1,96 @@
+---
+schema: routine/v1
+id: worktree-gc
+description: |
+  Scheduled garbage collection of merged/integrated git worktrees. Fires the
+  `worktree_gc` tool with `apply: true` so worktrees whose branch is merged
+  (or fresh) and whose tree is clean are reclaimed hands-off — the worktree is
+  removed and its branch deleted. An OPEN PR, live sessions, or anything
+  unresolved is always held and never touched; a dirty-but-integrated worktree
+  is left in place unless `salvageDirty` is turned on (it is not, here).
+  Ships DISABLED (`enabled: false`) — install it into a workspace's `.routines/`
+  and flip `enabled: true` to activate.
+version: "1.0.0"
+schedule:
+  kind: cron
+  cron: "0 4 * * *"
+  timezone: "UTC"
+  catchup: skip
+target:
+  tool: worktree_gc
+  inputs:
+    apply: true
+    salvageDirty: false
+retry:
+  max_attempts: 1
+  backoff: fixed
+on_failure:
+  create_work_item: true
+  fire_event: worktree.gc.failed
+fires_events:
+  - worktree.gc.completed
+  - worktree.gc.failed
+enabled: false
+tags: [worktree, gc, maintenance]
+---
+
+# Worktree GC Routine
+
+Runs daily at **04:00 UTC** and invokes the `worktree_gc` tool (shipped in
+[`@agentproto/worktree`](../../README.md), exposed over MCP + HTTP by the
+daemon) with `apply: true`. This reaps merged worktrees automatically so a
+long-running workspace doesn't accumulate stale `_worktrees/*` trees and their
+dead `wt/*` branches.
+
+## What it does
+
+Each fire re-runs the same plan/apply engine (`planGc` / `applyGc` in
+`packages/worktree/src/gc.ts`) that backs `agentproto worktree gc --apply`:
+
+- **`reclaim`** — branch is merged (or fresh/zero-commit) **and** the tree is
+  clean → the worktree is removed and its branch deleted.
+- **`salvage`** — integrated but the tree is dirty → **held** here, because
+  `salvageDirty` is `false`. Turn that input on only if you want dirty
+  integrated worktrees archived (snapshot-then-remove) rather than left alone.
+- **`hold`** — an open PR, live sessions, or anything unresolved → never
+  touched, regardless of any flag.
+
+Every entry is re-classified from scratch immediately before it is acted on,
+so a plan that has gone stale between planning and applying is refused rather
+than acted on.
+
+## Safety invariants (inherited from the engine)
+
+These are enforced by the engine, not by this manifest — the routine cannot
+weaken them:
+
+- **Merge-gated reclaim.** Teardown only fires when integration ∈
+  {merged, fresh} **and** the tree is clean.
+- **Open = hold.** A worktree with an open PR or live sessions is always held.
+- **Dirty = salvage-only.** A dirty integrated worktree is only ever archived
+  (never silently discarded), and only when `salvageDirty` is `true`.
+
+## Repo scope at fire time
+
+`target.inputs` carries no `repoRoot`, so the daemon resolves the repo to gc
+from the **active workspace** (`resolveWorktreeQueryRoot` →
+`getActiveWorkspace`). Pin a specific repo by adding `repoRoot: <abs path>` or
+`workspaceSlug: <slug>` to `target.inputs` before enabling — `repoRoot` wins
+over `workspaceSlug`, which wins over the active workspace.
+
+## Enabling
+
+This routine is opt-in. To activate it in a workspace:
+
+1. Copy this directory to the workspace's routine library —
+   `<workspace>/.routines/worktree-gc/ROUTINE.md` (the path
+   `@agentproto/routine`'s `routineSpec.pathOf` expects).
+2. Set `enabled: true` in the frontmatter (and, if desired, pin `repoRoot` /
+   `workspaceSlug` per above).
+3. Reload routines so the daemon registers the schedule.
+
+## Failure routing
+
+If a fire fails, `retry` gives it a single attempt (no backoff), then
+`on_failure` opens a work item and fires `worktree.gc.failed`. A clean run
+fires `worktree.gc.completed`.

package/routines/worktree-gc-notify/ROUTINE.md

@@ -0,0 +1,70 @@
+---
+schema: routine/v1
+id: worktree-gc-notify
+description: |
+  Scheduled worktree gc + Telegram notification, as ONE `target.workflow`
+  routine instead of a bare `target.tool` fire — the sibling `worktree-gc`
+  routine (`../worktree-gc/ROUTINE.md`) gc's but never reports out; this
+  fires `worktree-gc-notify/WORKFLOW.md`, whose three tool steps gc, format,
+  and notify hosted agentpush in one run. Ships DISABLED (`enabled: false`)
+  — install it into a workspace's `.routines/` and flip `enabled: true` to
+  activate. See the WORKFLOW.md alongside this file for what each step does.
+version: "1.0.0"
+schedule:
+  kind: cron
+  cron: "0 4 * * *"
+  timezone: "UTC"
+  catchup: skip
+target:
+  workflow:
+    file: /Volumes/SSDExternalMacStudio/Code/products/agentik/agentik-studio/projects/agentproto/ts/packages/worktree/routines/worktree-gc-notify/WORKFLOW.md
+  inputs:
+    chatId: "<REPLACE_WITH_YOUR_TELEGRAM_CHAT_ID>"
+retry:
+  max_attempts: 1
+  backoff: fixed
+on_failure:
+  create_work_item: true
+  fire_event: worktree.gc-notify.failed
+fires_events:
+  - worktree.gc-notify.completed
+  - worktree.gc-notify.failed
+enabled: false
+tags: [worktree, gc, maintenance, notify]
+---
+
+# Worktree GC + notify routine
+
+Runs daily at **04:00 UTC**, firing `worktree-gc-notify/WORKFLOW.md` via
+`workflow_run_file` (the same lowering every `target.workflow.file` routine
+goes through — see `routine-registrar.ts`'s `routineTargetToToolCall`). That
+workflow's three tool steps (`gc` → `format` → `notify`) are documented in
+the WORKFLOW.md itself.
+
+## Why a workflow target instead of `target.tool`
+
+`../worktree-gc/ROUTINE.md` already fires `worktree_gc` directly as a bare
+`target.tool` — simplest form, no reporting. This routine dogfoods the OTHER
+target shape (`target.workflow`), which needed the daemon-side
+`compileWorkflow` tool-registry fix to run at all: before that fix, ANY
+`tool` step in a WORKFLOW.md (this one has three) failed to resolve
+("no tool registered"), so a `target.workflow` routine whose workflow used
+tool steps could never actually complete.
+
+## Enabling
+
+1. Copy this directory to `<workspace>/.routines/worktree-gc-notify/`
+   (ROUTINE.md + WORKFLOW.md + entry.mjs together).
+2. Allowlist `bash` in that workspace's `.agentproto/allowed-commands.json`
+   (`command_execute`'s `notify` step needs it) — see the WORKFLOW.md.
+3. Set `enabled: true`, update `target.workflow.file` to wherever the
+   WORKFLOW.md actually lives in that environment, and replace
+   `target.inputs.chatId` with your own Telegram chat id.
+4. Reload routines, or fire it once ad-hoc via `routine_trigger` without
+   waiting for the schedule or flipping `enabled`.
+
+## Failure routing
+
+Same convention as `worktree-gc`: one retry attempt (no backoff), then
+`on_failure` opens a work item and fires `worktree.gc-notify.failed`. A
+clean run fires `worktree.gc-notify.completed`.

package/routines/worktree-gc-notify/WORKFLOW.md

@@ -0,0 +1,70 @@
+---
+name: Worktree GC + notify
+id: worktree-gc-notify
+description: |
+  Garbage-collects merged/fresh+clean worktrees under agentproto/ts, then
+  reports the outcome to Telegram via the hosted agentpush `send_message`
+  tool. Dogfoods a real multi-tool-step WORKFLOW.md now that the daemon's
+  `compileWorkflow` resolves `tool` steps through `dispatchTool` (see
+  `packages/runtime/src/workflow-tool-registry.ts`) instead of failing every
+  `tool` step with "no tool registered". The `format` step is entry-based —
+  there is no string expression language for a `transform` step's `compute`
+  in the declarative manifest.
+version: 0.1.0
+entry: ./entry.mjs
+inputs:
+  chatId:
+    type: string
+    description: Telegram chat id `notify` reports to. Operator-supplied — never hardcoded.
+outputs: {}
+steps:
+  - id: gc
+    kind: tool
+    tool: worktree_gc
+    inputs:
+      apply: true
+      salvageDirty: false
+      repoRoot: /Volumes/SSDExternalMacStudio/Code/products/agentik/agentik-studio/projects/agentproto/ts
+  - id: format
+    kind: transform
+  - id: notify
+    kind: tool
+    tool: command_execute
+    inputs:
+      command: bash
+      stdin: $steps.format
+---
+
+# Worktree GC + notify
+
+Three tool steps, in order:
+
+1. **`gc`** — `worktree_gc` with `apply: true`, `salvageDirty: false`. Same
+   safety invariants as the sibling `worktree-gc` routine (merge-gated
+   reclaim, open-PR-is-always-hold, dirty-is-salvage-only): this workflow
+   inherits them from the engine, it doesn't re-implement them.
+2. **`format`** — an entry-based `transform` step (see `entry.mjs`) that
+   turns `$steps.gc`'s structured `{ mode, outcomes }` into the exact JSON
+   body hosted agentpush's `POST /tools/send_message` expects (mirrors
+   `.plans/agentproto-maintenance-crons/notify-worktree-gc.sh`'s formatting).
+3. **`notify`** — `command_execute` running `bash -c '<curl to hosted
+   agentpush>'`, fed `format`'s output as `stdin` (`curl --data-binary @-`).
+   The LOCAL agentpush MCP is down; this goes straight to
+   `https://api.agentpush.io/tools/send_message` with the Bearer key sourced
+   from `envs/agentpush/.env.local`, same as the working cron script.
+
+## Enabling
+
+Ships wired to `routines/worktree-gc-notify/ROUTINE.md`, disabled
+(`enabled: false`). To activate in a workspace:
+
+1. Copy this directory to `<workspace>/.routines/worktree-gc-notify/`.
+2. `command_execute` requires `bash` (and whatever `curl` needs) allowlisted
+   in that workspace's `.agentproto/allowed-commands.json`.
+3. Set `enabled: true` on the copied `ROUTINE.md`, update
+   `target.workflow.file` if the workflow isn't installed at this same
+   absolute path in that environment (`workflow_run_file`'s `path` is read
+   as-is, with no anchoring to the routine's own directory), and set
+   `target.inputs.chatId` to your own Telegram chat id.
+4. Reload routines so the daemon registers the schedule (or fire it once
+   ad-hoc via `routine_trigger`).

package/routines/worktree-gc-notify/entry.mjs

@@ -0,0 +1,77 @@
+// Runtime source of truth for WORKFLOW.md's step graph. The frontmatter
+// mirrors this (id + kind) for governance, per `reconcileEntry`; `format`'s
+// `compute` is a real function, which is why this step can only be
+// entry-based — there is no string expression language for it in the
+// declarative manifest.
+export default {
+  name: "Worktree GC + notify",
+  id: "worktree-gc-notify",
+  description:
+    "Garbage-collect merged/fresh+clean worktrees, then report the outcome to Telegram via hosted agentpush.",
+  version: "0.1.0",
+  // `chatId` is the Telegram chat id `notify` reports to — operator-supplied
+  // at invocation (routine `target.inputs` / `workflow_run_file`'s `input`),
+  // never hardcoded, since this workflow ships in a public repo.
+  inputs: { chatId: { type: "string" } },
+  outputs: {},
+  steps: [
+    {
+      id: "gc",
+      kind: "tool",
+      tool: "worktree_gc",
+      inputs: {
+        apply: true,
+        salvageDirty: false,
+        repoRoot:
+          "/Volumes/SSDExternalMacStudio/Code/products/agentik/agentik-studio/projects/agentproto/ts",
+      },
+    },
+    {
+      id: "format",
+      kind: "transform",
+      // Turns the `gc` step's structured result into the exact JSON body
+      // hosted agentpush's `POST /tools/send_message` expects. The `$steps.*`
+      // ref grammar can substitute `$steps.gc` whole into another step's
+      // inputs, but can't serialize an object into a plain string a later
+      // tool step's `stdin` can carry — that's what this step is for.
+      compute: (b) => {
+        const gc = b.steps.gc ?? {}
+        const outcomes = Array.isArray(gc.outcomes) ? gc.outcomes : []
+        const counts = {}
+        for (const o of outcomes) counts[o.result] = (counts[o.result] || 0) + 1
+        const reaped = outcomes
+          .filter(o => o.result === "reclaimed")
+          .map(o => o.branch || o.path.split("/").pop())
+        const line =
+          Object.entries(counts)
+            .map(([k, v]) => `${v} ${k}`)
+            .join(", ") || "nothing to do"
+        const stamp = new Date().toISOString().slice(0, 16).replace("T", " ")
+        let text = `🧹 worktree-gc (${stamp} UTC) — ${line}`
+        if (reaped.length) text += `\nreaped: ${reaped.join(", ")}`
+        return JSON.stringify({
+          to: { channel: "telegram", address: b.input?.chatId },
+          content: { text },
+        })
+      },
+    },
+    {
+      id: "notify",
+      kind: "tool",
+      tool: "command_execute",
+      inputs: {
+        command: "bash",
+        args: [
+          "-c",
+          [
+            "set -a",
+            ". /Volumes/SSDExternalMacStudio/Code/products/agentik/agentik-studio/envs/agentpush/.env.local 2>/dev/null || true",
+            "set +a",
+            'curl -s --max-time 30 -X POST -H "Authorization: Bearer ${AGENTPUSH_API_KEY:-}" -H "Content-Type: application/json" https://api.agentpush.io/tools/send_message --data-binary @-',
+          ].join("\n"),
+        ],
+        stdin: "$steps.format",
+      },
+    },
+  ],
+}