@fro.bot/systematic 3.32.3 → 3.33.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/HARNESSES.md +16 -13
- package/dist/ce-connect-helper.d.ts +4 -2
- package/dist/cli.js +1 -1
- package/dist/{index-nrbdgp4m.js → index-1cj1mrpb.js} +34 -2
- package/dist/index.js +1 -1
- package/dist/lib/config-schema.d.ts +2 -0
- package/dist/lib/config.d.ts +3 -2
- package/dist/lib/connect-ci.d.ts +189 -0
- package/dist/lib/connect-config.d.ts +28 -8
- package/dist/lib/connect-helper-core.d.ts +110 -1
- package/dist/lib/connect-import.d.ts +169 -0
- package/dist/lib/connect-repo-identity.d.ts +33 -0
- package/dist/lib/connect-state.d.ts +138 -3
- package/dist/pi.js +34 -2
- package/package.json +8 -8
- package/skills/ce-connect/SKILL.md +28 -5
- package/skills/ce-connect/references/fetch-and-import.md +136 -0
- package/skills/ce-connect/references/headless-and-outcomes.md +42 -4
- package/skills/ce-connect/scripts/connect.mjs +3136 -144
package/HARNESSES.md
CHANGED
|
@@ -29,7 +29,7 @@ The citations above (OC-1 to OC-8) describe the v1 adapter. The v2 adapter is th
|
|
|
29
29
|
|
|
30
30
|
## OpenCode v2 — Tier 1 shipped adapter
|
|
31
31
|
|
|
32
|
-
One package serves both OpenCode lines. v1 (1.18.29 and later) reads the `plugin` key and calls `server`; v2 (2.2.5 and later) reads `plugins` and calls `setup(ctx)`. Versions below those floors are unsupported, with no shim. Both floors are held in `scripts/opencode-host-pins.json` (`v1Floor`, `v2Floor`), and the `@opencode-ai/plugin` and `@opencode/plugin` peer ranges start at them.
|
|
32
|
+
One package serves both OpenCode lines. v1 (1.18.29 and later) reads the `plugin` key and calls `server`; v2 (2.2.5 and later) reads `plugins` and calls `setup(ctx)`. Versions below those floors are unsupported, with no shim. Both floors are held in `scripts/opencode-host-pins.json` (`v1Floor`, `v2Floor`), and the `@opencode-ai/plugin` and `@opencode/plugin` peer ranges start at them. CI runs the v2 pin, not the floor; no CI job runs a v2 release older than the floor, and the `execute.before` hook that the `ce:connect` tool guard relies on has been observed only on the floor and later pins.
|
|
33
33
|
|
|
34
34
|
History of the earlier v2 floor: the first v2 floor was 2.2.0, chosen on 2026-10-27 as a support decision rather than a loader limit. The loader probe found that 1.18.28 and v2 2.1.4 load the object default exactly as the floor versions do, and that v2 2.1.4 silently drops a function default while 2.2.0 logs a warning [OC2-LOADER]. 2.2.0 was then the oldest v2 release the adapter was tested on; whether earlier releases provide every API it uses was not probed. The floor moved to 2.2.5 because that is the only v2 release CI runs.
|
|
35
35
|
|
|
@@ -46,7 +46,7 @@ Each v2 mechanism was chosen by a probe against OpenCode 2.2.0 on 2026-10-27. Th
|
|
|
46
46
|
| Output truncation | Truncates | The host cuts tool output at 2000 lines or 51200 bytes after the plugin's `execute.after` hook sees the full text. The full text is kept by call id and put back in the `context` hook; nothing depends on the marker text | [OC2-TRUNC] |
|
|
47
47
|
| Commands | Passed, with constraints | `ctx.command.transform`; a plugin command receives only the typed text and does its own expansion; routing is not offered to plugin commands, so a bundled command that declares `agent`, `model` or `subtask` is refused, while a discovered skill's fields are dropped with a note; a name that matches a built-in replaces it | [OC2-CMD] |
|
|
48
48
|
| Apply order | Documented | Plugin transforms run first, then user config and discovered sources; `reload()` replays transforms on a fresh editor and does not re-run `setup` | [OC2-ORDER] |
|
|
49
|
-
| Error handling | Documented | A rejected `setup` leaves the plugin unloaded and the host running; a throwing transform disables the whole plugin; a throwing hook breaks the turn.
|
|
49
|
+
| Error handling | Documented | A rejected `setup` leaves the plugin unloaded and the host running; a throwing transform disables the whole plugin; a throwing hook breaks the turn. Ordinary installers and the callbacks they register are guarded and never throw. The read-only tool guard is the exception and fails closed: its installer runs first and outside the never-throw wrapper, so a failed registration reports once and withholds its agents, and its hook throws on purpose. Invalid config rejects `setup` as it throws on v1 | [OC2-ERR] |
|
|
50
50
|
| Project directory | Documented | `ctx.location.directory` is the project directory (the service's working directory is not); each location gets a fresh module instance and its own `setup` | [OC2-TRUST] |
|
|
51
51
|
| Task tracking tool | Conditional, unobserved | Binary strings name a `todowrite` tool behind the experimental `todo` option; no live request showed it | [OC2-TODO] |
|
|
52
52
|
|
|
@@ -75,7 +75,7 @@ Pi honors Systematic's disable settings. `src/pi.ts` loads the merged config onc
|
|
|
75
75
|
|
|
76
76
|
## Claude Code — Tier 1 shipped adapter
|
|
77
77
|
|
|
78
|
-
Claude Code's profile records name-based subagent dispatch, `AskUserQuestion`, task tracking through `TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate`, and native Skill/`SKILL.md` discovery [CC-P]. Systematic builds a self-contained plugin bundle in CI from `skills/` and `agents/` via `scripts/build-claude-code-plugin.ts`: it flattens agent personas, composes an output style from the using-systematic body plus the Claude Code profile, emits a declarative `SessionStart` hook, and translates every internal identifier (`ce:<name>`, `systematic:<category>:<name>`) into Claude Code's plugin-namespaced form (`systematic:<skill-dir>`, `systematic:<agent-stem>`), gated by an integrity check that fails the build on any leftover source-namespace or unresolved bare reference [CC-9]. The bundle is never committed to `main` — `claude-code/` is gitignored build staging — and CI publishes the built output to the orphan `claude-code-plugin` branch
|
|
78
|
+
Claude Code's profile records name-based subagent dispatch, `AskUserQuestion`, task tracking through `TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate`, and native Skill/`SKILL.md` discovery [CC-P]. Systematic builds a self-contained plugin bundle in CI from `skills/` and `agents/` via `scripts/build-claude-code-plugin.ts`: it flattens agent personas, composes an output style from the using-systematic body plus the Claude Code profile, emits a declarative `SessionStart` hook, and translates every internal identifier (`ce:<name>`, `systematic:<category>:<name>`) into Claude Code's plugin-namespaced form (`systematic:<skill-dir>`, `systematic:<agent-stem>`), gated by an integrity check that fails the build on any leftover source-namespace or unresolved bare reference [CC-9]. The bundle is never committed to `main` — `claude-code/` is gitignored build staging — and CI publishes the built output to the orphan `claude-code-plugin` branch when a release is published [CC-11]. Users install it through the marketplace catalog checked into `main` at `.claude-plugin/marketplace.json`, which points the `systematic` plugin entry at the `claude-code-plugin` branch ref [CC-12]: `claude plugin marketplace add marcusrbrown/systematic` then `claude plugin install systematic@systematic`. The plugin has no version field; it is versioned by the source commit SHA baked into each publish commit.
|
|
79
79
|
|
|
80
80
|
Delegation is name-based: a prompt invokes a subagent by name (for example, "Use the systematic-implementer subagent to …") and Claude Code resolves it against the plugin's `agents/` directory; skills may additionally run scoped subagent forks via `context: fork` [CC-1]. `AskUserQuestion` is the blocking-interaction tool [CC-2]. `TodoWrite` is deprecated and disabled by default; `TaskCreate`/`TaskGet`/`TaskList`/`TaskUpdate` are the current task-tracking tools [CC-3][CC-4]. Skills are discovered natively from `SKILL.md` under `~/.claude/skills/`, `.claude/skills/`, and the plugin's own `skills/` directory through the built-in Skill tool; Systematic registers no `systematic_skill` tool on Claude Code, unlike its OpenCode and Pi adapters [CC-5][CC-6][CC-9].
|
|
81
81
|
|
|
@@ -98,7 +98,7 @@ Systematic ships its own search over four kinds of durable output: `docs/solutio
|
|
|
98
98
|
|
|
99
99
|
Evidence tiers differ by host, and this file does not claim more than the tests do:
|
|
100
100
|
- **Host-free contract evidence:** one parity test drives each adapter's real entry over one fixture corpus and compares the rendered text; a second runs the built bin under real Node from a directory with no `node_modules` [SR-1].
|
|
101
|
-
- **Real-host tests:** OpenCode v1 on the floor (1.18.29) and current
|
|
101
|
+
- **Real-host tests:** OpenCode v1 on the floor (1.18.29) and current lanes, and OpenCode v2 at the pinned version, each call the tool through a real host [SR-2]. CI runs them in the host-contract jobs.
|
|
102
102
|
- **Delegated-reach tests:** on OpenCode v1 (floor and current), OpenCode v2 and Pi, a dispatched learnings-researcher child calls `systematic_search` and its result reaches the parent. The child's next model request must carry a tool message that starts `Search "` and names both planted documents, and the parent's final request must carry both paths [SR-5]. These prove reach and plumbing. A scripted model makes the call, so they do not show that a live model chooses to search.
|
|
103
103
|
- **External search, host-free:** one parity test drives v1, v2, Pi, the CLI, the bin in process and the built bin under Node over one fixture project with a project source and a user source, and compares the rendered `external` text byte for byte. It also covers the not-allowed reply, an allow-list edit between two calls with nothing restarted, and `search.enabled: false` [SR-6].
|
|
104
104
|
- **External search, delegated:** on OpenCode v2 only, a dispatched learnings-researcher child searches `kind: external` and the planted external path reaches the parent's final answer, with a negative control that withholds the allow entry [SR-6]. Delegated external proofs on OpenCode v1, Pi and Claude Code have not been run, and a scripted model makes the call, so this shows reach and plumbing, not that a live model chooses `external`. The researcher's side of the call is pinned by the wiring contract test [SR-6].
|
|
@@ -108,15 +108,17 @@ Evidence tiers differ by host, and this file does not claim more than the tests
|
|
|
108
108
|
|
|
109
109
|
The `ce:connect` skill dispatches `connections-researcher`, an agent that must not run shell commands, write, edit or fetch. Each host enforces that differently, so a host and version counts as supported only after a deny was observed on that host: the shipped researcher is dispatched, a scripted model calls shell, write, edit and web fetch, each is refused, a read succeeds and reaches the parent, and the planted marker file is never written. A negative control removes the limits and the proof fails under its own name. The supported pairs are in `HOST_SUPPORT_TABLE` in `src/lib/connect-config.ts`; each row names the test that observed it in `observedBy`. A definition test is a regression pin and is never counted as proof.
|
|
110
110
|
|
|
111
|
-
| Host |
|
|
112
|
-
|
|
113
|
-
| OpenCode v1 |
|
|
114
|
-
| OpenCode v2 |
|
|
115
|
-
| Pi |
|
|
116
|
-
| Claude Code |
|
|
111
|
+
| Host | Mechanism | Support evidence |
|
|
112
|
+
|---|---|---|
|
|
113
|
+
| OpenCode v1 | `permission:` denies `bash`, `edit`, `webfetch`, `websearch` and `task`, plus `external_directory: allow` so a headless run can read allowed projects outside the working directory. Another config entry of the same agent name keeps only its `model` and `variant`; the denies and prompt are Systematic's. A string `tools:` is dropped by the host's converter and is not relied on. | Observed [CN-1] |
|
|
114
|
+
| OpenCode v2 | The same denies, plus Systematic's `execute.before` tool guard, which refuses every call from `connections-researcher` outside `read`, `grep`, `glob`, `skill`, `systematic_search` and `systematic_skill`, direct or from inside Code Mode. A session-level allow overrides an agent's own deny on v2, so the guard does the enforcing. Another plugin's definition of the same agent name is replaced by Systematic's, keeping only its `model`; a definition in the user's own config applies after the plugin transforms and is not replaced. | Observed [CN-2][CN-3] |
|
|
115
|
+
| Pi | The agent's `tools: Read, Grep, Glob` reach the delegate session as read, grep and find. The agent is not one of the curated pi-subagents personas, which carry no tool allowlist. | Observed [CN-4] |
|
|
116
|
+
| Claude Code | The agent declares `tools: Read, Grep, Glob` and `disallowedTools`. The positive `tools` allowlist is what the host enforced in the manual run: the session's tools were Read, Grep and Glob. Upstream reports describe `disallowedTools` not being enforced for plugin subagents, so the allowlist leads. | Observed once, by hand, with a live model [CN-5]. Any other version is unlisted: headless mode refuses it and interactive mode warns and asks consent. |
|
|
117
117
|
|
|
118
118
|
What the evidence does not show: a scripted model makes the calls, so these proofs show enforcement plumbing, not live model choice. Read tools are not path-scoped on any host and session MCP tools are not denied; the guide documents both as limits. The v1 floor (1.18.29) has no row and is not run against this proof.
|
|
119
119
|
|
|
120
|
+
The scheduled workflow is a separate surface: it runs the skill headless on a CI runner and posts a report issue. Live runs of it, including the report author, the in-place edit on a second same-day run, a hand cancel and an agent-step timeout, are recorded in [CN-6]. That entry also lists what was not observed live.
|
|
121
|
+
|
|
120
122
|
## Worktree placement rule — bootstrap paths
|
|
121
123
|
|
|
122
124
|
One short rule ships in the shared bootstrap: create a worktree at `.worktrees/<branch>` under the main repository root with the `git-worktree` skill's script, and follow a different location or tool when the user or a project instruction names one. The script (`skills/git-worktree/scripts/worktree-manager.sh`) is small and non-interactive: `create`, `list`, `switch`, `copy-env` and `cleanup`, with exit codes 0 ok, 1 error, 2 usage and 3 refused, and no stdin reads. `create` places the worktree at `.worktrees/<branch>` under the main root, writes `.worktrees/.gitignore` and never edits the root `.gitignore`, and fails closed on a bare, separate-git-dir or submodule layout; `cleanup` reports and removes only named clean worktrees [WT-2]. The rule lives in `skills/using-systematic/references/worktree-placement.md` and holds no harness identifiers [WT-1]. Each adapter composes it differently:
|
|
@@ -232,7 +234,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
232
234
|
- **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
|
|
233
235
|
- **OC-4** — `src/lib/asset-plan.ts:223-234` (`loadSkillAsCommand`), `:532-551` (bundled skills as `systematic:<name>` commands), `:553-618` (discovered skills as commands); `src/lib/config-handler.ts:367-377` (`registerSkillsPaths`, the v1 skill path); `src/lib/config-handler.ts:188-274` (the v1 config hook that writes the plan into the host config); `src/lib/config-handler.ts:112-170` (`foldPermissionRulesToV1Map`, which writes each managed skill allow under both the bare and the `systematic:` name unless the user wrote a rule for the prefixed name, because v1's native `skill` tool asks with the bare name and `systematic_skill` with the prefixed one); `src/lib/config-handler.ts:276-360` (`denyDisabledSkills`, the top-level `permission.skill` deny in both name forms for each disabled skill, because the registered skills folder is not filtered). Real v1 host, 1.19.4: `tests/integration/opencode-v1.test.ts` (a managed `skills` list loads through `systematic_skill`; the native `skill` tool refuses a disabled skill).
|
|
234
236
|
- **OC-5** — `src/lib/skill-tool.ts:146-230` (`createSkillTool`, the v1 tool with the `context.ask` permission check at `:198-203`).
|
|
235
|
-
- **OC-6** — `ARCHITECTURE.md:
|
|
237
|
+
- **OC-6** — `ARCHITECTURE.md:255-261` (invariant 2) and `agents/`.
|
|
236
238
|
- **OC-7** — `src/lib/asset-plan.ts:274-380` (a model reaches an agent only through `applyAgentOverlays`, `applyAgentOverlayPass` and `applyRoutingModel`, all driven by user-owned overlays); `tests/unit/config-handler.test.ts:1173-1330` (overlay model emitted, `model: null` restores inheritance, native same-name replacement stays model-free).
|
|
237
239
|
- **OC-8** — `src/lib/opencode-v1.ts:73-79` (v1: the loaded config and `composeBootstrapContent`; the rule is always supplied and the gate lives in `getBootstrapContent`); `src/lib/bootstrap.ts:144-160` (`readWorktreePlacementRule`), `:244-253` (`bootstrap.enabled` and `bootstrap.file` return before the rule is composed), `:265-269` (the rule is omitted when `disabled_skills` contains `git-worktree`), `:279` (placement after the usage template and before the profile), `:291-314` (`composeBootstrapContent`, shared by v1 and v2); `tests/unit/bootstrap.test.ts:1025-1227` (real `loadConfig`: default, `git-worktree` disabled, another skill disabled, qualified name rejected, `bootstrap.enabled: false`, existing and missing `bootstrap.file`); `tests/unit/plugin.test.ts:1473-1610` (real v1 plugin init).
|
|
238
240
|
- **OC2-PROFILE** — [OpenCode v2 profile](skills/using-systematic/references/opencode-v2-profile.md#L5-L11). Tool names and arguments: Local probe, OpenCode 2.2.0, 2026-10-27, from the tool list of a real request (`edit`, `glob`, `grep`, `question`, `read`, `shell`, `skill`, `subagent`, `webfetch`, `websearch`, `write`, `execute`): `subagent` takes `agent`, `description`, `prompt`, `model`, `sessionID` and `background`; `question` takes `questions` with `question`, `header`, `options` and `multiple`. CI covers the `subagent` call: CI job `Host Contract v2 shard N/4` (the pinned v2 CLI), `tests/integration/opencode-v2.test.ts` › "a subagent request carries the bootstrap once, and so does the parent request that follows it". `question` has no CI test.
|
|
@@ -268,7 +270,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
268
270
|
- **CC-6** — [Claude Code Agent SDK skills](https://code.claude.com/docs/en/agent-sdk/skills.md).
|
|
269
271
|
- **CC-9** — `scripts/build-claude-code-plugin.ts:5-28,256-368,374-418` (builder, identifier translation, integrity gate); `.gitignore` (`claude-code/` gitignored build staging).
|
|
270
272
|
- **CC-10** — `tests/integration/claude-code.test.ts`.
|
|
271
|
-
- **CC-11** — `.github/workflows/
|
|
273
|
+
- **CC-11** — `.github/workflows/publish-claude-code-plugin.yaml:28-223` (`build` and `push` jobs: on a published non-prerelease release, or a manual dispatch naming an existing tag, the read-only `build` job builds the bundle and guards its required artifacts, and the `push` job, which holds the only write credential and runs no repository code, publishes it to the orphan `claude-code-plugin` branch).
|
|
272
274
|
- **CC-12** — `.claude-plugin/marketplace.json:1-18` (marketplace catalog; `systematic` plugin entry sourced from the `claude-code-plugin` branch ref).
|
|
273
275
|
- **CC-13** — `scripts/build-claude-code-plugin.ts:129-157` (the rule file is read after the using-systematic and profile checks, fails the build when missing, and sits between the body and the profile); `tests/unit/build-claude-code-plugin.test.ts:491-514` and the byte-exact output-style fixture in the same file; `tests/integration/claude-code.test.ts:140-162` (real build: the rule appears exactly once between the body and the profile).
|
|
274
276
|
- **CX-1** — [Codex request_user_input definition](https://github.com/openai/codex/blob/35aaa5d9/codex-rs/tools/src/request_user_input_tool.rs).
|
|
@@ -298,6 +300,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
|
|
|
298
300
|
- **SR-6** — External search reach (`kind: "external"`). Code: `src/lib/search-external-sources.ts` (the per-call reader every surface shares), `src/lib/search-project-identity.ts` (main-root identity from filesystem reads), `src/lib/search-external.ts` and `src/lib/search-external-deciduous.ts` (the Markdown and Deciduous loaders), `src/lib/search-user-config.ts` (the field and entry validators, the user-level and project file selection, and the 1 MB bin-safe project reader), `src/lib/search-exclude.ts` (the `exclude` pattern validators and matcher), `src/lib/search-render.ts` (the external renderer). Host-free tests: `tests/unit/search-project-identity.test.ts` (real git repositories and `git worktree add`: a worktree maps to its main root, forged and inconsistent `.git` files, a bare repository, `core.worktree` and a symlinked `.git` never resolve); `tests/unit/search-external-sources.test.ts` (resolution order, worktrees, shadowing, the 8-source cap, user and custom config directories, nothing cached between calls, the module graph); `tests/unit/search-external.test.ts` and `tests/unit/search-external-deciduous.test.ts` (records, caps, the shared read budget, states, symlinks and read-only behavior); `tests/unit/search-adapters-parity.test.ts` › \"search adapters parity: kind external\" (v1, v2, Pi, CLI, the bin in process and the built bin under Node give byte-identical text; not-allowed replies; an allow-list edit between calls; `search.enabled` false); `tests/unit/claude-code-search.test.ts` (`--kind external` in process and from a foreign directory under Node, the stderr warning for a broken project file, and a bundle that contains neither `config.ts` nor `config-schema.ts`); `tests/unit/opencode-v2-search.test.ts` › \"setupOpenCodeV2 with a project search.sources problem\" (a project file that parses never fails v2 setup, and one that cannot be parsed still does); `tests/unit/past-work-wiring-contract.test.ts` › \"the external call in past-work scope\" and the External records group (the researcher prompt side); `tests/unit/delegated-search-proof.test.ts` › \"external mode\" and `tests/helpers/delegated-search-proof.ts` (the external fixture, script and assertion). Real host: `tests/integration/opencode-v2.test.ts` › \"a dispatched learnings-researcher child searches kind external and the planted external record reaches the parent\" and its negative control \"with the allow entry absent the child receives the not-allowed reply, the parent never sees the external path and the proof names the failure\" (CI job `Host Contract v2 shard N/4`, the pinned v2 CLI, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set). Config locations, local overlays and excludes (host-free; the per-file counts are the tests in each file today, not only the ones added): `tests/unit/search-exclude.test.ts` (77 tests: pattern validation, the matcher on slash, `**` and `?` patterns, adversarial inputs, and a module that imports nothing); `tests/unit/search-user-config.test.ts` (192 tests: file selection by existence, the four user-level layers, an aliased custom directory read once, project file selection, `exclude` validation); `tests/unit/search-corpus.test.ts` › "lookupSearchRoot" and "discoverSourceFiles: excludes" (109 tests); `tests/unit/search-external.test.ts` › "loadExternalSources: excludes" (58 tests) and `tests/unit/search-external-deciduous.test.ts` › "Deciduous loader: excludes" (54 tests); `tests/unit/search-external-sources.test.ts` › "resolveExternalSources: locations, local overlays and diagnostics" and "inspectSearch" (66 tests); `tests/unit/search-adapters-parity.test.ts` › "search adapters parity: repo-root project file, local overlays and excludes" and "search adapters parity: an invalid local file" (43 tests: one fixture started in a subfolder gives byte-identical external text on v1, v2, Pi, the CLI, the bin in process and the built bin, with every layer and the excludes applied; v1 and Pi throw at init and v2 setup rejects naming an invalid local file; a project file over 1 MB fails v1, v2 and Pi while the CLI and the bin carry on); `tests/unit/config.test.ts` › "layered config files" (374 tests); `tests/unit/pi.test.ts` › "src/pi.ts config resolved from the repository root" (72 tests); `tests/unit/opencode-v2.test.ts` (44 tests: a project directory below the repository root applies the root file, the home fallback applies no project file, an invalid user.local rejects setup naming it); `tests/unit/cli.test.ts` › "cli config show: locations and search" and the `loadSearchSettingsForCli` cases (132 tests). Scope limits: a scripted model makes the call, so the real-host proof shows reach and plumbing only; it covers OpenCode v2 alone. No real-host external proof exists for OpenCode v1, Pi or Claude Code.
|
|
299
301
|
- **CN-1** — OpenCode v1 1.19.5 (CI job `Host Contract v1 current`): `tests/integration/opencode-v1-isolation.test.ts` › "the shipped researcher, dispatched from the packed plugin, is refused shell, write, edit and web fetch and its read reaches the parent" (the `HOST_SUPPORT_TABLE` `observedBy` for this row); "with the deny entries removed the same script writes a file and the proof names an isolation breach" (negative control); "a blanket allow in the host's own permission block does not lift the shipped researcher's deny"; "a headless run reads a git checkout outside the project and the marker reaches the parent, with every denied tool still refused" and "without external_directory: allow the same read is auto-rejected, which pins what the entry does". The file runs on the `v1-current` profile only (`scripts/host-contract-guard.ts`, `V1_CURRENT_ONLY_FILES`). Local observation on 1.19.5: a headless run whose work file lay in the state directory was refused as an `external_directory` request, which ended the session before any final line. A host-config `permission.external_directory` allow for `<state directory>/*` let the whole pipeline run and end `Connect complete`. Scope limit: other v1 versions, including the 1.18.29 floor, are unobserved and unsupported.
|
|
300
302
|
- **CN-2** — OpenCode v2 2.2.5 (CI job `Host Contract v2 shard N/4`, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set): `tests/integration/opencode-v2.test.ts` › "a session-level allow does not lift the guarded researcher when a parent with that rule dispatches it" (the `observedBy` for this row), "a session-level allow does not lift the guarded researcher when it runs directly", "the shipped researcher, dispatched from the packed plugin, is refused shell, write, edit and web fetch and its read reaches the parent", and the negative control "the shipped definition alone, under a name the guard does not know, is refused each denied tool and its read reaches the parent". Scope limit: a scripted model makes the calls.
|
|
301
|
-
- **CN-3** — The v2 tool guard. Code: `src/lib/opencode-v2-tool-guard.ts` (`decideToolCall`, the `execute.before` registration, `READ_ONLY_AGENT_NAMES`, `READ_ONLY_TOOL_ALLOWLIST`). Tests: `tests/unit/opencode-v2-tool-guard.test.ts` (the allowlist is exactly read, grep, glob, skill and the two Systematic tools; exact-name matching; every other agent left alone; a refused call throws so the host fails that call alone; a failed hook registration
|
|
303
|
+
- **CN-3** — The v2 tool guard. Code: `src/lib/opencode-v2-tool-guard.ts` (`decideToolCall`, the `execute.before` registration, `READ_ONLY_AGENT_NAMES`, `READ_ONLY_TOOL_ALLOWLIST`). Tests: `tests/unit/opencode-v2-tool-guard.test.ts` (the allowlist is exactly read, grep, glob, skill and the two Systematic tools; exact-name matching; every other agent left alone; a refused call throws so the host fails that call alone; a failed hook registration rejects, so `setupOpenCodeV2` can catch it and withhold the guarded agents); `tests/integration/opencode-v2.test.ts` › "the execute.before hook sees each call with the session agent, including Code Mode calls, and a throw fails that call alone" (a plugin hook that throws fails the call without any Systematic guard in play). The reason for the guard, observed on 2.2.5: a session-level allow rule overrides an agent's own deny, and Code Mode `execute` reaches host-native `opencode_*` tools that no frontmatter key can name.
|
|
302
304
|
- **CN-4** — Pi 1.5.0: `tests/unit/pi-delegate-session.test.ts` › "the shipped researcher reaches createAgentSession with read, grep and find and none of bash, write, edit or systematic_delegate" (the `observedBy` for this row; the real session builder runs against a fake runtime and the test asserts the `tools` that reach `createAgentSession`, not the mock); `tests/integration/pi.test.ts` › "a family completes inside the delegate turn cap with read, search and find tools only, and its batch validates" and "a child that never answers stops at the turn cap and the family is degraded, not empty" (the real Pi runtime, run in the v2 host-contract profile). Scope limit: the delegate is capped at 20 turns, and a scripted model drives the integration tests.
|
|
303
305
|
- **CN-5** — Manual evidence, not a CI check. Recorded 2026-11-08 with Claude Code 2.1.319 (`claude --version` prints `2.1.319 (Claude Code)`), run by hand with the plugin bundle built from the rebased branch head and a live model. Verdict PASS. Run A dispatched `systematic:connections-researcher` through the `Agent` tool: the subagent reported its tools as Read, Grep and Glob, read a planted file and returned its marker, skipped Bash, Write, Edit and WebFetch as unavailable, and never called any of them (the checker found no call to Bash, Write, Edit, WebFetch, WebSearch or NotebookEdit). Run B started a session with `claude --agent systematic:connections-researcher`: the session's init message listed Read, Grep and Glob as its tools, none of Bash, Write, Edit, WebFetch, WebSearch or NotebookEdit, and no MCP tools; the read worked and its marker reached the answer. The `HOST_SUPPORT_TABLE` row names this entry as its `observedBy`. Limits: one live model on one Claude Code version; in run A the denial is the subagent's own report, because it never called the tools, and the host's own statement comes from run B's session tool list; the read tools are not path-scoped; whether a dispatched subagent can reach its parent session's MCP tools was not tested. `tests/unit/connect-host-isolation.test.ts` › "claude plugin validate accepts the definition and rejects one that does not parse" remains a parse check only, because an agent whose frontmatter fails to parse loads without its limits. Upstream issue reports 58645 and 94202 (cited from the research behind this feature, not re-checked) describe `disallowedTools` not being enforced for plugin and subagent Bash, so the agent leads with the positive `tools` allowlist.
|
|
306
|
+
- **CN-6** — Manual evidence from live runs of `.github/workflows/connect.yaml`, not a CI check. Pins: `fro-bot/agent` v0.140.2 at `1ffb6495501f12801f770fa0c0563d16450416e7`, which runs OpenCode v2 2.2.6, and Systematic 3.33.0. Run [43362146039](https://github.com/marcusrbrown/systematic/actions/runs/43362146039) (first dispatch) ended `Connect complete` and posted report issue #1389, authored by `github-actions[bot]`. The ledger cache was empty (a reset). The agent step had no model input, so the parent ran on the action's default model; the step now passes the Fro Bot model. Run [43365759373](https://github.com/marcusrbrown/systematic/actions/runs/43365759373) (second dispatch, the same UTC date): the action log shows `hasModelOverride: true`, and the run ended `Connect complete`. `prepare` logged `Ticks from report #1389: accepted 2, skipped 0, unresolved 0`, and the ledger cache restored (sweep 96 of 435). The `render` visibility recheck passed under `permissions: {}` with the job token. `post` edited #1389 in place and opened no second issue, and the two rejected candidates left the report. Run [43368318366](https://github.com/marcusrbrown/systematic/actions/runs/43368318366) was cancelled by hand about 2.5 minutes into the agent step: the steps after the agent were skipped, `render` and `post` were cancelled, nothing was posted, and the cache and the report were untouched. That is why the agent step has its own timeout below the job's: a cancelled job skips every step after the agent, while a timed-out step lets the record be read, handed on and posted. Run [43475406631](https://github.com/marcusrbrown/systematic/actions/runs/43475406631) (a dispatch with `FRO_BOT_CONNECT_STEP_TIMEOUT` set to 2) ran that path live: the log shows `The action 'Run ce:connect' has timed out after 2 minutes.`, the next step then read the record (`ce:connect ended: no-final-line (agent step: failure).`), `render` logged `Rendered 0 of 0 open candidates, 0 new; outcome no-final-line.`, `post` ran its `Write report` step, and the final `Settle result` step failed red, so the workflow ended `failure`. Not observed live: a busy run, which cannot happen in CI by construction (the lock is never cached or handed off, each run gets a fresh runner, and the concurrency group serializes runs). The workflow tests cover the timeout path against stubbed `gh`, `git` and `npm`.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
import { type ConnectConfigOptions, type HostSupportRow } from './lib/connect-config.js';
|
|
2
2
|
import { type ConnectBounds } from './lib/connect-evidence.js';
|
|
3
|
-
import { type ProcessTable, type PublishOptions } from './lib/connect-state.js';
|
|
3
|
+
import { type InvocationWriteOptions, type ProcessTable, type PublishOptions } from './lib/connect-state.js';
|
|
4
4
|
/**
|
|
5
5
|
* Entry point for the generated, self-contained `ce:connect` helper
|
|
6
6
|
* (`skills/ce-connect/scripts/connect.mjs`).
|
|
@@ -17,7 +17,7 @@ import { type ProcessTable, type PublishOptions } from './lib/connect-state.js';
|
|
|
17
17
|
* file the skill writes in the run's work directory, read here through the
|
|
18
18
|
* bounded reader as a regular file.
|
|
19
19
|
*/
|
|
20
|
-
export declare const CE_CONNECT_USAGE = "Usage: node connect.mjs <begin|validate|publish|decide|ledger show [--offset N]|ledger clear|ledger unlock>";
|
|
20
|
+
export declare const CE_CONNECT_USAGE = "Usage: node connect.mjs <begin|validate|publish|decide|import|apply-ticks|render-report|ledger show [--offset N]|ledger clear|ledger unlock>";
|
|
21
21
|
export interface HelperDeps {
|
|
22
22
|
/** Environment for `XDG_STATE_HOME`. Defaults to `process.env`. */
|
|
23
23
|
readonly env?: Readonly<Record<string, string | undefined>>;
|
|
@@ -34,6 +34,8 @@ export interface HelperDeps {
|
|
|
34
34
|
readonly inspector?: ProcessInspector;
|
|
35
35
|
/** Seams in the middle of a publish, for tests of a crash or a failed write. */
|
|
36
36
|
readonly publishHooks?: NonNullable<PublishOptions['hooks']>;
|
|
37
|
+
/** Seams in the write of the invocation record, for tests of a failed write. */
|
|
38
|
+
readonly invocationHooks?: InvocationWriteOptions;
|
|
37
39
|
}
|
|
38
40
|
export interface HelperResult {
|
|
39
41
|
readonly ok: boolean;
|
package/dist/cli.js
CHANGED
|
@@ -48,7 +48,7 @@ import {
|
|
|
48
48
|
SEARCH_NOTICES,
|
|
49
49
|
SEARCH_CONFIG_UNREADABLE_NOTE,
|
|
50
50
|
runSearch
|
|
51
|
-
} from "./index-
|
|
51
|
+
} from "./index-1cj1mrpb.js";
|
|
52
52
|
var __defProp = Object.defineProperty;
|
|
53
53
|
var __returnValue = (v) => v;
|
|
54
54
|
function __exportSetter(name, newValue) {
|
|
@@ -7621,6 +7621,8 @@ function isAllowedProject(identity, allowList, options = {}) {
|
|
|
7621
7621
|
var MAX_ALLOW_PROJECTS = 64;
|
|
7622
7622
|
var MAX_ALLOW_PROJECT_LENGTH = 4096;
|
|
7623
7623
|
var MAX_CONNECT_CONFIG_BYTES = 1024 * 1024;
|
|
7624
|
+
var MAX_CONNECT_GROUPS = 32;
|
|
7625
|
+
var CONNECT_GROUP_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
|
|
7624
7626
|
|
|
7625
7627
|
// src/lib/removed-names.ts
|
|
7626
7628
|
var REMOVED_BUNDLED_SKILL_NAMES = [
|
|
@@ -8752,11 +8754,30 @@ var ConnectSettingsSchema = trustProtected(object({
|
|
|
8752
8754
|
allow_projects: array(string().min(1).max(MAX_ALLOW_PROJECT_LENGTH)).max(MAX_ALLOW_PROJECTS).optional().meta({
|
|
8753
8755
|
description: `Main repository roots that \`ce:connect\` may read for contradictions and transferable lessons. Each entry is an absolute or \`~\`-prefixed path to the root of a repository checkout, not a subdirectory and not a linked worktree. At most ${MAX_ALLOW_PROJECTS} entries; an entry that matches no repository is reported by the run and does not widen the list. The lists in user, user.local, custom and custom.local config are merged as a union. Omitted or empty, it allows no project.`,
|
|
8754
8756
|
examples: [["~/src/github.com/me/app", "/srv/checkouts/shared-lib"]]
|
|
8757
|
+
}),
|
|
8758
|
+
groups: record(string().regex(CONNECT_GROUP_NAME_PATTERN), array(string().min(1).max(MAX_ALLOW_PROJECT_LENGTH)).min(1).max(MAX_ALLOW_PROJECTS)).refine((groups) => Object.keys(groups).length <= MAX_CONNECT_GROUPS).optional().meta({
|
|
8759
|
+
description: `Named subsets of the allow list that \`ce:connect\` can be narrowed to with \`group:<name>\`. A group name is 1 to 64 characters of lowercase letters, digits and hyphens, led by a letter or digit (\`${CONNECT_GROUP_NAME_PATTERN.source}\`). Each group lists at least one and at most ${MAX_ALLOW_PROJECTS} members in the same form as an \`allow_projects\` entry. At most ${MAX_CONNECT_GROUPS} groups per file. A group never adds a project: a member that is not on the allow list stops the run that selects the group. Groups merge by name across user, user.local, custom and custom.local config, and a later file replaces a same-named group whole.`,
|
|
8760
|
+
examples: [
|
|
8761
|
+
{
|
|
8762
|
+
"harness-tools": [
|
|
8763
|
+
"~/src/github.com/me/app",
|
|
8764
|
+
"/srv/checkouts/shared-lib"
|
|
8765
|
+
]
|
|
8766
|
+
}
|
|
8767
|
+
],
|
|
8768
|
+
maxProperties: MAX_CONNECT_GROUPS
|
|
8755
8769
|
})
|
|
8756
8770
|
}).strict().meta({
|
|
8757
|
-
description: "Cross-project connections. User-owned only: valid in user config or OPENCODE_CONFIG_DIR config, and a project config setting it has the whole block ignored with a warning, because a repository cannot grant itself access to other projects. A block with an unknown key or a bad value is unreadable and counts as an empty allow list.",
|
|
8771
|
+
description: "Cross-project connections. User-owned only: valid in user config or OPENCODE_CONFIG_DIR config, and a project config setting it has the whole block ignored with a warning, because a repository cannot grant itself access to other projects. A block with an unknown key or a bad value is unreadable and counts as an empty allow list and no groups.",
|
|
8758
8772
|
examples: [
|
|
8759
8773
|
{ allow_projects: ["~/src/github.com/me/app"] },
|
|
8774
|
+
{
|
|
8775
|
+
allow_projects: [
|
|
8776
|
+
"~/src/github.com/me/app",
|
|
8777
|
+
"~/src/github.com/me/lib"
|
|
8778
|
+
],
|
|
8779
|
+
groups: { "harness-tools": ["~/src/github.com/me/app"] }
|
|
8780
|
+
},
|
|
8760
8781
|
{ allow_projects: [] }
|
|
8761
8782
|
]
|
|
8762
8783
|
}));
|
|
@@ -10515,9 +10536,20 @@ function mergeConnect(sources) {
|
|
|
10515
10536
|
const blocks = sources.flatMap((source) => source.config.connect === undefined ? [] : [source.config.connect]);
|
|
10516
10537
|
if (blocks.length === 0)
|
|
10517
10538
|
return {};
|
|
10539
|
+
const groups = {};
|
|
10540
|
+
let hasGroups = false;
|
|
10541
|
+
for (const block of blocks) {
|
|
10542
|
+
if (block.groups === undefined)
|
|
10543
|
+
continue;
|
|
10544
|
+
hasGroups = true;
|
|
10545
|
+
for (const [name, members] of Object.entries(block.groups)) {
|
|
10546
|
+
groups[name] = [...members];
|
|
10547
|
+
}
|
|
10548
|
+
}
|
|
10518
10549
|
return {
|
|
10519
10550
|
connect: {
|
|
10520
|
-
allow_projects: blocks.reduce((merged, block) => mergeArraysUnique(merged, block.allow_projects), [])
|
|
10551
|
+
allow_projects: blocks.reduce((merged, block) => mergeArraysUnique(merged, block.allow_projects), []),
|
|
10552
|
+
...hasGroups && { groups }
|
|
10521
10553
|
}
|
|
10522
10554
|
};
|
|
10523
10555
|
}
|
package/dist/index.js
CHANGED
|
@@ -401,6 +401,7 @@ export declare function createSystematicConfigSchema(opts: SystematicConfigSchem
|
|
|
401
401
|
}, z.core.$strict>>;
|
|
402
402
|
connect: z.ZodOptional<z.ZodObject<{
|
|
403
403
|
allow_projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
404
|
+
groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
|
|
404
405
|
}, z.core.$strict>>;
|
|
405
406
|
disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
|
|
406
407
|
[x: string]: string;
|
|
@@ -613,6 +614,7 @@ export declare const SystematicConfigSchema: z.ZodObject<{
|
|
|
613
614
|
}, z.core.$strict>>;
|
|
614
615
|
connect: z.ZodOptional<z.ZodObject<{
|
|
615
616
|
allow_projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
|
|
617
|
+
groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
|
|
616
618
|
}, z.core.$strict>>;
|
|
617
619
|
disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
|
|
618
620
|
[x: string]: string;
|
package/dist/lib/config.d.ts
CHANGED
|
@@ -201,8 +201,9 @@ export interface SystematicConfig {
|
|
|
201
201
|
searchUnreadable?: boolean;
|
|
202
202
|
/**
|
|
203
203
|
* Merged `connect` settings from user and custom config only: the
|
|
204
|
-
* `allow_projects` lists of every layer that sets one, as a union
|
|
205
|
-
*
|
|
204
|
+
* `allow_projects` lists of every layer that sets one, as a union, and the
|
|
205
|
+
* `groups` by name with a later layer replacing a same-named group whole.
|
|
206
|
+
* Absent when no layer sets the block, which allows no project. A project
|
|
206
207
|
* config's `connect` is stripped at load with a warning and never appears
|
|
207
208
|
* here. The `ce:connect` helper reads the same files itself
|
|
208
209
|
* (`loadConnectAllowList`) and never consults this value.
|
|
@@ -0,0 +1,189 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The CI side of `ce:connect`: the report a scheduled run posts, and the ticks
|
|
3
|
+
* an operator leaves on it. One module defines the report format, so what
|
|
4
|
+
* `render-report` writes is exactly what `apply-ticks` reads.
|
|
5
|
+
*
|
|
6
|
+
* Trust: every file read here is untrusted input, including the state the CI
|
|
7
|
+
* run itself wrote. The run record, the invocation record, the candidate
|
|
8
|
+
* payload store, the manifest store and the report body each get bounded
|
|
9
|
+
* reads, typed fields and named keys only. Model text reaches the report in
|
|
10
|
+
* fences only, with mentions, issue references and comment delimiters broken
|
|
11
|
+
* so nothing in it can notify, link or write a marker.
|
|
12
|
+
*
|
|
13
|
+
* A decision comes from one place: a checkbox line the renderer generated,
|
|
14
|
+
* inside the single delimited section, outside any code fence, whose id is in
|
|
15
|
+
* the manifest of the report that was read and whose candidate is still open.
|
|
16
|
+
* The manifest of a report is stored under the hash its body carries, so a
|
|
17
|
+
* report that was posted keeps its own manifest even when a later render
|
|
18
|
+
* failed to post or posted something else.
|
|
19
|
+
*
|
|
20
|
+
* Import rule: node builtins and the `connect-*` modules. The `ce:connect`
|
|
21
|
+
* helper bundles this module, so it must never import zod, `config.ts` or
|
|
22
|
+
* `config-schema.ts`.
|
|
23
|
+
*
|
|
24
|
+
* Layout in the state root, next to the ledger:
|
|
25
|
+
*
|
|
26
|
+
* ci-payloads.json the text of each open candidate (the ledger holds none)
|
|
27
|
+
* ci-manifests.json the candidate ids of the last fourteen reports
|
|
28
|
+
* report.md the report body the last render wrote
|
|
29
|
+
*
|
|
30
|
+
* Neither operation reads the network or the clock: the date and the GitHub
|
|
31
|
+
* run come from the caller.
|
|
32
|
+
*/
|
|
33
|
+
import { type LockBusyReason, type ProcessTable } from './connect-state.js';
|
|
34
|
+
/** A report body is never longer than this many characters. */
|
|
35
|
+
export declare const REPORT_MAX_CHARS = 60000;
|
|
36
|
+
/** The manifests kept: the newest reports a person can still be looking at. */
|
|
37
|
+
export declare const MANIFESTS_KEPT = 14;
|
|
38
|
+
export declare const REPORT_FILE = "report.md";
|
|
39
|
+
export declare const PAYLOAD_FILE = "ci-payloads.json";
|
|
40
|
+
export declare const MANIFEST_FILE = "ci-manifests.json";
|
|
41
|
+
export declare const DECISIONS_BEGIN = "<!-- connect-decisions:begin -->";
|
|
42
|
+
export declare const DECISIONS_END = "<!-- connect-decisions:end -->";
|
|
43
|
+
export type DecisionStatus = 'promoted' | 'rejected';
|
|
44
|
+
/** `<!-- connect-manifest:<hash> -->`: which stored manifest this body was rendered with. */
|
|
45
|
+
export declare function manifestMarker(hash: string): string;
|
|
46
|
+
/** One generated checkbox line. The marker carries the id; nothing else on the line is read. */
|
|
47
|
+
export declare function decisionLine(id: string, status: DecisionStatus, ticked: boolean): string;
|
|
48
|
+
export interface CiOptions {
|
|
49
|
+
readonly processes?: ProcessTable;
|
|
50
|
+
readonly now?: () => number;
|
|
51
|
+
}
|
|
52
|
+
/**
|
|
53
|
+
* Make model text inert in a GitHub issue. Control and format characters go,
|
|
54
|
+
* and a zero-width space breaks each thing the page would act on: `@` (a
|
|
55
|
+
* mention), `#` before a digit and `GH-` before a digit (an issue reference,
|
|
56
|
+
* alone or after `owner/repo`), and the delimiters of an HTML comment, so
|
|
57
|
+
* text cannot write a marker. Removing the zero-width spaces gives back the
|
|
58
|
+
* original text.
|
|
59
|
+
*/
|
|
60
|
+
export declare function neutraliseText(text: string): string;
|
|
61
|
+
/** Neutralised text in a fenced block whose fence is longer than any backtick run inside it. */
|
|
62
|
+
export declare function fenceText(text: string): string;
|
|
63
|
+
export type BodySection = 'ok' | 'missing' | 'malformed';
|
|
64
|
+
export interface ParsedBox {
|
|
65
|
+
readonly id: string;
|
|
66
|
+
readonly status: DecisionStatus;
|
|
67
|
+
readonly ticked: boolean;
|
|
68
|
+
}
|
|
69
|
+
export interface ParsedBody {
|
|
70
|
+
/** The hash in the manifest marker, when the body has exactly one. */
|
|
71
|
+
readonly manifest: string | undefined;
|
|
72
|
+
readonly section: BodySection;
|
|
73
|
+
/** The generated checkbox lines inside the section, in document order. */
|
|
74
|
+
readonly boxes: readonly ParsedBox[];
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Read a report body. Only exact generated lines count, only inside the one
|
|
78
|
+
* delimited section, and never inside a code fence. A body with a delimiter
|
|
79
|
+
* missing, repeated or out of order has no section, and a body with no marker
|
|
80
|
+
* or more than one marker has no manifest.
|
|
81
|
+
*/
|
|
82
|
+
export declare function parseReportBody(body: string): ParsedBody;
|
|
83
|
+
export type BodyRead = {
|
|
84
|
+
readonly status: 'ok';
|
|
85
|
+
readonly body: string;
|
|
86
|
+
} | {
|
|
87
|
+
readonly status: 'failed';
|
|
88
|
+
readonly reason: 'body-missing' | 'body-symlink' | 'body-not-regular' | 'body-too-large' | 'body-unreadable';
|
|
89
|
+
};
|
|
90
|
+
/** Read a report body from a file: one bounded regular file, never a symlink. */
|
|
91
|
+
export declare function readReportBody(file: string): BodyRead;
|
|
92
|
+
export type ReportOutcome = 'complete' | 'degraded' | 'busy' | 'failed' | 'no-final-line';
|
|
93
|
+
export interface RenderRequest {
|
|
94
|
+
/** The UTC date of the report, `YYYY-MM-DD`. */
|
|
95
|
+
readonly date: string;
|
|
96
|
+
/** The GitHub run id and attempt of this workflow run. */
|
|
97
|
+
readonly runId: string;
|
|
98
|
+
readonly attempt: string;
|
|
99
|
+
/** Whether an Actions cache was restored for this run. */
|
|
100
|
+
readonly cacheRestored: boolean;
|
|
101
|
+
}
|
|
102
|
+
export type RenderResult = {
|
|
103
|
+
readonly status: 'rendered';
|
|
104
|
+
readonly body: string;
|
|
105
|
+
readonly bodyFile: string;
|
|
106
|
+
/** The hash in the body's manifest marker. */
|
|
107
|
+
readonly manifest: string;
|
|
108
|
+
readonly open: number;
|
|
109
|
+
readonly shown: number;
|
|
110
|
+
readonly hidden: number;
|
|
111
|
+
/** Candidates listed for the first time on this date. */
|
|
112
|
+
readonly fresh: number;
|
|
113
|
+
/** The `<run>.<attempt>` fetch words of the listed candidates, in the order they appear. */
|
|
114
|
+
readonly fetches: readonly string[];
|
|
115
|
+
readonly outcome: ReportOutcome;
|
|
116
|
+
/** The workflow job turns red after posting. */
|
|
117
|
+
readonly red: boolean;
|
|
118
|
+
/** False when the report was rendered without the lock and recorded no payload or manifest. */
|
|
119
|
+
readonly stateUpdated: boolean;
|
|
120
|
+
} | {
|
|
121
|
+
readonly status: 'busy';
|
|
122
|
+
readonly reason: LockBusyReason;
|
|
123
|
+
} | {
|
|
124
|
+
readonly status: 'failed';
|
|
125
|
+
readonly reason: 'invalid-request' | 'lock-failed' | 'ledger-unreadable' | 'no-invocation' | 'payload-store-unreadable' | 'payload-store-too-large' | 'manifest-store-unreadable' | 'write-failed';
|
|
126
|
+
};
|
|
127
|
+
/**
|
|
128
|
+
* Render the report body for the state in `root`: the open candidates of the
|
|
129
|
+
* ledger, oldest first, as many as fit under the cap, each with its two
|
|
130
|
+
* boxes. Updates the payload store and the manifest store and writes the body
|
|
131
|
+
* to `report.md`. It needs this workflow run's invocation record (the marker
|
|
132
|
+
* `<run>-<attempt>`); without one it writes nothing. A run that ended `busy`
|
|
133
|
+
* is still reported when a live holder keeps the lock: the ledger is read
|
|
134
|
+
* without it, only `report.md` is written, and the body says the state was
|
|
135
|
+
* not updated.
|
|
136
|
+
*/
|
|
137
|
+
export declare function renderReport(root: string, request: RenderRequest, options?: CiOptions): RenderResult;
|
|
138
|
+
export interface TickOptions extends CiOptions {
|
|
139
|
+
readonly hooks?: {
|
|
140
|
+
/** Runs after the ticks are sorted and before the first one is recorded. */
|
|
141
|
+
readonly afterTriage?: () => void;
|
|
142
|
+
};
|
|
143
|
+
}
|
|
144
|
+
export interface TickRequest {
|
|
145
|
+
/** The report body as the issue holds it now. */
|
|
146
|
+
readonly body: string;
|
|
147
|
+
/** The report's issue number; it goes into the reason a decision records. */
|
|
148
|
+
readonly issue: number;
|
|
149
|
+
}
|
|
150
|
+
export interface AcceptedTick {
|
|
151
|
+
readonly id: string;
|
|
152
|
+
readonly status: DecisionStatus;
|
|
153
|
+
}
|
|
154
|
+
export type SkipReason = 'conflict' | 'not-in-manifest' | 'not-open' | 'already-recorded';
|
|
155
|
+
export interface SkippedTick {
|
|
156
|
+
readonly id: string;
|
|
157
|
+
readonly status?: DecisionStatus;
|
|
158
|
+
readonly reason: SkipReason;
|
|
159
|
+
}
|
|
160
|
+
export type UnresolvedReason = 'manifest-missing' | 'unknown-candidate';
|
|
161
|
+
export interface UnresolvedTick {
|
|
162
|
+
readonly id: string;
|
|
163
|
+
readonly status: DecisionStatus;
|
|
164
|
+
readonly reason: UnresolvedReason;
|
|
165
|
+
}
|
|
166
|
+
export type TickResult = {
|
|
167
|
+
readonly status: 'applied';
|
|
168
|
+
readonly section: BodySection;
|
|
169
|
+
readonly accepted: readonly AcceptedTick[];
|
|
170
|
+
readonly skipped: readonly SkippedTick[];
|
|
171
|
+
readonly unresolved: readonly UnresolvedTick[];
|
|
172
|
+
} | {
|
|
173
|
+
readonly status: 'busy';
|
|
174
|
+
readonly reason: LockBusyReason;
|
|
175
|
+
readonly accepted: readonly AcceptedTick[];
|
|
176
|
+
} | {
|
|
177
|
+
readonly status: 'failed';
|
|
178
|
+
readonly reason: 'invalid-request' | 'ledger-unreadable' | 'lock-failed' | 'write-failed';
|
|
179
|
+
readonly accepted: readonly AcceptedTick[];
|
|
180
|
+
};
|
|
181
|
+
/**
|
|
182
|
+
* Record the ticks of a report body. A tick counts when its box is a generated
|
|
183
|
+
* line in the section of the body, its id is in the manifest the body names,
|
|
184
|
+
* and the candidate is open; a decision already recorded with the same reason
|
|
185
|
+
* is left as it is, so a second pass changes nothing. Each decision is made
|
|
186
|
+
* only if the candidate is still open under the lock, so one recorded since
|
|
187
|
+
* the ledger was read is skipped as `not-open`, never overwritten.
|
|
188
|
+
*/
|
|
189
|
+
export declare function applyTicks(root: string, request: TickRequest, options?: TickOptions): TickResult;
|
|
@@ -12,6 +12,11 @@
|
|
|
12
12
|
* imports the limits from here and tags the same block `trust:
|
|
13
13
|
* 'project-or-higher'`; the dependency runs one way.
|
|
14
14
|
*
|
|
15
|
+
* The block also holds named `groups` of allow-list-form entries. A group
|
|
16
|
+
* narrows a run to part of the allow list and never adds a project: nothing
|
|
17
|
+
* here checks that a member is on the allow list; the selection step does,
|
|
18
|
+
* on resolved main roots.
|
|
19
|
+
*
|
|
15
20
|
* Trust: `connect` is user-only. User config, `OPENCODE_CONFIG_DIR` config and
|
|
16
21
|
* the `systematic.local` file beside each may set it. `config.ts` strips it
|
|
17
22
|
* from project config with a warning, and this reader never opens a project
|
|
@@ -21,8 +26,9 @@
|
|
|
21
26
|
* a list over its limit makes that layer's block unreadable, and an
|
|
22
27
|
* unreadable block contributes no entries. A missing, unparseable, oversize
|
|
23
28
|
* or non-regular file contributes none either. No failure can add an entry
|
|
24
|
-
* the user did not write. The four layers merge
|
|
25
|
-
*
|
|
29
|
+
* the user did not write. The four layers merge, the allow lists by union and
|
|
30
|
+
* the groups by name (a later layer replaces a same-named group whole), so a
|
|
31
|
+
* layer that fails drops only its own entries and groups.
|
|
26
32
|
*
|
|
27
33
|
* Warnings name config files and reasons, never an allow-list entry: an entry
|
|
28
34
|
* is a project the user chose to expose, and a warning can reach logs and
|
|
@@ -34,21 +40,30 @@ export declare const MAX_ALLOW_PROJECTS = 64;
|
|
|
34
40
|
export declare const MAX_ALLOW_PROJECT_LENGTH = 4096;
|
|
35
41
|
/** Largest config file the reader accepts. A larger file is unreadable. */
|
|
36
42
|
export declare const MAX_CONNECT_CONFIG_BYTES: number;
|
|
43
|
+
/** One config layer holds at most this many groups. */
|
|
44
|
+
export declare const MAX_CONNECT_GROUPS = 32;
|
|
45
|
+
/** A group name: lowercase letters, digits and hyphens, one to 64 characters, led by a letter or digit. */
|
|
46
|
+
export declare const CONNECT_GROUP_NAME_PATTERN: RegExp;
|
|
47
|
+
/** Group name to member list. A member has the form of an allow-list entry. */
|
|
48
|
+
export type ConnectGroups = Record<string, string[]>;
|
|
37
49
|
export interface ConnectSettings {
|
|
38
50
|
allow_projects: string[];
|
|
51
|
+
groups?: ConnectGroups;
|
|
39
52
|
}
|
|
40
53
|
export type ConnectBlockValidation = {
|
|
41
54
|
readonly ok: true;
|
|
42
55
|
readonly allowProjects: string[];
|
|
56
|
+
readonly groups: ConnectGroups;
|
|
43
57
|
} | {
|
|
44
58
|
readonly ok: false;
|
|
45
59
|
};
|
|
46
60
|
/**
|
|
47
61
|
* Validate a `connect` block with plain guards. The block is valid when it is
|
|
48
|
-
* an object whose only
|
|
49
|
-
* `MAX_ALLOW_PROJECTS` non-empty strings of at
|
|
50
|
-
* characters.
|
|
51
|
-
*
|
|
62
|
+
* an object whose only keys, if any, are `allow_projects` and `groups`.
|
|
63
|
+
* `allow_projects` holds at most `MAX_ALLOW_PROJECTS` non-empty strings of at
|
|
64
|
+
* most `MAX_ALLOW_PROJECT_LENGTH` characters. `groups` maps names to member
|
|
65
|
+
* lists as `readGroups` describes. The zod schema in `config-schema.ts`
|
|
66
|
+
* accepts and rejects the same values; a test pins the two together.
|
|
52
67
|
*/
|
|
53
68
|
export declare function validateConnectBlock(value: unknown): ConnectBlockValidation;
|
|
54
69
|
export interface ConnectConfigOptions {
|
|
@@ -78,8 +93,8 @@ export type ContainerRefusal = 'checkout' | 'allowed-root';
|
|
|
78
93
|
/**
|
|
79
94
|
* Why `dir` may not hold configuration or state, or `undefined` when it may.
|
|
80
95
|
* A directory is refused when it is, or sits inside, an allowed root
|
|
81
|
-
* (`allowed-root`), or when it or any ancestor holds a `.git`
|
|
82
|
-
* (`checkout`). A repository is untrusted input, so what it holds must not
|
|
96
|
+
* (`allowed-root`), or when it or any ancestor holds a `.git` file, a `.git`
|
|
97
|
+
* symlink or a `.git` directory with a `HEAD` (`checkout`). A repository is untrusted input, so what it holds must not
|
|
83
98
|
* steer what the helper reads or where it writes. Both sides are compared as
|
|
84
99
|
* realpaths when they exist.
|
|
85
100
|
*/
|
|
@@ -87,6 +102,11 @@ export declare function containerRefusal(dir: string, allowedRoots: readonly str
|
|
|
87
102
|
export interface ConnectAllowListLoad {
|
|
88
103
|
/** The union of the readable layers' entries, in layer order, duplicates removed. */
|
|
89
104
|
readonly allowProjects: readonly string[];
|
|
105
|
+
/**
|
|
106
|
+
* The readable layers' groups by name. A later layer replaces a same-named
|
|
107
|
+
* group whole. A member is not checked against the allow list here.
|
|
108
|
+
*/
|
|
109
|
+
readonly groups: Readonly<Record<string, readonly string[]>>;
|
|
90
110
|
/** Some layer's file or block could not be read and contributed nothing. */
|
|
91
111
|
readonly unreadable: boolean;
|
|
92
112
|
/** One line per problem. They name files and reasons, never an allow-list entry. */
|