@nanocollective/roster 0.1.0-alpha.1

package/templates/ops/.github/workflows/session.yaml

@@ -0,0 +1,333 @@
+name: roster session
+
+# One staff member's unattended working session. Called by a ~25-line workflow in their own brain
+# repo, which is the only file that has to exist over there.
+#
+# Reusable workflows in a private repo can only be called from inside the same organisation, which
+# is exactly why this lives in the tenant's ops repo rather than in the framework. Nothing here
+# depends on npm, on a network fetch, or on an org the tenant does not control.
+
+on:
+  workflow_call:
+    inputs:
+      staff:
+        description: "Staff handle, as it appears in org.yaml"
+        required: true
+        type: string
+      kind:
+        description: "daily | mention | pr-mention"
+        required: false
+        default: daily
+        type: string
+      ops_repo:
+        description: "owner/name of the ops repo holding org.yaml and the prompts"
+        required: true
+        type: string
+      model:
+        required: false
+        default: claude-opus-5
+        type: string
+      timeout_minutes:
+        required: false
+        default: 60
+        type: number
+      allowed_tools:
+        required: false
+        default: "Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch"
+        type: string
+      # Trigger context. Empty on a scheduled run; set when a comment or a PR woke us.
+      issue_number:
+        required: false
+        default: ""
+        type: string
+      comment_id:
+        required: false
+        default: ""
+        type: string
+      pr_number:
+        required: false
+        default: ""
+        type: string
+    secrets:
+      APP_ID:
+        required: true
+      APP_PRIVATE_KEY:
+        required: true
+      PUBLIC_APP_ID:
+        required: false
+      PUBLIC_APP_PRIVATE_KEY:
+        required: false
+      # The agent's credential. Which one a caller passes depends on the agent it runs:
+      # AGENT_TOKEN is the general form, CLAUDE_CODE_OAUTH_TOKEN the name the reference runner
+      # has always used. Neither is required on its own, and exactly one has to be present.
+      AGENT_TOKEN:
+        required: false
+      CLAUDE_CODE_OAUTH_TOKEN:
+        required: false
+
+permissions:
+  contents: read
+
+jobs:
+  session:
+    runs-on: ubuntu-latest
+    timeout-minutes: ${{ inputs.timeout_minutes }}
+
+    # secrets are not usable in a step-level `if`, so the presence check is hoisted here.
+    env:
+      HAS_PUBLIC_APP: ${{ secrets.PUBLIC_APP_ID != '' }}
+
+    steps:
+      - name: Mint the private-tracker token
+        id: private
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.APP_ID }}
+          private-key: ${{ secrets.APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+
+      # A PR opened with the default GITHUB_TOKEN does not trigger pull_request workflows, so CI
+      # would never run and the gate would be empty. The App token is not optional here.
+      - name: Mint the public-repo token
+        id: public
+        if: env.HAS_PUBLIC_APP == 'true'
+        uses: actions/create-github-app-token@v2
+        with:
+          app-id: ${{ secrets.PUBLIC_APP_ID }}
+          private-key: ${{ secrets.PUBLIC_APP_PRIVATE_KEY }}
+          owner: ${{ github.repository_owner }}
+
+      # Tell the human it was heard. This is the only signal between the request and the reply
+      # several minutes later, and without it there is no way to tell "working" from "the trigger
+      # missed". It sits here, before any checkout, so the eyes land in seconds rather than after
+      # the clones.
+      #
+      # `mention` only. A pr-mention is already acknowledged by the forwarder in the public product
+      # repo, on the comment the human actually left, and reacting again here would put two on it.
+      # A daily run has nothing to react to.
+      #
+      # An `issues` payload carries no comment, so the eyes go on the issue itself. That is the
+      # route where a mention is typed straight into the body of a new issue.
+      #
+      # Never fatal: a missing reaction is cosmetic, and failing the job over one would cost the
+      # answer as well.
+      - name: React to the request
+        if: inputs.kind == 'mention' && (inputs.comment_id != '' || inputs.issue_number != '')
+        continue-on-error: true
+        env:
+          GH_TOKEN: ${{ steps.private.outputs.token }}
+          TARGET: ${{ inputs.comment_id != ''
+            && format('issues/comments/{0}', inputs.comment_id)
+            || format('issues/{0}', inputs.issue_number) }}
+        run: |
+          gh api --method POST "repos/${{ github.repository }}/$TARGET/reactions" \
+            -f content=eyes --silent
+
+      # The ops repo is the only thing we can clone without having read a manifest, so it goes
+      # first and then tells us everything else.
+      - name: Check out the org brain
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ inputs.ops_repo }}
+          path: roster-ops
+          token: ${{ steps.private.outputs.token }}
+
+      - name: Work out what to check out
+        id: plan
+        run: node roster-ops/runner-plan.mjs --staff "${{ inputs.staff }}" --ops roster-ops >> "$GITHUB_OUTPUT"
+
+      - name: Check out the brain
+        uses: actions/checkout@v7
+        with:
+          repository: ${{ steps.plan.outputs.brain_repo }}
+          path: ${{ steps.plan.outputs.brain_dir }}
+          token: ${{ steps.private.outputs.token }}
+          fetch-depth: 0
+
+      # Peers and product repos vary per staff member, so they are cloned rather than declared.
+      - name: Check out peers and product repos
+        env:
+          PRIVATE_TOKEN: ${{ steps.private.outputs.token }}
+          PUBLIC_TOKEN: ${{ steps.public.outputs.token }}
+          PEERS: ${{ steps.plan.outputs.peers }}
+          PRODUCTS: ${{ steps.plan.outputs.products }}
+        run: |
+          set -euo pipefail
+          for spec in $PEERS; do
+            repo="${spec%%:*}"; dir="${spec##*:}"
+            git clone --quiet --depth 1 "https://x-access-token:${PRIVATE_TOKEN}@github.com/${repo}.git" "$dir"
+            echo "peer:    $repo -> $dir"
+          done
+          for spec in $PRODUCTS; do
+            IFS=':' read -r repo dir depth <<< "$spec"
+            token="${PUBLIC_TOKEN:-$PRIVATE_TOKEN}"
+            args=(--quiet)
+            [ "$depth" != "0" ] && args+=(--depth "$depth")
+            git clone "${args[@]}" "https://x-access-token:${token}@github.com/${repo}.git" "$dir"
+            echo "product: $repo -> $dir"
+          done
+
+      # Commits read as the bot, not as a human, so the git history stays legible.
+      - name: Set git identity
+        env:
+          PRIVATE_SLUG: ${{ steps.private.outputs.app-slug }}
+          PUBLIC_SLUG: ${{ steps.public.outputs.app-slug }}
+          BRAIN_DIR: ${{ steps.plan.outputs.brain_dir }}
+          PEERS: ${{ steps.plan.outputs.peers }}
+          PRODUCTS: ${{ steps.plan.outputs.products }}
+        run: |
+          set -euo pipefail
+          identify() {
+            git -C "$1" config user.name "$2[bot]"
+            git -C "$1" config user.email "$2[bot]@users.noreply.github.com"
+          }
+          identify roster-ops "$PRIVATE_SLUG"
+          identify "$BRAIN_DIR" "$PRIVATE_SLUG"
+          for spec in $PEERS; do
+            dir="${spec##*:}"; [ -d "$dir" ] && identify "$dir" "$PRIVATE_SLUG"
+          done
+          for spec in $PRODUCTS; do
+            dir=$(echo "$spec" | cut -d: -f2)
+            [ -d "$dir" ] && identify "$dir" "${PUBLIC_SLUG:-$PRIVATE_SLUG}"
+          done
+
+      # A PR request is answered on the PR's own branch, never on a new one.
+      - name: Check out the PR branch
+        if: inputs.pr_number != ''
+        env:
+          GH_TOKEN: ${{ steps.public.outputs.token || steps.private.outputs.token }}
+          PRODUCT_DIR: ${{ steps.plan.outputs.product_dir }}
+          PRODUCT_REPO: ${{ steps.plan.outputs.product_repo }}
+        run: |
+          set -euo pipefail
+          [ -n "$PRODUCT_DIR" ] || { echo "no product repo to check a PR out of"; exit 1; }
+          cd "$PRODUCT_DIR"
+          gh pr checkout "${{ inputs.pr_number }}" --repo "$PRODUCT_REPO"
+          echo "on $(git branch --show-current)"
+
+      - uses: pnpm/action-setup@v6
+        if: steps.plan.outputs.needs_node == 'true'
+        with:
+          package_json_file: ${{ steps.plan.outputs.package_json }}
+
+      - name: Use Node.js 22
+        if: steps.plan.outputs.needs_node == 'true'
+        uses: actions/setup-node@v7
+        with:
+          node-version: 22
+          cache: pnpm
+          cache-dependency-path: ${{ steps.plan.outputs.package_json }}
+
+      # Composed at run time rather than baked in, so editing org/voice.md reaches every staff
+      # member on their next run without regenerating anything.
+      - name: Compose the prompt
+        id: compose
+        env:
+          ROSTER_CONTEXT: >-
+            {"issue_number":"${{ inputs.issue_number }}",
+             "comment_id":"${{ inputs.comment_id }}",
+             "pr_number":"${{ inputs.pr_number }}",
+             "repo":"${{ github.repository }}",
+             "actor":"${{ github.actor }}"}
+        run: |
+          node roster-ops/compose.mjs --staff "${{ inputs.staff }}" --kind "${{ inputs.kind }}" --ops roster-ops --brains . > .roster-prompt.txt
+          {
+            echo 'text<<ROSTER_PROMPT_5f3a9c'
+            cat .roster-prompt.txt
+            echo 'ROSTER_PROMPT_5f3a9c'
+          } >> "$GITHUB_OUTPUT"
+
+      # A caller may pass its credential under either name. Checked here so a missing one is an
+      # immediate, obvious failure rather than an authentication error from inside the agent,
+      # forty lines into a log, after the checkout has already happened.
+      - name: Check the agent has a credential
+        env:
+          A: ${{ secrets.AGENT_TOKEN }}
+          B: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+        run: |
+          if [ -z "$A" ] && [ -z "$B" ]; then
+            echo "::error::the caller passed no agent credential. Expected AGENT_TOKEN." >&2
+            exit 1
+          fi
+
+      - name: Work out which agent runs this
+        id: agent
+        run: node roster-ops/agents.mjs --staff "${{ inputs.staff }}" --ops roster-ops --brains . >> "$GITHUB_OUTPUT"
+
+      # `uses:` cannot be an expression, so an Action-based runner has to be written out
+      # literally. This is the reference one; every other agent goes through the step below.
+      - name: Run the session
+        if: steps.agent.outputs.kind == 'action'
+        uses: anthropics/claude-code-action@v1
+        env:
+          GH_TOKEN: ${{ steps.private.outputs.token }}
+          PUBLIC_TOKEN: ${{ steps.public.outputs.token }}
+          # Kept as an alias while charters and memory still name it. Retire once they do not.
+          PIPWEB_TOKEN: ${{ steps.public.outputs.token }}
+        with:
+          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN || secrets.AGENT_TOKEN }}
+          # These repos are private and single-user, so the usual reason to hide a run's output does
+          # not apply, and hiding it turns any failure into "is_error: true" with no message.
+          # Registered secrets are still masked by the runner.
+          show_full_output: true
+          github_token: ${{ steps.private.outputs.token }}
+          # No --max-turns. A run that legitimately needs more turns should get them: capping it
+          # fails the action *after* the work is done and committed, which is a false red rather
+          # than a saved penny. timeout-minutes is the real bound.
+          claude_args: >-
+            --model ${{ inputs.model }}
+            --allowedTools "${{ inputs.allowed_tools }}"
+          prompt: ${{ steps.compose.outputs.text }}
+
+      # Any agent with a command line. The prompt is handed over as a file, never as an
+      # argument: it is thousands of words containing quotes and backticks, and argv limits and
+      # shell quoting fail at 07:00 rather than in review.
+      - name: Run the session
+        if: steps.agent.outputs.kind == 'cli'
+        env:
+          GH_TOKEN: ${{ steps.private.outputs.token }}
+          PUBLIC_TOKEN: ${{ steps.public.outputs.token }}
+          PIPWEB_TOKEN: ${{ steps.public.outputs.token }}
+          AGENT_MODEL: ${{ steps.agent.outputs.model || inputs.model }}
+          AGENT_TOOLS: ${{ inputs.allowed_tools }}
+          AGENT_TOKEN: ${{ secrets.AGENT_TOKEN }}
+          FALLBACK_TOKEN: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
+          TOKEN_ENV: ${{ steps.agent.outputs.token_env }}
+          INSTALL: ${{ steps.agent.outputs.install }}
+          RUN: ${{ steps.agent.outputs.run }}
+        run: |
+          set -euo pipefail
+          TOKEN="${AGENT_TOKEN:-$FALLBACK_TOKEN}"
+          if [ -z "$TOKEN" ]; then
+            echo "::error::no credential. Pass AGENT_TOKEN from the caller." >&2
+            exit 1
+          fi
+          # The env var name is the agent's, so it is set here rather than declared above:
+          # an `env:` key cannot be an expression.
+          export "$TOKEN_ENV=$TOKEN"
+          export AGENT_PROMPT_FILE="$PWD/.roster-prompt.txt"
+
+          if [ -n "$INSTALL" ]; then
+            echo "::group::install ${{ steps.agent.outputs.id }}"
+            eval "$INSTALL"
+            echo "::endgroup::"
+          fi
+          eval "$RUN"
+
+      # A failed unattended run is otherwise a red X in a tab nobody opens. New in the roster
+      # migration, and deliberate: every failure path should end somewhere a human reads.
+      - name: Say so if the run did not finish
+        if: failure() || cancelled()
+        env:
+          GH_TOKEN: ${{ steps.private.outputs.token }}
+          BRAIN_DIR: ${{ steps.plan.outputs.brain_dir }}
+          BRAIN_REPO: ${{ steps.plan.outputs.brain_repo }}
+        run: |
+          set -euo pipefail
+          issue="${{ inputs.issue_number }}"
+          if [ -z "$issue" ]; then
+            issue=$(sed -n 's/^status_issue:[[:space:]]*//p' "$BRAIN_DIR/staff.yaml" | head -1 || true)
+          fi
+          [ -n "$issue" ] || { echo "no status_issue in staff.yaml; nothing to comment on"; exit 0; }
+          gh issue comment "$issue" --repo "$BRAIN_REPO" --body \
+            "This run did not finish, so there is no answer coming. [Run ${{ github.run_id }}](${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}) has the error."

