@opensoftware/foreman 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -1,3 +1,348 @@
-# Temporary Holding Version
+---
+covers: [modules/foreman/src/**, modules/foreman/scripts/**]
+---
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# foreman
+
+Run the factory's workflow for each work item: the stages of `factory.yaml` one after the other, each with its agent
+through the harness port, with human gates, steering and cancel, on Temporal. A run survives a restart of the
+foreman, and Temporal's UI shows its history. Decisions: [ADR 0067](../../docs/decisions/0067-foreman.md), on
+[ADR 0004](../../docs/decisions/0004-temporal.md), [ADR 0068](../../docs/decisions/0068-foreman-sandboxes.md) for
+sandboxes, and [ADR 0069](../../docs/decisions/0069-foreman-checks.md) for checks.
+
+## Quick start
+
+This quick start is scenario `SCN-FORE-001` and is tested on every change. You need the
+[Temporal CLI](https://docs.temporal.io/cli) for a local Temporal server and Git. Save a factory of two stages:
+
+```yaml factory.yaml
+version: 1
+factory: hello
+providers:
+  harness:
+    acp: "^0"
+agents:
+  plan:
+    harness: acp
+    model: routes/default
+    prompt: ./agents/plan.md
+  implement:
+    harness: acp
+    model: routes/default
+    prompt: ./agents/implement.md
+workflow:
+  - stage: plan
+  - stage: implement
+```
+
+```markdown agents/plan.md
+Write a plan for the work item into plan.md.
+```
+
+```markdown agents/implement.md
+Implement plan.md.
+```
+
+Commit it, start Temporal, and serve the foreman with Claude Code behind the `acp` harness adapter:
+
+```sh
+git init -q && git add -A && git commit -qm "the hello factory"
+temporal server start-dev --headless &
+export FOREMAN_API_TOKEN=dev-token
+export FOREMAN_HARNESSES='{"acp": "npx -y @opensoftware/harness-acp run --allow read,edit -- npx -y @agentclientprotocol/claude-agent-acp"}'
+npx @opensoftware/foreman serve
+```
+
+Save a work item, as intake publishes it:
+
+```json work.json
+{
+  "id": "wi_5d1c1f0a9e7b3c2d4e6f",
+  "type": "idea",
+  "title": "Export reports as CSV",
+  "requester": { "kind": "person", "id": "slack:U0PERSON", "displayName": "Varun" },
+  "origin": { "source": "api" },
+  "dedupeKey": "idea:export-csv"
+}
+```
+
+Start a run and read it:
+
+```sh
+curl -H "Authorization: Bearer dev-token" -H "content-type: application/json" \
+  --data @work.json http://localhost:8080/v1/runs
+curl -H "Authorization: Bearer dev-token" http://localhost:8080/v1/runs/run_…
+```
+
+The first call answers 201 with the run `run_…` in the state `running`. Once both agents ended their turns, the run is
+`complete` and both stages are `succeeded`. Temporal's UI at http://localhost:8233 shows the workflow `run_…`.
+
+## Sandboxes
+
+The quick start runs both agents on your machine. Run an agent you do not trust with that machine in a sandbox: give
+it `sandbox` in `factory.yaml`. This factory runs both stages on Docker, each in a fresh sandbox with 2 CPUs and 4 GiB,
+that may reach only npm and Anthropic's API:
+
+```yaml sandboxed/factory.yaml
+version: 1
+factory: hello
+providers:
+  harness:
+    acp: "^0"
+  sandbox:
+    docker: "^0"
+agents:
+  plan:
+    harness: acp
+    model: routes/default
+    prompt: ./agents/plan.md
+    secrets: [ref:file/anthropic-api-key]
+    sandbox:
+      template: node:24
+      cpu: 2
+      memory: 4Gi
+      egress: [registry.npmjs.org, api.anthropic.com]
+  implement:
+    harness: acp
+    model: routes/default
+    prompt: ./agents/implement.md
+    secrets: [ref:file/anthropic-api-key]
+    sandbox:
+      template: node:24
+      cpu: 2
+      memory: 4Gi
+      egress: [registry.npmjs.org, api.anthropic.com]
+workflow:
+  - stage: plan
+  - stage: implement
+```
+
+Put your Anthropic API key in the file `secrets/anthropic-api-key` and serve the foreman as in the quick start, with
+`export OSF_SECRETS_DIR=$PWD/secrets` for the [docker sandbox adapter](../../adapters/sandbox/docker/README.md). Each
+stage then goes like this:
+
+1. The foreman creates a sandbox with the adapter that the factory names under `providers.sandbox` (`docker` when it
+   names none) from the agent's `sandbox`. The spec holds each secret as a reference under a variable,
+   `ref:file/anthropic-api-key` as `ANTHROPIC_API_KEY`, and `OTEL_RESOURCE_ATTRIBUTES` with the run. The sandbox gets
+   a placeholder; its egress proxy puts the key in on the way to `api.anthropic.com`
+   ([sandbox port](../../ports/sandbox/README.md)). The foreman never reads a secret.
+2. It copies the run's folder into the sandbox, below the sandbox's working folder, as `<run ID>`.
+3. It runs the harness adapter's command line from `FOREMAN_HARNESSES` in the sandbox with the adapter's `exec`, and
+   speaks ACP to it. The template must hold that program; `node:24` holds `npx`.
+4. When the turn ended, it copies the folder back into the run's folder, so the next stage finds the files.
+5. It destroys the sandbox, also when the stage failed or was cancelled.
+
+`FOREMAN_SANDBOXES` maps an adapter's name to its command line; an adapter it does not name runs
+`npx -y @opensoftware/sandbox-<name>`. A factory names at most one sandbox adapter. An agent without `sandbox` runs on
+the foreman's machine in the run's folder. A sandboxed agent reaches no MCP server yet.
+
+## Checks
+
+A stage can wait for CI: give it `checks`, the names of the checks that must succeed on the run's pull request before
+it starts ([ADR 0069](../../docs/decisions/0069-foreman-checks.md)). This factory merges the pull request only when
+its check `verify` succeeded:
+
+```yaml checks/factory.yaml
+version: 1
+factory: hello
+providers:
+  harness:
+    acp: "^0"
+  forge:
+    github: "^0"
+agents:
+  plan:
+    harness: acp
+    model: routes/default
+    prompt: ./agents/plan.md
+  implement:
+    harness: acp
+    model: routes/default
+    prompt: ./agents/implement-pr.md
+  ship:
+    harness: acp
+    model: routes/default
+    prompt: ./agents/ship.md
+workflow:
+  - stage: plan
+  - stage: implement
+  - stage: ship
+    checks: [verify]
+```
+
+```markdown agents/implement-pr.md
+Implement plan.md on a new branch, push it and open a pull request. End with the pull request's link.
+```
+
+```markdown agents/ship.md
+Merge the pull request.
+```
+
+Serve it as in the quick start, with the forge adapter's token: `export FOREMAN_FORGE_TOKEN=…`. Then:
+
+1. The run's pull request is the last pull request link that an agent of an earlier stage wrote, in its messages or
+   in its tool calls' output: `https://<host>/<owner>/<name>/pull/<n>` (GitHub) or `…/pulls/<n>` (Forgejo). The run
+   shows it as `pullRequest`, every later stage's prompt ends with `Pull request: <link>`, and `run.completed@v1` lists
+   it in `pullRequests`.
+2. Before the stage `ship` starts, and before its gate if it has one, the foreman runs the
+   [forge adapter](../../ports/forge/README.md)'s `pr <owner>/<name> <n>` and reads the named checks. The stage lists
+   them under `checks`, each with `name` and `state`.
+3. Every check `success`: the stage starts. A check `failure` or `error`: the stage is `failed` without running its
+   agent, with the `reason` `the check verify ended with failure`, and the run is `failed`. A check `pending`, or one
+   the pull request does not have yet: the run and the stage are `blocked`, and the foreman reads the checks again
+   every `FOREMAN_CHECK_POLL_MS`. A cancel ends the wait.
+4. Without a pull request link, the stage is `failed` with the reason `no earlier stage linked a pull request`.
+
+The forge adapter is the one the factory names under `providers.forge`; a factory with `checks` names exactly one.
+`FOREMAN_FORGES` maps an adapter's name to its command line; an adapter it does not name runs
+`npx -y @opensoftware/forge-<name>`. It gets `FORGE_URL` and `FORGE_TOKEN` from `FOREMAN_FORGE_URL` and
+`FOREMAN_FORGE_TOKEN`.
+
+## Commands
+
+| Command | What it does |
+| --- | --- |
+| `foreman serve` | Serve the run API on `PORT` and run the workflow of `FOREMAN_FACTORY` on the Temporal server at `FOREMAN_TEMPORAL_ADDRESS`; with `FOREMAN_NATS_URL`, start a run for each `work.received@v1`. |
+
+## API
+
+| Route | What it does |
+| --- | --- |
+| `POST /v1/runs` | Start the run of a work item (the [work item](../../contracts/work-item/work-item.schema.json) format). 201 with the new run, 200 with the run the same work item started before, 400 with a problem that names the field. |
+| `GET /v1/runs/{runId}` | The run: `state`, `factory`, `factoryVersion`, `pullRequest`, `startedAt`, `endedAt` and its `stages`. 404 for a run the server does not know. |
+| `POST /v1/runs/{runId}/signals` | `{ "type": "steer", "message": "…" }` sends the message to the running stage's agent; `{ "type": "cancel" }` cancels the run. 202 with the run, 409 when the run ended. |
+
+The OpenAPI of the routes is in [`contracts/openapi/openapi.json`](../../contracts/openapi/openapi.json); the
+TypeScript type `paths` of `@opensoftware/contracts` types a client. Every route needs `Authorization: Bearer
+<FOREMAN_API_TOKEN>`, else 401. Errors are `application/problem+json` with `title`, `status` and `detail`.
+
+A run's ID is `run_` and 20 hex digits of the SHA-256 of the work item's ID, so a work item has one run. A run is
+`running`, `blocked` (at a gate or waiting for checks), `complete`, `failed` or `cancelled`. A stage is `pending`,
+`blocked`, `running`, `succeeded`, `failed`, `rejected` (by its gate) or `cancelled`; it has its harness `sessionId` once
+it started, its `gateId` once its gate was asked, its `checks` once they were read, and a `reason` when it failed for a
+reason the foreman knows.
+
+## How a run goes
+
+- **The factory.** `foreman serve` checks `FOREMAN_FACTORY` against the
+  [factory definition](../../contracts/factory-definition/factory-definition.schema.json) when it starts, and that each
+  stage's agent is declared; a wrong file exits 2 with the path in the file. Each run reads the file again when it
+  starts and keeps that version until it ends. Its `factoryVersion` is the commit of the repository that holds the
+  file.
+- **Stages.** The stages run in the order of `workflow`, each in the run's folder `OSF_DATA/runs/<run ID>`, or in a
+  sandbox when the stage's agent declares one ([Sandboxes](#sandboxes)). The foreman
+  starts the stage's harness adapter from `FOREMAN_HARNESSES`, speaks ACP to it, opens a session and sends one prompt:
+  the agent's prompt file, then the work item's ID, title and description. It allows the tool calls the adapter asks
+  about; limit them with the adapter's `--allow`. A turn that ends with `end_turn` succeeds the stage; any other end
+  fails or cancels it, ends the run, and leaves the later stages `pending`. The adapter gets
+  `OTEL_RESOURCE_ATTRIBUTES` with `osf.run.id`, `osf.work_item.id`, `osf.stage` and `osf.factory.version`.
+- **Checks.** Before a stage with `checks` starts, the foreman waits until those checks succeeded on the run's pull
+  request; a failing one fails the run ([Checks](#checks)).
+- **Gates.** Before a stage with a `gate` starts, the foreman asks gatekeeper at `FOREMAN_GATEKEEPER_URL`
+  ([gatekeeper](../gatekeeper/README.md#server)): the work item's ID, the stage, the summary `<title>: start the
+  stage <stage>`, the origin's link, and the gate's `policy` and `approvers` in `change`. The run is `blocked` until a
+  `gate.decided@v1` for that gate arrives on NATS. `approved` starts the stage; `rejected` or `expired` fails the run.
+- **Signals.** A steering message reaches the running stage's agent within `FOREMAN_POLL_MS` as a prompt in its
+  session, which the harness port treats as steering. A cancel ends the agent's turn, or the wait at a gate, and the
+  run is `cancelled`.
+- **Restarts.** The runs live in Temporal's history. A foreman that stops and starts again goes on with them; a stage
+  that ran when it stopped runs again, up to 3 times.
+
+## Events
+
+With `FOREMAN_NATS_URL`, the foreman starts a run for each [`work.received@v1`](../../contracts/events/work-received/work-received.schema.json)
+on `osf.work.received.v1`, and hands each [`gate.decided@v1`](../../contracts/events/gate-decided/gate-decided.schema.json)
+on `osf.gate.decided.v1` to the run of its work item. A run publishes
+[`run.started@v1`](../../contracts/events/run-started/run-started.schema.json) on `osf.run.started.v1` when it starts and
+[`run.completed@v1`](../../contracts/events/run-completed/run-completed.schema.json) on `osf.run.completed.v1` when it
+ends, with the outcome `succeeded`, `failed` or `cancelled`. Their IDs are the run's ID with `.started` and
+`.completed`. The subjects are core NATS: work published while no foreman listens is not started.
+
+## Releases
+
+release-please opens a release pull request from the Conventional Commits under `modules/foreman/`. Merging it creates
+the tag `foreman-v<version>`. The workflow `.github/workflows/publish-foreman.yml` then builds the package and
+publishes it to npm as `@opensoftware/foreman`. The first release is `0.1.0`; until `1.0.0`, a breaking change raises
+the minor version. The one-time setup is the same as for contracts
+([`contracts/README.md`](../../contracts/README.md#releases)).
+
+## Configuration
+
+<!-- generated by make docs from src/config.schema.json: do not edit -->
+
+| Variable | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `PORT` | string | `"8080"` | serve: the port the HTTP server listens on. |
+| `OSF_DATA` | string | `".foreman"` | serve: the folder of the runs' working folders, runs/<run ID>, and of the harness adapters' session records. |
+| `OSF_NOW` | string |  | The current time, like 2026-01-01T00:00:00Z, for the times of runs and stages. Default: the clock. |
+| `FOREMAN_API_TOKEN` | string |  | serve: the token that callers of /v1 send as Authorization: Bearer <token>. Required. |
+| `FOREMAN_FACTORY` | string | `"factory.yaml"` | serve: the factory definition. Its folder must be in a Git repository: a run's factory version is its commit. |
+| `FOREMAN_TEMPORAL_ADDRESS` | string | `"localhost:7233"` | serve: the gRPC address of the Temporal server. |
+| `FOREMAN_TEMPORAL_NAMESPACE` | string | `"default"` | serve: the Temporal namespace of the runs. |
+| `FOREMAN_TASK_QUEUE` | string | `"foreman"` | serve: the Temporal task queue of the runs' workflows and activities. |
+| `FOREMAN_HARNESSES` | string | `"{}"` | serve: a JSON object from harness name to the command line of its adapter. A harness it does not name runs npx -y @opensoftware/harness-<name> run. |
+| `FOREMAN_SANDBOXES` | string | `"{}"` | serve: a JSON object from sandbox adapter name to the command line of the adapter. An adapter it does not name runs npx -y @opensoftware/sandbox-<name>. The factory names its adapter under providers.sandbox, docker by default. |
+| `FOREMAN_FORGES` | string | `"{}"` | serve: a JSON object from forge adapter name to the command line of the adapter. An adapter it does not name runs npx -y @opensoftware/forge-<name>. The factory names its adapter under providers.forge. |
+| `FOREMAN_FORGE_URL` | string |  | serve: the forge adapter's FORGE_URL, for a factory whose stages have checks. Default: the adapter's own default. |
+| `FOREMAN_FORGE_TOKEN` | string |  | serve: the forge adapter's FORGE_TOKEN: a token that may read the pull requests and their checks. Never written to a file. |
+| `FOREMAN_CHECK_POLL_MS` | string | `"30000"` | serve: how long a stage that waits for pending checks waits before it reads them again, in milliseconds. |
+| `FOREMAN_POLL_MS` | string | `"1000"` | serve: how often a running stage looks for steering messages and a cancel, in milliseconds. |
+| `FOREMAN_GATEKEEPER_URL` | string |  | serve: the URL of gatekeeper serve, which a stage with a gate asks for a decision. Required for a factory with gates. |
+| `FOREMAN_GATEKEEPER_TOKEN` | string |  | serve: gatekeeper's API token, GATEKEEPER_API_TOKEN. |
+| `FOREMAN_NATS_URL` | string |  | serve: the NATS server for work.received@v1 and gate.decided@v1 in, and run.started@v1 and run.completed@v1 out. Unset: no events. |
+
+## Scenarios
+
+<!-- generated by make docs from features/: do not edit -->
+
+| ID | Status | Scenario |
+| --- | --- | --- |
+| SCN-FORE-001 | implemented | A program starts a run of the README's factory and it completes |
+| SCN-FORE-002 | implemented | Each stage's agent gets its prompt and the work item |
+| SCN-FORE-003 | implemented | The same work item again is the same run |
+| SCN-FORE-004 | implemented | A stage whose turn ends with "refusal" fails the run |
+| SCN-FORE-005 | implemented | A run the server does not know is 404 |
+| SCN-FORE-006 | implemented | A call without the API token is refused |
+| SCN-FORE-007 | implemented | A work item without a title is refused |
+| SCN-FORE-008 | implemented | A run carries the commit of the factory definition |
+| SCN-FORE-009 | implemented | A run keeps its factory version when the factory changes during the run |
+| SCN-FORE-010 | implemented | A stage that names an unknown agent stops the server at the start |
+| SCN-FORE-011 | implemented | The server needs an API token |
+| SCN-FORE-012 | implemented | A stage with a gate asks gatekeeper and the run waits |
+| SCN-FORE-013 | implemented | An approval of the gate starts the stage |
+| SCN-FORE-014 | implemented | A rejection of the gate fails the run |
+| SCN-FORE-015 | implemented | A decision for another gate does not start the stage |
+| SCN-FORE-016 | implemented | A steering message reaches the running stage's agent |
+| SCN-FORE-017 | implemented | A cancel ends the running stage's turn and the run |
+| SCN-FORE-018 | implemented | A cancel ends a run that waits at a gate |
+| SCN-FORE-019 | implemented | A signal to a run that ended is refused |
+| SCN-FORE-020 | implemented | An unknown signal is refused |
+| SCN-FORE-021 | implemented | A run goes on from its history after the foreman restarts |
+| SCN-FORE-022 | implemented | A work item from intake starts a run |
+| SCN-FORE-023 | implemented | A run that ends publishes its outcome and its factory version |
+| SCN-FORE-024 | implemented | The foreman allows a tool call that the stage's agent asks about |
+| SCN-FORE-025 | implemented | A stage whose harness does not start fails the run |
+| SCN-FORE-026 | implemented | A factory outside a Git repository stops the server at the start |
+| SCN-FORE-027 | implemented | An event without a valid work item starts no run |
+| SCN-FORE-028 | implemented | A stage's harness session carries the run |
+| SCN-FORE-029 | implemented | A run that fails publishes the outcome "failed" and the stage that failed |
+| SCN-FORE-030 | implemented | A cancelled run publishes the outcome "cancelled" |
+| SCN-FORE-031 | implemented | Two steering messages reach the agent once each, in order |
+| SCN-FORE-032 | implemented | A stage whose agent declares a sandbox runs in a sandbox created from it |
+| SCN-FORE-033 | implemented | The sandbox spec holds the agent's secret as a reference under its variable |
+| SCN-FORE-034 | implemented | A stage's sandbox carries the run in its environment |
+| SCN-FORE-035 | implemented | A file a stage writes in its sandbox reaches the run's folder and the next stage's sandbox |
+| SCN-FORE-036 | implemented | Each stage's sandbox is destroyed when the stage ends |
+| SCN-FORE-037 | implemented | A cancel destroys the sandbox of the running stage |
+| SCN-FORE-038 | implemented | A sandbox the adapter cannot create fails the run |
+| SCN-FORE-039 | implemented | The sandbox adapter is the one the factory names under "providers.sandbox" |
+| SCN-FORE-040 | implemented | A factory that names two sandbox adapters stops the server at the start |
+| SCN-FORE-041 | implemented | A stage whose agent declares no sandbox runs on the foreman's machine |
+| SCN-FORE-042 | implemented | A failing check stops the stage that waits for it |
+| SCN-FORE-043 | implemented | A stage starts when its checks succeeded |
+| SCN-FORE-044 | implemented | A pending check holds the stage until it succeeds |
+| SCN-FORE-045 | implemented | A check the pull request does not have yet holds the stage |
+| SCN-FORE-046 | implemented | A stage with checks fails when no earlier stage linked a pull request |
+| SCN-FORE-047 | implemented | A run shows its pull request and publishes it when it ends |
+| SCN-FORE-048 | implemented | A cancel ends a run that waits for a check |
+| SCN-FORE-049 | implemented | A factory with checks but without a forge adapter stops the server at the start |

package/dist/adapters/factory.js

@@ -0,0 +1,33 @@
+// Reads the factory (ADR 0067): factory.yaml, checked against the contract and for its stages' agents, the text of
+// each agent's prompt, and the factory version, the commit of the folder that holds the file.
+import { execFile } from "node:child_process";
+import { readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+import { promisify } from "node:util";
+import { UsageError } from "@opensoftware/cli";
+import { validate } from "@opensoftware/contracts";
+import { parse } from "yaml";
+import { definitionOf, stageProblems } from "../domain/definition.js";
+/** The factory at `path`; a file that cannot run is a usage error that names the file, the path in it and why. */
+export async function readFactory(path) {
+    const file = resolve(path);
+    const name = basename(file);
+    const document = parse(readFileSync(file, "utf8"));
+    const contract = validate("factory-definition", document);
+    const problems = contract.length ? contract : stageProblems(document);
+    if (problems.length)
+        throw new UsageError(problems.map((problem) => `${name}: ${problem.path}: ${problem.message}`).join("\n"));
+    const folder = dirname(file);
+    const read = (prompt) => readFileSync(resolve(folder, prompt), "utf8");
+    return { definition: definitionOf(document, read), version: await commitOf(folder, name) };
+}
+async function commitOf(folder, name) {
+    try {
+        const { stdout } = await promisify(execFile)("git", ["rev-parse", "HEAD"], { cwd: folder });
+        return stdout.trim();
+    }
+    catch {
+        throw new UsageError(`${name}: commit it in a Git repository; a run's factory version is that commit`);
+    }
+}
+//# sourceMappingURL=factory.js.map

package/dist/adapters/factory.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"factory.js","sourceRoot":"","sources":["../../src/adapters/factory.ts"],"names":[],"mappings":"AAAA,mHAAmH;AACnH,8FAA8F;AAC9F,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AACvD,OAAO,EAAE,SAAS,EAAE,MAAM,WAAW,CAAC;AACtC,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAC/C,OAAO,EAA0B,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAC3E,OAAO,EAAE,KAAK,EAAE,MAAM,MAAM,CAAC;AAC7B,OAAO,EAAmB,YAAY,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAQvF,kHAAkH;AAClH,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAY;IAC5C,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC3B,MAAM,IAAI,GAAG,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC5B,MAAM,QAAQ,GAAY,KAAK,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC;IAC5D,MAAM,QAAQ,GAAG,QAAQ,CAAC,oBAAoB,EAAE,QAAQ,CAAC,CAAC;IAC1D,MAAM,QAAQ,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,aAAa,CAAC,QAA6B,CAAC,CAAC;IAC3F,IAAI,QAAQ,CAAC,MAAM;QACjB,MAAM,IAAI,UAAU,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,GAAG,IAAI,KAAK,OAAO,CAAC,IAAI,KAAK,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC;IAC7G,MAAM,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC7B,MAAM,IAAI,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,YAAY,CAAC,OAAO,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,CAAC,CAAC;IAC/E,OAAO,EAAE,UAAU,EAAE,YAAY,CAAC,QAA6B,EAAE,IAAI,CAAC,EAAE,OAAO,EAAE,MAAM,QAAQ,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,CAAC;AAClH,CAAC;AAED,KAAK,UAAU,QAAQ,CAAC,MAAc,EAAE,IAAY;IAClD,IAAI,CAAC;QACH,MAAM,EAAE,MAAM,EAAE,GAAG,MAAM,SAAS,CAAC,QAAQ,CAAC,CAAC,KAAK,EAAE,CAAC,WAAW,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,CAAC,CAAC;QAC5F,OAAO,MAAM,CAAC,IAAI,EAAE,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,MAAM,IAAI,UAAU,CAAC,GAAG,IAAI,yEAAyE,CAAC,CAAC;IACzG,CAAC;AACH,CAAC"}

package/dist/adapters/forge.js

@@ -0,0 +1,16 @@
+// The run's pull request through the forge port (ADR 0057, ADR 0069). The adapter is a program; the foreman runs its
+// `pr` command and reads the checks of the pull request's head commit.
+import { execFile } from "node:child_process";
+/** The checks of the pull request `<repo>#<number>`; a failure names the adapter's error. */
+export function pullRequestChecks(adapter, env, repo, number) {
+    const [file, ...args] = adapter;
+    return new Promise((resolve, reject) => {
+        execFile(file, [...args, "pr", repo, number], { env }, (error, stdout, stderr) => {
+            if (error)
+                reject(new Error(`the forge adapter's pr failed: ${stderr.trim() || error.message}`));
+            else
+                resolve(JSON.parse(stdout).checks ?? []);
+        });
+    });
+}
+//# sourceMappingURL=forge.js.map

package/dist/adapters/forge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"forge.js","sourceRoot":"","sources":["../../src/adapters/forge.ts"],"names":[],"mappings":"AAAA,qHAAqH;AACrH,uEAAuE;AACvE,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAQ9C,6FAA6F;AAC7F,MAAM,UAAU,iBAAiB,CAC/B,OAAiB,EACjB,GAAuC,EACvC,IAAY,EACZ,MAAc;IAEd,MAAM,CAAC,IAAI,EAAE,GAAG,IAAI,CAAC,GAAG,OAAgC,CAAC;IACzD,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,QAAQ,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,CAAC,EAAE,EAAE,GAAG,EAAE,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE;YAC/E,IAAI,KAAK;gBAAE,MAAM,CAAC,IAAI,KAAK,CAAC,kCAAkC,MAAM,CAAC,IAAI,EAAE,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;;gBAC5F,OAAO,CAAE,IAAI,CAAC,KAAK,CAAC,MAAM,CAAiC,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QACjF,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/adapters/gatekeeper.js