package/templates/ops/agents.mjs

@@ -0,0 +1,143 @@
+#!/usr/bin/env node
+/**
+ * Which coding agent actually runs a session, and how to invoke it.
+ *
+ * VENDORED into every tenant's ops repo, for the same reason compose.mjs is: a scheduled run at
+ * 07:00 must not depend on npm, on a network fetch, or on an org the tenant does not control.
+ *
+ * roster knows nothing about any particular agent. A runner is three shell-level facts — how to
+ * install it, how to run it, and which environment variable carries its credential — and the
+ * presets below are conveniences, not a closed list. Anything with a command line that accepts a
+ * prompt works; see `agent:` in org.yaml.
+ *
+ * The prompt is always handed over as a file, never as an argument. It is thousands of words,
+ * it contains quotes and backticks, and argv limits and shell quoting are exactly the sort of
+ * thing that fails at 07:00 on a Tuesday rather than in review.
+ */
+
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { parseYaml } from "./compose.mjs";
+
+/**
+ * `action` is a GitHub Action step, which has to be written into session.yaml literally —
+ * `uses:` cannot be an expression. Only the reference Claude runner is one of these.
+ * `cli` is everything else: install a package, run a command. That path is open-ended.
+ */
+export const PRESETS = {
+  // The reference runner, and the default. Uses Anthropic's own action, which handles tool
+  // permissions and output for us.
+  "claude-code-action": {
+    kind: "action",
+    token_env: "CLAUDE_CODE_OAUTH_TOKEN",
+    model: "claude-opus-5",
+  },
+
+  // The same agent through its plain CLI, for anyone who would rather not depend on the action.
+  claude: {
+    kind: "cli",
+    install: "npm install -g @anthropic-ai/claude-code",
+    run: 'claude -p --model "$AGENT_MODEL" --allowedTools "$AGENT_TOOLS" < "$AGENT_PROMPT_FILE"',
+    token_env: "CLAUDE_CODE_OAUTH_TOKEN",
+    model: "claude-opus-5",
+  },
+
+  codex: {
+    kind: "cli",
+    install: "npm install -g @openai/codex",
+    // `exec -` reads the prompt from stdin. The sandbox has to be opened up because the whole
+    // point of a session is that it edits the checkout and pushes.
+    run: 'codex exec - --model "$AGENT_MODEL" --sandbox danger-full-access < "$AGENT_PROMPT_FILE"',
+    token_env: "CODEX_API_KEY",
+    model: "gpt-5-codex",
+  },
+
+  nanocoder: {
+    kind: "cli",
+    install: "npm install -g @nanocollective/nanocoder",
+    // `run` is its non-interactive mode; --trust-directory skips the first-run prompt that
+    // would otherwise hang a runner, and --plain avoids the TUI. The prompt is an argument
+    // here rather than stdin, so it is read out of the file.
+    run: 'nanocoder --model "$AGENT_MODEL" --mode yolo --trust-directory --plain run "$(cat "$AGENT_PROMPT_FILE")"',
+    token_env: "NANOCODER_API_KEY",
+    model: "",
+  },
+};
+
+/**
+ * The runner for a staff member: the org's choice, overridden per staff member, overridden by
+ * anything written out longhand. A tenant that needs an agent nobody has heard of writes
+ * `install`, `run` and `token_env` and never touches this file.
+ */
+export function resolveAgent(org, staff = {}) {
+  const asked = staff.agent ?? org.agent ?? {};
+  const spec = typeof asked === "string" ? { id: asked } : asked;
+  const id = spec.id ?? "claude-code-action";
+  const preset = PRESETS[id];
+
+  if (!preset && !(spec.install && spec.run)) {
+    throw new Error(
+      `unknown agent "${id}", and no install/run given.\n` +
+      `  Known: ${Object.keys(PRESETS).join(", ")}\n` +
+      `  Or describe your own in org.yaml:\n` +
+      `    agent:\n      id: ${id}\n      install: <shell>\n      run: <shell>\n      token_env: <VAR>`,
+    );
+  }
+
+  const merged = { kind: "cli", ...(preset ?? {}), ...strip(spec) };
+  if (merged.kind === "cli" && !merged.run) throw new Error(`agent "${id}" has no run command`);
+  if (!merged.token_env) throw new Error(`agent "${id}" does not say which env var carries its credential`);
+
+  return {
+    id,
+    kind: merged.kind,
+    install: merged.install ?? "",
+    run: merged.run ?? "",
+    token_env: merged.token_env,
+    // The staff member's own model wins; then the agent's default. Empty means "the agent's".
+    model: staff.model ?? merged.model ?? "",
+  };
+}
+
+function strip(o) {
+  const out = {};
+  for (const [k, v] of Object.entries(o)) if (v !== undefined && v !== null && v !== "") out[k] = v;
+  delete out.id;
+  return out;
+}
+
+/* --------------------------------- the runner --------------------------------- */
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  const at = (flag) => { const i = args.indexOf(flag); return i === -1 ? undefined : args[i + 1]; };
+  const opsDir = at("--ops") ?? "roster-ops";
+  const brainsDir = at("--brains") ?? ".";
+  const handle = at("--staff");
+
+  const org = parseYaml(readFileSync(join(opsDir, "org.yaml"), "utf8"), "org.yaml");
+  const entry = (org.staff ?? []).find((s) => s.handle === handle);
+  if (!entry) {
+    process.stderr.write(`agents: no staff member "${handle}" in org.yaml\n`);
+    process.exit(2);
+  }
+
+  let manifest = {};
+  try {
+    const dir = entry.dir ?? entry.handle;
+    manifest = parseYaml(readFileSync(join(brainsDir, dir, "staff.yaml"), "utf8"), "staff.yaml");
+  } catch {
+    /* A staff member with no manifest is doctor's problem; the org's default still resolves. */
+  }
+
+  const agent = resolveAgent(org, manifest);
+  const out = [
+    `kind=${agent.kind}`,
+    `id=${agent.id}`,
+    `token_env=${agent.token_env}`,
+    `model=${agent.model}`,
+    `install<<AGENT_EOF_9c1f\n${agent.install}\nAGENT_EOF_9c1f`,
+    `run<<AGENT_EOF_9c1f\n${agent.run}\nAGENT_EOF_9c1f`,
+  ].join("\n");
+  process.stdout.write(out + "\n");
+}