@@ -0,0 +1,18 @@
+export function gatekeeper(url, token) {
+    return {
+        async request(request) {
+            if (!url)
+                throw new Error("set FOREMAN_GATEKEEPER_URL: a stage has a gate");
+            const response = await fetch(new URL("/v1/gates", url), {
+                method: "POST",
+                headers: { "content-type": "application/json", ...(token ? { authorization: `Bearer ${token}` } : {}) },
+                body: JSON.stringify(request),
+            });
+            const body = await response.text();
+            if (!response.ok)
+                throw new Error(`gatekeeper answered ${response.status} to the gate request: ${body}`);
+            return JSON.parse(body);
+        },
+    };
+}
+//# sourceMappingURL=gatekeeper.js.map

package/dist/adapters/gatekeeper.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"gatekeeper.js","sourceRoot":"","sources":["../../src/adapters/gatekeeper.ts"],"names":[],"mappings":"AAQA,MAAM,UAAU,UAAU,CAAC,GAAuB,EAAE,KAAyB;IAC3E,OAAO;QACL,KAAK,CAAC,OAAO,CAAC,OAAO;YACnB,IAAI,CAAC,GAAG;gBAAE,MAAM,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC;YAC5E,MAAM,QAAQ,GAAG,MAAM,KAAK,CAAC,IAAI,GAAG,CAAC,WAAW,EAAE,GAAG,CAAC,EAAE;gBACtD,MAAM,EAAE,MAAM;gBACd,OAAO,EAAE,EAAE,cAAc,EAAE,kBAAkB,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,aAAa,EAAE,UAAU,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE;gBACvG,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC;aAC9B,CAAC,CAAC;YACH,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;YACnC,IAAI,CAAC,QAAQ,CAAC,EAAE;gBAAE,MAAM,IAAI,KAAK,CAAC,uBAAuB,QAAQ,CAAC,MAAM,yBAAyB,IAAI,EAAE,CAAC,CAAC;YACzG,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAa,CAAC;QACtC,CAAC;KACF,CAAC;AACJ,CAAC"}