From 5e3483c44892424b84c87160efe5e62219b2101c Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 19:55:02 +1000 Subject: [PATCH 01/64] feat(cli): support purpose-scoped login --- crates/runx-cli/src/launcher.rs | 2 +- crates/runx-cli/src/login.rs | 19 ++++++++++++++++++- crates/runx-cli/src/login_tests.rs | 7 ++++++- crates/runx-cli/tests/launcher.rs | 5 ++++- docs/publishing.md | 18 +++++++++++------- 5 files changed, 40 insertions(+), 11 deletions(-) diff --git a/crates/runx-cli/src/launcher.rs b/crates/runx-cli/src/launcher.rs index 5fb270fd7..c7f30efbb 100644 --- a/crates/runx-cli/src/launcher.rs +++ b/crates/runx-cli/src/launcher.rs @@ -325,7 +325,7 @@ Commands: runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [--json] runx history [query] [--skill s] [--status s] [--source s] [--actor a] [--artifact-type t] [--since iso] [--until iso] [--receipt-dir dir] [--json] runx list [tools|skills|graphs|packets|overlays] [--ok-only|--invalid-only] [--json] - runx login [--provider github|google|gitlab] [--api-base-url url] [--allow-local-api] [--json] + runx login [--provider github|google|gitlab] [--for default|publish] [--api-base-url url] [--allow-local-api] [--json] runx config set|get|list [agent.provider|agent.model|agent.api_key|public.api_token] [value] [--json] runx policy inspect|lint [--json] runx publish [--api-base-url url] [--token token] [--allow-local-api] [--json] diff --git a/crates/runx-cli/src/login.rs b/crates/runx-cli/src/login.rs index 032ae0c19..b4fb233f7 100644 --- a/crates/runx-cli/src/login.rs +++ b/crates/runx-cli/src/login.rs @@ -26,6 +26,7 @@ const DEFAULT_LOGIN_TIMEOUT_SECONDS: u64 = 180; pub struct LoginPlan { pub api_base_url: Option, pub provider: Option, + pub purpose: Option, pub allow_local_api: bool, pub json: bool, } @@ -139,6 +140,8 @@ struct LoginStartResponse { struct LoginStartRequest<'a> { #[serde(skip_serializing_if = "Option::is_none")] provider: Option<&'a str>, + #[serde(skip_serializing_if = "Option::is_none")] + purpose: Option<&'a str>, } #[derive(Clone, Debug, serde::Serialize, PartialEq, Eq)] @@ -170,6 +173,7 @@ struct LoginResult { pub fn parse_login_plan(args: &[OsString]) -> Result { let mut api_base_url = None; let mut provider = None; + let mut purpose = None; let mut allow_local_api = false; let mut json = false; let mut index = 1; @@ -197,6 +201,11 @@ pub fn parse_login_plan(args: &[OsString]) -> Result { provider = Some(value); index = next_index; } + "--for" | "--purpose" => { + let (value, next_index) = flag_value(args, index, flag, inline_value, "login")?; + purpose = Some(value); + index = next_index; + } "--allow-local-api" | "--allowLocalApi" => { if inline_value.is_some() { return Err("--allow-local-api does not take a value".to_owned()); @@ -210,6 +219,7 @@ pub fn parse_login_plan(args: &[OsString]) -> Result { Ok(LoginPlan { api_base_url, provider, + purpose, allow_local_api, json, }) @@ -264,7 +274,12 @@ fn run_login_command_with_transport( sleep: impl Fn(Duration), ) -> Result { let base_url = resolve_public_api_base_url(plan, env); - let started = start_login_session(transport, &base_url, plan.provider.as_deref())?; + let started = start_login_session( + transport, + &base_url, + plan.provider.as_deref(), + plan.purpose.as_deref(), + )?; let signin_url = started .authorization_url .as_deref() @@ -338,9 +353,11 @@ fn start_login_session( transport: &T, base_url: &str, provider: Option<&str>, + purpose: Option<&str>, ) -> Result { let request = LoginStartRequest { provider: provider.map(str::trim).filter(|value| !value.is_empty()), + purpose: purpose.map(str::trim).filter(|value| !value.is_empty()), }; let response = transport.send(HttpRequest { method: HttpMethod::Post, diff --git a/crates/runx-cli/src/login_tests.rs b/crates/runx-cli/src/login_tests.rs index ac7113532..602d59e5f 100644 --- a/crates/runx-cli/src/login_tests.rs +++ b/crates/runx-cli/src/login_tests.rs @@ -37,6 +37,8 @@ fn parses_login_plan() -> Result<(), String> { OsString::from("https://runx.test/"), OsString::from("--provider"), OsString::from("github"), + OsString::from("--for"), + OsString::from("publish"), OsString::from("--allow-local-api"), OsString::from("--json"), ]; @@ -45,6 +47,7 @@ fn parses_login_plan() -> Result<(), String> { LoginPlan { api_base_url: Some("https://runx.test/".to_owned()), provider: Some("github".to_owned()), + purpose: Some("publish".to_owned()), allow_local_api: true, json: true, } @@ -93,6 +96,7 @@ fn login_exchange_stores_encrypted_public_api_token() -> Result<(), Box Result<(), Box Result<(), String> { &LoginPlan { api_base_url: Some("https://runx.test/".to_owned()), provider: Some("bad".to_owned()), + purpose: None, allow_local_api: false, json: false, }, diff --git a/crates/runx-cli/tests/launcher.rs b/crates/runx-cli/tests/launcher.rs index eff6533bd..40d12c0f8 100644 --- a/crates/runx-cli/tests/launcher.rs +++ b/crates/runx-cli/tests/launcher.rs @@ -51,7 +51,7 @@ fn top_level_help_and_version_are_native() { ); assert_help_line( &help, - "runx login [--provider github|google|gitlab] [--api-base-url url] [--allow-local-api] [--json]", + "runx login [--provider github|google|gitlab] [--for default|publish] [--api-base-url url] [--allow-local-api] [--json]", ); assert!( !help.contains("runx connect"), @@ -121,12 +121,15 @@ fn routes_login_to_native_plan() { "login", "--provider", "github", + "--for", + "publish", "--api-base-url", "https://runx.test", "--json", ]), LauncherAction::RunLogin(LoginPlan { provider: Some("github".to_owned()), + purpose: Some("publish".to_owned()), api_base_url: Some("https://runx.test".to_owned()), allow_local_api: false, json: true, diff --git a/docs/publishing.md b/docs/publishing.md index 8d5f8a570..7dba365be 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -56,7 +56,7 @@ For humans, start at https://runx.ai/x/publish. There are two publish lanes: The CLI form keeps the public API token out of command lines: ```bash -runx login +runx login --for publish runx registry publish ./skills//SKILL.md --registry https://runx.ai ``` @@ -85,11 +85,13 @@ instead of trusting a client-supplied summary, while keeping local credentials, fixtures, source trees, and build trash out of the registry. The local harness still runs first for fast feedback. -`runx login` opens the hosted sign-in flow and stores the returned public API -token in the encrypted local config at `public.api_token`. Hosted CLI commands -use token precedence in this order: an explicit `--token` when the command has -one, then `RUNX_PUBLIC_API_TOKEN`, then the stored token from `runx login`. -`runx registry publish` uses the env or stored-token sources. +`runx login --for publish` opens the hosted sign-in flow and stores a +purpose-scoped public API token in the encrypted local config at +`public.api_token`. The token can publish and report skills, but it cannot move +money, mutate hosted billing state, or operate unrelated hosted surfaces. Hosted +CLI commands use token precedence in this order: an explicit `--token` when the +command has one, then `RUNX_PUBLIC_API_TOKEN`, then the stored token from +`runx login`. `runx registry publish` uses the env or stored-token sources. After a public URL publish, use the claim flow from the registry listing to prove control of the source repo and move matching versions toward verified discovery. @@ -103,7 +105,9 @@ runx treats it like every other governed action, with no special-casing: - The **connected identity** proves the publisher namespace. Hosted runx derives the owner from that identity; the request body cannot spoof it. - The **public API token is stored encrypted locally** and masked by `runx config`. - You can also use `RUNX_PUBLIC_API_TOKEN` for CI. + Use `runx login --for publish` for human publishing, or + `RUNX_PUBLIC_API_TOKEN` for CI when you intentionally inject the same narrow + credential. - New publishes start as **community**. Verification and evidence promote discovery; publisher declaration alone never does. - Hosted publishing is rate-limited per publisher identity. A noisy publisher From 81700aa34e006382e72dfa3ba9bf58193bccdba0 Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 20:08:36 +1000 Subject: [PATCH 02/64] fix(release): enforce cli version sync --- crates/Cargo.lock | 2 +- crates/runx-cli/Cargo.toml | 2 +- package.json | 1 + packages/cli/package.json | 2 +- .../check-publishable-package-manifests.mjs | 1 - scripts/check-verify-fast-plan.mjs | 6 ++--- scripts/set-release-version.ts | 24 +++++++++++++++---- scripts/verify-fast.mjs | 2 +- 8 files changed, 26 insertions(+), 14 deletions(-) diff --git a/crates/Cargo.lock b/crates/Cargo.lock index 355252635..64a2759c2 100644 --- a/crates/Cargo.lock +++ b/crates/Cargo.lock @@ -1633,7 +1633,7 @@ dependencies = [ [[package]] name = "runx-cli" -version = "0.6.0" +version = "0.6.3" dependencies = [ "base64", "ring", diff --git a/crates/runx-cli/Cargo.toml b/crates/runx-cli/Cargo.toml index 5b284875e..97105721a 100644 --- a/crates/runx-cli/Cargo.toml +++ b/crates/runx-cli/Cargo.toml @@ -5,7 +5,7 @@ autotests = false name = "runx-cli" # Kept in lockstep with packages/cli/package.json (the npm distribution line). # The release workflow stamps this from the npm manifest before building. -version = "0.6.0" +version = "0.6.3" edition.workspace = true rust-version.workspace = true description = "Cargo-installed launcher for the runx governed agent workflow CLI." diff --git a/package.json b/package.json index ef8ac4860..21d79ec90 100644 --- a/package.json +++ b/package.json @@ -30,6 +30,7 @@ "docs:api": "tsx scripts/gen-api-index.ts", "docs:exit-codes": "tsx scripts/check-cli-exit-codes.ts", "authoring:check-package-contract": "node scripts/check-authoring-package-contract.mjs", + "release:version:check": "tsx scripts/set-release-version.ts --check", "release:smoke-live": "node scripts/smoke-released-cli-live.mjs", "typecheck": "tsc -p tsconfig.typecheck.json --noEmit", "test": "node scripts/test-workspace.mjs", diff --git a/packages/cli/package.json b/packages/cli/package.json index 6ef691b97..65c68703b 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "@runxhq/cli", - "version": "0.6.0", + "version": "0.6.3", "description": "Runx CLI - native governed runtime for agent skills, tools, graphs, and packets.", "private": false, "license": "MIT", diff --git a/scripts/check-publishable-package-manifests.mjs b/scripts/check-publishable-package-manifests.mjs index 31f34151f..267114b6c 100644 --- a/scripts/check-publishable-package-manifests.mjs +++ b/scripts/check-publishable-package-manifests.mjs @@ -6,7 +6,6 @@ const packageNames = [ "authoring", "cli", "contracts", - "create-skill", "host-adapters", "langchain", ]; diff --git a/scripts/check-verify-fast-plan.mjs b/scripts/check-verify-fast-plan.mjs index bca9beb30..ec85d31b6 100644 --- a/scripts/check-verify-fast-plan.mjs +++ b/scripts/check-verify-fast-plan.mjs @@ -13,7 +13,6 @@ const parallelSourceGroup = sliceBetween( for (const forbidden of [ "authoring package contract", - "create-skill package contract", "rust:crate-graph", "rust:style", "cutover:legacy-check", @@ -29,13 +28,13 @@ for (const forbidden of [ for (const required of [ 'step("readiness structural guard"', 'step("demo inventory guard"', + 'step("release version sync"', 'await runSerialGroup("rust structure checks"', 'step("cutover:legacy-check"', 'step("build native runx binary"', 'step("build harness fixture oracle binary"', 'step("build workspace"', 'step("authoring package contract"', - 'step("create-skill package contract"', ]) { if (!source.includes(required)) { throw new Error(`verify:fast is missing required serialized step marker: ${required}`); @@ -45,7 +44,6 @@ for (const required of [ const buildWorkspaceIndex = source.indexOf('step("build workspace"'); for (const requiredAfterBuild of [ 'step("authoring package contract"', - 'step("create-skill package contract"', ]) { const stepIndex = source.indexOf(requiredAfterBuild); if (stepIndex < buildWorkspaceIndex) { @@ -53,7 +51,7 @@ for (const requiredAfterBuild of [ } } -console.log("verify:fast plan keeps package checks after build and Rust-heavy checks serialized."); +console.log("verify:fast plan keeps release drift checks early, package checks after build, and Rust-heavy checks serialized."); function sliceBetween(contents, start, end) { const startIndex = contents.indexOf(start); diff --git a/scripts/set-release-version.ts b/scripts/set-release-version.ts index d4b5c2828..8e42d5306 100644 --- a/scripts/set-release-version.ts +++ b/scripts/set-release-version.ts @@ -22,12 +22,14 @@ interface Finding { readonly message: string; } -const options = parseArgs(process.argv.slice(2)); -const findings: Finding[] = []; - const packageJsonPath = path.join(workspaceRoot, "packages", "cli", "package.json"); const cargoTomlPath = path.join(workspaceRoot, "crates", "runx-cli", "Cargo.toml"); const cargoLockPath = path.join(workspaceRoot, "crates", "Cargo.lock"); +const parsedOptions = parseArgs(process.argv.slice(2)); +const options = parsedOptions.version + ? parsedOptions + : { ...parsedOptions, version: currentPackageVersion(packageJsonPath) }; +const findings: Finding[] = []; stampPackageJson(packageJsonPath, options, findings); stampCargoToml(cargoTomlPath, options, findings); @@ -117,7 +119,7 @@ function parseArgs(argv: readonly string[]): Options { continue; } if (arg === "--help" || arg === "-h") { - console.log("Usage: tsx scripts/release-version.ts --version X.Y.Z [--check]"); + console.log("Usage: tsx scripts/set-release-version.ts [--version X.Y.Z] [--check]"); process.exit(0); } if (!version && !arg.startsWith("--")) { @@ -129,12 +131,24 @@ function parseArgs(argv: readonly string[]): Options { } // Tolerate a leading cli-v / v prefix so the raw tag can be passed through. version = version.replace(/^(?:cli-)?v/u, ""); - if (!SEMVER.test(version)) { + if (version && !SEMVER.test(version)) { throw new Error(`--version must be semver (got "${version}")`); } + if (!version && !check) { + throw new Error("--version is required unless --check is used"); + } return { version, check }; } +function currentPackageVersion(filePath: string): string { + const manifest = JSON.parse(readFileSync(filePath, "utf8")) as { version?: string }; + const version = manifest.version ?? ""; + if (!SEMVER.test(version)) { + throw new Error(`packages/cli/package.json has invalid version "${version}"`); + } + return version; +} + function relative(filePath: string): string { return path.relative(workspaceRoot, filePath).split(path.sep).join("/"); } diff --git a/scripts/verify-fast.mjs b/scripts/verify-fast.mjs index 0144281fa..fb2405e41 100644 --- a/scripts/verify-fast.mjs +++ b/scripts/verify-fast.mjs @@ -45,6 +45,7 @@ await runParallelGroup("source checks", [ step("boundary:check", "pnpm", ["boundary:check"]), step("test:boundary", "pnpm", ["test:boundary"]), step("typecheck", "pnpm", ["typecheck"]), + step("release version sync", "pnpm", ["release:version:check"]), step("integration module guard", "node", ["scripts/check-integration-test-modules.mjs"]), ]); @@ -89,7 +90,6 @@ if (cliBuild.status === 0 && oracleBuild.status === 0) { [ step("build workspace", "node", ["scripts/build-workspace.mjs"]), step("authoring package contract", "node", ["scripts/check-authoring-package-contract.mjs"]), - step("create-skill package contract", "node", ["scripts/check-create-skill-package-contract.mjs"]), step("publishable manifests", "node", ["scripts/check-publishable-package-manifests.mjs"]), step("fixtures:kernel:validate", "pnpm", ["fixtures:kernel:validate"]), step("fixtures:kernel:check", "pnpm", ["fixtures:kernel:check"]), From b00f65fb716f9affe2c17bd521295033caa4b388 Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 20:23:10 +1000 Subject: [PATCH 03/64] feat(scaffold): generate native skill packages --- .github/workflows/ci.yml | 18 +- .github/workflows/release.yml | 19 - CONTRIBUTING.md | 8 +- README.md | 3 +- crates/runx-cli/src/scaffold.rs | 17 +- crates/runx-cli/tests/launcher.rs | 4 +- crates/runx-cli/tests/tool.rs | 18 +- crates/runx-runtime/src/scaffold.rs | 5 +- crates/runx-runtime/src/scaffold/new.rs | 42 +- crates/runx-runtime/src/scaffold/templates.rs | 498 ++++-------------- crates/runx-runtime/tests/scaffold.rs | 10 +- crates/runx-runtime/tests/tool_catalogs.rs | 32 +- docs/api-surface.md | 10 - docs/getting-started.md | 5 +- docs/reference.md | 23 +- docs/ts-interop-boundary.md | 2 +- .../new-docs-demo/files/.gitattributes | 3 - .../files/.github/workflows/publish.yml | 30 -- .../scaffold/new-docs-demo/files/README.md | 36 +- .../scaffold/new-docs-demo/files/SKILL.md | 26 +- fixtures/scaffold/new-docs-demo/files/X.yaml | 48 +- .../files/dist/packets/echo.v1.schema.json | 15 - .../files/fixtures/agent.replay.json | 22 - .../new-docs-demo/files/fixtures/agent.yaml | 14 - .../fixtures/repos/readme-only/README.md | 1 - .../scaffold/new-docs-demo/files/package.json | 27 - fixtures/scaffold/new-docs-demo/files/run.mjs | 8 + .../new-docs-demo/files/src/packets/echo.ts | 8 - .../files/tools/docs/echo/fixtures/basic.yaml | 14 - .../files/tools/docs/echo/manifest.json | 41 -- .../files/tools/docs/echo/run.mjs | 6 - .../files/tools/docs/echo/src/index.ts | 18 - .../new-docs-demo/files/tsconfig.json | 12 - fixtures/scaffold/new-docs-demo/manifest.json | 24 +- packages/cli/src/commands/new.ts | 5 +- packages/cli/src/presentation/init-new.ts | 3 +- packages/cli/src/scaffold.ts | 433 +++++---------- packages/create-skill/README.md | 15 +- packages/create-skill/package.json | 2 +- scripts/generate-rust-scaffold-fixtures.ts | 1 - tests/init-command.test.ts | 22 +- 41 files changed, 375 insertions(+), 1173 deletions(-) delete mode 100644 fixtures/scaffold/new-docs-demo/files/.gitattributes delete mode 100644 fixtures/scaffold/new-docs-demo/files/.github/workflows/publish.yml delete mode 100644 fixtures/scaffold/new-docs-demo/files/dist/packets/echo.v1.schema.json delete mode 100644 fixtures/scaffold/new-docs-demo/files/fixtures/agent.replay.json delete mode 100644 fixtures/scaffold/new-docs-demo/files/fixtures/agent.yaml delete mode 100644 fixtures/scaffold/new-docs-demo/files/fixtures/repos/readme-only/README.md delete mode 100644 fixtures/scaffold/new-docs-demo/files/package.json create mode 100644 fixtures/scaffold/new-docs-demo/files/run.mjs delete mode 100644 fixtures/scaffold/new-docs-demo/files/src/packets/echo.ts delete mode 100644 fixtures/scaffold/new-docs-demo/files/tools/docs/echo/fixtures/basic.yaml delete mode 100644 fixtures/scaffold/new-docs-demo/files/tools/docs/echo/manifest.json delete mode 100644 fixtures/scaffold/new-docs-demo/files/tools/docs/echo/run.mjs delete mode 100644 fixtures/scaffold/new-docs-demo/files/tools/docs/echo/src/index.ts delete mode 100644 fixtures/scaffold/new-docs-demo/files/tsconfig.json diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index f327ddfb8..7ebc28f5b 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -160,17 +160,14 @@ jobs: run: node scripts/check-rust-kernel-parity.mjs --api-only authoring-smoke: - # Drift guard: scaffold -> install -> build -> harness end to end. Reds the - # build the moment the `runx new` authoring path breaks (stale package pins, - # toolkit drift, broken templates), so it can never silently rot again. + # Drift guard: scaffold -> harness end to end. Reds the build the moment the + # `runx new` native scaffold breaks (broken templates, harness regressions), + # so the authoring path can never silently rot. Native skills carry no npm + # deps and no build step, so this is scaffold then harness, nothing else. runs-on: ubuntu-latest steps: - name: Checkout uses: actions/checkout@v6 - - name: Setup pnpm - uses: pnpm/action-setup@v5 - with: - version: 10.18.2 - name: Setup Node uses: actions/setup-node@v6 with: @@ -184,7 +181,7 @@ jobs: - name: Build runx working-directory: crates run: cargo build -p runx-cli - - name: Scaffold, install, build, harness + - name: Scaffold and harness env: RUNX_RECEIPT_SIGN_KID: ci-authoring-smoke RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64: QkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkI= @@ -193,10 +190,7 @@ jobs: set -euo pipefail RUNX="$GITHUB_WORKSPACE/crates/target/debug/runx" "$RUNX" new authoring-smoke --directory "$RUNNER_TEMP/authoring-smoke" - cd "$RUNNER_TEMP/authoring-smoke" - pnpm install - "$RUNX" tool build --all --json - "$RUNX" harness . --json + "$RUNX" harness "$RUNNER_TEMP/authoring-smoke" --json checks: runs-on: ubuntu-latest diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index 5bab767bd..333f4bf03 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -307,25 +307,6 @@ jobs: fi ( cd "$dir" && npm publish --access public --tag latest ) done - - name: Publish workspace JS packages - # The cli-v* release also publishes the workspace JS packages the `runx new` - # authoring toolkit depends on, so they can never lag the binary again - # (the prior drift root cause). pnpm publish resolves the workspace: - # protocol to concrete versions; the list is dep-ordered (contracts first). - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} - NPM_CONFIG_PROVENANCE: "true" - run: | - set -euo pipefail - for dir in packages/contracts packages/authoring; do - name=$(node -p "require('./${dir}/package.json').name") - version=$(node -p "require('./${dir}/package.json').version") - if npm view "${name}@${version}" version >/dev/null 2>&1; then - echo "${name}@${version} already published; skipping" - continue - fi - pnpm --filter "${name}" publish --no-git-checks --access public --tag latest - done publish-crates: needs: [prepare, github-release] diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 9b0bc4636..144e107e7 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -120,13 +120,7 @@ Use `runx new ` when you already have the runx CLI available locally and w runx new docs-demo ``` -Use `npm create @runxhq/skill@latest ` for a cold start from npm: - -```bash -npm create @runxhq/skill@latest docs-demo -``` - -Both entry points go through the same scaffolder. Community skills should be authored as standalone packages; the runx repo itself is the first-party lane for official skills, runtime code, tests, and examples. +Community skills should be authored as standalone packages; the runx repo itself is the first-party lane for official skills, runtime code, tests, and examples. The first runnable example is documented in [docs/getting-started.md](docs/getting-started.md). The generated package export index is in [docs/api-surface.md](docs/api-surface.md). diff --git a/README.md b/README.md index 52810ceac..9be837fe3 100644 --- a/README.md +++ b/README.md @@ -101,8 +101,7 @@ cd oss && cargo build --manifest-path crates/Cargo.toml -p runx-cli ## author and publish ```bash -runx new my-skill # scaffold a standalone skill package -npm create @runxhq/skill@latest my-skill # or start from npm +runx new my-skill # scaffold a native cli-tool skill (SKILL.md + X.yaml + run.mjs, zero deps) ``` Write the prose, declare the profile, run it locally, then publish from a public repo at [runx.ai/x/publish](https://runx.ai/x/publish) or with `runx login && runx registry publish`. This repo is the first-party lane for official skills and the runtime; community skills ship as standalone packages. diff --git a/crates/runx-cli/src/scaffold.rs b/crates/runx-cli/src/scaffold.rs index 1e3d26bd8..9319a66e5 100644 --- a/crates/runx-cli/src/scaffold.rs +++ b/crates/runx-cli/src/scaffold.rs @@ -24,8 +24,6 @@ pub fn run_native_new(plan: NewPlan) -> ExitCode { let options = RunxNewOptions { name: plan.name, directory, - cli_package_version: scaffold_cli_package_version(), - authoring_package_version: scaffold_authoring_package_version(), }; match scaffold_runx_package(&options) { @@ -89,9 +87,8 @@ fn render_new_result(json: bool, result: &RunxNewResult) -> ExitCode { &NewJsonResult { status: "success", new: NewCommandResult { - action: "package", + action: "skill", name: &result.name, - packet_namespace: &result.packet_namespace, directory: &result.directory, files: &result.files, next_steps: &result.next_steps, @@ -102,8 +99,7 @@ fn render_new_result(json: bool, result: &RunxNewResult) -> ExitCode { write_stdout(&render_key_values( "runx new", &[ - ("package", Some(result.name.clone())), - ("packet_namespace", Some(result.packet_namespace.clone())), + ("skill", Some(result.name.clone())), ("directory", Some(result.directory.display().to_string())), ("files", Some(result.files.len().to_string())), ("next", Some(result.next_steps.join(" && "))), @@ -272,14 +268,6 @@ fn default_home_runx_dir() -> PathBuf { .join(".runx") } -fn scaffold_cli_package_version() -> String { - env::var("RUNX_CLI_PACKAGE_VERSION").unwrap_or_else(|_| "^0.6.2".to_owned()) -} - -fn scaffold_authoring_package_version() -> String { - env::var("RUNX_AUTHORING_PACKAGE_VERSION").unwrap_or_else(|_| "^0.2.0".to_owned()) -} - #[derive(Serialize)] struct NewJsonResult<'a> { status: &'static str, @@ -290,7 +278,6 @@ struct NewJsonResult<'a> { struct NewCommandResult<'a> { action: &'static str, name: &'a str, - packet_namespace: &'a str, directory: &'a Path, files: &'a [String], next_steps: &'a [String], diff --git a/crates/runx-cli/tests/launcher.rs b/crates/runx-cli/tests/launcher.rs index 40d12c0f8..3516f5488 100644 --- a/crates/runx-cli/tests/launcher.rs +++ b/crates/runx-cli/tests/launcher.rs @@ -695,10 +695,10 @@ fn routes_add_to_native_plan() { #[test] fn routes_tool_to_native_plan_and_rejects_unknown_subcommands() { assert_eq!( - plan(&["tool", "build", "tools/docs/echo", "--json"]), + plan(&["tool", "build", "tools/fixture/minimal", "--json"]), LauncherAction::RunTool(ToolPlan { action: ToolAction::Build, - path: Some(PathBuf::from("tools/docs/echo")), + path: Some(PathBuf::from("tools/fixture/minimal")), ref_or_query: None, all: false, source: None, diff --git a/crates/runx-cli/tests/tool.rs b/crates/runx-cli/tests/tool.rs index a5bedf21c..774ccdd26 100644 --- a/crates/runx-cli/tests/tool.rs +++ b/crates/runx-cli/tests/tool.rs @@ -45,10 +45,10 @@ fn tool_inspect_fixture_catalog_json() -> Result<(), Box> } #[test] -fn tool_build_scaffold_manifest_json() -> Result<(), Box> { - let temp_root = copy_scaffold_fixture("cli_tool_build")?; +fn tool_build_minimal_manifest_json() -> Result<(), Box> { + let temp_root = copy_tool_catalog_build_fixture("cli_tool_build", "minimal")?; let output = runx_command() - .args(["tool", "build", "tools/docs/echo", "--json"]) + .args(["tool", "build", "tools/fixture/minimal", "--json"]) .env("RUNX_CWD", &temp_root) .output()?; @@ -199,18 +199,6 @@ fn optional_oracle_contents(name: &str) -> Result, Box Result> { - let source = repo_root()?.join("fixtures/scaffold/new-docs-demo/files"); - let target = std::env::temp_dir() - .join("runx-tool-cli-tests") - .join(format!("{name}-{}", std::process::id())); - if target.exists() { - fs::remove_dir_all(&target)?; - } - copy_dir(&source, &target)?; - Ok(target) -} - fn copy_tool_catalog_build_fixture( name: &str, fixture_name: &str, diff --git a/crates/runx-runtime/src/scaffold.rs b/crates/runx-runtime/src/scaffold.rs index cb502f1e2..f23da9cd4 100644 --- a/crates/runx-runtime/src/scaffold.rs +++ b/crates/runx-runtime/src/scaffold.rs @@ -7,10 +7,7 @@ pub use init::{ InitAction, InitGeneratedValues, RunxInitOptions, RunxInitResult, RunxInstallState, RunxProjectState, ensure_runx_install_state, ensure_runx_project_state, runx_init, }; -pub use new::{ - RunxNewOptions, RunxNewResult, packet_namespace_for_name, sanitize_runx_package_name, - scaffold_runx_package, -}; +pub use new::{RunxNewOptions, RunxNewResult, sanitize_runx_package_name, scaffold_runx_package}; use std::fmt; use std::io; diff --git a/crates/runx-runtime/src/scaffold/new.rs b/crates/runx-runtime/src/scaffold/new.rs index 0dada3fbb..aeca05429 100644 --- a/crates/runx-runtime/src/scaffold/new.rs +++ b/crates/runx-runtime/src/scaffold/new.rs @@ -4,20 +4,17 @@ use std::path::{Path, PathBuf}; use serde::Serialize; use super::ScaffoldError; -use super::templates::{ScaffoldTemplateVersions, scaffold_package_files}; +use super::templates::scaffold_package_files; #[derive(Clone, Debug, PartialEq, Eq)] pub struct RunxNewOptions { pub name: String, pub directory: PathBuf, - pub authoring_package_version: String, - pub cli_package_version: String, } #[derive(Clone, Debug, PartialEq, Eq, Serialize)] pub struct RunxNewResult { pub name: String, - pub packet_namespace: String, pub directory: PathBuf, pub files: Vec, pub next_steps: Vec, @@ -25,20 +22,10 @@ pub struct RunxNewResult { pub fn scaffold_runx_package(options: &RunxNewOptions) -> Result { let name = sanitize_runx_package_name(&options.name); - let packet_namespace = packet_namespace_for_name(&name); let root = lexical_absolute(&options.directory)?; assert_writable_scaffold_target(&root)?; - let versions = ScaffoldTemplateVersions { - authoring_package_version: options.authoring_package_version.clone(), - authoring_toolkit_version: options - .authoring_package_version - .strip_prefix('^') - .unwrap_or(&options.authoring_package_version) - .to_owned(), - cli_package_version: options.cli_package_version.clone(), - }; - let writes = scaffold_package_files(&name, &packet_namespace, &versions); + let writes = scaffold_package_files(&name); fs::create_dir_all(&root) .map_err(|source| ScaffoldError::io("creating scaffold root", &root, source))?; @@ -48,14 +35,12 @@ pub fn scaffold_runx_package(options: &RunxNewOptions) -> Result String { } } -#[must_use] -pub fn packet_namespace_for_name(value: &str) -> String { - let unscoped = value.to_lowercase().trim_start_matches('@').to_owned(); - let namespace = trim_dots(&replace_runs( - &unscoped, - |character| character.is_ascii_lowercase() || character.is_ascii_digit(), - '.', - )); - if namespace.is_empty() { - "runx.package".to_owned() - } else { - namespace - } -} - fn assert_writable_scaffold_target(root: &Path) -> Result<(), ScaffoldError> { match fs::read_dir(root) { Ok(mut entries) => match entries.next() { @@ -151,7 +121,3 @@ fn trim_boundary_separators(value: &str) -> String { .trim_matches(|character| matches!(character, '.' | '_' | '-')) .to_owned() } - -fn trim_dots(value: &str) -> String { - value.trim_matches('.').to_owned() -} diff --git a/crates/runx-runtime/src/scaffold/templates.rs b/crates/runx-runtime/src/scaffold/templates.rs index a3eb131b9..8794edacd 100644 --- a/crates/runx-runtime/src/scaffold/templates.rs +++ b/crates/runx-runtime/src/scaffold/templates.rs @@ -1,14 +1,6 @@ -// rust-style-allow: large-file because the scaffold templates intentionally -// mirror the TypeScript scaffolder's checked output byte-for-byte. - -use sha2::{Digest, Sha256}; - -#[derive(Clone, Debug, PartialEq, Eq)] -pub struct ScaffoldTemplateVersions { - pub authoring_package_version: String, - pub authoring_toolkit_version: String, - pub cli_package_version: String, -} +// Native cli-tool skill scaffold: SKILL.md + X.yaml + run.mjs + README + .gitignore. +// The output has zero dependencies and no build step, so `runx new` produces a +// skill that runs and harnesses immediately, with nothing pinned that can drift. #[derive(Clone, Debug, PartialEq, Eq)] pub struct ScaffoldFile { @@ -16,59 +8,13 @@ pub struct ScaffoldFile { pub contents: String, } -pub fn scaffold_package_files( - name: &str, - packet_namespace: &str, - versions: &ScaffoldTemplateVersions, -) -> Vec { - let packet_id = format!("{packet_namespace}.echo.v1"); - let tool_source = tool_source(&packet_id); - let tool_runtime = tool_runtime(&packet_id); - let source_hash = source_hash(&tool_source, &tool_runtime); - let schema_hash = schema_hash(&packet_id); - let prompt_fingerprint = prompt_fingerprint(&packet_id); +pub fn scaffold_package_files(name: &str) -> Vec { vec![ - file( - "package.json", - package_json( - name, - &versions.authoring_package_version, - &versions.cli_package_version, - ), - ), - file("README.md", readme(name)), file("SKILL.md", skill_md(name)), file("X.yaml", x_yaml(name)), - file("src/packets/echo.ts", packet_source(&packet_id)), - file( - "dist/packets/echo.v1.schema.json", - packet_schema(packet_namespace, &packet_id), - ), - file("tools/docs/echo/src/index.ts", tool_source.clone()), - file("tools/docs/echo/run.mjs", tool_runtime), - file( - "tools/docs/echo/manifest.json", - tool_manifest( - &packet_id, - &source_hash, - &schema_hash, - &versions.authoring_toolkit_version, - ), - ), - file("tools/docs/echo/fixtures/basic.yaml", tool_fixture(&packet_id)), - file("fixtures/agent.yaml", agent_fixture_yaml(&packet_id)), - file( - "fixtures/agent.replay.json", - agent_replay_json(&packet_id, &prompt_fingerprint), - ), - file("fixtures/repos/readme-only/README.md", format!("# {name}\n")), - file(".github/workflows/publish.yml", publish_workflow()), + file("run.mjs", run_mjs()), + file("README.md", readme(name)), file(".gitignore", "node_modules/\n.runx/\n*.tgz\n".to_owned()), - file( - ".gitattributes", - "tools/**/run.mjs linguist-generated=true\ntools/**/manifest.json linguist-generated=true\ntools/**/dist/** linguist-generated=true\n".to_owned(), - ), - file("tsconfig.json", tsconfig_json()), ] } @@ -79,86 +25,36 @@ fn file(relative_path: &str, contents: String) -> ScaffoldFile { } } -fn package_json(name: &str, authoring_version: &str, cli_version: &str) -> String { - format!( - r#"{{ - "name": "{name}", - "version": "0.1.0", - "description": "Scaffolded runx skill package.", - "type": "module", - "publishConfig": {{ - "access": "public" - }}, - "scripts": {{ - "build": "runx tool build --all --json", - "runx:list": "runx list --json", - "runx:doctor": "runx doctor --json", - "runx:dev": "runx dev --lane deterministic --json", - "prepublishOnly": "runx tool build --all --json && runx doctor --json" - }}, - "runx": {{ - "packets": [ - "./dist/packets/*.schema.json" - ] - }}, - "devDependencies": {{ - "@runxhq/authoring": "{authoring_version}", - "@runxhq/cli": "{cli_version}", - "@tsconfig/node20": "^20.1.6", - "tsx": "^4.20.6" - }} -}}"# - ) -} - -fn readme(name: &str) -> String { - format!( - r#"# {name} - -Runx authoring package: composable skills governed by typed contracts. - -## Layout - -- `SKILL.md`: Anthropic-standard skill description. Read by humans and agents. -- `X.yaml`: runx execution profile layered on top of `SKILL.md`. -- `src/packets/`: typed packet contracts authored with TypeBox. -- `tools/`: deterministic implementation units authored with `defineTool`. -- `fixtures/`: examples and tests across deterministic, agent, and repo-integration lanes. - -## Authoring Loop - -```bash -pnpm install -pnpm build -pnpm runx:list -pnpm runx:doctor -pnpm runx:dev -``` - -Edit `tools/docs/echo/src/index.ts`, then run `runx tool build --all` to regenerate `manifest.json` and `run.mjs`. Add fixtures in `tools///fixtures/` to lock behaviour. - -Packet IDs are immutable. Schema changes mean a new packet ID, not an in-place edit. - -## Bootstrap - -- Canonical: `runx new {name}` -- Cold start: `npm create @runxhq/skill@latest {name}` - -## Publish - -The scaffold includes `.github/workflows/publish.yml`, which publishes with npm provenance from GitHub Actions. Before publishing, update `package.json` metadata for your repo and package. -"# - ) -} - fn skill_md(name: &str) -> String { format!( r#"--- name: {name} -description: Scaffolded runx skill package. +description: {name} runx skill. Replace this with what the skill does and returns. +source: + type: cli-tool + command: node + args: + - run.mjs + timeout_seconds: 30 + sandbox: + profile: readonly + cwd_policy: skill-directory +inputs: + message: + type: string + required: true + description: Input the skill acts on. Replace with the real inputs. +runx: + input_resolution: + required: + - message --- -Use this skill to demonstrate a governed runx authoring package. +# {name} + +Describe what this skill does, when an agent should reach for it, and what it +returns. Replace the echo in `run.mjs` with the real work, and add cases to +`X.yaml` so the behaviour is locked by the harness. "# ) } @@ -166,296 +62,92 @@ Use this skill to demonstrate a governed runx authoring package. fn x_yaml(name: &str) -> String { format!( r#"skill: {name} +version: "0.1.0" + +catalog: + kind: skill + audience: public + visibility: public + role: canonical + +harness: + cases: + - name: {name}-smoke + runner: default + inputs: + message: hello + expect: + status: sealed + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_closed + - name: {name}-empty-message-fails + runner: default + inputs: + message: "" + expect: + status: failure + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_failed runners: default: default: true - type: graph + type: cli-tool + command: node + args: + - run.mjs inputs: message: type: string - required: false - default: hello - graph: - name: {name} - steps: - - id: echo - tool: docs.echo - inputs: - message: inputs.message + required: true + description: Input the skill acts on. "# ) } -fn packet_source(packet_id: &str) -> String { - format!( - r#"import {{ definePacket, t }} from "@runxhq/authoring"; - -export const EchoPacket = definePacket({{ - id: "{packet_id}", - schema: t.Object({{ - message: t.String(), - }}), -}}); -"# - ) -} - -fn packet_schema(packet_namespace: &str, packet_id: &str) -> String { - let schema_path = packet_namespace.replace('.', "/"); - format!( - r#"{{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.runx.dev/{schema_path}/echo/v1.json", - "x-runx-packet-id": "{packet_id}", - "type": "object", - "required": [ - "message" - ], - "properties": {{ - "message": {{ - "type": "string" - }} - }}, - "additionalProperties": false -}}"# - ) -} - -fn tool_source(packet_id: &str) -> String { - format!( - r#"import {{ defineTool, stringInput }} from "@runxhq/authoring"; - -export default defineTool({{ - name: "docs.echo", - version: "0.1.0", - description: "Echo a docs message.", - inputs: {{ - message: stringInput({{ default: "hello" }}), - }}, - output: {{ - packet: "{packet_id}", - wrap_as: "echo_packet", - }}, - scopes: ["docs.read"], - run({{ inputs }}) {{ - return {{ message: inputs.message }}; - }}, -}}); -"# - ) +fn run_mjs() -> String { + r#"// Inputs arrive as RUNX_INPUT_ environment variables. Do the work and +// write the result to stdout. Replace this echo with the real logic. +const message = process.env.RUNX_INPUT_MESSAGE ?? ""; +if (message.trim().length === 0) { + process.stderr.write("message is required\n"); + process.exit(64); } - -fn tool_runtime(packet_id: &str) -> String { - format!( - r#"const fs = require("node:fs"); -const rawInputs = process.env.RUNX_INPUTS_PATH - ? fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8") - : (process.env.RUNX_INPUTS_JSON || "{{}}"); -const inputs = JSON.parse(rawInputs); -process.stdout.write(JSON.stringify({{ schema: "{packet_id}", data: {{ message: String(inputs.message || "hello") }} }})); +process.stdout.write(`${message}\n`); "# - ) + .to_owned() } -fn tool_manifest( - packet_id: &str, - source_hash: &str, - schema_hash: &str, - toolkit_version: &str, -) -> String { +fn readme(name: &str) -> String { format!( - r#"{{ - "schema": "runx.tool.manifest.v1", - "name": "docs.echo", - "version": "0.1.0", - "description": "Echo a docs message.", - "source": {{ - "type": "cli-tool", - "command": "node", - "args": [ - "./run.mjs" - ] - }}, - "runtime": {{ - "command": "node", - "args": [ - "./run.mjs" - ] - }}, - "inputs": {{ - "message": {{ - "type": "string", - "required": false, - "default": "hello" - }} - }}, - "output": {{ - "packet": "{packet_id}", - "wrap_as": "echo_packet" - }}, - "scopes": [ - "docs.read" - ], - "runx": {{ - "artifacts": {{ - "wrap_as": "echo_packet" - }} - }}, - "source_hash": "{source_hash}", - "schema_hash": "{schema_hash}", - "toolkit_version": "{toolkit_version}" -}}"# - ) -} + r#"# {name} -fn tool_fixture(packet_id: &str) -> String { - format!( - r#"name: echo-basic -lane: deterministic -target: - kind: tool - ref: docs.echo -inputs: - message: hello -expect: - status: sealed - output: - subset: - schema: {packet_id} - data: - message: hello -"# - ) -} +A native runx skill: a `SKILL.md` contract, an `X.yaml` execution profile, and a +`run.mjs` script. No build step and no dependencies. -fn agent_fixture_yaml(packet_id: &str) -> String { - format!( - r#"name: echo-agent-replay -lane: agent -target: - kind: skill - ref: . -inputs: - message: hello -agent: - mode: replay -expect: - status: sealed - outputs: - echo_packet: - matches_packet: {packet_id} -"# - ) -} +## Develop -fn agent_replay_json(packet_id: &str, prompt_fingerprint: &str) -> String { - format!( - r#"{{ - "schema": "runx.replay.v1", - "fixture": "echo-agent-replay", - "prompt_fingerprint": "{prompt_fingerprint}", - "recorded_at": "1970-01-01T00:00:00.000Z", - "target": {{ - "kind": "skill", - "ref": "." - }}, - "status": "sealed", - "outputs": {{ - "echo_packet": {{ - "schema": "{packet_id}", - "data": {{ - "message": "hello" - }} - }} - }}, - "usage": {{ - "mode": "scaffold" - }} -}}"# - ) -} +```bash +runx harness . --json # run the harness cases in X.yaml +runx skill . --input message=hello --json # run the skill once +runx history # inspect the signed receipt +``` -fn publish_workflow() -> String { - r#"name: publish +Edit `run.mjs` to do the real work, and keep both harness classes in `X.yaml`: +one happy path and one stop, error, or refusal case. -on: - workflow_dispatch: - release: - types: - - published +## Publish -jobs: - publish: - runs-on: ubuntu-latest - permissions: - contents: read - id-token: write - steps: - - uses: actions/checkout@v4 - - uses: pnpm/action-setup@v4 - with: - version: 10 - - uses: actions/setup-node@v4 - with: - node-version: 20 - registry-url: https://registry.npmjs.org - cache: pnpm - - run: pnpm install --frozen-lockfile - - run: pnpm build - - run: pnpm runx:doctor - - run: npm publish --provenance --access public - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} +```bash +runx login --provider github --for publish +runx registry publish . # the registry runs the harness as the publish gate +``` "# - .to_owned() -} - -fn tsconfig_json() -> String { - r#"{ - "extends": "@tsconfig/node20/tsconfig.json", - "compilerOptions": { - "module": "NodeNext", - "moduleResolution": "NodeNext", - "strict": true - }, - "include": [ - "src/**/*.ts", - "tools/**/*.ts" - ] -}"# - .to_owned() -} - -fn source_hash(tool_source: &str, tool_runtime: &str) -> String { - let mut hasher = Sha256::new(); - hasher.update("src/index.ts"); - hasher.update([0]); - hasher.update(tool_source); - hasher.update([0]); - hasher.update("run.mjs"); - hasher.update([0]); - hasher.update(tool_runtime); - hasher.update([0]); - format!("sha256:{:x}", hasher.finalize()) -} - -fn schema_hash(packet_id: &str) -> String { - let stable = format!( - r#"{{"artifacts":{{"wrap_as":"echo_packet"}},"inputs":{{"message":{{"default":"hello","required":false,"type":"string"}}}},"output":{{"packet":"{packet_id}","wrap_as":"echo_packet"}}}}"# - ); - format!("sha256:{}", hash_string(&stable)) -} - -fn prompt_fingerprint(packet_id: &str) -> String { - let stable = format!( - r#"{{"agent":{{"mode":"replay"}},"expect":{{"outputs":{{"echo_packet":{{"matches_packet":"{packet_id}"}}}},"status":"sealed"}},"inputs":{{"message":"hello"}},"target":{{"kind":"skill","ref":"."}}}}"# - ); - format!("sha256:{}", hash_string(&stable)) -} - -fn hash_string(value: &str) -> String { - let mut hasher = Sha256::new(); - hasher.update(value); - format!("{:x}", hasher.finalize()) + ) } diff --git a/crates/runx-runtime/tests/scaffold.rs b/crates/runx-runtime/tests/scaffold.rs index 74f771b3a..e6fcc1401 100644 --- a/crates/runx-runtime/tests/scaffold.rs +++ b/crates/runx-runtime/tests/scaffold.rs @@ -14,27 +14,23 @@ static NEXT_TEST_DIR: AtomicUsize = AtomicUsize::new(0); #[derive(Debug, Deserialize)] struct ScaffoldFixtureManifest { name: String, - packet_namespace: String, files: Vec, next_steps: Vec, } #[test] -fn new_scaffold_matches_typescript_fixture() -> Result<(), Box> { +fn new_scaffold_matches_native_fixture() -> Result<(), Box> { let temp = TestDir::create("new-byte-parity")?; let target = temp.path().join("docs-demo"); let options = RunxNewOptions { name: "docs-demo".to_owned(), directory: target.clone(), - authoring_package_version: "^0.1.4".to_owned(), - cli_package_version: "^0.5.22".to_owned(), }; let result = scaffold_runx_package(&options)?; let manifest = scaffold_fixture_manifest()?; assert_eq!(result.name, manifest.name); - assert_eq!(result.packet_namespace, manifest.packet_namespace); assert_eq!(result.files, manifest.files); assert_eq!( normalize_next_steps(&target, &result.next_steps), @@ -53,8 +49,6 @@ fn new_refuses_non_empty_targets() -> Result<(), Box> { let options = RunxNewOptions { name: "docs-demo".to_owned(), directory: target.clone(), - authoring_package_version: "^0.1.4".to_owned(), - cli_package_version: "^0.5.22".to_owned(), }; match scaffold_runx_package(&options) { @@ -62,7 +56,7 @@ fn new_refuses_non_empty_targets() -> Result<(), Box> { Err(error) => return Err(format!("expected non-empty target error, got {error}").into()), Ok(_) => return Err("expected non-empty target error".into()), } - assert!(!target.join("package.json").exists()); + assert!(!target.join("SKILL.md").exists()); Ok(()) } diff --git a/crates/runx-runtime/tests/tool_catalogs.rs b/crates/runx-runtime/tests/tool_catalogs.rs index 6511a0d29..81c8d0aef 100644 --- a/crates/runx-runtime/tests/tool_catalogs.rs +++ b/crates/runx-runtime/tests/tool_catalogs.rs @@ -8,9 +8,9 @@ use runx_runtime::{ }; #[test] -fn tool_catalogs_build_scaffold_manifest() -> Result<(), Box> { - let temp_root = copy_scaffold_fixture("build_scaffold_manifest")?; - let tool_dir = temp_root.join("tools/docs/echo"); +fn tool_catalogs_build_minimal_manifest() -> Result<(), Box> { + let temp_root = copy_minimal_tool_fixture("build_minimal_manifest")?; + let tool_dir = temp_root.join("tools/fixture/minimal"); let report = build_tool_catalogs(&ToolBuildOptions { root: temp_root.clone(), @@ -23,11 +23,11 @@ fn tool_catalogs_build_scaffold_manifest() -> Result<(), Box Result<(), Box Result<(), Box> { - let temp_root = copy_scaffold_fixture("inspect_local_manifest")?; + let temp_root = copy_minimal_tool_fixture("inspect_local_manifest")?; let report = inspect_tool(&ToolInspectOptions { root: temp_root.clone(), - tool_ref: "docs.echo".to_owned(), + tool_ref: "fixture.minimal".to_owned(), source: None, search_from_directory: temp_root.clone(), tool_roots: Vec::new(), @@ -89,11 +89,11 @@ fn tool_catalogs_inspect_local_manifest() -> Result<(), Box Result<(), Box> { - let temp_root = copy_scaffold_fixture("reject_absolute_manifest_path")?; - let manifest = temp_root.join("tools/docs/echo/manifest.json"); + let temp_root = copy_minimal_tool_fixture("reject_absolute_manifest_path")?; + let manifest = temp_root.join("tools/fixture/minimal/manifest.json"); let error = match inspect_tool(&ToolInspectOptions { root: temp_root.clone(), @@ -181,7 +181,7 @@ fn tool_catalogs_reject_absolute_explicit_manifest_path() -> Result<(), Box Result<(), Box> { - let temp_root = copy_scaffold_fixture("reject_parent_manifest_path")?; + let temp_root = copy_minimal_tool_fixture("reject_parent_manifest_path")?; let error = match inspect_tool(&ToolInspectOptions { root: temp_root.clone(), @@ -208,7 +208,7 @@ fn tool_catalogs_reject_parent_traversal_explicit_manifest_path() #[test] fn tool_catalogs_inspect_prefers_local_manifest_over_fixture_catalog() -> Result<(), Box> { - let temp_root = copy_scaffold_fixture("inspect_local_precedence")?; + let temp_root = copy_minimal_tool_fixture("inspect_local_precedence")?; let tool_dir = temp_root.join("tools/fixture/echo"); fs::create_dir_all(&tool_dir)?; fs::write( @@ -261,8 +261,8 @@ fn tool_catalogs_inspect_prefers_local_manifest_over_fixture_catalog() Ok(()) } -fn copy_scaffold_fixture(name: &str) -> Result> { - let source = repo_root()?.join("fixtures/scaffold/new-docs-demo/files"); +fn copy_minimal_tool_fixture(name: &str) -> Result> { + let source = repo_root()?.join("fixtures/tool-catalogs/build/minimal/workspace"); let target = std::env::temp_dir() .join("runx-tool-catalogs-tests") .join(format!("{name}-{}", std::process::id())); diff --git a/docs/api-surface.md b/docs/api-surface.md index 5486adb8a..7afd1f9fc 100644 --- a/docs/api-surface.md +++ b/docs/api-surface.md @@ -34,16 +34,6 @@ Version: `0.3.0` | --- | --- | --- | | `@runxhq/contracts` | `./dist/index.d.ts` | `./dist/index.js` | -## @runxhq/create-skill - -Cold-start scaffolder for runx standalone skill packages. - -Version: `0.2.0` - -| Import | Types | Runtime | -| --- | --- | --- | -| `@runxhq/create-skill` | `./dist/index.d.ts` | `./dist/index.js` | - ## @runxhq/host-adapters Thin host response adapters over the runx host protocol. diff --git a/docs/getting-started.md b/docs/getting-started.md index 87e7dadb6..2f195dbb5 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -77,9 +77,8 @@ crates/target/debug/runx history --json ## Next -- Use `crates/target/debug/runx new docs-demo` for local standalone skill - scaffolding. -- Use `npm create @runxhq/skill@latest docs-demo` when starting from npm. +- Use `crates/target/debug/runx new docs-demo` to scaffold a native cli-tool + skill (SKILL.md + X.yaml + run.mjs, zero npm deps). - Compose the example into a graph with [Skill To Graph](./skill-to-graph.md). - Publish a ready skill from a public repo at https://runx.ai/x/publish, or run `crates/target/debug/runx login` followed by `crates/target/debug/runx registry publish ... --registry https://runx.ai`. diff --git a/docs/reference.md b/docs/reference.md index 13f695835..b0cdb0517 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -99,7 +99,6 @@ Recommended flows: runx init runx init -g --prefetch official runx new docs-demo -npm create @runxhq/skill@latest docs-demo runx list skills runx registry search sourcey --json runx skill sourcey/sourcey@1.0.0 --registry https://runx.example.test --project . --json @@ -145,9 +144,9 @@ contract layer: Rust-owned schema artifacts. - `@runxhq/cli`: npm distribution wrapper and client presentation around the native CLI. -- `@runxhq/authoring`, `@runxhq/create-skill`, `@runxhq/host-adapters`, and - `@runxhq/langchain`: authoring, scaffolding, host presentation, and bridge - packages over language-neutral contracts. +- `@runxhq/authoring`, `@runxhq/host-adapters`, and `@runxhq/langchain`: + authoring, host presentation, and bridge packages over language-neutral + contracts. For the generated package export index, see [docs/api-surface.md](docs/api-surface.md). @@ -220,22 +219,16 @@ publish policy. See [docs/issue-to-pr.md](docs/issue-to-pr.md). ## Standalone Skill Packages -`runx new ` is the canonical standalone package scaffold: +`runx new ` scaffolds a native cli-tool skill (SKILL.md + X.yaml + +run.mjs, zero npm deps, no build step): ```bash runx new docs-demo ``` -For cold-start adoption, the package entrypoint is: - -```bash -npm create @runxhq/skill@latest docs-demo -``` - -Both entrypoints go through the same scaffolder. Community skills should be -authored and published as standalone packages created this way. The main `runx` -repo is the first-party lane for official skills and runtime code, not the -community package catalog. +Community skills should be authored and published as standalone packages created +this way. The main `runx` repo is the first-party lane for official skills and +runtime code, not the community package catalog. Registry search and install now normalize public trust into three tiers: `first_party`, `verified`, and `community`. Richer provenance and attestation diff --git a/docs/ts-interop-boundary.md b/docs/ts-interop-boundary.md index f8a568295..4fd555f78 100644 --- a/docs/ts-interop-boundary.md +++ b/docs/ts-interop-boundary.md @@ -118,7 +118,7 @@ truth, so it is recorded here rather than implied. | `@runxhq/cli` | Stays as a platform-aware npm launcher that resolves and execs the Rust binary. It must remain useful from an installed package without TypeScript sources and must fail closed instead of falling back to TypeScript local execution. | | `@runxhq/contracts` | Stays as the published generated TypeScript view of `runx-contracts`, maintained with fixture cross-validation. | | `@runxhq/core` | Deleted. Its registry/config/parser remnants were not a shipped execution boundary; live OSS code uses Rust crates, generated contracts, tool-local modules, or explicit protocol packages instead. Cloud imports the promoted `@runx/protocol` package. | -| `@runxhq/create-skill` | Stays as a thin npm bootstrapper that wraps `runx new` through the CLI. | +| `@runxhq/create-skill` | Deprecated compatibility package. `runx new` is the supported scaffold entrypoint. | | `@runxhq/host-adapters` | Stays as thin host response adapters over the runx host protocol, retargeted to `@runxhq/contracts` types. It can shape host/client responses, not execute trusted local runtime behavior. | | `@runxhq/langchain` | Stays as an optional LangChain bridge that shells the `runx` CLI or uses documented external protocols for governed skill and tool invocation. | | `runx-py` | Stays as a thin Python client over `runx` CLI JSON output. | diff --git a/fixtures/scaffold/new-docs-demo/files/.gitattributes b/fixtures/scaffold/new-docs-demo/files/.gitattributes deleted file mode 100644 index 5f1233cc6..000000000 --- a/fixtures/scaffold/new-docs-demo/files/.gitattributes +++ /dev/null @@ -1,3 +0,0 @@ -tools/**/run.mjs linguist-generated=true -tools/**/manifest.json linguist-generated=true -tools/**/dist/** linguist-generated=true diff --git a/fixtures/scaffold/new-docs-demo/files/.github/workflows/publish.yml b/fixtures/scaffold/new-docs-demo/files/.github/workflows/publish.yml deleted file mode 100644 index 3e9c3be3b..000000000 --- a/fixtures/scaffold/new-docs-demo/files/.github/workflows/publish.yml +++ /dev/null @@ -1,30 +0,0 @@ -name: publish - -on: - workflow_dispatch: - release: - types: - - published - -jobs: - publish: - runs-on: ubuntu-latest - permissions: - contents: read - id-token: write - steps: - - uses: actions/checkout@v4 - - uses: pnpm/action-setup@v4 - with: - version: 10 - - uses: actions/setup-node@v4 - with: - node-version: 20 - registry-url: https://registry.npmjs.org - cache: pnpm - - run: pnpm install --frozen-lockfile - - run: pnpm build - - run: pnpm runx:doctor - - run: npm publish --provenance --access public - env: - NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }} diff --git a/fixtures/scaffold/new-docs-demo/files/README.md b/fixtures/scaffold/new-docs-demo/files/README.md index 431b38b84..8b71dcc39 100644 --- a/fixtures/scaffold/new-docs-demo/files/README.md +++ b/fixtures/scaffold/new-docs-demo/files/README.md @@ -1,34 +1,22 @@ # docs-demo -Runx authoring package: composable skills governed by typed contracts. +A native runx skill: a `SKILL.md` contract, an `X.yaml` execution profile, and a +`run.mjs` script. No build step and no dependencies. -## Layout - -- `SKILL.md`: Anthropic-standard skill description. Read by humans and agents. -- `X.yaml`: runx execution profile layered on top of `SKILL.md`. -- `src/packets/`: typed packet contracts authored with TypeBox. -- `tools/`: deterministic implementation units authored with `defineTool`. -- `fixtures/`: examples and tests across deterministic, agent, and repo-integration lanes. - -## Authoring Loop +## Develop ```bash -pnpm install -pnpm build -pnpm runx:list -pnpm runx:doctor -pnpm runx:dev +runx harness . --json # run the harness cases in X.yaml +runx skill . --input message=hello --json # run the skill once +runx history # inspect the signed receipt ``` -Edit `tools/docs/echo/src/index.ts`, then run `runx tool build --all` to regenerate `manifest.json` and `run.mjs`. Add fixtures in `tools///fixtures/` to lock behaviour. - -Packet IDs are immutable. Schema changes mean a new packet ID, not an in-place edit. - -## Bootstrap - -- Canonical: `runx new docs-demo` -- Cold start: `npm create @runxhq/skill@latest docs-demo` +Edit `run.mjs` to do the real work, and keep both harness classes in `X.yaml`: +one happy path and one stop, error, or refusal case. ## Publish -The scaffold includes `.github/workflows/publish.yml`, which publishes with npm provenance from GitHub Actions. Before publishing, update `package.json` metadata for your repo and package. +```bash +runx login --provider github --for publish +runx registry publish . # the registry runs the harness as the publish gate +``` diff --git a/fixtures/scaffold/new-docs-demo/files/SKILL.md b/fixtures/scaffold/new-docs-demo/files/SKILL.md index 267b36dee..4bbf62f39 100644 --- a/fixtures/scaffold/new-docs-demo/files/SKILL.md +++ b/fixtures/scaffold/new-docs-demo/files/SKILL.md @@ -1,6 +1,28 @@ --- name: docs-demo -description: Scaffolded runx skill package. +description: docs-demo runx skill. Replace this with what the skill does and returns. +source: + type: cli-tool + command: node + args: + - run.mjs + timeout_seconds: 30 + sandbox: + profile: readonly + cwd_policy: skill-directory +inputs: + message: + type: string + required: true + description: Input the skill acts on. Replace with the real inputs. +runx: + input_resolution: + required: + - message --- -Use this skill to demonstrate a governed runx authoring package. +# docs-demo + +Describe what this skill does, when an agent should reach for it, and what it +returns. Replace the echo in `run.mjs` with the real work, and add cases to +`X.yaml` so the behaviour is locked by the harness. diff --git a/fixtures/scaffold/new-docs-demo/files/X.yaml b/fixtures/scaffold/new-docs-demo/files/X.yaml index e3def5349..302a4c0a5 100644 --- a/fixtures/scaffold/new-docs-demo/files/X.yaml +++ b/fixtures/scaffold/new-docs-demo/files/X.yaml @@ -1,18 +1,46 @@ skill: docs-demo +version: "0.1.0" + +catalog: + kind: skill + audience: public + visibility: public + role: canonical + +harness: + cases: + - name: docs-demo-smoke + runner: default + inputs: + message: hello + expect: + status: sealed + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_closed + - name: docs-demo-empty-message-fails + runner: default + inputs: + message: "" + expect: + status: failure + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_failed runners: default: default: true - type: graph + type: cli-tool + command: node + args: + - run.mjs inputs: message: type: string - required: false - default: hello - graph: - name: docs-demo - steps: - - id: echo - tool: docs.echo - inputs: - message: inputs.message + required: true + description: Input the skill acts on. diff --git a/fixtures/scaffold/new-docs-demo/files/dist/packets/echo.v1.schema.json b/fixtures/scaffold/new-docs-demo/files/dist/packets/echo.v1.schema.json deleted file mode 100644 index 338e48f7a..000000000 --- a/fixtures/scaffold/new-docs-demo/files/dist/packets/echo.v1.schema.json +++ /dev/null @@ -1,15 +0,0 @@ -{ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": "https://schemas.runx.dev/docs/demo/echo/v1.json", - "x-runx-packet-id": "docs.demo.echo.v1", - "type": "object", - "required": [ - "message" - ], - "properties": { - "message": { - "type": "string" - } - }, - "additionalProperties": false -} diff --git a/fixtures/scaffold/new-docs-demo/files/fixtures/agent.replay.json b/fixtures/scaffold/new-docs-demo/files/fixtures/agent.replay.json deleted file mode 100644 index a6aaec708..000000000 --- a/fixtures/scaffold/new-docs-demo/files/fixtures/agent.replay.json +++ /dev/null @@ -1,22 +0,0 @@ -{ - "schema": "runx.replay.v1", - "fixture": "echo-agent-replay", - "prompt_fingerprint": "sha256:31db40e2189f146c20e995cf583b1bb2b1df46f0a2d06f14af10e39b9afbf1e2", - "recorded_at": "1970-01-01T00:00:00.000Z", - "target": { - "kind": "skill", - "ref": "." - }, - "status": "sealed", - "outputs": { - "echo_packet": { - "schema": "docs.demo.echo.v1", - "data": { - "message": "hello" - } - } - }, - "usage": { - "mode": "scaffold" - } -} diff --git a/fixtures/scaffold/new-docs-demo/files/fixtures/agent.yaml b/fixtures/scaffold/new-docs-demo/files/fixtures/agent.yaml deleted file mode 100644 index ca0f13757..000000000 --- a/fixtures/scaffold/new-docs-demo/files/fixtures/agent.yaml +++ /dev/null @@ -1,14 +0,0 @@ -name: echo-agent-replay -lane: agent -target: - kind: skill - ref: . -inputs: - message: hello -agent: - mode: replay -expect: - status: sealed - outputs: - echo_packet: - matches_packet: docs.demo.echo.v1 diff --git a/fixtures/scaffold/new-docs-demo/files/fixtures/repos/readme-only/README.md b/fixtures/scaffold/new-docs-demo/files/fixtures/repos/readme-only/README.md deleted file mode 100644 index 051582016..000000000 --- a/fixtures/scaffold/new-docs-demo/files/fixtures/repos/readme-only/README.md +++ /dev/null @@ -1 +0,0 @@ -# docs-demo diff --git a/fixtures/scaffold/new-docs-demo/files/package.json b/fixtures/scaffold/new-docs-demo/files/package.json deleted file mode 100644 index e264ac84f..000000000 --- a/fixtures/scaffold/new-docs-demo/files/package.json +++ /dev/null @@ -1,27 +0,0 @@ -{ - "name": "docs-demo", - "version": "0.1.0", - "description": "Scaffolded runx skill package.", - "type": "module", - "publishConfig": { - "access": "public" - }, - "scripts": { - "build": "runx tool build --all --json", - "runx:list": "runx list --json", - "runx:doctor": "runx doctor --json", - "runx:dev": "runx dev --lane deterministic --json", - "prepublishOnly": "runx tool build --all --json && runx doctor --json" - }, - "runx": { - "packets": [ - "./dist/packets/*.schema.json" - ] - }, - "devDependencies": { - "@runxhq/authoring": "^0.1.4", - "@runxhq/cli": "^0.5.22", - "@tsconfig/node20": "^20.1.6", - "tsx": "^4.20.6" - } -} diff --git a/fixtures/scaffold/new-docs-demo/files/run.mjs b/fixtures/scaffold/new-docs-demo/files/run.mjs new file mode 100644 index 000000000..0c4e3016a --- /dev/null +++ b/fixtures/scaffold/new-docs-demo/files/run.mjs @@ -0,0 +1,8 @@ +// Inputs arrive as RUNX_INPUT_ environment variables. Do the work and +// write the result to stdout. Replace this echo with the real logic. +const message = process.env.RUNX_INPUT_MESSAGE ?? ""; +if (message.trim().length === 0) { + process.stderr.write("message is required\n"); + process.exit(64); +} +process.stdout.write(`${message}\n`); diff --git a/fixtures/scaffold/new-docs-demo/files/src/packets/echo.ts b/fixtures/scaffold/new-docs-demo/files/src/packets/echo.ts deleted file mode 100644 index 2d27b6dcc..000000000 --- a/fixtures/scaffold/new-docs-demo/files/src/packets/echo.ts +++ /dev/null @@ -1,8 +0,0 @@ -import { definePacket, t } from "@runxhq/authoring"; - -export const EchoPacket = definePacket({ - id: "docs.demo.echo.v1", - schema: t.Object({ - message: t.String(), - }), -}); diff --git a/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/fixtures/basic.yaml b/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/fixtures/basic.yaml deleted file mode 100644 index 7b477d7b5..000000000 --- a/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/fixtures/basic.yaml +++ /dev/null @@ -1,14 +0,0 @@ -name: echo-basic -lane: deterministic -target: - kind: tool - ref: docs.echo -inputs: - message: hello -expect: - status: sealed - output: - subset: - schema: docs.demo.echo.v1 - data: - message: hello diff --git a/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/manifest.json b/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/manifest.json deleted file mode 100644 index ec1a556b9..000000000 --- a/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/manifest.json +++ /dev/null @@ -1,41 +0,0 @@ -{ - "schema": "runx.tool.manifest.v1", - "name": "docs.echo", - "version": "0.1.0", - "description": "Echo a docs message.", - "source": { - "type": "cli-tool", - "command": "node", - "args": [ - "./run.mjs" - ] - }, - "runtime": { - "command": "node", - "args": [ - "./run.mjs" - ] - }, - "inputs": { - "message": { - "type": "string", - "required": false, - "default": "hello" - } - }, - "output": { - "packet": "docs.demo.echo.v1", - "wrap_as": "echo_packet" - }, - "scopes": [ - "docs.read" - ], - "runx": { - "artifacts": { - "wrap_as": "echo_packet" - } - }, - "source_hash": "sha256:43323caad0616b9c0bf771663ac556a6aea2971d65c4e23a59d440d9b0b61229", - "schema_hash": "sha256:d5c0e413e7484e04bec267def5ecfe1f63fafb94d8cd96c7fab17d2608b0631a", - "toolkit_version": "0.1.4" -} diff --git a/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/run.mjs b/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/run.mjs deleted file mode 100644 index 6a8c8f60d..000000000 --- a/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/run.mjs +++ /dev/null @@ -1,6 +0,0 @@ -const fs = require("node:fs"); -const rawInputs = process.env.RUNX_INPUTS_PATH - ? fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8") - : (process.env.RUNX_INPUTS_JSON || "{}"); -const inputs = JSON.parse(rawInputs); -process.stdout.write(JSON.stringify({ schema: "docs.demo.echo.v1", data: { message: String(inputs.message || "hello") } })); diff --git a/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/src/index.ts b/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/src/index.ts deleted file mode 100644 index 1ff7e0f9b..000000000 --- a/fixtures/scaffold/new-docs-demo/files/tools/docs/echo/src/index.ts +++ /dev/null @@ -1,18 +0,0 @@ -import { defineTool, stringInput } from "@runxhq/authoring"; - -export default defineTool({ - name: "docs.echo", - version: "0.1.0", - description: "Echo a docs message.", - inputs: { - message: stringInput({ default: "hello" }), - }, - output: { - packet: "docs.demo.echo.v1", - wrap_as: "echo_packet", - }, - scopes: ["docs.read"], - run({ inputs }) { - return { message: inputs.message }; - }, -}); diff --git a/fixtures/scaffold/new-docs-demo/files/tsconfig.json b/fixtures/scaffold/new-docs-demo/files/tsconfig.json deleted file mode 100644 index 0e8456a3d..000000000 --- a/fixtures/scaffold/new-docs-demo/files/tsconfig.json +++ /dev/null @@ -1,12 +0,0 @@ -{ - "extends": "@tsconfig/node20/tsconfig.json", - "compilerOptions": { - "module": "NodeNext", - "moduleResolution": "NodeNext", - "strict": true - }, - "include": [ - "src/**/*.ts", - "tools/**/*.ts" - ] -} diff --git a/fixtures/scaffold/new-docs-demo/manifest.json b/fixtures/scaffold/new-docs-demo/manifest.json index 09f64c427..1351f9820 100644 --- a/fixtures/scaffold/new-docs-demo/manifest.json +++ b/fixtures/scaffold/new-docs-demo/manifest.json @@ -1,29 +1,15 @@ { "name": "docs-demo", - "packet_namespace": "docs.demo", "files": [ - "package.json", - "README.md", "SKILL.md", "X.yaml", - "src/packets/echo.ts", - "dist/packets/echo.v1.schema.json", - "tools/docs/echo/src/index.ts", - "tools/docs/echo/run.mjs", - "tools/docs/echo/manifest.json", - "tools/docs/echo/fixtures/basic.yaml", - "fixtures/agent.yaml", - "fixtures/agent.replay.json", - "fixtures/repos/readme-only/README.md", - ".github/workflows/publish.yml", - ".gitignore", - ".gitattributes", - "tsconfig.json" + "run.mjs", + "README.md", + ".gitignore" ], "next_steps": [ "cd ", - "pnpm install", - "pnpm build", - "runx dev" + "runx harness . --json", + "runx skill . --input message=hello --json" ] } diff --git a/packages/cli/src/commands/new.ts b/packages/cli/src/commands/new.ts index 0f746b515..2c4c642ff 100644 --- a/packages/cli/src/commands/new.ts +++ b/packages/cli/src/commands/new.ts @@ -8,9 +8,8 @@ export interface NewCommandArgs { } export interface NewResult { - readonly action: "package"; + readonly action: "skill"; readonly name: string; - readonly packet_namespace: string; readonly directory: string; readonly files: readonly string[]; readonly next_steps: readonly string[]; @@ -26,7 +25,7 @@ export async function handleNewCommand(parsed: NewCommandArgs, env: NodeJS.Proce directory, }); return { - action: "package", + action: "skill", ...result, }; } diff --git a/packages/cli/src/presentation/init-new.ts b/packages/cli/src/presentation/init-new.ts index d642e97f9..1dc7099c3 100644 --- a/packages/cli/src/presentation/init-new.ts +++ b/packages/cli/src/presentation/init-new.ts @@ -8,8 +8,7 @@ export function renderNewResult(result: NewResult, env: NodeJS.ProcessEnv = proc "runx new", "success", [ - ["package", result.name], - ["packet_namespace", result.packet_namespace], + ["skill", result.name], ["directory", result.directory], ["files", String(result.files.length)], ["next", result.next_steps.join(" && ")], diff --git a/packages/cli/src/scaffold.ts b/packages/cli/src/scaffold.ts index 3b6891743..68a8cd978 100644 --- a/packages/cli/src/scaffold.ts +++ b/packages/cli/src/scaffold.ts @@ -1,16 +1,8 @@ import { mkdir, readdir, writeFile } from "node:fs/promises"; import path from "node:path"; -import { sha256Prefixed } from "@runxhq/contracts"; import { isNodeError } from "./cli-util.js"; -import { sha256Stable } from "./authoring-utils.js"; -import { readCliDependencyVersion, readCliPackageMetadata } from "./metadata.js"; - -const toolkitVersion = readCliDependencyVersion("@runxhq/authoring"); -const authoringPackageVersion = `^${toolkitVersion}`; -const cliPackageVersion = `^${readCliPackageMetadata().version}`; - export interface ScaffoldRunxPackageOptions { readonly name: string; readonly directory: string; @@ -18,7 +10,6 @@ export interface ScaffoldRunxPackageOptions { export interface ScaffoldRunxPackageResult { readonly name: string; - readonly packet_namespace: string; readonly directory: string; readonly files: readonly string[]; readonly next_steps: readonly string[]; @@ -26,315 +17,157 @@ export interface ScaffoldRunxPackageResult { export async function scaffoldRunxPackage(options: ScaffoldRunxPackageOptions): Promise { const name = sanitizeRunxPackageName(options.name); - const packetNamespace = packetNamespaceForName(name); const root = path.resolve(options.directory); await assertWritableScaffoldTarget(root); - const packetId = `${packetNamespace}.echo.v1`; - const toolSource = `import { defineTool, stringInput } from "@runxhq/authoring"; + const writes = scaffoldPackageFiles(name); + await mkdir(root, { recursive: true }); + await Promise.all(writes.map(([relativePath, contents]) => write(root, relativePath, contents))); -export default defineTool({ - name: "docs.echo", - version: "0.1.0", - description: "Echo a docs message.", - inputs: { - message: stringInput({ default: "hello" }), - }, - output: { - packet: "${packetId}", - wrap_as: "echo_packet", - }, - scopes: ["docs.read"], - run({ inputs }) { - return { message: inputs.message }; - }, -}); -`; - const toolRuntime = `const fs = require("node:fs"); -const rawInputs = process.env.RUNX_INPUTS_PATH - ? fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8") - : (process.env.RUNX_INPUTS_JSON || "{}"); -const inputs = JSON.parse(rawInputs); -process.stdout.write(JSON.stringify({ schema: "${packetId}", data: { message: String(inputs.message || "hello") } })); -`; - const toolInputs = { - message: { type: "string", required: false, default: "hello" }, - }; - const toolOutput = { packet: packetId, wrap_as: "echo_packet" }; - const toolRunx = { artifacts: { wrap_as: "echo_packet" } }; - const sourceHash = sha256ToolSourceContents({ - "src/index.ts": toolSource, - "run.mjs": toolRuntime, - }); - const schemaHash = sha256Stable({ - inputs: toolInputs, - output: toolOutput, - artifacts: toolRunx.artifacts, - }); - const agentFixture = { - target: { kind: "skill", ref: "." }, - inputs: { message: "hello" }, - agent: { mode: "replay" }, - expect: { - status: "sealed", - outputs: { - echo_packet: { - matches_packet: packetId, - }, - }, - }, + return { + name, + directory: root, + files: writes.map(([relativePath]) => relativePath), + next_steps: [ + `cd ${root}`, + "runx harness . --json", + "runx skill . --input message=hello --json", + ], }; +} - const writes: ReadonlyArray = [ - ["package.json", JSON.stringify({ - name, - version: "0.1.0", - description: "Scaffolded runx skill package.", - type: "module", - publishConfig: { - access: "public", - }, - scripts: { - build: "runx tool build --all --json", - "runx:list": "runx list --json", - "runx:doctor": "runx doctor --json", - "runx:dev": "runx dev --lane deterministic --json", - prepublishOnly: "runx tool build --all --json && runx doctor --json", - }, - runx: { - packets: ["./dist/packets/*.schema.json"], - }, - devDependencies: { - "@runxhq/authoring": authoringPackageVersion, - "@runxhq/cli": cliPackageVersion, - "@tsconfig/node20": "^20.1.6", - "tsx": "^4.20.6", - }, - }, null, 2)], - ["README.md", `# ${name} - -Runx authoring package: composable skills governed by typed contracts. - -## Layout - -- \`SKILL.md\`: Anthropic-standard skill description. Read by humans and agents. -- \`X.yaml\`: runx execution profile layered on top of \`SKILL.md\`. -- \`src/packets/\`: typed packet contracts authored with TypeBox. -- \`tools/\`: deterministic implementation units authored with \`defineTool\`. -- \`fixtures/\`: examples and tests across deterministic, agent, and repo-integration lanes. - -## Authoring Loop - -\`\`\`bash -pnpm install -pnpm build -pnpm runx:list -pnpm runx:doctor -pnpm runx:dev -\`\`\` - -Edit \`tools/docs/echo/src/index.ts\`, then run \`runx tool build --all\` to regenerate \`manifest.json\` and \`run.mjs\`. Add fixtures in \`tools///fixtures/\` to lock behaviour. +export function sanitizeRunxPackageName(value: string): string { + return value.trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^[._-]+|[._-]+$/g, "") || "runx-package"; +} -Packet IDs are immutable. Schema changes mean a new packet ID, not an in-place edit. +function scaffoldPackageFiles(name: string): ReadonlyArray { + return [ + ["SKILL.md", skillMd(name)], + ["X.yaml", xYaml(name)], + ["run.mjs", runMjs()], + ["README.md", readme(name)], + [".gitignore", "node_modules/\n.runx/\n*.tgz\n"], + ]; +} -## Bootstrap +function skillMd(name: string): string { + return `--- +name: ${name} +description: ${name} runx skill. Replace this with what the skill does and returns. +source: + type: cli-tool + command: node + args: + - run.mjs + timeout_seconds: 30 + sandbox: + profile: readonly + cwd_policy: skill-directory +inputs: + message: + type: string + required: true + description: Input the skill acts on. Replace with the real inputs. +runx: + input_resolution: + required: + - message +--- -- Canonical: \`runx new ${name}\` -- Cold start: \`npm create @runxhq/skill@latest ${name}\` +# ${name} -## Publish +Describe what this skill does, when an agent should reach for it, and what it +returns. Replace the echo in \`run.mjs\` with the real work, and add cases to +\`X.yaml\` so the behaviour is locked by the harness. +`; +} -The scaffold includes \`.github/workflows/publish.yml\`, which publishes with npm provenance from GitHub Actions. Before publishing, update \`package.json\` metadata for your repo and package. -`], - ["SKILL.md", `--- -name: ${name} -description: Scaffolded runx skill package. ---- +function xYaml(name: string): string { + return `skill: ${name} +version: "0.1.0" -Use this skill to demonstrate a governed runx authoring package. -`], - ["X.yaml", `skill: ${name} +catalog: + kind: skill + audience: public + visibility: public + role: canonical + +harness: + cases: + - name: ${name}-smoke + runner: default + inputs: + message: hello + expect: + status: sealed + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_closed + - name: ${name}-empty-message-fails + runner: default + inputs: + message: "" + expect: + status: failure + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_failed runners: default: default: true - type: graph + type: cli-tool + command: node + args: + - run.mjs inputs: message: type: string - required: false - default: hello - graph: - name: ${name} - steps: - - id: echo - tool: docs.echo - inputs: - message: inputs.message -`], - ["src/packets/echo.ts", `import { definePacket, t } from "@runxhq/authoring"; + required: true + description: Input the skill acts on. +`; +} -export const EchoPacket = definePacket({ - id: "${packetId}", - schema: t.Object({ - message: t.String(), - }), -}); -`], - ["dist/packets/echo.v1.schema.json", JSON.stringify({ - "$schema": "https://json-schema.org/draft/2020-12/schema", - "$id": `https://schemas.runx.dev/${packetNamespace.replaceAll(".", "/")}/echo/v1.json`, - "x-runx-packet-id": packetId, - type: "object", - required: ["message"], - properties: { - message: { type: "string" }, - }, - additionalProperties: false, - }, null, 2)], - ["tools/docs/echo/src/index.ts", toolSource], - ["tools/docs/echo/run.mjs", toolRuntime], - ["tools/docs/echo/manifest.json", JSON.stringify({ - schema: "runx.tool.manifest.v1", - name: "docs.echo", - version: "0.1.0", - description: "Echo a docs message.", - source: { type: "cli-tool", command: "node", args: ["./run.mjs"] }, - runtime: { command: "node", args: ["./run.mjs"] }, - inputs: toolInputs, - output: toolOutput, - scopes: ["docs.read"], - runx: toolRunx, - source_hash: sourceHash, - schema_hash: schemaHash, - toolkit_version: toolkitVersion, - }, null, 2)], - ["tools/docs/echo/fixtures/basic.yaml", `name: echo-basic -lane: deterministic -target: - kind: tool - ref: docs.echo -inputs: - message: hello -expect: - status: sealed - output: - subset: - schema: ${packetId} - data: - message: hello -`], - ["fixtures/agent.yaml", `name: echo-agent-replay -lane: agent -target: - kind: skill - ref: . -inputs: - message: hello -agent: - mode: replay -expect: - status: sealed - outputs: - echo_packet: - matches_packet: ${packetId} -`], - ["fixtures/agent.replay.json", JSON.stringify({ - schema: "runx.replay.v1", - fixture: "echo-agent-replay", - prompt_fingerprint: sha256Stable(agentFixture), - recorded_at: "1970-01-01T00:00:00.000Z", - target: agentFixture.target, - status: "sealed", - outputs: { - echo_packet: { - schema: packetId, - data: { - message: "hello", - }, - }, - }, - usage: { - mode: "scaffold", - }, - }, null, 2)], - ["fixtures/repos/readme-only/README.md", `# ${name} -`], - [".github/workflows/publish.yml", `name: publish +function runMjs(): string { + return `// Inputs arrive as RUNX_INPUT_ environment variables. Do the work and +// write the result to stdout. Replace this echo with the real logic. +const message = process.env.RUNX_INPUT_MESSAGE ?? ""; +if (message.trim().length === 0) { + process.stderr.write("message is required\\n"); + process.exit(64); +} +process.stdout.write(\`${"${message}"}\\n\`); +`; +} -on: - workflow_dispatch: - release: - types: - - published +function readme(name: string): string { + return `# ${name} -jobs: - publish: - runs-on: ubuntu-latest - permissions: - contents: read - id-token: write - steps: - - uses: actions/checkout@v4 - - uses: pnpm/action-setup@v4 - with: - version: 10 - - uses: actions/setup-node@v4 - with: - node-version: 20 - registry-url: https://registry.npmjs.org - cache: pnpm - - run: pnpm install --frozen-lockfile - - run: pnpm build - - run: pnpm runx:doctor - - run: npm publish --provenance --access public - env: - NODE_AUTH_TOKEN: \${{ secrets.NPM_TOKEN }} -`], - [".gitignore", `node_modules/ -.runx/ -*.tgz -`], - [".gitattributes", "tools/**/run.mjs linguist-generated=true\ntools/**/manifest.json linguist-generated=true\ntools/**/dist/** linguist-generated=true\n"], - ["tsconfig.json", JSON.stringify({ - extends: "@tsconfig/node20/tsconfig.json", - compilerOptions: { - module: "NodeNext", - moduleResolution: "NodeNext", - strict: true, - }, - include: ["src/**/*.ts", "tools/**/*.ts"], - }, null, 2)], - ]; +A native runx skill: a \`SKILL.md\` contract, an \`X.yaml\` execution profile, and a +\`run.mjs\` script. No build step and no dependencies. - await mkdir(root, { recursive: true }); - await Promise.all(writes.map(([relativePath, contents]) => write(root, relativePath, contents))); +## Develop - return { - name, - packet_namespace: packetNamespace, - directory: root, - files: writes.map(([relativePath]) => relativePath), - next_steps: [ - `cd ${root}`, - "pnpm install", - "pnpm build", - "runx dev", - ], - }; -} +\`\`\`bash +runx harness . --json # run the harness cases in X.yaml +runx skill . --input message=hello --json # run the skill once +runx history # inspect the signed receipt +\`\`\` -export function sanitizeRunxPackageName(value: string): string { - return value.trim().toLowerCase().replace(/[^a-z0-9_.-]+/g, "-").replace(/^[._-]+|[._-]+$/g, "") || "runx-package"; -} +Edit \`run.mjs\` to do the real work, and keep both harness classes in \`X.yaml\`: +one happy path and one stop, error, or refusal case. -function packetNamespaceForName(value: string): string { - return value - .toLowerCase() - .replace(/^@/, "") - .replace(/[^a-z0-9]+/g, ".") - .replace(/^\.+|\.+$/g, "") - || "runx.package"; +## Publish + +\`\`\`bash +runx login --provider github --for publish +runx registry publish . # the registry runs the harness as the publish gate +\`\`\` +`; } async function assertWritableScaffoldTarget(root: string): Promise { @@ -354,19 +187,3 @@ async function write(root: string, relativePath: string, contents: string): Prom await mkdir(path.dirname(filePath), { recursive: true }); await writeFile(filePath, contents.endsWith("\n") ? contents : `${contents}\n`); } - -function sha256ToolSourceContents(files: Readonly>): string { - const chunks: Uint8Array[] = []; - for (const relativePath of ["src/index.ts", "run.mjs"]) { - if (files[relativePath] === undefined) { - continue; - } - chunks.push( - Buffer.from(relativePath), - Buffer.from("\0"), - Buffer.from(files[relativePath] ?? ""), - Buffer.from("\0"), - ); - } - return sha256Prefixed(Buffer.concat(chunks)); -} diff --git a/packages/create-skill/README.md b/packages/create-skill/README.md index 1406dce37..9762bff66 100644 --- a/packages/create-skill/README.md +++ b/packages/create-skill/README.md @@ -1,25 +1,26 @@ # @runxhq/create-skill -Initializer package behind: +Deprecated compatibility wrapper behind the old npm initializer: ```bash npm create @runxhq/skill@latest my-skill ``` -The canonical runx command remains: +The supported runx command is: ```bash runx new my-skill ``` -This package is intentionally thin. It invokes the `runx` binary from -`@runxhq/cli` so the scaffolding logic stays in one native CLI path. +This package is intentionally thin and should not grow new behaviour. It invokes +the `runx` binary from `@runxhq/cli` so the scaffolding logic stays in the +native CLI path. ## Rust takeover boundary -`@runxhq/create-skill` remains a thin npm bootstrapper. After the Rust CLI -cutover it continues to wrap `runx new` through the bundled CLI rather than -reimplementing scaffolding logic. +`@runxhq/create-skill` is compatibility-only after the Rust CLI cutover. It +continues to wrap `runx new` through the bundled CLI rather than reimplementing +scaffolding logic. See the [TypeScript interop boundary](../../docs/ts-interop-boundary.md) for the package disposition and ownership rules. diff --git a/packages/create-skill/package.json b/packages/create-skill/package.json index 828f1a358..298ab9033 100644 --- a/packages/create-skill/package.json +++ b/packages/create-skill/package.json @@ -1,7 +1,7 @@ { "name": "@runxhq/create-skill", "version": "0.2.0", - "description": "Cold-start scaffolder for runx standalone skill packages.", + "description": "Deprecated compatibility wrapper around runx new.", "private": false, "license": "MIT", "type": "module", diff --git a/scripts/generate-rust-scaffold-fixtures.ts b/scripts/generate-rust-scaffold-fixtures.ts index b8bcb7826..3ab3ea617 100644 --- a/scripts/generate-rust-scaffold-fixtures.ts +++ b/scripts/generate-rust-scaffold-fixtures.ts @@ -33,7 +33,6 @@ try { path.join(fixtureRoot, "manifest.json"), `${JSON.stringify({ name: result.name, - packet_namespace: result.packet_namespace, files: result.files, next_steps: normalizeNextSteps(result.next_steps), }, null, 2)}\n`, diff --git a/tests/init-command.test.ts b/tests/init-command.test.ts index 2b574c834..136c262fd 100644 --- a/tests/init-command.test.ts +++ b/tests/init-command.test.ts @@ -7,7 +7,7 @@ import { describe, expect, it } from "vitest"; import { runCli } from "../packages/cli/src/index.js"; describe("runx init", () => { - it("scaffolds a new authoring package through runx new", async () => { + it("scaffolds a native skill through runx new", async () => { const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-new-package-")); const stdout = createMemoryStream(); const stderr = createMemoryStream(); @@ -25,31 +25,23 @@ describe("runx init", () => { readonly new: { readonly action: string; readonly name: string; - readonly packet_namespace: string; readonly directory: string; readonly files: readonly string[]; }; }; const target = path.join(tempDir, "docs-demo"); expect(report.new).toMatchObject({ - action: "package", + action: "skill", name: "docs-demo", - packet_namespace: "docs.demo", directory: target, }); expect(report.new.files).toContain("SKILL.md"); + expect(report.new.files).toContain("X.yaml"); + expect(report.new.files).toContain("run.mjs"); await expect(readFile(path.join(target, "SKILL.md"), "utf8")).resolves.toContain("name: docs-demo"); - await expect(readFile(path.join(target, "X.yaml"), "utf8")).resolves.toContain("tool: docs.echo"); - await expect(readFile(path.join(target, "tools/docs/echo/fixtures/basic.yaml"), "utf8")).resolves.toContain("lane: deterministic"); - await expect(readFile(path.join(target, "fixtures/agent.yaml"), "utf8")).resolves.toContain("lane: agent"); - await expect(readFile(path.join(target, "fixtures/agent.replay.json"), "utf8")).resolves.toContain("runx.replay.v1"); - await expect(readFile(path.join(target, "dist/packets/echo.v1.schema.json"), "utf8")).resolves.toContain("docs.demo.echo.v1"); - const manifest = JSON.parse(await readFile(path.join(target, "tools/docs/echo/manifest.json"), "utf8")) as { - readonly source_hash?: string; - readonly schema_hash?: string; - }; - expect(manifest.source_hash).toMatch(/^sha256:[a-f0-9]{64}$/); - expect(manifest.schema_hash).toMatch(/^sha256:[a-f0-9]{64}$/); + await expect(readFile(path.join(target, "X.yaml"), "utf8")).resolves.toContain("type: cli-tool"); + await expect(readFile(path.join(target, "run.mjs"), "utf8")).resolves.toContain("RUNX_INPUT_MESSAGE"); + await expect(stat(path.join(target, "package.json"))).rejects.toMatchObject({ code: "ENOENT" }); } finally { await rm(tempDir, { recursive: true, force: true }); } From c107ff6e4fd4fdd5b291e6dcd07af22a22ba8a4a Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 20:28:03 +1000 Subject: [PATCH 04/64] chore(scaffold): remove create skill wrapper --- README.md | 1 + docs/getting-started.md | 4 +- docs/reference.md | 3 + docs/ts-interop-boundary.md | 3 +- packages/create-skill/README.md | 26 ----- packages/create-skill/bin/create-skill.js | 27 ------ packages/create-skill/package.json | 37 ------- packages/create-skill/src/index.test.ts | 81 ---------------- packages/create-skill/src/index.ts | 82 ---------------- pnpm-lock.yaml | 6 -- .../check-create-skill-package-contract.mjs | 97 ------------------- 11 files changed, 8 insertions(+), 359 deletions(-) delete mode 100644 packages/create-skill/README.md delete mode 100755 packages/create-skill/bin/create-skill.js delete mode 100644 packages/create-skill/package.json delete mode 100644 packages/create-skill/src/index.test.ts delete mode 100644 packages/create-skill/src/index.ts delete mode 100644 scripts/check-create-skill-package-contract.mjs diff --git a/README.md b/README.md index 9be837fe3..815133e12 100644 --- a/README.md +++ b/README.md @@ -101,6 +101,7 @@ cd oss && cargo build --manifest-path crates/Cargo.toml -p runx-cli ## author and publish ```bash +npx @runxhq/cli new my-skill # cold-start with no install: downloads the launcher, runs the same native scaffold runx new my-skill # scaffold a native cli-tool skill (SKILL.md + X.yaml + run.mjs, zero deps) ``` diff --git a/docs/getting-started.md b/docs/getting-started.md index 2f195dbb5..a70ab0faa 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -78,7 +78,9 @@ crates/target/debug/runx history --json ## Next - Use `crates/target/debug/runx new docs-demo` to scaffold a native cli-tool - skill (SKILL.md + X.yaml + run.mjs, zero npm deps). + skill (SKILL.md + X.yaml + run.mjs, zero npm deps). To cold-start without + installing runx first, run `npx @runxhq/cli new docs-demo`; it downloads the + launcher and runs the same native scaffold. - Compose the example into a graph with [Skill To Graph](./skill-to-graph.md). - Publish a ready skill from a public repo at https://runx.ai/x/publish, or run `crates/target/debug/runx login` followed by `crates/target/debug/runx registry publish ... --registry https://runx.ai`. diff --git a/docs/reference.md b/docs/reference.md index b0cdb0517..36d6ab824 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -226,6 +226,9 @@ run.mjs, zero npm deps, no build step): runx new docs-demo ``` +To cold-start without installing runx first, run `npx @runxhq/cli new docs-demo`; +it downloads the launcher and runs the same native scaffold. + Community skills should be authored and published as standalone packages created this way. The main `runx` repo is the first-party lane for official skills and runtime code, not the community package catalog. diff --git a/docs/ts-interop-boundary.md b/docs/ts-interop-boundary.md index 4fd555f78..5ef53e345 100644 --- a/docs/ts-interop-boundary.md +++ b/docs/ts-interop-boundary.md @@ -115,10 +115,9 @@ truth, so it is recorded here rather than implied. | Package | Disposition | | --- | --- | | `@runxhq/authoring` | Stays as authoring tooling for skills, manifests, protocol fixtures, and generated artifacts until the authoring DX plan decides whether any piece moves to Rust or scafld. It does not own trusted local execution. | -| `@runxhq/cli` | Stays as a platform-aware npm launcher that resolves and execs the Rust binary. It must remain useful from an installed package without TypeScript sources and must fail closed instead of falling back to TypeScript local execution. | +| `@runxhq/cli` | Stays as a platform-aware npm launcher that resolves and execs the Rust binary. It must remain useful from an installed package without TypeScript sources and must fail closed instead of falling back to TypeScript local execution. It also carries the drift-free cold-start: `npx @runxhq/cli new ` downloads the launcher and runs the same native `runx new` scaffold without a prior runx install. | | `@runxhq/contracts` | Stays as the published generated TypeScript view of `runx-contracts`, maintained with fixture cross-validation. | | `@runxhq/core` | Deleted. Its registry/config/parser remnants were not a shipped execution boundary; live OSS code uses Rust crates, generated contracts, tool-local modules, or explicit protocol packages instead. Cloud imports the promoted `@runx/protocol` package. | -| `@runxhq/create-skill` | Deprecated compatibility package. `runx new` is the supported scaffold entrypoint. | | `@runxhq/host-adapters` | Stays as thin host response adapters over the runx host protocol, retargeted to `@runxhq/contracts` types. It can shape host/client responses, not execute trusted local runtime behavior. | | `@runxhq/langchain` | Stays as an optional LangChain bridge that shells the `runx` CLI or uses documented external protocols for governed skill and tool invocation. | | `runx-py` | Stays as a thin Python client over `runx` CLI JSON output. | diff --git a/packages/create-skill/README.md b/packages/create-skill/README.md deleted file mode 100644 index 9762bff66..000000000 --- a/packages/create-skill/README.md +++ /dev/null @@ -1,26 +0,0 @@ -# @runxhq/create-skill - -Deprecated compatibility wrapper behind the old npm initializer: - -```bash -npm create @runxhq/skill@latest my-skill -``` - -The supported runx command is: - -```bash -runx new my-skill -``` - -This package is intentionally thin and should not grow new behaviour. It invokes -the `runx` binary from `@runxhq/cli` so the scaffolding logic stays in the -native CLI path. - -## Rust takeover boundary - -`@runxhq/create-skill` is compatibility-only after the Rust CLI cutover. It -continues to wrap `runx new` through the bundled CLI rather than reimplementing -scaffolding logic. - -See the [TypeScript interop boundary](../../docs/ts-interop-boundary.md) for -the package disposition and ownership rules. diff --git a/packages/create-skill/bin/create-skill.js b/packages/create-skill/bin/create-skill.js deleted file mode 100755 index 26c62c505..000000000 --- a/packages/create-skill/bin/create-skill.js +++ /dev/null @@ -1,27 +0,0 @@ -#!/usr/bin/env node - -import { existsSync } from "node:fs"; -import path from "node:path"; -import { fileURLToPath, pathToFileURL } from "node:url"; -import process from "node:process"; - -const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), ".."); -const distEntry = path.join(packageRoot, "dist", "index.js"); - -if (existsSync(distEntry)) { - const { runCreateSkill } = await import(pathToFileURL(distEntry).href); - const exitCode = await runCreateSkill(process.argv.slice(2), { - stdin: process.stdin, - stdout: process.stdout, - stderr: process.stderr, - }); - process.exitCode = exitCode; -} else { - const hint = [ - "create-skill: packaged dist is missing.", - "Run the workspace build before invoking this package.", - `Expected entry: ${distEntry}`, - ].join("\n"); - process.stderr.write(`${hint}\n`); - process.exitCode = 1; -} diff --git a/packages/create-skill/package.json b/packages/create-skill/package.json deleted file mode 100644 index 298ab9033..000000000 --- a/packages/create-skill/package.json +++ /dev/null @@ -1,37 +0,0 @@ -{ - "name": "@runxhq/create-skill", - "version": "0.2.0", - "description": "Deprecated compatibility wrapper around runx new.", - "private": false, - "license": "MIT", - "type": "module", - "homepage": "https://github.com/runxhq/runx", - "bugs": { - "url": "https://github.com/runxhq/runx/issues" - }, - "repository": { - "type": "git", - "url": "git+https://github.com/runxhq/runx.git", - "directory": "packages/create-skill" - }, - "publishConfig": { - "access": "public" - }, - "bin": { - "create-skill": "./bin/create-skill.js" - }, - "files": [ - "README.md", - "bin", - "dist" - ], - "exports": { - ".": { - "types": "./dist/index.d.ts", - "import": "./dist/index.js" - } - }, - "dependencies": { - "@runxhq/cli": "workspace:^0.5.22" - } -} diff --git a/packages/create-skill/src/index.test.ts b/packages/create-skill/src/index.test.ts deleted file mode 100644 index 1328a6f4f..000000000 --- a/packages/create-skill/src/index.test.ts +++ /dev/null @@ -1,81 +0,0 @@ -import { Writable } from "node:stream"; - -import { describe, expect, it } from "vitest"; - -import { runCreateSkill, type CliIo } from "./index.js"; - -class MemoryWritable extends Writable { - #chunks: string[] = []; - - _write(chunk: Buffer | string, _encoding: BufferEncoding, callback: (error?: Error | null) => void): void { - this.#chunks.push(typeof chunk === "string" ? chunk : chunk.toString("utf8")); - callback(); - } - - contents(): string { - return this.#chunks.join(""); - } -} - -function createIo() { - const stdout = new MemoryWritable(); - const stderr = new MemoryWritable(); - return { - stdout, - stderr, - io: { - stdin: process.stdin, - stdout: stdout as unknown as NodeJS.WriteStream, - stderr: stderr as unknown as NodeJS.WriteStream, - } satisfies CliIo, - }; -} - -describe("@runxhq/create-skill", () => { - it("forwards to runx new with the original args", async () => { - const calls: unknown[] = []; - const { io, stdout, stderr } = createIo(); - const env = { ...process.env, INIT_CWD: "/tmp/project-root" }; - - const exitCode = await runCreateSkill( - ["demo-skill", "--directory", "packages/demo-skill"], - io, - env, - async (argv, receivedIo, receivedEnv) => { - calls.push({ argv, receivedIo, receivedEnv }); - return 0; - }, - ); - - expect(exitCode).toBe(0); - expect(stdout.contents()).toBe(""); - expect(stderr.contents()).toBe(""); - expect(calls).toEqual([ - { - argv: ["demo-skill", "--directory", "packages/demo-skill"], - receivedIo: io, - receivedEnv: env, - }, - ]); - }); - - it("prints help to stdout", async () => { - const { io, stdout, stderr } = createIo(); - - const exitCode = await runCreateSkill(["--help"], io, process.env, async () => 1); - - expect(exitCode).toBe(0); - expect(stdout.contents()).toContain("npm create @runxhq/skill@latest "); - expect(stderr.contents()).toBe(""); - }); - - it("requires a package name", async () => { - const { io, stdout, stderr } = createIo(); - - const exitCode = await runCreateSkill([], io, process.env, async () => 0); - - expect(exitCode).toBe(64); - expect(stdout.contents()).toBe(""); - expect(stderr.contents()).toContain("runx new "); - }); -}); diff --git a/packages/create-skill/src/index.ts b/packages/create-skill/src/index.ts deleted file mode 100644 index 199f6123f..000000000 --- a/packages/create-skill/src/index.ts +++ /dev/null @@ -1,82 +0,0 @@ -import { spawn } from "node:child_process"; -import type { Readable, Writable } from "node:stream"; - -export interface CliIo { - readonly stdin: Readable; - readonly stdout: Writable; - readonly stderr: Writable; -} - -export type RunCliLike = ( - argv: readonly string[], - io?: CliIo, - env?: NodeJS.ProcessEnv, -) => Promise; - -const usageLines = [ - "Usage:", - " npm create @runxhq/skill@latest [-- --directory dir]", - " runx new [--directory dir]", - "", - "Notes:", - " runx new is the canonical command.", - " The create package is a cold-start entrypoint for the same scaffolder.", -]; - -export async function runRunxNew( - argv: readonly string[], - io: CliIo = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr }, - env: NodeJS.ProcessEnv = process.env, -): Promise { - const runxBin = env.RUNX_BIN ?? "runx"; - return await new Promise((resolve) => { - let settled = false; - const finish = (code: number) => { - if (!settled) { - settled = true; - resolve(code); - } - }; - const child = spawn(runxBin, ["new", ...argv], { - env, - stdio: "inherit", - }); - child.on("error", (error) => { - io.stderr.write(`create-skill: failed to start runx: ${error.message}\n`); - finish(127); - }); - child.on("exit", (code, signal) => { - if (signal) { - io.stderr.write(`create-skill: runx exited from signal ${signal}\n`); - finish(1); - return; - } - finish(code ?? 1); - }); - }); -} - -export function writeCreateSkillUsage(stream: Writable): void { - stream.write(`${usageLines.join("\n")}\n`); -} - -export async function runCreateSkill( - argv: readonly string[] = process.argv.slice(2), - io: CliIo = { stdin: process.stdin, stdout: process.stdout, stderr: process.stderr }, - env: NodeJS.ProcessEnv = process.env, - runCliImpl: RunCliLike = runRunxNew, -): Promise { - if (argv.length === 1 && (argv[0] === "--help" || argv[0] === "-h")) { - writeCreateSkillUsage(io.stdout); - return 0; - } - if (argv.length === 0) { - writeCreateSkillUsage(io.stderr); - return 64; - } - return await runCliImpl(argv, io, env); -} - -if (import.meta.url === new URL(process.argv[1] ?? "", "file:").href) { - process.exitCode = await runCreateSkill(); -} diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index 66463cca0..a8e1403ab 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -50,12 +50,6 @@ importers: specifier: ^8.20.0 version: 8.20.0 - packages/create-skill: - dependencies: - '@runxhq/cli': - specifier: workspace:^0.5.22 - version: link:../cli - packages/host-adapters: dependencies: '@runxhq/contracts': diff --git a/scripts/check-create-skill-package-contract.mjs b/scripts/check-create-skill-package-contract.mjs deleted file mode 100644 index 06f5ab454..000000000 --- a/scripts/check-create-skill-package-contract.mjs +++ /dev/null @@ -1,97 +0,0 @@ -import { execFile } from "node:child_process"; -import { mkdtemp, readFile, rm, stat } from "node:fs/promises"; -import os from "node:os"; -import path from "node:path"; -import { promisify } from "node:util"; -import { fileURLToPath } from "node:url"; - -const execFileAsync = promisify(execFile); -const workspaceRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url))); -const packageRoot = path.join(workspaceRoot, "packages", "create-skill"); -const distEntry = path.join(packageRoot, "dist", "index.js"); -const binEntry = path.join(packageRoot, "bin", "create-skill.js"); -const runxBinary = process.env.RUNX_BIN - ?? path.join(workspaceRoot, "crates", "target", "debug", process.platform === "win32" ? "runx.exe" : "runx"); -const npm = process.platform === "win32" ? "npm.cmd" : "npm"; -const cargo = process.platform === "win32" ? "cargo.exe" : "cargo"; - -const dist = await stat(distEntry); -if (!dist.isFile()) { - throw new Error(`create-skill dist entry is missing: ${distEntry}`); -} -const distSource = await readFile(distEntry, "utf8"); -if (distSource.includes(".build/runtime")) { - throw new Error("create-skill dist entry still points at .build/runtime instead of the packaged dist tree."); -} - -const bin = await stat(binEntry); -if (!bin.isFile() || (bin.mode & 0o111) === 0) { - throw new Error(`create-skill bin entry is missing or not executable: ${binEntry}`); -} - -const pack = await execFileAsync(npm, ["pack", "--dry-run", "--json"], { - cwd: packageRoot, - timeout: 30_000, - maxBuffer: 1024 * 1024, -}); -const [report] = JSON.parse(pack.stdout); -const files = new Set(report.files.map((file) => file.path)); -for (const required of [ - "README.md", - "bin/create-skill.js", - "dist/index.js", - "dist/index.d.ts", - "dist/src/index.js", - "dist/src/index.d.ts", -]) { - if (!files.has(required)) { - throw new Error(`create-skill package is missing ${required}`); - } -} - -const tempRoot = await mkdtemp(path.join(os.tmpdir(), "runx-create-skill-")); -try { - if (!(await statIfExists(runxBinary))?.isFile()) { - await execFileAsync(cargo, ["build", "--manifest-path", "crates/Cargo.toml", "-p", "runx-cli"], { - cwd: workspaceRoot, - timeout: 120_000, - maxBuffer: 1024 * 1024, - }); - } - const targetDir = path.join(tempRoot, "demo-skill"); - await execFileAsync(process.execPath, [binEntry, "demo-skill", "--directory", targetDir], { - cwd: workspaceRoot, - timeout: 30_000, - maxBuffer: 1024 * 1024, - env: { - ...process.env, - RUNX_CWD: tempRoot, - RUNX_BIN: runxBinary, - }, - }); - for (const required of [ - "SKILL.md", - "X.yaml", - ".github/workflows/publish.yml", - "tools/docs/echo/src/index.ts", - ]) { - const requiredPath = path.join(targetDir, required); - const entry = await statIfExists(requiredPath); - if (!entry?.isFile()) { - throw new Error(`create-skill smoke run did not produce ${required}`); - } - } -} finally { - await rm(tempRoot, { recursive: true, force: true }); -} - -async function statIfExists(filePath) { - try { - return await stat(filePath); - } catch (error) { - if (error && typeof error === "object" && "code" in error && error.code === "ENOENT") { - return undefined; - } - throw error; - } -} From f3177c30f9731cf637a3cefd2aa2af557c858eb1 Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 21:11:16 +1000 Subject: [PATCH 05/64] fix(cli): target hosted api for publish auth --- README.md | 2 +- crates/runx-cli/src/launcher.rs | 2 +- crates/runx-cli/src/public_api.rs | 2 +- crates/runx-cli/src/publish_tests.rs | 2 +- crates/runx-cli/src/url_add.rs | 2 +- docs/getting-started.md | 3 ++- docs/publishing.md | 2 +- docs/reference.md | 2 +- packages/cli/src/commands/url-add.test.ts | 4 ++-- packages/cli/src/commands/url-add.ts | 2 +- 10 files changed, 12 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 815133e12..8d234eff7 100644 --- a/README.md +++ b/README.md @@ -105,7 +105,7 @@ npx @runxhq/cli new my-skill # cold-start with no install: download runx new my-skill # scaffold a native cli-tool skill (SKILL.md + X.yaml + run.mjs, zero deps) ``` -Write the prose, declare the profile, run it locally, then publish from a public repo at [runx.ai/x/publish](https://runx.ai/x/publish) or with `runx login && runx registry publish`. This repo is the first-party lane for official skills and the runtime; community skills ship as standalone packages. +Write the prose, declare the profile, run it locally, then publish from a public repo at [runx.ai/x/publish](https://runx.ai/x/publish) or with `runx login --for publish && runx registry publish`. This repo is the first-party lane for official skills and the runtime; community skills ship as standalone packages. ## docs diff --git a/crates/runx-cli/src/launcher.rs b/crates/runx-cli/src/launcher.rs index c7f30efbb..668bda0d5 100644 --- a/crates/runx-cli/src/launcher.rs +++ b/crates/runx-cli/src/launcher.rs @@ -376,7 +376,7 @@ Usage: runx publish [--api-base-url url] [--token token] [--allow-local-api] [--json] Options: - --api-base-url url Public API base URL (default: RUNX_PUBLIC_API_BASE_URL or https://runx.ai) + --api-base-url url Public API base URL (default: RUNX_PUBLIC_API_BASE_URL or https://api.runx.ai) --token token Public API token (default: RUNX_PUBLIC_API_TOKEN or runx login) --allow-local-api Allow loopback/private public API URLs for local dogfood only --json Print the raw notary response as JSON diff --git a/crates/runx-cli/src/public_api.rs b/crates/runx-cli/src/public_api.rs index 008eec06b..7e65116a0 100644 --- a/crates/runx-cli/src/public_api.rs +++ b/crates/runx-cli/src/public_api.rs @@ -3,7 +3,7 @@ use std::collections::BTreeMap; use runx_runtime::registry::{DefaultRuntimeHttpTransport, RuntimeHttpError}; use serde::Deserialize; -pub(crate) const DEFAULT_BASE_URL: &str = "https://runx.ai"; +pub(crate) const DEFAULT_BASE_URL: &str = "https://api.runx.ai"; const BASE_URL_ENV: &str = "RUNX_PUBLIC_API_BASE_URL"; pub(crate) fn resolve_base_url(explicit: Option<&str>, env: &BTreeMap) -> String { diff --git a/crates/runx-cli/src/publish_tests.rs b/crates/runx-cli/src/publish_tests.rs index 86d1c5543..d8a8cb493 100644 --- a/crates/runx-cli/src/publish_tests.rs +++ b/crates/runx-cli/src/publish_tests.rs @@ -126,7 +126,7 @@ fn resolves_publish_endpoint_and_token_precedence() -> Result<(), Box = BTreeMap::new(); assert_eq!( resolve_public_api_base_url(&plan_no_override, &empty_env), - "https://runx.ai", + "https://api.runx.ai", ); } diff --git a/docs/getting-started.md b/docs/getting-started.md index a70ab0faa..ec11ec521 100644 --- a/docs/getting-started.md +++ b/docs/getting-started.md @@ -83,6 +83,7 @@ crates/target/debug/runx history --json launcher and runs the same native scaffold. - Compose the example into a graph with [Skill To Graph](./skill-to-graph.md). - Publish a ready skill from a public repo at https://runx.ai/x/publish, or run - `crates/target/debug/runx login` followed by `crates/target/debug/runx registry publish ... --registry https://runx.ai`. + `crates/target/debug/runx login --for publish` followed by + `crates/target/debug/runx registry publish ... --registry https://api.runx.ai`. See [Publishing](./publishing.md) for the full local and hosted paths. - See [API Surface](./api-surface.md) for public package exports. diff --git a/docs/publishing.md b/docs/publishing.md index 7dba365be..2e85998e4 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -57,7 +57,7 @@ The CLI form keeps the public API token out of command lines: ```bash runx login --for publish -runx registry publish ./skills//SKILL.md --registry https://runx.ai +runx registry publish ./skills//SKILL.md --registry https://api.runx.ai ``` For remote publishes the CLI sends a bounded skill package: diff --git a/docs/reference.md b/docs/reference.md index 36d6ab824..39109173e 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -376,7 +376,7 @@ runx publish ./.runx/receipts/.json `runx publish` posts the full sealed receipt to `POST /v1/receipts/notarize` with `publish: true`, then prints the public `/r` link and content hash returned by the notary. Configure the hosted API with `RUNX_PUBLIC_API_BASE_URL` (default -`https://runx.ai`) and authenticate with `RUNX_PUBLIC_API_TOKEN` or `--token` +`https://api.runx.ai`) and authenticate with `RUNX_PUBLIC_API_TOKEN` or `--token` (or run `runx login`). For local hosted dogfood only, point at a loopback API and opt into the private diff --git a/packages/cli/src/commands/url-add.test.ts b/packages/cli/src/commands/url-add.test.ts index fd8569e1a..67e7cbb79 100644 --- a/packages/cli/src/commands/url-add.test.ts +++ b/packages/cli/src/commands/url-add.test.ts @@ -33,8 +33,8 @@ describe("isGithubRepoUrl", () => { }); describe("resolveUrlAddApiBaseUrl", () => { - it("falls back to runx.ai", () => { - expect(resolveUrlAddApiBaseUrl({})).toBe("https://runx.ai"); + it("falls back to the hosted API origin", () => { + expect(resolveUrlAddApiBaseUrl({})).toBe("https://api.runx.ai"); }); it("respects RUNX_PUBLIC_API_BASE_URL", () => { diff --git a/packages/cli/src/commands/url-add.ts b/packages/cli/src/commands/url-add.ts index 3201924c9..3fcb46b03 100644 --- a/packages/cli/src/commands/url-add.ts +++ b/packages/cli/src/commands/url-add.ts @@ -141,5 +141,5 @@ export function renderUrlAddResult(result: UrlAddIndexResult): string { } export function resolveUrlAddApiBaseUrl(env: Record): string { - return env.RUNX_PUBLIC_API_BASE_URL?.trim() || "https://runx.ai"; + return env.RUNX_PUBLIC_API_BASE_URL?.trim() || "https://api.runx.ai"; } From a57b6929f901251731ce0524b9bc8d4961752da9 Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 21:45:26 +1000 Subject: [PATCH 06/64] feat: frantic drain uses server pending cursor + event trigger default to the /internal/thread-outbox pending cursor (drops the fragile client cursor-cache that re-walked history on a fresh runner) and listen for a board-sync repository_dispatch so the venue can trigger the drain low-latency. --- .../workflows/frantic-github-thread-sync.yml | 6 ++++ scripts/frantic-github-thread-sync.mjs | 32 +++++++++++++++---- 2 files changed, 32 insertions(+), 6 deletions(-) diff --git a/.github/workflows/frantic-github-thread-sync.yml b/.github/workflows/frantic-github-thread-sync.yml index c83005750..d2c088ade 100644 --- a/.github/workflows/frantic-github-thread-sync.yml +++ b/.github/workflows/frantic-github-thread-sync.yml @@ -4,6 +4,12 @@ env: FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: true on: + # The venue fires repository_dispatch (board-sync) on board mutations so the drain + # runs promptly. The cron below is the backstop: GitHub throttles high-frequency + # schedules (they fire roughly hourly under load), so this event is what makes the + # sync low-latency and reliable rather than schedule-only. + repository_dispatch: + types: [board-sync] workflow_dispatch: inputs: after_event_id: diff --git a/scripts/frantic-github-thread-sync.mjs b/scripts/frantic-github-thread-sync.mjs index af6f27dbd..6f579bef6 100644 --- a/scripts/frantic-github-thread-sync.mjs +++ b/scripts/frantic-github-thread-sync.mjs @@ -11,8 +11,13 @@ const PROVIDER_SCRIPT = path.join(__dirname, "../tools/thread/thread_outbox_prov async function main() { const config = readConfig(process.env); - const afterEventId = readCursor(config.cursorFile) ?? config.afterEventId; - const payload = await fetchThreadOutbox({ ...config, afterEventId }); + // Default to the server-side per-thread cursor (?pending=true) so CI needs no + // client cursor file. An explicit after_event_id or a populated cursor file + // still wins and pins the client-side walk for one-off replays. + const explicitCursor = readCursor(config.cursorFile) ?? config.explicitAfterEventId; + const pending = explicitCursor === undefined; + const afterEventId = pending ? 0 : explicitCursor; + const payload = await fetchThreadOutbox({ ...config, afterEventId, pending }); const intents = Array.isArray(payload.intents) ? payload.intents : []; let maxEventId = afterEventId; const observations = []; @@ -42,12 +47,16 @@ async function main() { if (!config.dryRun && observations.length > 0) { await postThreadObservations(config, observations); } - if (!config.dryRun && config.cursorFile && maxEventId > afterEventId) { + // Only persist a client cursor when explicitly walking by after_event_id. In + // the default pending mode the server tracks each thread's cursor from the + // observations we post back, so a client cursor file is neither read nor written. + if (!config.dryRun && !pending && config.cursorFile && maxEventId > afterEventId) { writeFileSync(config.cursorFile, `${maxEventId}\n`); } process.stdout.write(`${JSON.stringify({ ok: true, + pending, fetched: intents.length, observed: observations.length, after_event_id: afterEventId, @@ -68,7 +77,7 @@ function readConfig(env) { provider: trim(env.FRANTIC_THREAD_PROVIDER) ?? "github", targetRepo: trim(env.FRANTIC_GITHUB_TARGET_REPO ?? env.FRANTIC_BOARD_REPO), limit: positiveInteger(env.FRANTIC_THREAD_LIMIT, 50), - afterEventId: positiveInteger(env.FRANTIC_THREAD_AFTER_EVENT_ID, 0), + explicitAfterEventId: optionalPositiveInteger(env.FRANTIC_THREAD_AFTER_EVENT_ID), cursorFile: trim(env.FRANTIC_THREAD_CURSOR_FILE), adapterId: trim(env.FRANTIC_THREAD_ADAPTER_ID) ?? "runx-github-thread-adapter", dryRun: env.FRANTIC_THREAD_DRY_RUN === "1" || env.FRANTIC_THREAD_DRY_RUN === "true", @@ -79,7 +88,11 @@ function readConfig(env) { async function fetchThreadOutbox(config) { const url = new URL("/internal/thread-outbox", config.apiBaseUrl); url.searchParams.set("provider", config.provider); - url.searchParams.set("after_event_id", String(config.afterEventId)); + if (config.pending) { + url.searchParams.set("pending", "true"); + } else { + url.searchParams.set("after_event_id", String(config.afterEventId)); + } url.searchParams.set("limit", String(config.limit)); if (config.targetRepo) { url.searchParams.set("target_repo", config.targetRepo); @@ -158,7 +171,9 @@ function readCursor(cursorFile) { if (!cursorFile || !existsSync(cursorFile)) { return undefined; } - return positiveInteger(readFileSync(cursorFile, "utf8"), 0); + // An empty or zero cursor file means "no explicit cursor"; fall through to the + // server-side pending read rather than re-walking all history from event 0. + return optionalPositiveInteger(readFileSync(cursorFile, "utf8")); } function positiveInteger(value, fallback) { @@ -166,6 +181,11 @@ function positiveInteger(value, fallback) { return Number.isFinite(parsed) && parsed >= 0 ? parsed : fallback; } +function optionalPositiveInteger(value) { + const parsed = Number.parseInt(String(value ?? ""), 10); + return Number.isFinite(parsed) && parsed > 0 ? parsed : undefined; +} + function numberOrZero(value) { return positiveInteger(value, 0); } From 1624bb1e98a271f9dd51e66c54501fd29bd48fb8 Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 22:21:35 +1000 Subject: [PATCH 07/64] test(runtime): grant sandbox fallback for mixed credential graph --- crates/runx-runtime/tests/local_credential_provision.rs | 9 ++++++++- 1 file changed, 8 insertions(+), 1 deletion(-) diff --git a/crates/runx-runtime/tests/local_credential_provision.rs b/crates/runx-runtime/tests/local_credential_provision.rs index 05a731b3e..eb64f9e1a 100644 --- a/crates/runx-runtime/tests/local_credential_provision.rs +++ b/crates/runx-runtime/tests/local_credential_provision.rs @@ -178,7 +178,7 @@ fn graph_http_credential_does_not_break_local_cli_tool_steps() )] .into_iter() .collect(), - env: http_private_network_grant_env(), + env: mixed_http_cli_graph_env(), cwd: temp.path().to_path_buf(), local_credential: Some(LocalCredentialDescriptor { provider: "example-crm".to_owned(), @@ -226,6 +226,13 @@ fn local_sandbox_fallback_env() -> BTreeMap { .into() } +#[cfg(feature = "http")] +fn mixed_http_cli_graph_env() -> BTreeMap { + let mut env = http_private_network_grant_env(); + env.extend(local_sandbox_fallback_env()); + env +} + /// A cli-tool skill that echoes the delivered `$GITHUB_TOKEN`. The command is a /// local shell process: no network, no hosted dependency. fn write_echo_token_skill(root: &Path) -> Result> { From d9ac817d889988695a7b18a0125bde6bc21b2336 Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 22:57:47 +1000 Subject: [PATCH 08/64] fix(cli): sign publish harness preflight --- crates/runx-cli/src/main.rs | 1 + crates/runx-cli/src/registry/package.rs | 90 ++++++++++++++++++- .../src/execution/orchestrator.rs | 2 + .../execution/skill_front/inline_harness.rs | 10 ++- 4 files changed, 98 insertions(+), 5 deletions(-) diff --git a/crates/runx-cli/src/main.rs b/crates/runx-cli/src/main.rs index b68cd0fb7..c989b2c95 100644 --- a/crates/runx-cli/src/main.rs +++ b/crates/runx-cli/src/main.rs @@ -249,6 +249,7 @@ fn run_inline_harness(skill_path: &Path, receipt_dir: Option<&OsString>) -> Exit let request = runx_runtime::InlineHarnessRequest { skill_path: skill_path.to_path_buf(), receipt_dir: receipt_dir.map(PathBuf::from), + env: None, }; let report = match runx_cli::runtime::local_orchestrator().run_inline_harness(&request) { Ok(report) => report, diff --git a/crates/runx-cli/src/registry/package.rs b/crates/runx-cli/src/registry/package.rs index eccd75507..d37a8af23 100644 --- a/crates/runx-cli/src/registry/package.rs +++ b/crates/runx-cli/src/registry/package.rs @@ -9,7 +9,10 @@ use std::process; use std::time::{SystemTime, UNIX_EPOCH}; use runx_contracts::{JsonObject, JsonValue}; -use runx_runtime::registry::RegistryPublishHarnessReport; +use runx_runtime::{ + RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64_ENV, RUNX_RECEIPT_SIGN_ISSUER_TYPE_ENV, + RUNX_RECEIPT_SIGN_KID_ENV, registry::RegistryPublishHarnessReport, +}; use serde::Serialize; use super::{RegistryCliError, internal_error}; @@ -89,6 +92,7 @@ pub(super) fn run_publish_harness( let request = runx_runtime::InlineHarnessRequest { skill_path: harness_path.to_path_buf(), receipt_dir: Some(receipt_dir.clone()), + env: Some(publish_harness_env()), }; let report = crate::runtime::local_orchestrator().run_inline_harness(&request); let _ignored = fs::remove_dir_all(&receipt_dir); @@ -132,6 +136,43 @@ struct PublishHarnessPackage { const MAX_REMOTE_PUBLISH_FILE_BYTES: u64 = 512 * 1024; const MAX_REMOTE_PUBLISH_TOTAL_BYTES: u64 = 2 * 1024 * 1024; const MAX_REMOTE_PUBLISH_FILE_COUNT: usize = 128; +const PUBLISH_HARNESS_SIGNING_KID: &str = "runx-publish-harness-local"; +const PUBLISH_HARNESS_SIGNING_SEED_BASE64: &str = "QkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkI="; +const PUBLISH_HARNESS_SIGNING_ISSUER_TYPE: &str = "ci"; + +fn publish_harness_env() -> BTreeMap { + let mut env = env::vars().collect(); + ensure_publish_harness_signing_env(&mut env); + env +} + +fn ensure_publish_harness_signing_env(env: &mut BTreeMap) { + if [ + RUNX_RECEIPT_SIGN_KID_ENV, + RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64_ENV, + RUNX_RECEIPT_SIGN_ISSUER_TYPE_ENV, + ] + .iter() + .all(|name| env_value_is_blank(env, name)) + { + env.insert( + RUNX_RECEIPT_SIGN_KID_ENV.to_owned(), + PUBLISH_HARNESS_SIGNING_KID.to_owned(), + ); + env.insert( + RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64_ENV.to_owned(), + PUBLISH_HARNESS_SIGNING_SEED_BASE64.to_owned(), + ); + env.insert( + RUNX_RECEIPT_SIGN_ISSUER_TYPE_ENV.to_owned(), + PUBLISH_HARNESS_SIGNING_ISSUER_TYPE.to_owned(), + ); + } +} + +fn env_value_is_blank(env: &BTreeMap, name: &str) -> bool { + env.get(name).is_none_or(|value| value.trim().is_empty()) +} fn publish_harness_package( markdown: &str, @@ -562,10 +603,55 @@ fn publish_harness_report( #[cfg(test)] mod tests { use super::{ - collect_publish_package_files, should_reject_remote_publish_file, unique_temp_dir, + PUBLISH_HARNESS_SIGNING_ISSUER_TYPE, PUBLISH_HARNESS_SIGNING_KID, + collect_publish_package_files, ensure_publish_harness_signing_env, + should_reject_remote_publish_file, unique_temp_dir, }; use std::fs; + use runx_runtime::{ + RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64_ENV, RUNX_RECEIPT_SIGN_ISSUER_TYPE_ENV, + RUNX_RECEIPT_SIGN_KID_ENV, + }; + + #[test] + fn publish_harness_supplies_local_signing_env_for_fresh_users() { + let mut env = std::collections::BTreeMap::new(); + + ensure_publish_harness_signing_env(&mut env); + + assert_eq!( + env.get(RUNX_RECEIPT_SIGN_KID_ENV).map(String::as_str), + Some(PUBLISH_HARNESS_SIGNING_KID) + ); + assert_eq!( + env.get(RUNX_RECEIPT_SIGN_ISSUER_TYPE_ENV) + .map(String::as_str), + Some(PUBLISH_HARNESS_SIGNING_ISSUER_TYPE) + ); + assert!( + env.get(RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64_ENV) + .is_some_and(|value| !value.trim().is_empty()) + ); + } + + #[test] + fn publish_harness_does_not_mask_partial_signing_env() { + let mut env = std::collections::BTreeMap::from([( + RUNX_RECEIPT_SIGN_KID_ENV.to_owned(), + "explicit-kid".to_owned(), + )]); + + ensure_publish_harness_signing_env(&mut env); + + assert_eq!( + env.get(RUNX_RECEIPT_SIGN_KID_ENV).map(String::as_str), + Some("explicit-kid") + ); + assert!(!env.contains_key(RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64_ENV)); + assert!(!env.contains_key(RUNX_RECEIPT_SIGN_ISSUER_TYPE_ENV)); + } + #[test] fn remote_publish_rejects_common_secret_file_names() { for path in [ diff --git a/crates/runx-runtime/src/execution/orchestrator.rs b/crates/runx-runtime/src/execution/orchestrator.rs index 71ff92592..8192f95c2 100644 --- a/crates/runx-runtime/src/execution/orchestrator.rs +++ b/crates/runx-runtime/src/execution/orchestrator.rs @@ -90,6 +90,7 @@ pub struct HarnessRunRequest { pub struct InlineHarnessRequest { pub skill_path: PathBuf, pub receipt_dir: Option, + pub env: Option>, } #[derive(Clone, Debug, Default, PartialEq, Eq)] @@ -205,6 +206,7 @@ impl LocalOrchestrator { Ok(super::skill_front::run_inline_harness_with_effects( &request.skill_path, request.receipt_dir.as_deref(), + request.env.as_ref(), &self.effects, )?) } diff --git a/crates/runx-runtime/src/execution/skill_front/inline_harness.rs b/crates/runx-runtime/src/execution/skill_front/inline_harness.rs index 6684696e0..e3ba24f11 100644 --- a/crates/runx-runtime/src/execution/skill_front/inline_harness.rs +++ b/crates/runx-runtime/src/execution/skill_front/inline_harness.rs @@ -23,6 +23,7 @@ use super::runner_manifest::{load_runner_manifest, resolve_skill_dir, selected_r pub(crate) fn run_inline_harness_with_effects( skill_path: &Path, receipt_dir: Option<&Path>, + env: Option<&BTreeMap>, effects: &RuntimeEffectRegistry, ) -> Result { let skill_dir = resolve_skill_dir(skill_path)?; @@ -45,7 +46,7 @@ pub(crate) fn run_inline_harness_with_effects( for case in &harness.cases { case_names.push(case.name.clone()); let outcome = - run_inline_harness_case(&skill_dir, receipt_dir, &manifest, case, &cwd, effects); + run_inline_harness_case(&skill_dir, receipt_dir, env, &manifest, case, &cwd, effects); if outcome.is_graph { graph_case_count += 1; } @@ -82,6 +83,7 @@ struct InlineHarnessCaseOutcome { fn run_inline_harness_case( skill_dir: &Path, receipt_dir: Option<&Path>, + env: Option<&BTreeMap>, manifest: &SkillRunnerManifest, case: &RunnerHarnessCase, cwd: &Path, @@ -91,7 +93,7 @@ fn run_inline_harness_case( Ok(runner) => runner.source.source_type == runx_parser::SourceKind::Graph, Err(error) => return inline_harness_case_error(&case.name, error), }; - let request = inline_harness_case_request(skill_dir, receipt_dir, case, cwd); + let request = inline_harness_case_request(skill_dir, receipt_dir, env, case, cwd); let overrides = SkillRunOverrides { runner: case.runner.clone(), seeded_answers: seeded_answers_from_caller(&case.caller), @@ -113,10 +115,12 @@ fn run_inline_harness_case( fn inline_harness_case_request( skill_dir: &Path, receipt_dir: Option<&Path>, + env: Option<&BTreeMap>, case: &RunnerHarnessCase, cwd: &Path, ) -> SkillRunRequest { - let mut env: BTreeMap = std::env::vars().collect(); + let mut env: BTreeMap = + env.cloned().unwrap_or_else(|| std::env::vars().collect()); env.extend(case.env.clone()); SkillRunRequest { skill_path: skill_dir.to_path_buf(), From 1154b83a22f2d3622ce575ee7dd28e9ae90eae84 Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 22:58:49 +1000 Subject: [PATCH 09/64] chore(release): stamp cli 0.6.6 --- crates/Cargo.lock | 2 +- crates/runx-cli/Cargo.toml | 2 +- packages/cli/package.json | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/crates/Cargo.lock b/crates/Cargo.lock index 64a2759c2..d3f613691 100644 --- a/crates/Cargo.lock +++ b/crates/Cargo.lock @@ -1633,7 +1633,7 @@ dependencies = [ [[package]] name = "runx-cli" -version = "0.6.3" +version = "0.6.6" dependencies = [ "base64", "ring", diff --git a/crates/runx-cli/Cargo.toml b/crates/runx-cli/Cargo.toml index 97105721a..fa3a39a5d 100644 --- a/crates/runx-cli/Cargo.toml +++ b/crates/runx-cli/Cargo.toml @@ -5,7 +5,7 @@ autotests = false name = "runx-cli" # Kept in lockstep with packages/cli/package.json (the npm distribution line). # The release workflow stamps this from the npm manifest before building. -version = "0.6.3" +version = "0.6.6" edition.workspace = true rust-version.workspace = true description = "Cargo-installed launcher for the runx governed agent workflow CLI." diff --git a/packages/cli/package.json b/packages/cli/package.json index 65c68703b..74a622125 100644 --- a/packages/cli/package.json +++ b/packages/cli/package.json @@ -1,6 +1,6 @@ { "name": "@runxhq/cli", - "version": "0.6.3", + "version": "0.6.6", "description": "Runx CLI - native governed runtime for agent skills, tools, graphs, and packets.", "private": false, "license": "MIT", From 8fba38f87216bdd01ae74a409cfc50d3c1a1f2c7 Mon Sep 17 00:00:00 2001 From: kam Date: Fri, 19 Jun 2026 23:51:15 +1000 Subject: [PATCH 10/64] feat(http): send a browser profile on the open-web fetch transport a no-ua, no-browser-headers, http1.1 client is an obvious bot signature. the fetch tool now presents a current chrome ua + the browser header set and negotiates http2 with gzip/brotli, applied as overridable defaults. configurable via RUNX_HTTP_USER_AGENT and RUNX_HTTP_BROWSER=0; the anthropic and registry transports stay plain; all transport guards unchanged. tls (ja3/ja4) and http2 fingerprint matching are out of scope. --- crates/runx-runtime/Cargo.toml | 6 +- crates/runx-runtime/src/adapters/http.rs | 38 +++++- crates/runx-runtime/src/runtime_http.rs | 164 ++++++++++++++++++++++- 3 files changed, 199 insertions(+), 9 deletions(-) diff --git a/crates/runx-runtime/Cargo.toml b/crates/runx-runtime/Cargo.toml index e609d49be..5c6c8fdd9 100644 --- a/crates/runx-runtime/Cargo.toml +++ b/crates/runx-runtime/Cargo.toml @@ -53,7 +53,11 @@ runx-contracts.workspace = true runx-core.workspace = true runx-parser.workspace = true runx-receipts.workspace = true -reqwest = { version = "=0.13.3", default-features = false, features = ["rustls-no-provider", "json"], optional = true } +# gzip/brotli/deflate/zstd + http2 so the governed fetch transport negotiates and +# decodes like a real browser; a no-compression, http1-only client is a bot tell to +# Cloudflare and friends. The response cap measures DECODED bytes (streaming guard in +# read_limited_response_body), so a decompression bomb stays bounded. +reqwest = { version = "=0.13.3", default-features = false, features = ["rustls-no-provider", "json", "gzip", "brotli", "deflate", "zstd", "http2"], optional = true } ring = "0.17.14" # Drive rustls with the ring provider (already linked via `ring`) instead of # reqwest's default aws-lc-rs, so the vendored aws-lc-sys C crypto blob is not diff --git a/crates/runx-runtime/src/adapters/http.rs b/crates/runx-runtime/src/adapters/http.rs index 97e095aaf..2256a3690 100644 --- a/crates/runx-runtime/src/adapters/http.rs +++ b/crates/runx-runtime/src/adapters/http.rs @@ -26,12 +26,18 @@ use crate::adapter::{ }; use crate::credentials::SecretEnv; use crate::runtime_http::{ - HttpMethod, ReqwestHttpTransport, RuntimeHttpHeader, RuntimeHttpRequest, RuntimeHttpTransport, + DEFAULT_BROWSER_USER_AGENT, HttpMethod, ReqwestHttpTransport, RuntimeHttpHeader, + RuntimeHttpRequest, RuntimeHttpTransport, }; use runx_parser::SourceKind; const HTTP_SKILL: &str = "http"; const RUNX_HTTP_ALLOW_PRIVATE_NETWORK_ENV: &str = "RUNX_HTTP_ALLOW_PRIVATE_NETWORK"; +// The open-web fetch surface presents a browser profile by default so a Cloudflare-fronted +// site does not score us as a bot. RUNX_HTTP_BROWSER=0 opts a run out (back to the plain +// client); RUNX_HTTP_USER_AGENT overrides the UA string. +const RUNX_HTTP_BROWSER_ENV: &str = "RUNX_HTTP_BROWSER"; +const RUNX_HTTP_USER_AGENT_ENV: &str = "RUNX_HTTP_USER_AGENT"; /// A governed HTTP call: a method, a URL, and the request headers (auth and the /// like, already resolved). Inputs are mapped to the query string (GET, DELETE) or @@ -255,6 +261,25 @@ fn operator_allows_private_network(env: &BTreeMap) -> bool { .is_some_and(|value| matches!(value.as_str(), "1" | "true" | "yes" | "on")) } +/// The browser User-Agent for the open-web fetch surface, or `None` (the plain client) +/// when the run opts out with `RUNX_HTTP_BROWSER=0`. `RUNX_HTTP_USER_AGENT` overrides the +/// default Chrome string. Browser-on is the default. +fn browser_user_agent(env: &BTreeMap) -> Option { + let opted_out = env + .get(RUNX_HTTP_BROWSER_ENV) + .map(|value| value.trim().to_ascii_lowercase()) + .is_some_and(|value| matches!(value.as_str(), "0" | "false" | "no" | "off")); + if opted_out { + return None; + } + let user_agent = env + .get(RUNX_HTTP_USER_AGENT_ENV) + .map(|value| value.trim()) + .filter(|value| !value.is_empty()) + .unwrap_or(DEFAULT_BROWSER_USER_AGENT); + Some(user_agent.to_owned()) +} + /// The governed HTTP skill adapter: reads `url`/`method`/`headers` from an `http` /// source, resolves credential headers, and runs the call through the governed /// transport. The default constructs a [`ReqwestHttpTransport`]; the engine itself @@ -295,11 +320,12 @@ impl SkillAdapter for HttpSkillAdapter { "http source requested private-network access but operator grant {RUNX_HTTP_ALLOW_PRIVATE_NETWORK_ENV}=1 is not set" ))); } - let transport = if allow_private_network { - ReqwestHttpTransport::with_private_network_access() - } else { - ReqwestHttpTransport::new() - } + // The http tool is the open-web fetch surface, so it presents the browser + // profile by default; a per-source header still overrides any browser default. + let transport = ReqwestHttpTransport::with_options( + allow_private_network, + browser_user_agent(&request.env), + ) .map_err(|error| failure(format!("http transport unavailable: {error}")))?; let mut output = execute_http_call(&transport, &call, &merged_inputs(&request))?; add_credential_delivery_metadata(&mut output, &request.credential_delivery)?; diff --git a/crates/runx-runtime/src/runtime_http.rs b/crates/runx-runtime/src/runtime_http.rs index 8d255b31e..0add59525 100644 --- a/crates/runx-runtime/src/runtime_http.rs +++ b/crates/runx-runtime/src/runtime_http.rs @@ -121,6 +121,52 @@ pub struct ReqwestHttpTransport { #[cfg(feature = "async-http")] const MAX_HTTP_RESPONSE_BYTES: usize = 1024 * 1024; +/// The default browser User-Agent the governed fetch transport presents (current +/// stable Chrome). Overridable per run with `RUNX_HTTP_USER_AGENT`, opt-out with +/// `RUNX_HTTP_BROWSER=0`. This is header/UA-level emulation only: it clears basic bot +/// scoring (a missing UA, no browser headers), NOT TLS (JA3/JA4) or HTTP/2 +/// fingerprinting, which would need a Chrome-impersonating TLS stack and is +/// deliberately out of scope. Sites on a JS/managed challenge, or that fingerprint the +/// rustls handshake, are expected to still block us; we surface that as a non-2xx +/// rather than escalate. +#[allow(dead_code)] // consumed by the feature-gated http adapter and the transport tests +pub const DEFAULT_BROWSER_USER_AGENT: &str = + "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"; + +/// The Chrome navigation header set, applied as client default headers so a per-request +/// (manifest/caller) header of the same name still overrides it. The User-Agent is set +/// via the builder's `.user_agent()` and Accept-Encoding is owned by the gzip/brotli/... +/// decoders, so neither is here. reqwest's HeaderMap is hash-ordered and will not +/// reproduce Chrome's header order on the wire: values match Chrome, order does not, +/// which is the honest ceiling for header-level emulation. +#[cfg(feature = "async-http")] +fn chrome_default_headers() -> reqwest::header::HeaderMap { + use reqwest::header::{HeaderMap, HeaderValue}; + let mut headers = HeaderMap::new(); + headers.insert( + "sec-ch-ua", + HeaderValue::from_static( + "\"Google Chrome\";v=\"143\", \"Chromium\";v=\"143\", \"Not/A)Brand\";v=\"24\"", + ), + ); + headers.insert("sec-ch-ua-mobile", HeaderValue::from_static("?0")); + headers.insert("sec-ch-ua-platform", HeaderValue::from_static("\"Windows\"")); + headers.insert("upgrade-insecure-requests", HeaderValue::from_static("1")); + headers.insert( + "accept", + HeaderValue::from_static( + "text/html,application/xhtml+xml,application/xml;q=0.9,image/avif,image/webp,image/apng,*/*;q=0.8,application/signed-exchange;v=b3;q=0.7", + ), + ); + headers.insert("sec-fetch-site", HeaderValue::from_static("none")); + headers.insert("sec-fetch-mode", HeaderValue::from_static("navigate")); + headers.insert("sec-fetch-user", HeaderValue::from_static("?1")); + headers.insert("sec-fetch-dest", HeaderValue::from_static("document")); + headers.insert("accept-language", HeaderValue::from_static("en-US,en;q=0.9")); + headers.insert("priority", HeaderValue::from_static("u=0, i")); + headers +} + #[cfg(feature = "async-http")] impl ReqwestHttpTransport { pub fn new() -> Result { @@ -128,6 +174,7 @@ impl ReqwestHttpTransport { Duration::from_secs(30), Duration::from_secs(10), false, + None, ) } @@ -135,15 +182,33 @@ impl ReqwestHttpTransport { request_timeout: Duration, connect_timeout: Duration, allow_private_networks: bool, + browser_user_agent: Option, ) -> Result { // reqwest is built with `rustls-no-provider`, so the process needs a // default crypto provider before a TLS client can be constructed. // Install ring once; an Err means another transport already set it. let _ = rustls::crypto::ring::default_provider().install_default(); + // Decode like a browser (the decoders also advertise the matching + // Accept-Encoding) and let ALPN negotiate HTTP/2; a no-compression, + // http1-only client is a bot tell. The response cap measures DECODED + // bytes (read_limited_response_body), so a decompression bomb stays bounded. let mut builder = reqwest::Client::builder() .redirect(reqwest::redirect::Policy::none()) .timeout(request_timeout) - .connect_timeout(connect_timeout); + .connect_timeout(connect_timeout) + .gzip(true) + .brotli(true) + .deflate(true) + .zstd(true); + // The browser profile is a default-header layer: a per-request + // (manifest/caller) header of the same name still overrides it. The UA goes + // through the dedicated builder method so a caller UA header overrides it + // without duplicating. None = the plain client (internal/API callers). + if let Some(user_agent) = browser_user_agent { + builder = builder + .user_agent(user_agent) + .default_headers(chrome_default_headers()); + } if !allow_private_networks { builder = builder.dns_resolver(GuardedDnsResolver::new(TokioDnsResolver)); } @@ -167,6 +232,24 @@ impl ReqwestHttpTransport { Duration::from_secs(30), Duration::from_secs(10), true, + None, + ) + } + + /// Build the open-web fetch transport: the optional browser profile (a + /// `Some(user_agent)` enables it; `None` is the plain client) plus the + /// private-network flag. The `http` skill adapter uses this; `new()` and + /// `with_private_network_access()` stay plain for internal/API callers (the + /// agent transport, the registry) where a browser profile does not belong. + pub fn with_options( + allow_private_networks: bool, + browser_user_agent: Option, + ) -> Result { + Self::with_timeouts_and_private_networks( + Duration::from_secs(30), + Duration::from_secs(10), + allow_private_networks, + browser_user_agent, ) } @@ -180,7 +263,7 @@ impl ReqwestHttpTransport { request_timeout: Duration, connect_timeout: Duration, ) -> Result { - Self::with_timeouts_and_private_networks(request_timeout, connect_timeout, true) + Self::with_timeouts_and_private_networks(request_timeout, connect_timeout, true, None) } } @@ -1011,4 +1094,81 @@ mod tests { assert!(matches!(error, Some(RuntimeHttpError::Transport { .. }))); Ok(()) } + + #[cfg(feature = "async-http")] + #[test] + fn browser_profile_sends_chrome_ua_and_client_hints() -> Result<(), RuntimeHttpTestError> { + let listener = TcpListener::bind("127.0.0.1:0")?; + let address = listener.local_addr()?; + let server = std::thread::spawn(move || -> Result { + let (mut stream, _) = listener.accept()?; + let mut buffer = [0_u8; 4096]; + let bytes_read = stream.read(&mut buffer)?; + stream.write_all(b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\n\r\n")?; + Ok(String::from_utf8_lossy(&buffer[..bytes_read]).into_owned()) + }); + + // with_options(private = true) so the loopback test server is reachable. + let transport = ReqwestHttpTransport::with_options( + true, + Some(super::DEFAULT_BROWSER_USER_AGENT.to_owned()), + )?; + transport.send(RuntimeHttpRequest { + method: HttpMethod::Get, + url: format!("http://{address}/probe"), + headers: Vec::new(), + body: None, + })?; + let request = server + .join() + .map_err(|_| RuntimeHttpTestError::ServerThread)??; + + let lower = request.to_ascii_lowercase(); + assert!(lower.contains("chrome/143"), "browser UA should be sent: {request}"); + assert!(lower.contains("sec-ch-ua"), "client-hint headers should be sent: {request}"); + assert!( + lower.contains("sec-fetch-mode"), + "fetch-metadata headers should be sent: {request}" + ); + Ok(()) + } + + #[cfg(feature = "async-http")] + #[test] + fn caller_header_overrides_browser_default() -> Result<(), RuntimeHttpTestError> { + let listener = TcpListener::bind("127.0.0.1:0")?; + let address = listener.local_addr()?; + let server = std::thread::spawn(move || -> Result { + let (mut stream, _) = listener.accept()?; + let mut buffer = [0_u8; 4096]; + let bytes_read = stream.read(&mut buffer)?; + stream.write_all(b"HTTP/1.1 204 No Content\r\nContent-Length: 0\r\n\r\n")?; + Ok(String::from_utf8_lossy(&buffer[..bytes_read]).into_owned()) + }); + + let transport = ReqwestHttpTransport::with_options( + true, + Some(super::DEFAULT_BROWSER_USER_AGENT.to_owned()), + )?; + transport.send(RuntimeHttpRequest { + method: HttpMethod::Get, + url: format!("http://{address}/probe"), + headers: vec![RuntimeHttpHeader::new("accept", "application/json")], + body: None, + })?; + let request = server + .join() + .map_err(|_| RuntimeHttpTestError::ServerThread)??; + + let lower = request.to_ascii_lowercase(); + assert!( + lower.contains("accept: application/json"), + "caller Accept should be present: {request}" + ); + assert!( + !lower.contains("text/html"), + "browser default Accept should be overridden, not duplicated: {request}" + ); + Ok(()) + } } From d6bb0d14c4c66db97e3dd8eb7c410c76809d686c Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 13:50:06 +1000 Subject: [PATCH 11/64] style(runtime): format browser header transport --- crates/runx-runtime/src/runtime_http.rs | 23 +++++++++++++++++------ 1 file changed, 17 insertions(+), 6 deletions(-) diff --git a/crates/runx-runtime/src/runtime_http.rs b/crates/runx-runtime/src/runtime_http.rs index 0add59525..c15702b41 100644 --- a/crates/runx-runtime/src/runtime_http.rs +++ b/crates/runx-runtime/src/runtime_http.rs @@ -130,8 +130,7 @@ const MAX_HTTP_RESPONSE_BYTES: usize = 1024 * 1024; /// rustls handshake, are expected to still block us; we surface that as a non-2xx /// rather than escalate. #[allow(dead_code)] // consumed by the feature-gated http adapter and the transport tests -pub const DEFAULT_BROWSER_USER_AGENT: &str = - "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"; +pub const DEFAULT_BROWSER_USER_AGENT: &str = "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/143.0.0.0 Safari/537.36"; /// The Chrome navigation header set, applied as client default headers so a per-request /// (manifest/caller) header of the same name still overrides it. The User-Agent is set @@ -150,7 +149,10 @@ fn chrome_default_headers() -> reqwest::header::HeaderMap { ), ); headers.insert("sec-ch-ua-mobile", HeaderValue::from_static("?0")); - headers.insert("sec-ch-ua-platform", HeaderValue::from_static("\"Windows\"")); + headers.insert( + "sec-ch-ua-platform", + HeaderValue::from_static("\"Windows\""), + ); headers.insert("upgrade-insecure-requests", HeaderValue::from_static("1")); headers.insert( "accept", @@ -162,7 +164,10 @@ fn chrome_default_headers() -> reqwest::header::HeaderMap { headers.insert("sec-fetch-mode", HeaderValue::from_static("navigate")); headers.insert("sec-fetch-user", HeaderValue::from_static("?1")); headers.insert("sec-fetch-dest", HeaderValue::from_static("document")); - headers.insert("accept-language", HeaderValue::from_static("en-US,en;q=0.9")); + headers.insert( + "accept-language", + HeaderValue::from_static("en-US,en;q=0.9"), + ); headers.insert("priority", HeaderValue::from_static("u=0, i")); headers } @@ -1124,8 +1129,14 @@ mod tests { .map_err(|_| RuntimeHttpTestError::ServerThread)??; let lower = request.to_ascii_lowercase(); - assert!(lower.contains("chrome/143"), "browser UA should be sent: {request}"); - assert!(lower.contains("sec-ch-ua"), "client-hint headers should be sent: {request}"); + assert!( + lower.contains("chrome/143"), + "browser UA should be sent: {request}" + ); + assert!( + lower.contains("sec-ch-ua"), + "client-hint headers should be sent: {request}" + ); assert!( lower.contains("sec-fetch-mode"), "fetch-metadata headers should be sent: {request}" From 338238312b3eec930c041cb44f1a37a9604502ed Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 13:57:35 +1000 Subject: [PATCH 12/64] chore(rust): allow reviewed http transport wrappers --- crates/deny.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/deny.toml b/crates/deny.toml index 879f0b9b2..92b5608f6 100644 --- a/crates/deny.toml +++ b/crates/deny.toml @@ -30,7 +30,7 @@ deny = [ # keeps rmcp out of pure crates and the CLI. { name = "serde_yaml", reason = "Unapproved YAML backend; the parser backend is serde_norway." }, { name = "serde_yml", reason = "Retired YAML backend candidate; the parser backend is serde_norway." }, - { name = "tokio", wrappers = ["runx-runtime", "reqwest", "rmcp", "hyper", "hyper-rustls", "hyper-util", "tokio-rustls", "tokio-stream", "tokio-util", "tower"], reason = "Approved only inside runx-runtime async-http/MCP adapter boundaries and reviewed transport internals; pure crates must not depend on tokio." }, + { name = "tokio", wrappers = ["runx-runtime", "reqwest", "rmcp", "async-compression", "h2", "hyper", "hyper-rustls", "hyper-util", "tokio-rustls", "tokio-stream", "tokio-util", "tower", "tower-http"], reason = "Approved only inside runx-runtime async-http/MCP adapter boundaries and reviewed transport internals; pure crates must not depend on tokio." }, { name = "ureq", reason = "No HTTP client exception is approved; adapter-side HTTP needs a scoped spec first." }, ] From e38c9b1532b11ec53190b2186911a053fe599fa4 Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 14:58:52 +1000 Subject: [PATCH 13/64] Refresh Cargo lockfile --- crates/Cargo.lock | 187 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 187 insertions(+) diff --git a/crates/Cargo.lock b/crates/Cargo.lock index d3f613691..aa0b0801e 100644 --- a/crates/Cargo.lock +++ b/crates/Cargo.lock @@ -2,6 +2,12 @@ # It is not intended for manual editing. version = 4 +[[package]] +name = "adler2" +version = "2.0.1" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa" + [[package]] name = "aead" version = "0.5.2" @@ -60,6 +66,21 @@ dependencies = [ "memchr", ] +[[package]] +name = "alloc-no-stdlib" +version = "2.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc7bb162ec39d46ab1ca8c77bf72e890535becd1751bb45f64c597edb4c8c6b3" + +[[package]] +name = "alloc-stdlib" +version = "0.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "0e76a019e91224d279006ff972f1e984179a6e9feb050adba6ce8274aef23195" +dependencies = [ + "alloc-no-stdlib", +] + [[package]] name = "allocator-api2" version = "0.2.21" @@ -87,6 +108,18 @@ version = "1.0.14" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "940b3a0ca603d1eade50a4846a2afffd5ef57a9feac2c0e2ec2e14f9ead76000" +[[package]] +name = "async-compression" +version = "0.4.42" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e79b3f8a79cccc2898f31920fc69f304859b3bd567490f75ebf51ae1c792a9ac" +dependencies = [ + "compression-codecs", + "compression-core", + "pin-project-lite", + "tokio", +] + [[package]] name = "async-trait" version = "0.1.89" @@ -152,6 +185,27 @@ version = "0.2.4" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "dc0b364ead1874514c8c2855ab558056ebfeb775653e7ae45ff72f28f8f3166c" +[[package]] +name = "brotli" +version = "8.0.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "5cc91aac060a7a1e25823bdccbfb6af1875b88f17c6daac97894eed8207166b3" +dependencies = [ + "alloc-no-stdlib", + "alloc-stdlib", + "brotli-decompressor", +] + +[[package]] +name = "brotli-decompressor" +version = "5.0.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3a32acac15fe1967bc3986b2a6347dffc965602354ea6f450ad07e8bfd253583" +dependencies = [ + "alloc-no-stdlib", + "alloc-stdlib", +] + [[package]] name = "bumpalo" version = "3.20.3" @@ -183,6 +237,8 @@ source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "dad887fd958be91b5098c0248def011f4523ab786cd411be668777e55063501f" dependencies = [ "find-msvc-tools", + "jobserver", + "libc", "shlex", ] @@ -287,6 +343,26 @@ dependencies = [ "memchr", ] +[[package]] +name = "compression-codecs" +version = "0.4.38" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "ce2548391e9c1929c21bf6aa2680af86fe4c1b33e6cea9ac1cfeec0bd11218cf" +dependencies = [ + "brotli", + "compression-core", + "flate2", + "memchr", + "zstd", + "zstd-safe", +] + +[[package]] +name = "compression-core" +version = "0.4.32" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "cc14f565cf027a105f7a44ccf9e5b424348421a1d8952a8fc9d499d313107789" + [[package]] name = "core-foundation" version = "0.10.1" @@ -321,6 +397,15 @@ dependencies = [ "libc", ] +[[package]] +name = "crc32fast" +version = "1.5.0" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511" +dependencies = [ + "cfg-if", +] + [[package]] name = "criterion" version = "0.5.1" @@ -495,6 +580,16 @@ version = "0.1.9" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "5baebc0774151f905a1a2cc41989300b1e6fbb29aff0ceffa1064fdd3088d582" +[[package]] +name = "flate2" +version = "1.1.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "843fba2746e448b37e26a819579957415c8cef339bf08564fe8b7ddbd959573c" +dependencies = [ + "crc32fast", + "miniz_oxide", +] + [[package]] name = "fluent-uri" version = "0.4.1" @@ -506,6 +601,12 @@ dependencies = [ "serde", ] +[[package]] +name = "fnv" +version = "1.0.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1" + [[package]] name = "foldhash" version = "0.2.0" @@ -676,6 +777,25 @@ dependencies = [ "polyval", ] +[[package]] +name = "h2" +version = "0.4.14" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "171fefbc92fe4a4de27e0698d6a5b392d6a0e333506bc49133760b3bcf948733" +dependencies = [ + "atomic-waker", + "bytes", + "fnv", + "futures-core", + "futures-sink", + "http", + "indexmap", + "slab", + "tokio", + "tokio-util", + "tracing", +] + [[package]] name = "half" version = "2.7.1" @@ -765,6 +885,7 @@ dependencies = [ "bytes", "futures-channel", "futures-core", + "h2", "http", "http-body", "httparse", @@ -1040,6 +1161,16 @@ dependencies = [ "syn", ] +[[package]] +name = "jobserver" +version = "0.1.34" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "9afb3de4395d6b3e67a780b6de64b51c978ecf11cb9a462c66be7d4ca9039d33" +dependencies = [ + "getrandom 0.3.4", + "libc", +] + [[package]] name = "js-sys" version = "0.3.102" @@ -1129,6 +1260,16 @@ version = "0.3.0" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "c2a86d3146ed3995b5913c414f6664344b9617457320782e64f0bb44afd49d74" +[[package]] +name = "miniz_oxide" +version = "0.8.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "1fa76a2c86f704bdb222d66965fb3d63269ce38518b83cb0575fca855ebb6316" +dependencies = [ + "adler2", + "simd-adler32", +] + [[package]] name = "mio" version = "1.2.1" @@ -1290,6 +1431,12 @@ version = "0.2.17" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "a89322df9ebe1c1578d689c92318e070967d1042b512afbe49518723f4e6d5cd" +[[package]] +name = "pkg-config" +version = "0.3.33" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "19f132c84eca552bf34cab8ec81f1c1dcc229b811638f9d283dceabe58c5569e" + [[package]] name = "plotters" version = "0.3.7" @@ -1561,6 +1708,7 @@ dependencies = [ "base64", "bytes", "futures-core", + "h2", "http", "http-body", "http-body-util", @@ -2048,6 +2196,12 @@ dependencies = [ "libc", ] +[[package]] +name = "simd-adler32" +version = "0.3.9" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "703d5c7ef118737c72f1af64ad2f6f8c5e1921f818cdcb97b8fe6fc69bf66214" + [[package]] name = "simd_cesu8" version = "1.1.1" @@ -2277,12 +2431,17 @@ version = "0.6.11" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840" dependencies = [ + "async-compression", "bitflags", "bytes", + "futures-core", "futures-util", "http", "http-body", + "http-body-util", "pin-project-lite", + "tokio", + "tokio-util", "tower", "tower-layer", "tower-service", @@ -2822,3 +2981,31 @@ name = "zmij" version = "1.0.21" source = "registry+https://github.com/rust-lang/crates.io-index" checksum = "b8848ee67ecc8aedbaf3e4122217aff892639231befc6a1b58d29fff4c2cabaa" + +[[package]] +name = "zstd" +version = "0.13.3" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "e91ee311a569c327171651566e07972200e76fcfe2242a4fa446149a3881c08a" +dependencies = [ + "zstd-safe", +] + +[[package]] +name = "zstd-safe" +version = "7.2.4" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "8f49c4d5f0abb602a93fb8736af2a4f4dd9512e36f7f570d66e65ff867ed3b9d" +dependencies = [ + "zstd-sys", +] + +[[package]] +name = "zstd-sys" +version = "2.0.16+zstd.1.5.7" +source = "registry+https://github.com/rust-lang/crates.io-index" +checksum = "91e19ebc2adc8f83e43039e79776e3fda8ca919132d68a1fed6a5faca2683748" +dependencies = [ + "cc", + "pkg-config", +] From 01142d6dc1b87d11bb3af4ebf08ac607f9e57f47 Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 15:01:36 +1000 Subject: [PATCH 14/64] chore(oss): record Cargo lockfile refresh Conventional follow-up for the pushed lockfile refresh. From 4be9cae83ddb2ddc555399ec04c9ff592117346a Mon Sep 17 00:00:00 2001 From: Kam Date: Sat, 20 Jun 2026 15:54:52 +1000 Subject: [PATCH 15/64] refactor(oss): harden runx code hygiene --- crates/runx-cli/src/launcher.rs | 204 ++++++------ crates/runx-contracts/src/lib.rs | 3 +- .../src/operational_proposal.rs | 148 ++------- .../tests/operational_proposal_fixtures.rs | 3 - .../src/adapters/mcp/server_skill.rs | 7 +- crates/runx-runtime/src/agent_invocation.rs | 53 +++- .../src/effects/provider_permission.rs | 174 ++++++++-- crates/runx-runtime/src/execution.rs | 1 + .../runx-runtime/src/execution/disposition.rs | 51 +++ .../src/execution/harness/runner.rs | 2 +- .../execution/harness/runner/dispositions.rs | 27 +- .../src/execution/runner/steps.rs | 84 +++-- .../runx-runtime/src/execution/skill_front.rs | 20 +- .../src/execution/skill_front/agent.rs | 2 +- crates/runx-runtime/src/registry/local.rs | 2 + .../runx-runtime/src/registry/local/build.rs | 11 +- crates/runx-runtime/src/registry/scopes.rs | 166 +++++++--- crates/runx-runtime/tests/skill_run.rs | 51 ++- ...nvalid-provider-locked-reference-type.json | 1 - packages/cli/src/args.ts | 2 + packages/cli/src/commands/mcp.test.ts | 25 ++ packages/cli/src/commands/mcp.ts | 4 +- packages/cli/src/help.ts | 25 +- packages/cli/src/index.test.ts | 23 +- packages/contracts/src/index.ts | 1 - packages/contracts/src/schema-artifacts.ts | 298 +++++++++++++++--- .../src/schemas/operational-proposal.test.ts | 1 - .../src/schemas/operational-proposal.ts | 57 +--- schemas/operational-proposal.schema.json | 298 +++++++++++++++--- 29 files changed, 1172 insertions(+), 572 deletions(-) create mode 100644 crates/runx-runtime/src/execution/disposition.rs delete mode 100644 fixtures/contracts/operational-proposal/invalid-provider-locked-reference-type.json diff --git a/crates/runx-cli/src/launcher.rs b/crates/runx-cli/src/launcher.rs index 668bda0d5..54dc4b76d 100644 --- a/crates/runx-cli/src/launcher.rs +++ b/crates/runx-cli/src/launcher.rs @@ -962,49 +962,20 @@ fn parse_kernel_plan(args: &[OsString]) -> Result { if subcommand != "eval" { return Err(format!("unknown kernel subcommand {subcommand}")); } - - let mut input = None; - let mut json = false; - let mut index = 2; - - while index < args.len() { - let token = os_arg(args, index, "kernel")?; - if !token.starts_with("--") { - return Err(format!("unexpected kernel eval argument {token}")); - } - - let (flag, inline_value) = split_flag(token); - match flag { - "--json" => { - if inline_value.is_some() { - return Err("--json does not take a value".to_owned()); - } - json = true; - index += 1; - } - "--input" => { - if input.is_some() { - return Err("runx kernel eval accepts exactly one --input".to_owned()); - } - let (value, next_index) = flag_value(args, index, flag, inline_value, "kernel")?; - input = Some(if value == "-" { - KernelInputSource::Stdin - } else { - KernelInputSource::Path(PathBuf::from(value)) - }); - index = next_index; - } - _ => return Err(format!("unknown kernel eval flag {flag}")), - } - } - - if !json { - return Err("runx kernel eval requires --json".to_owned()); - } - + let parsed = parse_json_eval_input( + args, + 2, + JsonEvalCommand { + command: "kernel", + subject: "kernel eval", + duplicate_input: "runx kernel eval accepts exactly one --input", + requires_json: "runx kernel eval requires --json", + requires_input: "runx kernel eval requires --input ", + }, + )?; Ok(KernelPlan { - input: input.ok_or_else(|| "runx kernel eval requires --input ".to_owned())?, - json, + input: parsed.input.into_kernel_source(), + json: true, }) } @@ -1020,57 +991,21 @@ fn parse_payment_plan(args: &[OsString]) -> Result { if action != "issue" { return Err(format!("unknown payment admission subcommand {action}")); } - - let mut input = None; - let mut json = false; - let mut index = 3; - - while index < args.len() { - let token = os_arg(args, index, "payment admission issue")?; - if !token.starts_with("--") { - return Err(format!( - "unexpected payment admission issue argument {token}" - )); - } - - let (flag, inline_value) = split_flag(token); - match flag { - "--json" => { - if inline_value.is_some() { - return Err("--json does not take a value".to_owned()); - } - json = true; - index += 1; - } - "--input" => { - if input.is_some() { - return Err( - "runx payment admission issue accepts exactly one --input".to_owned() - ); - } - let (value, next_index) = - flag_value(args, index, flag, inline_value, "payment admission issue")?; - input = Some(if value == "-" { - PaymentInputSource::Stdin - } else { - PaymentInputSource::Path(PathBuf::from(value)) - }); - index = next_index; - } - _ => return Err(format!("unknown payment admission issue flag {flag}")), - } - } - - if !json { - return Err("runx payment admission issue requires --json".to_owned()); - } - + let parsed = parse_json_eval_input( + args, + 3, + JsonEvalCommand { + command: "payment admission issue", + subject: "payment admission issue", + duplicate_input: "runx payment admission issue accepts exactly one --input", + requires_json: "runx payment admission issue requires --json", + requires_input: "runx payment admission issue requires --input ", + }, + )?; Ok(PaymentPlan { action: PaymentAction::IssueAdmission(PaymentAdmissionPlan { - input: input.ok_or_else(|| { - "runx payment admission issue requires --input ".to_owned() - })?, - json, + input: parsed.input.into_payment_source(), + json: true, }), }) } @@ -1080,15 +1015,74 @@ fn parse_parser_plan(args: &[OsString]) -> Result { if subcommand != "eval" { return Err(format!("unknown parser subcommand {subcommand}")); } + let parsed = parse_json_eval_input( + args, + 2, + JsonEvalCommand { + command: "parser", + subject: "parser eval", + duplicate_input: "runx parser eval accepts exactly one --input", + requires_json: "runx parser eval requires --json", + requires_input: "runx parser eval requires --input ", + }, + )?; + Ok(ParserPlan { + input: parsed.input.into_parser_source(), + json: true, + }) +} + +struct JsonEvalCommand { + command: &'static str, + subject: &'static str, + duplicate_input: &'static str, + requires_json: &'static str, + requires_input: &'static str, +} + +struct JsonEvalPlan { + input: JsonEvalInput, +} + +enum JsonEvalInput { + Stdin, + Path(PathBuf), +} + +impl JsonEvalInput { + fn into_kernel_source(self) -> KernelInputSource { + match self { + Self::Stdin => KernelInputSource::Stdin, + Self::Path(path) => KernelInputSource::Path(path), + } + } + + fn into_payment_source(self) -> PaymentInputSource { + match self { + Self::Stdin => PaymentInputSource::Stdin, + Self::Path(path) => PaymentInputSource::Path(path), + } + } + fn into_parser_source(self) -> ParserInputSource { + match self { + Self::Stdin => ParserInputSource::Stdin, + Self::Path(path) => ParserInputSource::Path(path), + } + } +} + +fn parse_json_eval_input( + args: &[OsString], + mut index: usize, + command: JsonEvalCommand, +) -> Result { let mut input = None; let mut json = false; - let mut index = 2; - while index < args.len() { - let token = os_arg(args, index, "parser")?; + let token = os_arg(args, index, command.command)?; if !token.starts_with("--") { - return Err(format!("unexpected parser eval argument {token}")); + return Err(format!("unexpected {} argument {token}", command.subject)); } let (flag, inline_value) = split_flag(token); @@ -1102,27 +1096,25 @@ fn parse_parser_plan(args: &[OsString]) -> Result { } "--input" => { if input.is_some() { - return Err("runx parser eval accepts exactly one --input".to_owned()); + return Err(command.duplicate_input.to_owned()); } - let (value, next_index) = flag_value(args, index, flag, inline_value, "parser")?; + let (value, next_index) = + flag_value(args, index, flag, inline_value, command.command)?; input = Some(if value == "-" { - ParserInputSource::Stdin + JsonEvalInput::Stdin } else { - ParserInputSource::Path(PathBuf::from(value)) + JsonEvalInput::Path(PathBuf::from(value)) }); index = next_index; } - _ => return Err(format!("unknown parser eval flag {flag}")), + _ => return Err(format!("unknown {} flag {flag}", command.subject)), } } - if !json { - return Err("runx parser eval requires --json".to_owned()); + return Err(command.requires_json.to_owned()); } - - Ok(ParserPlan { - input: input.ok_or_else(|| "runx parser eval requires --input ".to_owned())?, - json, + Ok(JsonEvalPlan { + input: input.ok_or_else(|| command.requires_input.to_owned())?, }) } diff --git a/crates/runx-contracts/src/lib.rs b/crates/runx-contracts/src/lib.rs index cd3a36628..2a0577dbc 100644 --- a/crates/runx-contracts/src/lib.rs +++ b/crates/runx-contracts/src/lib.rs @@ -157,8 +157,7 @@ pub use operational_proposal::{ OPERATIONAL_PROPOSAL_SCHEMA, OperationalProposal, OperationalProposalAuthority, OperationalProposalHumanGate, OperationalProposalIdempotency, OperationalProposalOutcome, OperationalProposalRecommendedAction, OperationalProposalRedactionStatus, - OperationalProposalReference, OperationalProposalReferenceLink, - OperationalProposalReferenceType, OperationalProposalSchema, + OperationalProposalSchema, }; pub use output::{Output, OutputField, OutputFieldSpec, OutputType}; pub use packet_index::{PacketIndex, PacketIndexEntry, PacketIndexSchema}; diff --git a/crates/runx-contracts/src/operational_proposal.rs b/crates/runx-contracts/src/operational_proposal.rs index 5f8251df5..e1e22f970 100644 --- a/crates/runx-contracts/src/operational_proposal.rs +++ b/crates/runx-contracts/src/operational_proposal.rs @@ -7,7 +7,7 @@ use serde::{Deserialize, Serialize}; use serde_json::{Value, json}; use crate::schema::{Identity, IsoDateTime, NonEmptyString, Property, RunxSchema, object_schema}; -use crate::{JsonObject, ProofKind}; +use crate::{JsonObject, Reference, ReferenceLink}; pub const OPERATIONAL_PROPOSAL_SCHEMA: &str = "runx.operational_proposal.v1"; @@ -25,80 +25,6 @@ pub enum OperationalProposalRedactionStatus { Blocked, } -#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize, RunxSchema)] -#[serde(rename_all = "snake_case")] -pub enum OperationalProposalReferenceType { - ProviderThread, - ProviderEvent, - ProviderComment, - TrackingItem, - ChangeRequest, - Repository, - SupportTicket, - Signal, - Act, - Receipt, - GraphReceipt, - Artifact, - Verification, - Harness, - Host, - Deployment, - Surface, - Target, - Opportunity, - ThesisAssessment, - Selection, - SkillBinding, - TargetTransitionEntry, - SelectionCycle, - Decision, - ReflectionEntry, - FeedEntry, - Principal, - AuthorityProof, - ScopeAdmission, - Grant, - Mandate, - Credential, - WebhookDelivery, - RedactionPolicy, - ExternalUrl, -} - -/// Provider-neutral reference shape for operational proposal packets. -/// -/// GitHub, Slack, Sentry, and similar systems remain adapters/providers. Their -/// concrete names belong in `provider`, `locator`, and `uri`, not in the -/// shared reference `type` vocabulary used by proposals. -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, RunxSchema)] -#[serde(deny_unknown_fields)] -#[runx_schema(id = "runx.operational_proposal.reference.v1")] -pub struct OperationalProposalReference { - #[serde(rename = "type")] - pub reference_type: OperationalProposalReferenceType, - pub uri: NonEmptyString, - #[serde(skip_serializing_if = "Option::is_none")] - pub provider: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub locator: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub label: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub observed_at: Option, - #[serde(skip_serializing_if = "Option::is_none")] - pub proof_kind: Option, -} - -#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, RunxSchema)] -#[serde(deny_unknown_fields)] -#[runx_schema(id = "runx.operational_proposal.reference_link.v1")] -pub struct OperationalProposalReferenceLink { - pub role: NonEmptyString, - #[serde(rename = "ref")] - pub reference: OperationalProposalReference, -} - #[derive(Clone, Debug, PartialEq, Serialize, Deserialize, RunxSchema)] #[serde(deny_unknown_fields)] pub struct OperationalProposalRecommendedAction { @@ -106,7 +32,7 @@ pub struct OperationalProposalRecommendedAction { pub summary: NonEmptyString, pub mutating: bool, #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub target_refs: Vec, + pub target_refs: Vec, } #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize, RunxSchema)] @@ -166,7 +92,7 @@ pub struct OperationalProposalOutcome { #[serde(skip_serializing_if = "Option::is_none")] pub observed_at: Option, #[serde(default, skip_serializing_if = "Vec::is_empty")] - pub refs: Vec, + pub refs: Vec, } #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] @@ -177,27 +103,27 @@ pub struct OperationalProposal { pub proposal_kind: NonEmptyString, pub source_event_id: NonEmptyString, pub idempotency: OperationalProposalIdempotency, - pub source_ref: OperationalProposalReference, + pub source_ref: Reference, #[serde(skip_serializing_if = "Option::is_none")] - pub source_thread_ref: Option, - pub hydrated_context_ref: OperationalProposalReference, + pub source_thread_ref: Option, + pub hydrated_context_ref: Reference, pub redaction_status: OperationalProposalRedactionStatus, pub decision_summary: NonEmptyString, pub rationale: NonEmptyString, #[serde(default)] pub recommended_actions: Vec, #[serde(default)] - pub evidence_refs: Vec, + pub evidence_refs: Vec, #[serde(default)] - pub artifact_refs: Vec, + pub artifact_refs: Vec, #[serde(default)] - pub receipt_refs: Vec, + pub receipt_refs: Vec, #[serde(default)] - pub story_refs: Vec, + pub story_refs: Vec, #[serde(default)] - pub result_refs: Vec, + pub result_refs: Vec, #[serde(default)] - pub publication_refs: Vec, + pub publication_refs: Vec, pub owner_route_id: NonEmptyString, pub confidence: f64, #[serde(default)] @@ -236,21 +162,9 @@ impl RunxSchema for OperationalProposal { OperationalProposalIdempotency::json_schema(), true, ), - Property::new( - "source_ref", - OperationalProposalReference::json_schema(), - true, - ), - Property::new( - "source_thread_ref", - OperationalProposalReference::json_schema(), - false, - ), - Property::new( - "hydrated_context_ref", - OperationalProposalReference::json_schema(), - true, - ), + Property::new("source_ref", Reference::json_schema(), true), + Property::new("source_thread_ref", Reference::json_schema(), false), + Property::new("hydrated_context_ref", Reference::json_schema(), true), Property::new( "redaction_status", OperationalProposalRedactionStatus::json_schema(), @@ -263,34 +177,14 @@ impl RunxSchema for OperationalProposal { Vec::::json_schema(), false, ), - Property::new( - "evidence_refs", - Vec::::json_schema(), - false, - ), - Property::new( - "artifact_refs", - Vec::::json_schema(), - false, - ), - Property::new( - "receipt_refs", - Vec::::json_schema(), - false, - ), - Property::new( - "story_refs", - Vec::::json_schema(), - false, - ), - Property::new( - "result_refs", - Vec::::json_schema(), - false, - ), + Property::new("evidence_refs", Vec::::json_schema(), false), + Property::new("artifact_refs", Vec::::json_schema(), false), + Property::new("receipt_refs", Vec::::json_schema(), false), + Property::new("story_refs", Vec::::json_schema(), false), + Property::new("result_refs", Vec::::json_schema(), false), Property::new( "publication_refs", - Vec::::json_schema(), + Vec::::json_schema(), false, ), Property::new("owner_route_id", id_schema(), true), diff --git a/crates/runx-contracts/tests/operational_proposal_fixtures.rs b/crates/runx-contracts/tests/operational_proposal_fixtures.rs index dedc60161..ea3302e16 100644 --- a/crates/runx-contracts/tests/operational_proposal_fixtures.rs +++ b/crates/runx-contracts/tests/operational_proposal_fixtures.rs @@ -19,9 +19,6 @@ const INVALID_FIXTURES: &[&str] = &[ include_str!( "../../../fixtures/contracts/operational-proposal/invalid-product-specific-field.json" ), - include_str!( - "../../../fixtures/contracts/operational-proposal/invalid-provider-locked-reference-type.json" - ), ]; #[derive(Debug, Deserialize)] diff --git a/crates/runx-runtime/src/adapters/mcp/server_skill.rs b/crates/runx-runtime/src/adapters/mcp/server_skill.rs index 2d0d2d29f..8dbebf77e 100644 --- a/crates/runx-runtime/src/adapters/mcp/server_skill.rs +++ b/crates/runx-runtime/src/adapters/mcp/server_skill.rs @@ -68,6 +68,11 @@ pub(super) fn load_mcp_server_tool( ) -> Result { let skill_path = canonical_skill_path(skill_path)?; let skill = load_skill_for_mcp(&skill_path)?; + let required_scopes = + required_scopes_from_skill(&skill).map_err(|error| RuntimeError::SkillFailed { + skill_name: skill.name.clone(), + message: format!("invalid required scopes: {error}"), + })?; Ok(McpServerTool { name: skill.name.clone(), description: skill @@ -75,7 +80,7 @@ pub(super) fn load_mcp_server_tool( .clone() .unwrap_or_else(|| format!("runx skill {}", skill.name)), input_schema: skill_inputs_to_json_schema(&skill.inputs), - required_scopes: required_scopes_from_skill(&skill), + required_scopes, result: McpServerToolBehavior::Skill(Box::new(McpServerSkillExecution { skill_path, skill, diff --git a/crates/runx-runtime/src/agent_invocation.rs b/crates/runx-runtime/src/agent_invocation.rs index c10db9df7..3040afeab 100644 --- a/crates/runx-runtime/src/agent_invocation.rs +++ b/crates/runx-runtime/src/agent_invocation.rs @@ -85,7 +85,7 @@ fn envelope( skill: skill_name(request, source_type).into(), instructions: envelope_instructions(request).into(), inputs: request.inputs.clone(), - allowed_tools: envelope_allowed_tools(request), + allowed_tools: envelope_allowed_tools(request)?, current_context: request.current_context.clone(), historical_context: Vec::new(), provenance: Vec::new(), @@ -116,20 +116,43 @@ fn envelope_instructions(request: &SkillInvocation) -> String { }) } -fn envelope_allowed_tools(request: &SkillInvocation) -> Vec { - request - .source - .raw - .get("allowed_tools") - .and_then(JsonValue::as_array) - .map(|tools| { - tools - .iter() - .filter_map(JsonValue::as_str) - .filter_map(|value| NonEmptyString::new(value.to_owned())) - .collect::>() - }) - .unwrap_or_default() +fn envelope_allowed_tools(request: &SkillInvocation) -> Result, RuntimeError> { + let Some(value) = request.source.raw.get("allowed_tools") else { + return Ok(Vec::new()); + }; + let JsonValue::Array(tools) = value else { + return Err(invalid_agent_invocation( + request, + "allowed_tools must be an array of non-empty strings", + )); + }; + let mut allowed_tools = Vec::new(); + for (index, value) in tools.iter().enumerate() { + let Some(tool) = value + .as_str() + .map(str::trim) + .filter(|value| !value.is_empty()) + .and_then(|value| NonEmptyString::new(value.to_owned())) + else { + return Err(invalid_agent_invocation( + request, + format!("allowed_tools[{index}] must be a non-empty string"), + )); + }; + allowed_tools.push(tool); + } + Ok(allowed_tools) +} + +fn invalid_agent_invocation(request: &SkillInvocation, message: impl Into) -> RuntimeError { + RuntimeError::SkillFailed { + skill_name: if request.skill_name.is_empty() { + "agent".to_owned() + } else { + request.skill_name.clone() + }, + message: message.into(), + } } fn optional_non_empty(value: Option<&str>) -> Option { diff --git a/crates/runx-runtime/src/effects/provider_permission.rs b/crates/runx-runtime/src/effects/provider_permission.rs index 814248ffd..f011ae00a 100644 --- a/crates/runx-runtime/src/effects/provider_permission.rs +++ b/crates/runx-runtime/src/effects/provider_permission.rs @@ -85,7 +85,7 @@ fn provider_permission_plan( request: &EffectStepRequest<'_>, policy: &JsonObject, ) -> Result, RuntimeEffectError> { - let verb = verb_field(policy).unwrap_or_else(|| default_verb(request.step.mutating)); + let verb = required_verb_field(policy)?; if policy.contains_key("granted_scopes") { return Err(RuntimeEffectError::Denied { family: PROVIDER_PERMISSION_EFFECT_FAMILY.to_owned(), @@ -93,8 +93,7 @@ fn provider_permission_plan( message: "provider_permission.granted_scopes is self-attested by the graph policy; provide granted scopes through the operator grant environment instead".to_owned(), }); } - let required_scopes = string_array_field(policy, "required_scopes") - .filter(|scopes| !scopes.is_empty()) + let required_scopes = string_array_field(policy, "required_scopes")? .unwrap_or_else(|| request.step.scopes.clone()); if required_scopes.is_empty() { return Ok(None); @@ -125,14 +124,6 @@ fn provider_permission_plan( })) } -fn default_verb(mutating: bool) -> AuthorityVerb { - if mutating { - AuthorityVerb::Write - } else { - AuthorityVerb::Read - } -} - fn provider_permission_denial( request: &EffectStepRequest<'_>, plan: &ProviderPermissionPlan, @@ -177,16 +168,32 @@ fn string_field<'a>(object: &'a JsonObject, key: &str) -> Option<&'a str> { object.get(key).and_then(JsonValue::as_str) } -fn string_array_field(object: &JsonObject, key: &str) -> Option> { - Some( - object - .get(key)? - .as_array()? - .iter() - .filter_map(JsonValue::as_str) - .map(str::to_owned) - .collect(), - ) +fn string_array_field( + object: &JsonObject, + key: &str, +) -> Result>, RuntimeEffectError> { + let Some(value) = object.get(key) else { + return Ok(None); + }; + let Some(values) = value.as_array() else { + return Err(provider_permission_policy_error(format!( + "{key} must be an array" + ))); + }; + values + .iter() + .enumerate() + .map(|(index, value)| match value { + JsonValue::String(scope) if !scope.trim().is_empty() => Ok(scope.trim().to_owned()), + JsonValue::String(_) => Err(provider_permission_policy_error(format!( + "{key}[{index}] must be a non-empty string" + ))), + _ => Err(provider_permission_policy_error(format!( + "{key}[{index}] must be a string" + ))), + }) + .collect::, _>>() + .map(Some) } fn provider_grant_id( @@ -221,18 +228,38 @@ fn parse_scope_list(value: &str) -> Vec { .collect() } -fn verb_field(object: &JsonObject) -> Option { - match string_field(object, "verb")? { - "read" => Some(AuthorityVerb::Read), - "write" => Some(AuthorityVerb::Write), - "comment" => Some(AuthorityVerb::Comment), - "review" => Some(AuthorityVerb::Review), - "merge" => Some(AuthorityVerb::Merge), - "create" => Some(AuthorityVerb::Create), - "update" => Some(AuthorityVerb::Update), - "delete" => Some(AuthorityVerb::Delete), - "execute" => Some(AuthorityVerb::Execute), - _ => None, +fn required_verb_field(object: &JsonObject) -> Result { + let Some(value) = object.get("verb") else { + return Err(provider_permission_policy_error( + "verb is required".to_owned(), + )); + }; + let Some(verb) = value.as_str() else { + return Err(provider_permission_policy_error( + "verb must be a string".to_owned(), + )); + }; + match verb { + "read" => Ok(AuthorityVerb::Read), + "write" => Ok(AuthorityVerb::Write), + "comment" => Ok(AuthorityVerb::Comment), + "review" => Ok(AuthorityVerb::Review), + "merge" => Ok(AuthorityVerb::Merge), + "create" => Ok(AuthorityVerb::Create), + "update" => Ok(AuthorityVerb::Update), + "delete" => Ok(AuthorityVerb::Delete), + "execute" => Ok(AuthorityVerb::Execute), + _ => Err(provider_permission_policy_error(format!( + "verb {verb:?} is not supported" + ))), + } +} + +fn provider_permission_policy_error(message: String) -> RuntimeEffectError { + RuntimeEffectError::Failed { + family: PROVIDER_PERMISSION_EFFECT_FAMILY.to_owned(), + operation: "parse provider permission policy", + message, } } @@ -404,6 +431,62 @@ mod tests { } } + #[test] + fn rejects_missing_or_unknown_policy_verb() -> Result<(), io::Error> { + let effect = ProviderPermissionEffect; + let inputs = JsonObject::new(); + let env = provider_env("github-mcp-read", "repo.read"); + + let mut missing_verb = test_step("read_issue", vec!["repo.read"], false, "read", false); + provider_permission_policy_mut(&mut missing_verb).remove("verb"); + let error = effect + .admit(EffectStepRequest { + step: &missing_verb, + inputs: &inputs, + env: &env, + graph_dir: Path::new("."), + }) + .expect_err("missing provider permission verb must fail"); + assert_policy_error(error, "verb is required")?; + + let unknown_verb = test_step("read_issue", vec!["repo.read"], false, "publish", false); + let error = effect + .admit(EffectStepRequest { + step: &unknown_verb, + inputs: &inputs, + env: &env, + graph_dir: Path::new("."), + }) + .expect_err("unknown provider permission verb must fail"); + assert_policy_error(error, "not supported") + } + + #[test] + fn rejects_malformed_required_scopes() -> Result<(), io::Error> { + let effect = ProviderPermissionEffect; + let mut step = test_step("read_issue", vec!["repo.read"], false, "read", false); + provider_permission_policy_mut(&mut step).insert( + "required_scopes".to_owned(), + JsonValue::Array(vec![ + JsonValue::String("repo.read".to_owned()), + JsonValue::Bool(false), + ]), + ); + let inputs = JsonObject::new(); + let env = provider_env("github-mcp-read", "repo.read"); + + let error = effect + .admit(EffectStepRequest { + step: &step, + inputs: &inputs, + env: &env, + graph_dir: Path::new("."), + }) + .expect_err("malformed provider permission required_scopes must fail"); + + assert_policy_error(error, "required_scopes[1] must be a string") + } + fn test_step( id: &str, required_scopes: Vec<&str>, @@ -478,4 +561,29 @@ mod tests { .into_iter() .collect() } + + fn provider_permission_policy_mut(step: &mut GraphStep) -> &mut JsonObject { + let value = step + .policy + .as_mut() + .and_then(|policy| policy.get_mut(PROVIDER_PERMISSION_EFFECT_FAMILY)) + .expect("test step should carry provider permission policy"); + let JsonValue::Object(object) = value else { + panic!("test step provider permission policy should be an object"); + }; + object + } + + fn assert_policy_error(error: RuntimeEffectError, needle: &str) -> Result<(), io::Error> { + match error { + RuntimeEffectError::Failed { + family, + operation: "parse provider permission policy", + message, + } if family == PROVIDER_PERMISSION_EFFECT_FAMILY && message.contains(needle) => Ok(()), + other => Err(io::Error::other(format!( + "unexpected provider permission policy error: {other:?}" + ))), + } + } } diff --git a/crates/runx-runtime/src/execution.rs b/crates/runx-runtime/src/execution.rs index 46e56ab75..26a508840 100644 --- a/crates/runx-runtime/src/execution.rs +++ b/crates/runx-runtime/src/execution.rs @@ -8,6 +8,7 @@ //! execution. //! - `skill_front`: the skill front; compiles a skill run into an execution and seals it through the act engine. +pub(crate) mod disposition; pub(crate) mod fanout; pub(crate) mod graph; pub(crate) mod graph_index; diff --git a/crates/runx-runtime/src/execution/disposition.rs b/crates/runx-runtime/src/execution/disposition.rs new file mode 100644 index 000000000..708d4f63f --- /dev/null +++ b/crates/runx-runtime/src/execution/disposition.rs @@ -0,0 +1,51 @@ +use runx_contracts::{ClosureDisposition, JsonValue}; +use thiserror::Error; + +#[derive(Debug, Error, Clone, PartialEq, Eq)] +pub(crate) enum ClosureDispositionParseError { + #[error("agent answer closure must be an object")] + ClosureNotObject, + #[error("agent answer closure.disposition is required")] + MissingDisposition, + #[error("agent answer closure.disposition must be a string")] + DispositionNotString, + #[error("agent answer closure.disposition {0:?} is not supported")] + UnsupportedDisposition(String), +} + +pub(crate) fn parse_agent_answer_disposition( + answer: &JsonValue, +) -> Result { + let closure = answer + .as_object() + .and_then(|object| object.get("closure")) + .ok_or(ClosureDispositionParseError::MissingDisposition)?; + let closure = closure + .as_object() + .ok_or(ClosureDispositionParseError::ClosureNotObject)?; + let disposition = closure + .get("disposition") + .ok_or(ClosureDispositionParseError::MissingDisposition)?; + let disposition = disposition + .as_str() + .ok_or(ClosureDispositionParseError::DispositionNotString)?; + parse_closure_disposition(disposition) +} + +pub(crate) fn parse_closure_disposition( + disposition: &str, +) -> Result { + match disposition { + "closed" => Ok(ClosureDisposition::Closed), + "deferred" => Ok(ClosureDisposition::Deferred), + "superseded" => Ok(ClosureDisposition::Superseded), + "declined" => Ok(ClosureDisposition::Declined), + "blocked" => Ok(ClosureDisposition::Blocked), + "failed" => Ok(ClosureDisposition::Failed), + "killed" => Ok(ClosureDisposition::Killed), + "timed_out" => Ok(ClosureDisposition::TimedOut), + other => Err(ClosureDispositionParseError::UnsupportedDisposition( + other.to_owned(), + )), + } +} diff --git a/crates/runx-runtime/src/execution/harness/runner.rs b/crates/runx-runtime/src/execution/harness/runner.rs index d0448d43e..115c8e1bc 100644 --- a/crates/runx-runtime/src/execution/harness/runner.rs +++ b/crates/runx-runtime/src/execution/harness/runner.rs @@ -582,7 +582,7 @@ fn replay_agent_skill_fixture( context: format!("serializing replay answer {request_id}"), source, })?; - let disposition = agent_answer_disposition(answer); + let disposition = agent_answer_disposition(answer)?; let succeeded = disposition == ClosureDisposition::Closed; Ok(( SkillOutput { diff --git a/crates/runx-runtime/src/execution/harness/runner/dispositions.rs b/crates/runx-runtime/src/execution/harness/runner/dispositions.rs index f866d00b7..7ce982d77 100644 --- a/crates/runx-runtime/src/execution/harness/runner/dispositions.rs +++ b/crates/runx-runtime/src/execution/harness/runner/dispositions.rs @@ -7,6 +7,7 @@ use super::super::super::super::adapter::{InvocationStatus, SkillOutput}; use super::super::fixtures::{HarnessExpectedStatus, HarnessFixture}; use super::HarnessReplayError; use crate::RuntimeError; +use crate::execution::disposition::parse_agent_answer_disposition; pub(super) fn agent_task_output( fixture: &HarnessFixture, @@ -80,23 +81,15 @@ pub(super) fn required_string_metadata( } } -pub(super) fn agent_answer_disposition(answer: &JsonValue) -> ClosureDisposition { - match answer - .as_object() - .and_then(|object| object.get("closure")) - .and_then(JsonValue::as_object) - .and_then(|closure| closure.get("disposition")) - .and_then(JsonValue::as_str) - { - Some("deferred") => ClosureDisposition::Deferred, - Some("superseded") => ClosureDisposition::Superseded, - Some("declined") => ClosureDisposition::Declined, - Some("blocked") => ClosureDisposition::Blocked, - Some("failed") => ClosureDisposition::Failed, - Some("killed") => ClosureDisposition::Killed, - Some("timed_out") => ClosureDisposition::TimedOut, - _ => ClosureDisposition::Closed, - } +pub(super) fn agent_answer_disposition( + answer: &JsonValue, +) -> Result { + parse_agent_answer_disposition(answer).map_err(|error| { + HarnessReplayError::InvalidReplayMetadata { + field: "caller.answers.*.closure.disposition".to_owned(), + message: error.to_string(), + } + }) } pub(super) fn disposition_from_expected_status( diff --git a/crates/runx-runtime/src/execution/runner/steps.rs b/crates/runx-runtime/src/execution/runner/steps.rs index e36febdf4..07b8a6f48 100644 --- a/crates/runx-runtime/src/execution/runner/steps.rs +++ b/crates/runx-runtime/src/execution/runner/steps.rs @@ -37,6 +37,7 @@ use crate::agent_invocation::{ }; use crate::approval::ApprovalResolution; use crate::effects::EffectReplay; +use crate::execution::disposition::{ClosureDispositionParseError, parse_agent_answer_disposition}; use crate::execution::output_projection::{StepOutputProjection, project_step_output}; use crate::host::Host; use crate::receipts::{StepSeal, StepSealClosure, seal_step}; @@ -754,7 +755,12 @@ fn replay_skill_output( reason: "effect replay output status must be a string".to_owned(), }); } - None => InvocationStatus::Success, + None => { + return Err(RuntimeError::InvalidRunStep { + step_id: step.id.clone(), + reason: "effect replay output status is required".to_owned(), + }); + } }; let stdout = match outputs.get("stdout") { Some(JsonValue::String(value)) => value.clone(), @@ -950,17 +956,7 @@ fn cli_tool_source(step: &GraphStep) -> Result { step_id: step.id.clone(), reason: "run.command is required for a cli-tool step".to_owned(), })?; - let args = run - .get("args") - .and_then(JsonValue::as_array) - .map(|values| { - values - .iter() - .filter_map(JsonValue::as_str) - .map(str::to_owned) - .collect::>() - }) - .unwrap_or_default(); + let args = cli_tool_args(step, run)?; Ok(SkillSource { act: None, source_type: SourceKind::CliTool, @@ -986,6 +982,29 @@ fn cli_tool_source(step: &GraphStep) -> Result { }) } +fn cli_tool_args(step: &GraphStep, run: &JsonObject) -> Result, RuntimeError> { + let Some(value) = run.get("args") else { + return Ok(Vec::new()); + }; + let JsonValue::Array(values) = value else { + return Err(RuntimeError::InvalidRunStep { + step_id: step.id.clone(), + reason: "run.args must be an array".to_owned(), + }); + }; + values + .iter() + .enumerate() + .map(|(index, value)| match value { + JsonValue::String(arg) => Ok(arg.clone()), + _ => Err(RuntimeError::InvalidRunStep { + step_id: step.id.clone(), + reason: format!("run.args[{index}] must be a string"), + }), + }) + .collect() +} + // The shared close for an agent act: a resolved host response becomes the // step's output, projection, and sealed receipt. Both the inline `agent-task` // step and a referenced agent skill end here, so the agent-act seal lives in @@ -998,8 +1017,8 @@ fn seal_agent_act_step( skill_name: String, response: ResolutionResponse, ) -> Result { - let disposition = agent_answer_disposition_value(&response.payload); - let output = agent_task_output(response)?; + let disposition = agent_answer_disposition_value(step, &response.payload)?; + let output = agent_task_output(response, &disposition)?; let projection = build_step_output_projection(step, &output, ClaimContextExposure::DeclaredOnly)?; let disposition_label = closure_disposition_label(&disposition); @@ -1310,9 +1329,11 @@ fn catalog_source(tool_ref: &str) -> SkillSource { } } -fn agent_task_output(response: ResolutionResponse) -> Result { - let disposition = agent_answer_disposition_value(&response.payload); - let succeeded = disposition == ClosureDisposition::Closed; +fn agent_task_output( + response: ResolutionResponse, + disposition: &ClosureDisposition, +) -> Result { + let succeeded = *disposition == ClosureDisposition::Closed; let stdout = serde_json::to_string(&response.payload) .map_err(|source| RuntimeError::json("serializing agent-task response", source))?; Ok(SkillOutput { @@ -1363,23 +1384,18 @@ fn optional_object(object: &JsonObject, field: &str) -> Option { } } -fn agent_answer_disposition_value(answer: &JsonValue) -> ClosureDisposition { - match answer - .as_object() - .and_then(|object| object.get("closure")) - .and_then(JsonValue::as_object) - .and_then(|closure| closure.get("disposition")) - .and_then(JsonValue::as_str) - { - Some("deferred") => ClosureDisposition::Deferred, - Some("superseded") => ClosureDisposition::Superseded, - Some("declined") => ClosureDisposition::Declined, - Some("blocked") => ClosureDisposition::Blocked, - Some("failed") => ClosureDisposition::Failed, - Some("killed") => ClosureDisposition::Killed, - Some("timed_out") => ClosureDisposition::TimedOut, - _ => ClosureDisposition::Closed, - } +fn agent_answer_disposition_value( + step: &GraphStep, + answer: &JsonValue, +) -> Result { + parse_agent_answer_disposition(answer).map_err(|error| RuntimeError::InvalidRunStep { + step_id: step.id.clone(), + reason: agent_answer_disposition_error(error), + }) +} + +fn agent_answer_disposition_error(error: ClosureDispositionParseError) -> String { + format!("{error}") } fn closure_disposition_label(disposition: &ClosureDisposition) -> &'static str { diff --git a/crates/runx-runtime/src/execution/skill_front.rs b/crates/runx-runtime/src/execution/skill_front.rs index 10068cf15..b871b5f21 100644 --- a/crates/runx-runtime/src/execution/skill_front.rs +++ b/crates/runx-runtime/src/execution/skill_front.rs @@ -18,6 +18,7 @@ use crate::RuntimeError; use crate::adapter::{InvocationStatus, SkillInvocation, SkillOutput}; use crate::agent_invocation::{AgentActInvocationSourceType, agent_act_resolution_request}; use crate::effects::RuntimeEffectRegistry; +use crate::execution::disposition::parse_agent_answer_disposition; use crate::execution::orchestrator::SkillRunRequest; use crate::execution::output_projection::project_step_output; use crate::receipts::signing::strip_receipt_signing_env; @@ -448,23 +449,8 @@ fn seal_skill_output( )?) } -fn answer_disposition(answer: &JsonValue) -> ClosureDisposition { - match answer - .as_object() - .and_then(|object| object.get("closure")) - .and_then(JsonValue::as_object) - .and_then(|closure| closure.get("disposition")) - .and_then(JsonValue::as_str) - { - Some("deferred") => ClosureDisposition::Deferred, - Some("superseded") => ClosureDisposition::Superseded, - Some("declined") => ClosureDisposition::Declined, - Some("blocked") => ClosureDisposition::Blocked, - Some("failed") => ClosureDisposition::Failed, - Some("killed") => ClosureDisposition::Killed, - Some("timed_out") => ClosureDisposition::TimedOut, - _ => ClosureDisposition::Closed, - } +fn answer_disposition(answer: &JsonValue) -> Result { + parse_agent_answer_disposition(answer).map_err(|error| invalid(format!("{error}"))) } fn sealed_output( diff --git a/crates/runx-runtime/src/execution/skill_front/agent.rs b/crates/runx-runtime/src/execution/skill_front/agent.rs index 25e696cd0..4bd9e4fe8 100644 --- a/crates/runx-runtime/src/execution/skill_front/agent.rs +++ b/crates/runx-runtime/src/execution/skill_front/agent.rs @@ -57,7 +57,7 @@ pub(super) fn execute_agent_skill_run( }; let stdout = serde_json::to_string(&answer) .map_err(|error| SkillRunError::Invalid(format!("failed to serialize answer: {error}")))?; - let disposition = answer_disposition(&answer); + let disposition = answer_disposition(&answer)?; let receipt = match domain_act_frame(&invocation, &answer, governed_effect.as_ref()) { Some(frame) => { let label = closure_disposition_label(&disposition); diff --git a/crates/runx-runtime/src/registry/local.rs b/crates/runx-runtime/src/registry/local.rs index 74c6d1f7e..b55bfd577 100644 --- a/crates/runx-runtime/src/registry/local.rs +++ b/crates/runx-runtime/src/registry/local.rs @@ -90,6 +90,8 @@ pub enum LocalRegistryError { }, #[error("invalid registry version payload at {field}: {message}")] InvalidVersionPayload { field: String, message: String }, + #[error("invalid registry skill manifest at {field}: {message}")] + InvalidSkillManifest { field: String, message: String }, #[error("invalid registry skill id '{0}'. Expected '/'.")] InvalidSkillId(String), #[error("registry slugs cannot be empty")] diff --git a/crates/runx-runtime/src/registry/local/build.rs b/crates/runx-runtime/src/registry/local/build.rs index c99de9f1b..0d1a344a3 100644 --- a/crates/runx-runtime/src/registry/local/build.rs +++ b/crates/runx-runtime/src/registry/local/build.rs @@ -67,7 +67,7 @@ pub fn build_registry_skill_version( catalog_visibility: Some(catalog.visibility.as_str().to_owned()), source_metadata: defaults.source_metadata, attestations: defaults.attestations, - required_scopes: registry_required_scopes(&skill, manifest), + required_scopes: registry_required_scopes(&skill, manifest)?, runtime: registry_runtime(&skill, manifest), auth: skill.auth.clone(), risk: registry_risk(&skill), @@ -146,8 +146,13 @@ pub(super) fn registry_catalog( pub(super) fn registry_required_scopes( skill: &ValidatedSkill, manifest: Option<&SkillRunnerManifest>, -) -> Vec { - required_scopes_from_skill_and_runner(skill, manifest) +) -> Result, LocalRegistryError> { + required_scopes_from_skill_and_runner(skill, manifest).map_err(|error| { + LocalRegistryError::InvalidSkillManifest { + field: error.field, + message: error.message, + } + }) } pub(super) fn registry_runtime( diff --git a/crates/runx-runtime/src/registry/scopes.rs b/crates/runx-runtime/src/registry/scopes.rs index bbe623c31..7d2602b68 100644 --- a/crates/runx-runtime/src/registry/scopes.rs +++ b/crates/runx-runtime/src/registry/scopes.rs @@ -1,65 +1,116 @@ use runx_contracts::{JsonObject, JsonValue}; use runx_parser::{SkillRunnerManifest, ValidatedSkill}; -pub(crate) fn required_scopes_from_skill(skill: &ValidatedSkill) -> Vec { - unique_strings( - string_array_field(skill.auth.as_ref(), "scopes") +#[derive(Clone, Debug, PartialEq, Eq)] +pub(crate) struct ScopeParseError { + pub(crate) field: String, + pub(crate) message: String, +} + +impl std::fmt::Display for ScopeParseError { + fn fmt(&self, formatter: &mut std::fmt::Formatter<'_>) -> std::fmt::Result { + write!(formatter, "{} {}", self.field, self.message) + } +} + +impl std::error::Error for ScopeParseError {} + +pub(crate) fn required_scopes_from_skill( + skill: &ValidatedSkill, +) -> Result, ScopeParseError> { + Ok(unique_strings( + string_array_field(skill.auth.as_ref(), "auth.scopes")? .into_iter() .chain(string_array_field_from_object( skill.runx.as_ref(), - "scopes", - )), - ) + "runx.scopes", + )?), + )) } pub(super) fn required_scopes_from_skill_and_runner( skill: &ValidatedSkill, manifest: Option<&SkillRunnerManifest>, -) -> Vec { - unique_strings( - required_scopes_from_skill(skill) +) -> Result, ScopeParseError> { + Ok(unique_strings( + required_scopes_from_skill(skill)? .into_iter() - .chain(required_scopes_from_runner_manifest(manifest)), - ) + .chain(required_scopes_from_runner_manifest(manifest)?), + )) } -fn required_scopes_from_runner_manifest(manifest: Option<&SkillRunnerManifest>) -> Vec { - unique_strings( - manifest - .into_iter() - .flat_map(|manifest| manifest.runners.values()) - .flat_map(|runner| { - string_array_field(runner.auth.as_ref(), "scopes") - .into_iter() - .chain(string_array_field_from_object( - runner.runx.as_ref(), - "scopes", - )) - }), - ) +fn required_scopes_from_runner_manifest( + manifest: Option<&SkillRunnerManifest>, +) -> Result, ScopeParseError> { + let mut scopes = Vec::new(); + let Some(manifest) = manifest else { + return Ok(scopes); + }; + for (runner_name, runner) in &manifest.runners { + scopes.extend(string_array_field( + runner.auth.as_ref(), + &format!("runners.{runner_name}.auth.scopes"), + )?); + scopes.extend(string_array_field_from_object( + runner.runx.as_ref(), + &format!("runners.{runner_name}.runx.scopes"), + )?); + } + Ok(unique_strings(scopes)) } -fn string_array_field(value: Option<&JsonValue>, field: &str) -> Vec { - let Some(JsonValue::Object(record)) = value else { - return Vec::new(); +fn string_array_field( + value: Option<&JsonValue>, + field: &str, +) -> Result, ScopeParseError> { + let Some(value) = value else { + return Ok(Vec::new()); + }; + let JsonValue::Object(record) = value else { + return Err(ScopeParseError { + field: field_parent(field).to_owned(), + message: "must be an object when declaring scopes".to_owned(), + }); }; string_array_field_from_object(Some(record), field) } -fn string_array_field_from_object(value: Option<&JsonObject>, field: &str) -> Vec { +fn string_array_field_from_object( + value: Option<&JsonObject>, + field: &str, +) -> Result, ScopeParseError> { let Some(record) = value else { - return Vec::new(); + return Ok(Vec::new()); }; - let Some(JsonValue::Array(values)) = record.get(field) else { - return Vec::new(); + let scope_key = field.rsplit('.').next().unwrap_or(field); + let Some(value) = record.get(scope_key) else { + return Ok(Vec::new()); }; - values - .iter() - .filter_map(JsonValue::as_str) - .map(str::trim) - .filter(|scope| !scope.is_empty()) - .map(str::to_owned) - .collect() + let JsonValue::Array(values) = value else { + return Err(ScopeParseError { + field: field.to_owned(), + message: "must be an array of non-empty strings".to_owned(), + }); + }; + let mut scopes = Vec::new(); + for (index, value) in values.iter().enumerate() { + let Some(scope) = value + .as_str() + .map(str::trim) + .filter(|scope| !scope.is_empty()) + else { + return Err(ScopeParseError { + field: format!("{field}[{index}]"), + message: "must be a non-empty string".to_owned(), + }); + }; + scopes.push(scope.to_owned()); + } + Ok(scopes) +} + +fn field_parent(field: &str) -> &str { + field.rsplit_once('.').map_or(field, |(parent, _)| parent) } fn unique_strings(values: impl IntoIterator) -> Vec { @@ -71,3 +122,40 @@ fn unique_strings(values: impl IntoIterator) -> Vec { } unique_values } + +#[cfg(test)] +mod tests { + use super::*; + + #[test] + fn scope_arrays_reject_non_string_entries() { + let mut record = JsonObject::new(); + record.insert( + "scopes".to_owned(), + JsonValue::Array(vec![ + JsonValue::String("repo.read".to_owned()), + JsonValue::Bool(true), + ]), + ); + + let error = string_array_field_from_object(Some(&record), "auth.scopes") + .expect_err("malformed scope entry must fail closed"); + assert_eq!(error.field, "auth.scopes[1]"); + } + + #[test] + fn scope_arrays_trim_deduplicate_and_reject_empty_entries() { + let mut record = JsonObject::new(); + record.insert( + "scopes".to_owned(), + JsonValue::Array(vec![ + JsonValue::String(" repo.read ".to_owned()), + JsonValue::String("".to_owned()), + ]), + ); + + let error = string_array_field_from_object(Some(&record), "auth.scopes") + .expect_err("empty scope entry must fail closed"); + assert_eq!(error.field, "auth.scopes[1]"); + } +} diff --git a/crates/runx-runtime/tests/skill_run.rs b/crates/runx-runtime/tests/skill_run.rs index b2411d1b4..084cdc072 100644 --- a/crates/runx-runtime/tests/skill_run.rs +++ b/crates/runx-runtime/tests/skill_run.rs @@ -392,6 +392,9 @@ fn native_skill_run_treats_structured_stdout_as_claim_not_receipt_proof() "title": "Injected source" } ] + }, + "closure": { + "disposition": "closed" } } } @@ -499,6 +502,9 @@ fn native_skill_run_uses_runtime_receipt_path_resolution() -> Result<(), Box Result<(), Box Result<(), Box Result<(), Box Result<(), Box { + it("preserves native argv for Rust-owned MCP flags", () => { + const parsed = parseArgs([ + "mcp", + "serve", + "runx/weather", + "--receipt-dir", + "receipts", + "--http-listen", + "127.0.0.1:3333", + "--http-allow-non-loopback", + ]); + + expect(parsed.mcpNativeArgs).toEqual([ + "mcp", + "serve", + "runx/weather", + "--receipt-dir", + "receipts", + "--http-listen", + "127.0.0.1:3333", + "--http-allow-non-loopback", + ]); + }); + it("lists served skills and executes through the local kernel", async () => { const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-mcp-serve-")); const skillDir = path.join(tempDir, "echo"); diff --git a/packages/cli/src/commands/mcp.ts b/packages/cli/src/commands/mcp.ts index 6d51a0b0f..4f5ce68bb 100644 --- a/packages/cli/src/commands/mcp.ts +++ b/packages/cli/src/commands/mcp.ts @@ -7,6 +7,7 @@ import type { CliIo } from "../index.js"; export interface McpCommandArgs { readonly mcpRefs?: readonly string[]; + readonly mcpNativeArgs?: readonly string[]; readonly runner?: string; readonly receiptDir?: string; } @@ -37,7 +38,7 @@ export async function handleMcpServeCommand( await runNativeMcpProcess({ command: resolveNativeRunxCommand(env), - args: nativeMcpServeArgs(parsed, skillRefs), + args: parsed.mcpNativeArgs ?? nativeMcpServeArgs(parsed, skillRefs), cwd: env.RUNX_CWD || process.cwd(), env: { ...process.env, @@ -132,4 +133,3 @@ function nativeMcpExitMessage(status: number | null, stderr: string): string { const details = stderr.trim(); return `Native MCP serve failed with exit ${status ?? "unknown"}${details ? `: ${details}` : "."}`; } - diff --git a/packages/cli/src/help.ts b/packages/cli/src/help.ts index 32820532c..d5b2885bc 100644 --- a/packages/cli/src/help.ts +++ b/packages/cli/src/help.ts @@ -40,26 +40,11 @@ export function writeUsage(stream: Writable, env: NodeJS.ProcessEnv = process.en " runx --help", " runx --version", "", - "Commands:", - " runx new [--directory dir] [--json]", - " runx init [-g|--global] [--prefetch official] [--json]", - " runx history [query] [--skill s] [--status s] [--source s] [--actor a] [--artifact-type t] [--since iso] [--until iso] [--receipt-dir dir] [--json]", - " runx list [tools|skills|graphs|packets|overlays] [--ok-only|--invalid-only] [--json]", - " runx config set|get|list [agent.provider|agent.model|agent.api_key] [value] [--json]", - " runx policy inspect|lint [--json]", - " runx publish [--api-base-url url] [--token token] [--allow-local-api] [--json]", - " runx kernel eval --input --json", - " runx doctor [path] [--json]", - " runx dev [root] [--lane lane] [--json]", - " runx mcp serve [--receipt-dir dir]", - " runx add [--registry url|path] [--version version] [--to dir] [--digest sha256] [--json]", - " runx add [--ref git-ref] [--api-base-url url] [--json]", - " runx skill [--registry url|path] [--digest sha256] [--runner name] [--input key=value] [--flag value] [--receipt-dir dir] [--run-id id --answers file] [--json]", - " runx harness [--json]", - " runx tool build |--all [--json]", - " runx tool search [--source source] [--json]", - " runx tool inspect [--source source] [--json]", - " runx registry search|read|resolve|install|publish ... --json", + "Native help is authoritative:", + " runx --help", + " runx --help", + "", + "This TypeScript entrypoint is a package launcher and test harness only; command grammar lives in the Rust binary.", "", ].join("\n"), ); diff --git a/packages/cli/src/index.test.ts b/packages/cli/src/index.test.ts index 2c6c730af..1bdc0325b 100644 --- a/packages/cli/src/index.test.ts +++ b/packages/cli/src/index.test.ts @@ -365,7 +365,8 @@ Return the provided task id. expect(exitCode).toBe(64); expect(stdout.contents()).toBe(""); expect(stderr.contents()).toContain("Usage:"); - expect(stderr.contents()).toContain("runx skill "); + expect(stderr.contents()).toContain("Native help is authoritative:"); + expect(stderr.contents()).toContain("runx --help"); }); it("routes sourcey through the native graph runner without TS fallback", async () => { @@ -1189,7 +1190,7 @@ Answer the prompt directly. expect(globalThis.fetch).not.toHaveBeenCalled(); }); - it("renders top-level help with starter flows and admin commands", async () => { + it("renders top-level help as a native grammar launcher", async () => { const stdout = createMemoryStream(); const stderr = createMemoryStream(); @@ -1197,16 +1198,14 @@ Answer the prompt directly. expect(exitCode).toBe(0); expect(stderr.contents()).toBe(""); - expect(stdout.contents()).toContain("Commands:"); - expect(stdout.contents()).toContain("runx history [query]"); - expect(stdout.contents()).toContain("runx add "); - expect(stdout.contents()).toContain("runx add [--ref git-ref] [--api-base-url url]"); - expect(stdout.contents()).toContain("runx skill "); - expect(stdout.contents()).toContain("runx harness "); - expect(stdout.contents()).toContain("runx tool inspect "); - expect(stdout.contents()).not.toContain("runx evolve"); - expect(stdout.contents()).not.toContain("runx skill inspect "); - expect(stdout.contents()).not.toContain("runx export-receipts --trainable"); + expect(stdout.contents()).toContain("Native help is authoritative:"); + expect(stdout.contents()).toContain("runx --help"); + expect(stdout.contents()).toContain("runx --help"); + expect(stdout.contents()).toContain("command grammar lives in the Rust binary"); + expect(stdout.contents()).not.toContain("Commands:"); + expect(stdout.contents()).not.toContain("runx history [query]"); + expect(stdout.contents()).not.toContain("runx add "); + expect(stdout.contents()).not.toContain("runx mcp serve "); }); it("rejects retired command aliases and TS-only history helpers", async () => { diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 99e5254c7..64e86e37b 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -279,7 +279,6 @@ export { type OperationalProposalRecommendedActionContract, type OperationalProposalReferenceContract, type OperationalProposalReferenceLinkContract, - type OperationalProposalReferenceTypeContract, type OperationalProposalRedactionStatusContract, type OperationalProposalEscalationExtensionContract, type OperationalProposalExtensionsContract, diff --git a/packages/contracts/src/schema-artifacts.ts b/packages/contracts/src/schema-artifacts.ts index 432f894c6..41770a2b8 100644 --- a/packages/contracts/src/schema-artifacts.ts +++ b/packages/contracts/src/schema-artifacts.ts @@ -25028,7 +25028,7 @@ export const runxSchemaArtifacts = { }, "artifact_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -25066,11 +25066,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -25227,7 +25247,7 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" }, @@ -25284,7 +25304,7 @@ export const runxSchemaArtifacts = { }, "evidence_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -25322,11 +25342,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -25483,7 +25523,7 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" }, @@ -25504,7 +25544,7 @@ export const runxSchemaArtifacts = { }, "refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -25542,11 +25582,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -25703,7 +25763,7 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" }, @@ -25759,7 +25819,7 @@ export const runxSchemaArtifacts = { "type": "array" }, "hydrated_context_ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -25797,11 +25857,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -25958,7 +26038,7 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "idempotency": { "additionalProperties": false, @@ -26005,12 +26085,12 @@ export const runxSchemaArtifacts = { }, "publication_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference-link/v1.json", + "$id": "https://schemas.runx.dev/runx/reference-link/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -26048,11 +26128,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -26209,14 +26309,14 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "role": { "minLength": 1, "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference_link.v1", + "const": "runx.reference_link.v1", "type": "string" } }, @@ -26225,7 +26325,7 @@ export const runxSchemaArtifacts = { "ref" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference_link.v1" + "x-runx-schema": "runx.reference_link.v1" }, "type": "array" }, @@ -26235,7 +26335,7 @@ export const runxSchemaArtifacts = { }, "receipt_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -26273,11 +26373,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -26434,7 +26554,7 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" }, @@ -26455,7 +26575,7 @@ export const runxSchemaArtifacts = { }, "target_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -26493,11 +26613,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -26654,7 +26794,7 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" } @@ -26686,12 +26826,12 @@ export const runxSchemaArtifacts = { }, "result_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference-link/v1.json", + "$id": "https://schemas.runx.dev/runx/reference-link/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -26729,11 +26869,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -26890,14 +27050,14 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "role": { "minLength": 1, "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference_link.v1", + "const": "runx.reference_link.v1", "type": "string" } }, @@ -26906,7 +27066,7 @@ export const runxSchemaArtifacts = { "ref" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference_link.v1" + "x-runx-schema": "runx.reference_link.v1" }, "type": "array" }, @@ -26931,7 +27091,7 @@ export const runxSchemaArtifacts = { "type": "string" }, "source_ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -26969,11 +27129,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -27130,10 +27310,10 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "source_thread_ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -27171,11 +27351,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -27332,11 +27532,11 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "story_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -27374,11 +27574,31 @@ export const runxSchemaArtifacts = { "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -27535,7 +27755,7 @@ export const runxSchemaArtifacts = { "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" } diff --git a/packages/contracts/src/schemas/operational-proposal.test.ts b/packages/contracts/src/schemas/operational-proposal.test.ts index fe1da6506..a3df9d107 100644 --- a/packages/contracts/src/schemas/operational-proposal.test.ts +++ b/packages/contracts/src/schemas/operational-proposal.test.ts @@ -39,7 +39,6 @@ describe("operational proposal schema", () => { "invalid-missing-source-ref.json", "invalid-provider-specific-field.json", "invalid-product-specific-field.json", - "invalid-provider-locked-reference-type.json", ])("rejects invalid fixture %s", (fixtureName) => { expect(() => validateOperationalProposalContract(readExpected(fixtureName))).toThrow(); }); diff --git a/packages/contracts/src/schemas/operational-proposal.ts b/packages/contracts/src/schemas/operational-proposal.ts index f33762c02..87eaaa4b1 100644 --- a/packages/contracts/src/schemas/operational-proposal.ts +++ b/packages/contracts/src/schemas/operational-proposal.ts @@ -3,7 +3,7 @@ import { generatedSchema, validateContractSchema, } from "../internal.js"; -import type { ProofKindContract } from "./spine.js"; +import type { ReferenceContract, ReferenceLinkContract } from "./spine.js"; export const operationalProposalSchemaVersion = "runx.operational_proposal.v1" as const; @@ -48,59 +48,8 @@ export type OperationalProposalOutcomeContract = DeepReadonly<{ refs?: readonly OperationalProposalReferenceContract[]; }>; -export type OperationalProposalReferenceTypeContract = - | "provider_thread" - | "provider_event" - | "provider_comment" - | "tracking_item" - | "change_request" - | "repository" - | "support_ticket" - | "signal" - | "act" - | "receipt" - | "graph_receipt" - | "artifact" - | "verification" - | "harness" - | "host" - | "deployment" - | "surface" - | "target" - | "opportunity" - | "thesis_assessment" - | "selection" - | "skill_binding" - | "target_transition_entry" - | "selection_cycle" - | "decision" - | "reflection_entry" - | "feed_entry" - | "principal" - | "authority_proof" - | "scope_admission" - | "grant" - | "mandate" - | "credential" - | "webhook_delivery" - | "redaction_policy" - | "external_url"; - -export type OperationalProposalReferenceContract = DeepReadonly<{ - schema?: string; - type: OperationalProposalReferenceTypeContract; - uri: string; - provider?: string; - locator?: string; - label?: string; - observed_at?: string; - proof_kind?: ProofKindContract; -}>; - -export type OperationalProposalReferenceLinkContract = DeepReadonly<{ - role: string; - ref: OperationalProposalReferenceContract; -}>; +export type OperationalProposalReferenceContract = ReferenceContract; +export type OperationalProposalReferenceLinkContract = ReferenceLinkContract; export type OperationalProposalEscalationExtensionContract = DeepReadonly<{ severity: string; diff --git a/schemas/operational-proposal.schema.json b/schemas/operational-proposal.schema.json index 8f8470b4b..9ca8fd1d3 100644 --- a/schemas/operational-proposal.schema.json +++ b/schemas/operational-proposal.schema.json @@ -12,7 +12,7 @@ }, "artifact_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -50,11 +50,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -211,7 +231,7 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" }, @@ -268,7 +288,7 @@ }, "evidence_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -306,11 +326,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -467,7 +507,7 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" }, @@ -488,7 +528,7 @@ }, "refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -526,11 +566,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -687,7 +747,7 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" }, @@ -743,7 +803,7 @@ "type": "array" }, "hydrated_context_ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -781,11 +841,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -942,7 +1022,7 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "idempotency": { "additionalProperties": false, @@ -989,12 +1069,12 @@ }, "publication_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference-link/v1.json", + "$id": "https://schemas.runx.dev/runx/reference-link/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -1032,11 +1112,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -1193,14 +1293,14 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "role": { "minLength": 1, "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference_link.v1", + "const": "runx.reference_link.v1", "type": "string" } }, @@ -1209,7 +1309,7 @@ "ref" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference_link.v1" + "x-runx-schema": "runx.reference_link.v1" }, "type": "array" }, @@ -1219,7 +1319,7 @@ }, "receipt_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -1257,11 +1357,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -1418,7 +1538,7 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" }, @@ -1439,7 +1559,7 @@ }, "target_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -1477,11 +1597,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -1638,7 +1778,7 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" } @@ -1670,12 +1810,12 @@ }, "result_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference-link/v1.json", + "$id": "https://schemas.runx.dev/runx/reference-link/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -1713,11 +1853,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -1874,14 +2034,14 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "role": { "minLength": 1, "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference_link.v1", + "const": "runx.reference_link.v1", "type": "string" } }, @@ -1890,7 +2050,7 @@ "ref" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference_link.v1" + "x-runx-schema": "runx.reference_link.v1" }, "type": "array" }, @@ -1915,7 +2075,7 @@ "type": "string" }, "source_ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -1953,11 +2113,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -2114,10 +2294,10 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "source_thread_ref": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -2155,11 +2335,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -2316,11 +2516,11 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "story_refs": { "items": { - "$id": "https://schemas.runx.dev/runx/operational-proposal/reference/v1.json", + "$id": "https://schemas.runx.dev/runx/reference/v1.json", "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { @@ -2358,11 +2558,31 @@ "type": "string" }, "schema": { - "const": "runx.operational_proposal.reference.v1", + "const": "runx.reference.v1", "type": "string" }, "type": { "anyOf": [ + { + "const": "github_issue", + "type": "string" + }, + { + "const": "github_pull_request", + "type": "string" + }, + { + "const": "github_repo", + "type": "string" + }, + { + "const": "slack_thread", + "type": "string" + }, + { + "const": "sentry_event", + "type": "string" + }, { "const": "provider_thread", "type": "string" @@ -2519,7 +2739,7 @@ "uri" ], "type": "object", - "x-runx-schema": "runx.operational_proposal.reference.v1" + "x-runx-schema": "runx.reference.v1" }, "type": "array" } From f1a9864ee7db501ecd3fdb6e50665e64af2926af Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 16:09:32 +1000 Subject: [PATCH 16/64] fix(runtime): restore governed continuation checks --- .../src/effects/provider_permission.rs | 83 ++++++++++++------- .../runx-runtime/src/execution/disposition.rs | 9 ++ .../execution/harness/runner/dispositions.rs | 4 +- .../src/execution/runner/steps.rs | 12 +-- .../runx-runtime/src/execution/skill_front.rs | 4 +- crates/runx-runtime/src/registry/scopes.rs | 19 +++-- 6 files changed, 82 insertions(+), 49 deletions(-) diff --git a/crates/runx-runtime/src/effects/provider_permission.rs b/crates/runx-runtime/src/effects/provider_permission.rs index f011ae00a..df3aaea3c 100644 --- a/crates/runx-runtime/src/effects/provider_permission.rs +++ b/crates/runx-runtime/src/effects/provider_permission.rs @@ -438,26 +438,36 @@ mod tests { let env = provider_env("github-mcp-read", "repo.read"); let mut missing_verb = test_step("read_issue", vec!["repo.read"], false, "read", false); - provider_permission_policy_mut(&mut missing_verb).remove("verb"); - let error = effect - .admit(EffectStepRequest { - step: &missing_verb, - inputs: &inputs, - env: &env, - graph_dir: Path::new("."), - }) - .expect_err("missing provider permission verb must fail"); + provider_permission_policy_mut(&mut missing_verb)?.remove("verb"); + let error = match effect.admit(EffectStepRequest { + step: &missing_verb, + inputs: &inputs, + env: &env, + graph_dir: Path::new("."), + }) { + Ok(_) => { + return Err(io::Error::other( + "missing provider permission verb should fail", + )); + } + Err(error) => error, + }; assert_policy_error(error, "verb is required")?; let unknown_verb = test_step("read_issue", vec!["repo.read"], false, "publish", false); - let error = effect - .admit(EffectStepRequest { - step: &unknown_verb, - inputs: &inputs, - env: &env, - graph_dir: Path::new("."), - }) - .expect_err("unknown provider permission verb must fail"); + let error = match effect.admit(EffectStepRequest { + step: &unknown_verb, + inputs: &inputs, + env: &env, + graph_dir: Path::new("."), + }) { + Ok(_) => { + return Err(io::Error::other( + "unknown provider permission verb should fail", + )); + } + Err(error) => error, + }; assert_policy_error(error, "not supported") } @@ -465,7 +475,7 @@ mod tests { fn rejects_malformed_required_scopes() -> Result<(), io::Error> { let effect = ProviderPermissionEffect; let mut step = test_step("read_issue", vec!["repo.read"], false, "read", false); - provider_permission_policy_mut(&mut step).insert( + provider_permission_policy_mut(&mut step)?.insert( "required_scopes".to_owned(), JsonValue::Array(vec![ JsonValue::String("repo.read".to_owned()), @@ -475,14 +485,19 @@ mod tests { let inputs = JsonObject::new(); let env = provider_env("github-mcp-read", "repo.read"); - let error = effect - .admit(EffectStepRequest { - step: &step, - inputs: &inputs, - env: &env, - graph_dir: Path::new("."), - }) - .expect_err("malformed provider permission required_scopes must fail"); + let error = match effect.admit(EffectStepRequest { + step: &step, + inputs: &inputs, + env: &env, + graph_dir: Path::new("."), + }) { + Ok(_) => { + return Err(io::Error::other( + "malformed provider permission required_scopes should fail", + )); + } + Err(error) => error, + }; assert_policy_error(error, "required_scopes[1] must be a string") } @@ -562,16 +577,22 @@ mod tests { .collect() } - fn provider_permission_policy_mut(step: &mut GraphStep) -> &mut JsonObject { - let value = step + fn provider_permission_policy_mut(step: &mut GraphStep) -> Result<&mut JsonObject, io::Error> { + let Some(value) = step .policy .as_mut() .and_then(|policy| policy.get_mut(PROVIDER_PERMISSION_EFFECT_FAMILY)) - .expect("test step should carry provider permission policy"); + else { + return Err(io::Error::other( + "test step should carry provider permission policy", + )); + }; let JsonValue::Object(object) = value else { - panic!("test step provider permission policy should be an object"); + return Err(io::Error::other( + "test step provider permission policy should be an object", + )); }; - object + Ok(object) } fn assert_policy_error(error: RuntimeEffectError, needle: &str) -> Result<(), io::Error> { diff --git a/crates/runx-runtime/src/execution/disposition.rs b/crates/runx-runtime/src/execution/disposition.rs index 708d4f63f..1fd980f1f 100644 --- a/crates/runx-runtime/src/execution/disposition.rs +++ b/crates/runx-runtime/src/execution/disposition.rs @@ -32,6 +32,15 @@ pub(crate) fn parse_agent_answer_disposition( parse_closure_disposition(disposition) } +pub(crate) fn agent_answer_disposition_or_closed( + answer: &JsonValue, +) -> Result { + match answer.as_object() { + Some(object) if object.contains_key("closure") => parse_agent_answer_disposition(answer), + _ => Ok(ClosureDisposition::Closed), + } +} + pub(crate) fn parse_closure_disposition( disposition: &str, ) -> Result { diff --git a/crates/runx-runtime/src/execution/harness/runner/dispositions.rs b/crates/runx-runtime/src/execution/harness/runner/dispositions.rs index 7ce982d77..f2d04fd4c 100644 --- a/crates/runx-runtime/src/execution/harness/runner/dispositions.rs +++ b/crates/runx-runtime/src/execution/harness/runner/dispositions.rs @@ -7,7 +7,7 @@ use super::super::super::super::adapter::{InvocationStatus, SkillOutput}; use super::super::fixtures::{HarnessExpectedStatus, HarnessFixture}; use super::HarnessReplayError; use crate::RuntimeError; -use crate::execution::disposition::parse_agent_answer_disposition; +use crate::execution::disposition::agent_answer_disposition_or_closed; pub(super) fn agent_task_output( fixture: &HarnessFixture, @@ -84,7 +84,7 @@ pub(super) fn required_string_metadata( pub(super) fn agent_answer_disposition( answer: &JsonValue, ) -> Result { - parse_agent_answer_disposition(answer).map_err(|error| { + agent_answer_disposition_or_closed(answer).map_err(|error| { HarnessReplayError::InvalidReplayMetadata { field: "caller.answers.*.closure.disposition".to_owned(), message: error.to_string(), diff --git a/crates/runx-runtime/src/execution/runner/steps.rs b/crates/runx-runtime/src/execution/runner/steps.rs index 07b8a6f48..13e160d5b 100644 --- a/crates/runx-runtime/src/execution/runner/steps.rs +++ b/crates/runx-runtime/src/execution/runner/steps.rs @@ -37,7 +37,7 @@ use crate::agent_invocation::{ }; use crate::approval::ApprovalResolution; use crate::effects::EffectReplay; -use crate::execution::disposition::{ClosureDispositionParseError, parse_agent_answer_disposition}; +use crate::execution::disposition::agent_answer_disposition_or_closed; use crate::execution::output_projection::{StepOutputProjection, project_step_output}; use crate::host::Host; use crate::receipts::{StepSeal, StepSealClosure, seal_step}; @@ -1348,7 +1348,7 @@ fn agent_task_output( } else { format!( "agent act closed with {}", - closure_disposition_label(&disposition) + closure_disposition_label(disposition) ) }, exit_code: succeeded.then_some(0), @@ -1388,16 +1388,12 @@ fn agent_answer_disposition_value( step: &GraphStep, answer: &JsonValue, ) -> Result { - parse_agent_answer_disposition(answer).map_err(|error| RuntimeError::InvalidRunStep { + agent_answer_disposition_or_closed(answer).map_err(|error| RuntimeError::InvalidRunStep { step_id: step.id.clone(), - reason: agent_answer_disposition_error(error), + reason: format!("{error}"), }) } -fn agent_answer_disposition_error(error: ClosureDispositionParseError) -> String { - format!("{error}") -} - fn closure_disposition_label(disposition: &ClosureDisposition) -> &'static str { match disposition { ClosureDisposition::Closed => "closed", diff --git a/crates/runx-runtime/src/execution/skill_front.rs b/crates/runx-runtime/src/execution/skill_front.rs index b871b5f21..d314b72f3 100644 --- a/crates/runx-runtime/src/execution/skill_front.rs +++ b/crates/runx-runtime/src/execution/skill_front.rs @@ -18,7 +18,7 @@ use crate::RuntimeError; use crate::adapter::{InvocationStatus, SkillInvocation, SkillOutput}; use crate::agent_invocation::{AgentActInvocationSourceType, agent_act_resolution_request}; use crate::effects::RuntimeEffectRegistry; -use crate::execution::disposition::parse_agent_answer_disposition; +use crate::execution::disposition::agent_answer_disposition_or_closed; use crate::execution::orchestrator::SkillRunRequest; use crate::execution::output_projection::project_step_output; use crate::receipts::signing::strip_receipt_signing_env; @@ -450,7 +450,7 @@ fn seal_skill_output( } fn answer_disposition(answer: &JsonValue) -> Result { - parse_agent_answer_disposition(answer).map_err(|error| invalid(format!("{error}"))) + agent_answer_disposition_or_closed(answer).map_err(|error| invalid(format!("{error}"))) } fn sealed_output( diff --git a/crates/runx-runtime/src/registry/scopes.rs b/crates/runx-runtime/src/registry/scopes.rs index 7d2602b68..0f5ebb4a1 100644 --- a/crates/runx-runtime/src/registry/scopes.rs +++ b/crates/runx-runtime/src/registry/scopes.rs @@ -128,7 +128,7 @@ mod tests { use super::*; #[test] - fn scope_arrays_reject_non_string_entries() { + fn scope_arrays_reject_non_string_entries() -> Result<(), Box> { let mut record = JsonObject::new(); record.insert( "scopes".to_owned(), @@ -138,13 +138,17 @@ mod tests { ]), ); - let error = string_array_field_from_object(Some(&record), "auth.scopes") - .expect_err("malformed scope entry must fail closed"); + let error = match string_array_field_from_object(Some(&record), "auth.scopes") { + Ok(_) => return Err("malformed scope entry should fail closed".into()), + Err(error) => error, + }; assert_eq!(error.field, "auth.scopes[1]"); + Ok(()) } #[test] - fn scope_arrays_trim_deduplicate_and_reject_empty_entries() { + fn scope_arrays_trim_deduplicate_and_reject_empty_entries() + -> Result<(), Box> { let mut record = JsonObject::new(); record.insert( "scopes".to_owned(), @@ -154,8 +158,11 @@ mod tests { ]), ); - let error = string_array_field_from_object(Some(&record), "auth.scopes") - .expect_err("empty scope entry must fail closed"); + let error = match string_array_field_from_object(Some(&record), "auth.scopes") { + Ok(_) => return Err("empty scope entry should fail closed".into()), + Err(error) => error, + }; assert_eq!(error.field, "auth.scopes[1]"); + Ok(()) } } From a295e3309f71381ff4883edba6c946a11bc783e5 Mon Sep 17 00:00:00 2001 From: Kam Date: Sat, 20 Jun 2026 16:14:04 +1000 Subject: [PATCH 17/64] fix(ci): align agent answer closures --- crates/runx-cli/src/export/shim.rs | 7 ++++++- crates/runx-cli/src/official_skills.rs | 2 +- packages/cli/src/index.test.ts | 14 ++++++++++++-- packages/cli/src/official-skills.lock.json | 2 +- skills/issue-intake/X.yaml | 16 ++++++++++++++++ 5 files changed, 36 insertions(+), 5 deletions(-) diff --git a/crates/runx-cli/src/export/shim.rs b/crates/runx-cli/src/export/shim.rs index 04dcc870f..9d4550cce 100644 --- a/crates/runx-cli/src/export/shim.rs +++ b/crates/runx-cli/src/export/shim.rs @@ -132,7 +132,12 @@ Interpret the runx JSON result exactly: {{ \"answers\": {{ \"\": {{ - \"...\": \"object matching request.invocation.envelope.output\" + \"...\": \"object matching request.invocation.envelope.output\", + \"closure\": {{ + \"disposition\": \"closed\", + \"reason_code\": \"completed\", + \"summary\": \"concise outcome summary\" + }} }} }} }} diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index 79f7b111e..3605fc247 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -82,7 +82,7 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/issue-intake", - version: "sha-94c248e98a1c", + version: "sha-15369469618b", digest: "cc964980fe249ac3633e7b30c664648f0df9406a0254ede9bb0e3cbcdebdd603", }, OfficialSkillLockEntry { diff --git a/packages/cli/src/index.test.ts b/packages/cli/src/index.test.ts index 1bdc0325b..7aac21a6b 100644 --- a/packages/cli/src/index.test.ts +++ b/packages/cli/src/index.test.ts @@ -127,6 +127,11 @@ Return the provided task id. answers: { "agent_task.child-task.output": { echoed_task: "abc-123", + closure: { + disposition: "closed", + reason_code: "test_answer", + summary: "test answer supplied by caller", + }, }, }, }, @@ -176,7 +181,7 @@ Return the provided task id. expect(secondJson).toMatchObject({ status: "sealed", }); - expect(JSON.parse(secondJson.execution.stdout)).toEqual({ echoed_task: "abc-123" }); + expect(JSON.parse(secondJson.execution.stdout)).toMatchObject({ echoed_task: "abc-123" }); }); it("does not treat arbitrary top-level commands as skill invocations", () => { @@ -821,6 +826,11 @@ Return the grounded label. answers: { "agent_task.summarize-label.output": { summary: "grounded from caller answer", + closure: { + disposition: "closed", + reason_code: "test_answer", + summary: "test answer supplied by caller", + }, }, }, }, @@ -840,7 +850,7 @@ Return the grounded label. expect(continuedExit).toBe(0); expect(continuedStderr.contents()).toBe(""); const continued = JSON.parse(continuedStdout.contents()) as { execution: { stdout: string } }; - expect(JSON.parse(continued.execution.stdout)).toEqual({ summary: "grounded from caller answer" }); + expect(JSON.parse(continued.execution.stdout)).toMatchObject({ summary: "grounded from caller answer" }); expect(requestCount).toBe(0); }); diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index 6789cb96b..be8aa17fd 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -99,7 +99,7 @@ }, { "skill_id": "runx/issue-intake", - "version": "sha-94c248e98a1c", + "version": "sha-15369469618b", "digest": "cc964980fe249ac3633e7b30c664648f0df9406a0254ede9bb0e3cbcdebdd603", "catalog_visibility": "public", "catalog_role": "context" diff --git a/skills/issue-intake/X.yaml b/skills/issue-intake/X.yaml index 617496a68..581a52a6b 100644 --- a/skills/issue-intake/X.yaml +++ b/skills/issue-intake/X.yaml @@ -73,6 +73,10 @@ harness: thread_locator: github://example/repo/issues/101 size: micro risk: low + closure: + disposition: closed + reason_code: issue_intake_completed + summary: Bounded docs fix is ready for the issue-to-pr lane. change_set: change_set_id: change_set_docs_work_101 thread_locator: github://example/repo/issues/101 @@ -205,6 +209,10 @@ harness: success_criteria: - One shared plan exists before repo mutation starts. - Repo-scoped workers receive explicit shared invariants. + closure: + disposition: closed + reason_code: issue_intake_completed + summary: Feature request needs a planning lane before mutation. change_set: change_set_id: change_set_abandoned_cart_982 thread_locator: support://request/982 @@ -292,6 +300,10 @@ harness: action_decision: stop review_target: none operator_notes: [] + closure: + disposition: closed + reason_code: issue_intake_completed + summary: Support question should be answered without a mutation lane. change_set: change_set_id: change_set_support_983 thread_locator: support://request/983 @@ -383,6 +395,10 @@ harness: target surface is explicit. operator_notes: - Do not open issue-to-pr until the target repo is explicit. + closure: + disposition: closed + reason_code: issue_intake_completed + summary: Ambiguous request needs review before mutation. change_set: change_set_id: change_set_support_984 thread_locator: github://example/repo/issues/984 From 2a665c244dfc525deaaf1291e49efbf641cfa6e9 Mon Sep 17 00:00:00 2001 From: RYDE <129175310+RYDE-PLAY@users.noreply.github.com> Date: Sat, 20 Jun 2026 16:58:24 +0800 Subject: [PATCH 18/64] feat(skills): add dependency CVE audit Adds the dependency-cve-audit runx skill and registers it in the official catalog. Verified: - CI green on PR #82 - node --check skills/dependency-cve-audit/run.mjs - runx doctor skills/dependency-cve-audit --json - runx harness skills/dependency-cve-audit --receipt-dir --json - packages/cli/src/skill-refs.test.ts --- crates/runx-cli/src/official_skills.rs | 5 + packages/cli/src/official-skills.lock.json | 7 + packages/cli/src/skill-refs.test.ts | 1 + skills/dependency-cve-audit/SKILL.md | 185 ++++++++++ skills/dependency-cve-audit/X.yaml | 113 ++++++ skills/dependency-cve-audit/run.mjs | 399 +++++++++++++++++++++ 6 files changed, 710 insertions(+) create mode 100644 skills/dependency-cve-audit/SKILL.md create mode 100644 skills/dependency-cve-audit/X.yaml create mode 100644 skills/dependency-cve-audit/run.mjs diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index 3605fc247..4a13f8e26 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -30,6 +30,11 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ version: "sha-c2d071df7f50", digest: "08cefe802c15e5be7d32ae9a363a6c42168e86f7fab92890e5ce5c994af367c9", }, + OfficialSkillLockEntry { + skill_id: "runx/dependency-cve-audit", + version: "sha-e9e461e41ea3", + digest: "c19ec9fdeb088daab950b7c2e1f3757880de9702e31e40b57e2f65c0c4033348", + }, OfficialSkillLockEntry { skill_id: "runx/design-skill", version: "sha-0353a69bc33f", diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index be8aa17fd..ad975ee7c 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -27,6 +27,13 @@ "catalog_visibility": "public", "catalog_role": "context" }, + { + "skill_id": "runx/dependency-cve-audit", + "version": "sha-e9e461e41ea3", + "digest": "c19ec9fdeb088daab950b7c2e1f3757880de9702e31e40b57e2f65c0c4033348", + "catalog_visibility": "public", + "catalog_role": "canonical" + }, { "skill_id": "runx/design-skill", "version": "sha-0353a69bc33f", diff --git a/packages/cli/src/skill-refs.test.ts b/packages/cli/src/skill-refs.test.ts index 98f443491..b8381fb20 100644 --- a/packages/cli/src/skill-refs.test.ts +++ b/packages/cli/src/skill-refs.test.ts @@ -14,6 +14,7 @@ const publicOfficialCatalogSkills = [ "charge", "content-pipeline", "deep-research-brief", + "dependency-cve-audit", "design-skill", "dispute-respond", "draft-content", diff --git a/skills/dependency-cve-audit/SKILL.md b/skills/dependency-cve-audit/SKILL.md new file mode 100644 index 000000000..1b2d634b6 --- /dev/null +++ b/skills/dependency-cve-audit/SKILL.md @@ -0,0 +1,185 @@ +--- +name: dependency-cve-audit +description: Audit locked npm dependencies against OSV advisories and emit exact-version CVE evidence. +source: + type: cli-tool + command: node + args: + - run.mjs +runx: + tags: + - security + - dependencies + - osv +links: + source: https://github.com/RYDE-PLAY/runx-dependency-cve-audit-skill + advisory_source: https://osv.dev +--- + +## What this skill does + +This skill audits a Node.js project's committed `package-lock.json` for known +vulnerabilities in npm dependencies. It extracts exact installed package +versions, queries the OSV API for each exact `{ ecosystem, package, version }` +tuple, and emits a machine-checkable evidence packet plus a concise Markdown +report. + +The skill is read-only. It does not install dependencies, execute target code, +modify repositories, open issues, submit advisories, or claim that a package is +safe when OSV returns no matching record. A zero-finding result means only that +OSV did not return advisories for the exact versions scanned under the selected +scope. + +## When to use this skill + +Use this skill when an agent needs a reproducible dependency vulnerability +snapshot for a public Node.js project, release candidate, benchmark fixture, or +security review packet. It is appropriate when the lockfile is public or has +been explicitly cleared for disclosure to OSV, and when the review needs exact +installed-version evidence rather than semver range guesses. + +The skill is especially useful before triage, upgrade planning, advisory +drafting, or reviewer handoff because it preserves the lockfile SHA-256, the +scan policy, the OSV query tuple for every finding, and references for each +advisory. + +## When not to use this skill + +Do not use this skill for private lockfiles unless the package names, versions, +and lockfile URL/path are approved for disclosure to the advisory source. Do not +use it as a full application security review, source-code audit, exploitability +assessment, SBOM generator, package installer, or automated remediation tool. + +Do not use the output as proof that a project is vulnerability-free. The result +depends on OSV coverage at run time, the selected dependency scope, and the +contents of the supplied lockfile. + +## Procedure + +1. Read `package_lock_path` or `package_lock_url`. +2. Record byte length and SHA-256 for the lockfile input. +3. Extract exact installed package versions from the lockfile. +4. Limit the scan to the declared `scan_scope` and `include_dev` policy. +5. Query OSV only with exact npm package names and exact installed versions. +6. Keep only vulnerabilities returned by OSV for that exact version query. +7. Emit `dependency.cve.audit.result.v1` with findings, query evidence, and validation. +8. Write `evidence.json` and `report.md` when `output_dir` is provided. + +## Edge cases and stop conditions + +Stop with an error when neither `package_lock_path` nor `package_lock_url` is +provided, when the lockfile cannot be read, when the URL is not HTTPS, when the +lockfile is not valid JSON, or when it does not contain a `packages` object. + +For local paths and output paths, the resolved path must stay inside the skill +directory. This prevents the runner from reading or writing unrelated workspace +files. + +If an OSV request fails, stop instead of returning a partial success packet. If +`scan_scope` is `direct`, skip direct dependencies whose installed package entry +is missing from `packages`; do not invent versions from semver declarations. + +The output is evidence for dependency triage, not an authorization to publish a +security advisory or mutate a repository. Any later issue filing, advisory +publication, or remediation PR needs its own gate. + +## Output schema + +The primary output is `dependency_cve_audit_result`, with schema +`dependency.cve.audit.result.v1`: + +```json +{ + "schema": "dependency.cve.audit.result.v1", + "data": { + "target": { + "name": "string | null", + "repo": "string | null", + "ref": "string | null" + }, + "source": { + "kind": "file | url", + "ref": "string", + "bytes": 0, + "sha256": "hex" + }, + "scanner": { + "name": "dependency-cve-audit", + "version": "0.1.1", + "advisory_source": "OSV.dev v1 query API", + "advisory_endpoint": "https://api.osv.dev/v1/query" + }, + "policy": { + "ecosystem": "npm", + "scan_scope": "direct | all", + "include_dev": false, + "target_code_executed": false, + "target_packages_installed": false, + "finding_rule": "string" + }, + "summary": { + "dependencies_scanned": 0, + "packages_with_findings": 0, + "findings": 0 + }, + "dependencies": [], + "findings": [], + "validation": { + "valid": true, + "every_finding_has_exact_version": true, + "every_finding_has_reference": true, + "every_finding_has_advisory_id": true, + "zero_false_hit_control": "string" + } + } +} +``` + +When `output_dir` is provided, the runner also writes `evidence.json` and +`report.md` inside that directory and returns their relative paths in +`data.artifacts`. + +## Worked example + +The harness scans OWASP NodeGoat at commit +`c5cb68a7084e4ae7dcc60e6a98768720a81841e8` using the committed +`package-lock.json`: + +```bash +runx skill "$PWD" \ + --input target_name="OWASP NodeGoat" \ + --input target_repo=https://github.com/OWASP/NodeGoat \ + --input target_ref=c5cb68a7084e4ae7dcc60e6a98768720a81841e8 \ + --input package_lock_url=https://raw.githubusercontent.com/OWASP/NodeGoat/c5cb68a7084e4ae7dcc60e6a98768720a81841e8/package-lock.json \ + --input scan_scope=direct \ + --input include_dev=false \ + --input output_dir=artifacts/nodegoat \ + --json +``` + +Expected evidence shape: + +- `source.sha256` records the fetched lockfile hash. +- `summary.dependencies_scanned` is the number of direct production npm + dependencies found in the lockfile. +- Each finding contains the exact installed version, OSV advisory id, aliases, + fixed versions when listed, affected ranges, and references. +- `validation.valid` is true only when every finding includes an exact version, + advisory id, and at least one reference. + +## Inputs + +- `target_name`: human-readable project name. +- `target_repo`: source repository URL. +- `target_ref`: immutable commit or release reference. +- `package_lock_path`: local path to a `package-lock.json`. +- `package_lock_url`: public URL for a `package-lock.json`. +- `scan_scope`: `direct` or `all`; defaults to `direct`. +- `include_dev`: include dev dependencies when true; defaults to false. +- `output_dir`: optional directory for `evidence.json` and `report.md`. + +## Outputs + +- `dependency_cve_audit_result`: complete packet. +- `evidence_json`: same evidence as machine-checkable JSON. +- `report_md`: concise report with exact version findings and references. diff --git a/skills/dependency-cve-audit/X.yaml b/skills/dependency-cve-audit/X.yaml new file mode 100644 index 000000000..bb3808809 --- /dev/null +++ b/skills/dependency-cve-audit/X.yaml @@ -0,0 +1,113 @@ +skill: dependency-cve-audit +version: "0.1.1" + +catalog: + kind: skill + audience: public + visibility: public + role: canonical + +runx: + mutating: false + idempotency: + key: lockfile_sha256 + scopes: + - dependencies.read + - advisories.osv.query + policy: + data_classification: public_dependency_metadata + network: + allowed: + - https://api.osv.dev/v1/query + - https://raw.githubusercontent.com/ + forbidden: + - private repositories + - package installation + - source code execution + verifier_notes: + - Every finding is produced from an exact package name and exact installed version query. + - The dogfood fixture pins the target repository to an immutable commit URL. + artifacts: + emits: + - dependency_cve_audit_result + - evidence_json + - report_md + wrap_as: dependency_cve_audit_packet + +harness: + cases: + - name: nodegoat-direct-production + runner: default + inputs: + target_name: OWASP NodeGoat + target_repo: https://github.com/OWASP/NodeGoat + target_ref: c5cb68a7084e4ae7dcc60e6a98768720a81841e8 + package_lock_url: https://raw.githubusercontent.com/OWASP/NodeGoat/c5cb68a7084e4ae7dcc60e6a98768720a81841e8/package-lock.json + scan_scope: direct + include_dev: false + output_dir: artifacts/nodegoat + expect: + status: sealed + +runners: + default: + default: true + type: cli-tool + command: /usr/bin/env + args: + - node + - run.mjs + scopes: + - dependencies.read + - advisories.osv.query + policy: + reads: + - public npm package lockfiles + calls: + - OSV exact-version query API + writes: + - evidence.json + - report.md + disallows: + - installing target packages + - executing target project code + - using private repository contents + inputs: + target_name: + type: string + required: true + description: Human-readable project name. + target_repo: + type: string + required: true + description: Public source repository URL. + target_ref: + type: string + required: false + description: Immutable commit, tag, or release reference. + package_lock_path: + type: string + required: false + description: Local package-lock.json path inside the skill directory. + package_lock_url: + type: string + required: false + description: Public package-lock.json URL. + scan_scope: + type: string + required: false + default: direct + description: direct or all dependencies. + include_dev: + type: boolean + required: false + default: false + description: Include development dependencies. + output_dir: + type: string + required: false + description: Directory inside the skill directory where artifacts should be written. + outputs: + dependency_cve_audit_result: object + evidence_json: object + report_md: string diff --git a/skills/dependency-cve-audit/run.mjs b/skills/dependency-cve-audit/run.mjs new file mode 100644 index 000000000..6a8eb140a --- /dev/null +++ b/skills/dependency-cve-audit/run.mjs @@ -0,0 +1,399 @@ +import crypto from "node:crypto"; +import fs from "node:fs"; +import path from "node:path"; + +const OSV_QUERY_URL = "https://api.osv.dev/v1/query"; +const SCHEMA = "dependency.cve.audit.result.v1"; + +const inputs = readInputs(); +const skillRoot = process.cwd(); +const scanScope = inputs.scan_scope || "direct"; +const includeDev = inputs.include_dev === true; + +if (!["direct", "all"].includes(scanScope)) { + throw new Error("scan_scope must be direct or all"); +} + +const source = await readLockfile(inputs, skillRoot); +const lockfile = JSON.parse(source.text); +const dependencies = collectDependencies(lockfile, { scanScope, includeDev }); +const findings = await queryFindings(dependencies); +const evidence = buildEvidence({ inputs, source, dependencies, findings, scanScope, includeDev }); +const report = renderReport(evidence); + +writeArtifacts(inputs.output_dir, evidence, report, skillRoot); + +process.stdout.write(`${JSON.stringify(evidence, null, 2)}\n`); + +function readInputs() { + const raw = process.env.RUNX_INPUTS_PATH + ? fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8") + : process.env.RUNX_INPUTS_JSON || "{}"; + return JSON.parse(raw); +} + +async function readLockfile(rawInputs, root) { + if (typeof rawInputs.package_lock_path === "string" && rawInputs.package_lock_path.length > 0) { + const resolved = path.resolve(root, rawInputs.package_lock_path); + ensureInside(root, resolved, "package_lock_path"); + const text = fs.readFileSync(resolved, "utf8"); + return { kind: "file", ref: rawInputs.package_lock_path, text }; + } + if (typeof rawInputs.package_lock_url === "string" && rawInputs.package_lock_url.length > 0) { + const url = new URL(rawInputs.package_lock_url); + if (!["https:"].includes(url.protocol)) { + throw new Error("package_lock_url must be https"); + } + const response = await fetch(url, { headers: { accept: "application/json,text/plain,*/*" } }); + if (!response.ok) { + throw new Error(`GET ${url.href} returned ${response.status}`); + } + return { kind: "url", ref: url.href, text: await response.text() }; + } + throw new Error("package_lock_path or package_lock_url is required"); +} + +function collectDependencies(lockfile, { scanScope, includeDev }) { + if (!lockfile || typeof lockfile !== "object") { + throw new Error("package-lock.json must be a JSON object"); + } + if (!lockfile.packages || typeof lockfile.packages !== "object") { + throw new Error("package-lock.json packages object is required"); + } + + const root = lockfile.packages[""] || {}; + const prodDirect = new Set(Object.keys(root.dependencies || {})); + const devDirect = new Set(Object.keys(root.devDependencies || {})); + const directNames = new Set([...prodDirect, ...(includeDev ? devDirect : [])]); + const results = []; + + if (scanScope === "direct") { + for (const name of directNames) { + const pkgPath = `node_modules/${name}`; + const pkg = lockfile.packages[pkgPath]; + if (!pkg || typeof pkg !== "object" || typeof pkg.version !== "string") { + continue; + } + results.push(dependencyRecord({ + name, + pkg, + pkgPath, + prodDirect, + devDirect, + })); + } + return dedupeDependencies(results).sort((a, b) => a.name.localeCompare(b.name)); + } + + for (const [pkgPath, pkg] of Object.entries(lockfile.packages)) { + if (!pkgPath || !pkgPath.startsWith("node_modules/") || !pkg || typeof pkg !== "object") { + continue; + } + if (!pkg.version || typeof pkg.version !== "string") { + continue; + } + if (pkg.dev === true && !includeDev) { + continue; + } + + const name = packageNameFromLockPath(pkgPath); + results.push(dependencyRecord({ + name, + pkg, + pkgPath, + prodDirect, + devDirect, + })); + } + + return dedupeDependencies(results).sort((a, b) => a.name.localeCompare(b.name)); +} + +function packageNameFromLockPath(pkgPath) { + const marker = "node_modules/"; + const rest = pkgPath.slice(pkgPath.lastIndexOf(marker) + marker.length); + if (rest.startsWith("@")) { + const [scope, name] = rest.split("/"); + return `${scope}/${name}`; + } + return rest.split("/")[0]; +} + +function dependencyRecord({ name, pkg, pkgPath, prodDirect, devDirect }) { + const isProdDirect = prodDirect.has(name) && pkgPath === `node_modules/${name}`; + const isDevDirect = devDirect.has(name) && pkgPath === `node_modules/${name}`; + return { + ecosystem: "npm", + name, + version: pkg.version, + relation: isProdDirect ? "direct-production" : isDevDirect ? "direct-development" : "transitive", + lockfile_path: pkgPath, + resolved: typeof pkg.resolved === "string" ? pkg.resolved : null, + integrity: typeof pkg.integrity === "string" ? pkg.integrity : null, + }; +} + +function dedupeDependencies(dependencies) { + const seen = new Set(); + const results = []; + for (const dep of dependencies) { + const key = `${dep.name}@${dep.version}`; + if (!seen.has(key)) { + seen.add(key); + results.push(dep); + } + } + return results; +} + +async function queryFindings(dependencies) { + const findings = []; + for (const dependency of dependencies) { + const response = await fetch(OSV_QUERY_URL, { + method: "POST", + headers: { "content-type": "application/json", accept: "application/json" }, + body: JSON.stringify({ + version: dependency.version, + package: { + ecosystem: dependency.ecosystem, + name: dependency.name, + }, + }), + }); + if (!response.ok) { + throw new Error(`OSV query for ${dependency.name}@${dependency.version} returned ${response.status}`); + } + const payload = await response.json(); + for (const vuln of payload.vulns || []) { + findings.push(normalizeVulnerability(dependency, vuln)); + } + } + return findings.sort((a, b) => + `${a.dependency.name}:${a.advisory_id}`.localeCompare(`${b.dependency.name}:${b.advisory_id}`), + ); +} + +function normalizeVulnerability(dependency, vuln) { + const references = (vuln.references || []) + .map((ref) => ({ type: ref.type || "WEB", url: ref.url })) + .filter((ref) => typeof ref.url === "string" && ref.url.startsWith("http")); + const severities = (vuln.severity || []).map((entry) => `${entry.type}:${entry.score}`); + const aliases = Array.isArray(vuln.aliases) ? vuln.aliases : []; + + return { + dependency, + query: { + ecosystem: dependency.ecosystem, + package: dependency.name, + version: dependency.version, + advisory_source: OSV_QUERY_URL, + }, + advisory_id: vuln.id, + cve_ids: aliases.filter((alias) => alias.startsWith("CVE-")), + aliases, + summary: vuln.summary || "", + severity: severityLabel(vuln), + severity_vectors: severities, + fixed_versions: fixedVersions(vuln), + affected_ranges: affectedRangesForPackage(vuln, dependency.name), + published: vuln.published || null, + modified: vuln.modified || null, + references, + source_records: sourceRecords(vuln), + }; +} + +function severityLabel(vuln) { + const specific = vuln.database_specific || {}; + if (typeof specific.severity === "string" && specific.severity.length > 0) { + return specific.severity.toLowerCase(); + } + if (Array.isArray(vuln.severity) && vuln.severity.length > 0) { + return vuln.severity[0].score; + } + return "unknown"; +} + +function fixedVersions(vuln) { + const versions = new Set(); + for (const affected of vuln.affected || []) { + for (const range of affected.ranges || []) { + for (const event of range.events || []) { + if (event.fixed) versions.add(event.fixed); + } + } + } + return [...versions].sort(compareVersionish); +} + +function affectedRangesForPackage(vuln, packageName) { + const ranges = []; + for (const affected of vuln.affected || []) { + if (affected.package?.name !== packageName) continue; + for (const range of affected.ranges || []) { + ranges.push({ + type: range.type || null, + events: (range.events || []).map((event) => ({ ...event })), + }); + } + } + return ranges; +} + +function sourceRecords(vuln) { + const records = new Set(); + for (const affected of vuln.affected || []) { + const source = affected.database_specific?.source; + if (source) records.add(source); + } + return [...records].sort(); +} + +function compareVersionish(a, b) { + return String(a).localeCompare(String(b), undefined, { numeric: true, sensitivity: "base" }); +} + +function buildEvidence({ inputs, source, dependencies, findings, scanScope, includeDev }) { + const uniquePackagesWithFindings = new Set(findings.map((finding) => finding.dependency.name)); + const everyFindingHasExactVersion = findings.every((finding) => + finding.query.version === finding.dependency.version + && finding.query.package === finding.dependency.name + && finding.dependency.version.length > 0, + ); + const everyFindingHasReference = findings.every((finding) => finding.references.length > 0); + const everyFindingHasAdvisoryId = findings.every((finding) => finding.advisory_id.length > 0); + + return { + schema: SCHEMA, + data: { + target: { + name: inputs.target_name || null, + repo: inputs.target_repo || null, + ref: inputs.target_ref || null, + }, + source: { + kind: source.kind, + ref: source.ref, + bytes: Buffer.byteLength(source.text), + sha256: sha256(source.text), + }, + scanner: { + name: "dependency-cve-audit", + version: "0.1.1", + advisory_source: "OSV.dev v1 query API", + advisory_endpoint: OSV_QUERY_URL, + }, + policy: { + ecosystem: "npm", + scan_scope: scanScope, + include_dev: includeDev, + target_code_executed: false, + target_packages_installed: false, + finding_rule: "A finding is included only when OSV returns it for the exact npm package name and exact installed version from package-lock.json.", + }, + summary: { + dependencies_scanned: dependencies.length, + packages_with_findings: uniquePackagesWithFindings.size, + findings: findings.length, + }, + dependencies, + findings, + validation: { + valid: everyFindingHasExactVersion && everyFindingHasReference && everyFindingHasAdvisoryId, + every_finding_has_exact_version: everyFindingHasExactVersion, + every_finding_has_reference: everyFindingHasReference, + every_finding_has_advisory_id: everyFindingHasAdvisoryId, + zero_false_hit_control: "Each OSV request uses only the exact package name and version read from the lockfile; no inferred ranges or guessed versions are reported.", + }, + }, + }; +} + +function renderReport(packet) { + const data = packet.data; + const lines = []; + lines.push("# Dependency CVE Audit Report"); + lines.push(""); + lines.push(`Target: ${data.target.name}`); + lines.push(`Repository: ${data.target.repo}`); + lines.push(`Reference: ${data.target.ref}`); + lines.push(`Lockfile: ${data.source.ref}`); + lines.push(`Lockfile SHA-256: \`${data.source.sha256}\``); + lines.push(""); + lines.push("## Summary"); + lines.push(""); + lines.push(`- Advisory source: ${data.scanner.advisory_source} (${data.scanner.advisory_endpoint})`); + lines.push(`- Scan scope: ${data.policy.scan_scope} npm dependencies`); + lines.push(`- Include dev dependencies: ${data.policy.include_dev}`); + lines.push(`- Dependencies scanned: ${data.summary.dependencies_scanned}`); + lines.push(`- Packages with findings: ${data.summary.packages_with_findings}`); + lines.push(`- Exact-version findings: ${data.summary.findings}`); + lines.push(`- Target code executed: ${data.policy.target_code_executed}`); + lines.push(`- Target packages installed: ${data.policy.target_packages_installed}`); + lines.push(""); + lines.push("## Findings"); + lines.push(""); + + if (data.findings.length === 0) { + lines.push("No OSV vulnerabilities were returned for the scanned exact versions."); + } else { + lines.push("| Package | Version | Advisory | CVE aliases | Severity | Fixed versions | Primary reference |"); + lines.push("| --- | --- | --- | --- | --- | --- | --- |"); + for (const finding of data.findings) { + lines.push([ + finding.dependency.name, + finding.dependency.version, + finding.advisory_id, + finding.cve_ids.join(", ") || "none", + finding.severity, + finding.fixed_versions.join(", ") || "not listed", + finding.references[0]?.url || "not listed", + ].map(markdownCell).join(" | ").replace(/^/, "| ").replace(/$/, " |")); + } + } + + lines.push(""); + lines.push("## Reproducibility Controls"); + lines.push(""); + lines.push("- The lockfile URL is pinned to an immutable Git commit."); + lines.push("- Every dependency version comes from `package-lock.json`, not semver range resolution."); + lines.push("- Every finding is returned by OSV for an exact npm package and version query."); + lines.push("- The audit does not install packages or execute target project code."); + lines.push("- `evidence.json` contains the full dependency list, OSV query tuple, advisory IDs, aliases, references, and validation booleans."); + lines.push(""); + + return `${lines.join("\n")}\n`; +} + +function markdownCell(value) { + return String(value).replace(/\|/g, "\\|").replace(/\n/g, " "); +} + +function writeArtifacts(outputDir, evidence, report, root) { + if (!outputDir) { + evidence.data.artifacts = {}; + return; + } + const resolved = path.resolve(root, outputDir); + ensureInside(root, resolved, "output_dir"); + fs.mkdirSync(resolved, { recursive: true }); + const evidencePath = path.join(resolved, "evidence.json"); + const reportPath = path.join(resolved, "report.md"); + evidence.data.artifacts = { + evidence_json: path.relative(root, evidencePath), + report_md: path.relative(root, reportPath), + }; + fs.writeFileSync(evidencePath, `${JSON.stringify(evidence, null, 2)}\n`); + fs.writeFileSync(reportPath, report); +} + +function ensureInside(root, resolved, label) { + const normalizedRoot = root.endsWith(path.sep) ? root : `${root}${path.sep}`; + if (resolved !== root && !resolved.startsWith(normalizedRoot)) { + throw new Error(`${label} must stay inside the skill directory`); + } +} + +function sha256(value) { + return crypto.createHash("sha256").update(value).digest("hex"); +} From cece0b15b80ba7606abf0b2ec3e25d5a97855492 Mon Sep 17 00:00:00 2001 From: fy <44690232+fengyangxxx@users.noreply.github.com> Date: Sat, 20 Jun 2026 17:00:02 +0800 Subject: [PATCH 19/64] feat(skills): add structured extraction Adds the structured-extraction runx skill and completes the paid follow-up integration work. Maintainer cleanup added: - deterministic tool fixture for structured.extract - SKILL.md frontmatter for official catalog generation - official skill lock/Rust table/catalog allowlist entries Verified: - CI green on PR #80 - local merge simulation after #82 - node --check skills/structured-extraction/tools/structured/extract/run.mjs - runx doctor skills/structured-extraction --json - runx harness skills/structured-extraction --receipt-dir --json - runx dev tools/structured/extract --json with RUNX_PROJECT_DIR set to the skill root - packages/cli/src/skill-refs.test.ts --- crates/runx-cli/src/official_skills.rs | 5 + packages/cli/src/official-skills.lock.json | 7 + packages/cli/src/skill-refs.test.ts | 1 + skills/structured-extraction/README.md | 21 + skills/structured-extraction/SKILL.md | 34 + skills/structured-extraction/X.yaml | 83 + .../fixtures/rfc9110-http-semantics.html | 19015 ++++++++++++++++ .../fixtures/rfc9110-http-semantics.yaml | 21 + skills/structured-extraction/package.json | 7 + .../schemas/extraction.schema.json | 277 + .../structured/extract/fixtures/rfc9110.yaml | 27 + .../tools/structured/extract/manifest.json | 65 + .../tools/structured/extract/run.mjs | 415 + 13 files changed, 19978 insertions(+) create mode 100644 skills/structured-extraction/README.md create mode 100644 skills/structured-extraction/SKILL.md create mode 100644 skills/structured-extraction/X.yaml create mode 100644 skills/structured-extraction/fixtures/rfc9110-http-semantics.html create mode 100644 skills/structured-extraction/fixtures/rfc9110-http-semantics.yaml create mode 100644 skills/structured-extraction/package.json create mode 100644 skills/structured-extraction/schemas/extraction.schema.json create mode 100644 skills/structured-extraction/tools/structured/extract/fixtures/rfc9110.yaml create mode 100644 skills/structured-extraction/tools/structured/extract/manifest.json create mode 100644 skills/structured-extraction/tools/structured/extract/run.mjs diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index 4a13f8e26..648c99df4 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -320,6 +320,11 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ version: "sha-e513d3aed77c", digest: "2bfa94189cd3b7084a3b29e1f83de2d0787d28c5f0c962a15bac76155c24d95f", }, + OfficialSkillLockEntry { + skill_id: "runx/structured-extraction", + version: "sha-f14902374e11", + digest: "ebe37921d3b9cb63aa1ca5232a8075607d3b4ad541af4c1bc901ace749ea404f", + }, OfficialSkillLockEntry { skill_id: "runx/taste-profile", version: "sha-30ae4695f7a2", diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index ad975ee7c..c67d363cb 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -433,6 +433,13 @@ "catalog_visibility": "internal", "catalog_role": "runtime-path" }, + { + "skill_id": "runx/structured-extraction", + "version": "sha-f14902374e11", + "digest": "ebe37921d3b9cb63aa1ca5232a8075607d3b4ad541af4c1bc901ace749ea404f", + "catalog_visibility": "public", + "catalog_role": "canonical" + }, { "skill_id": "runx/taste-profile", "version": "sha-30ae4695f7a2", diff --git a/packages/cli/src/skill-refs.test.ts b/packages/cli/src/skill-refs.test.ts index b8381fb20..d798d06eb 100644 --- a/packages/cli/src/skill-refs.test.ts +++ b/packages/cli/src/skill-refs.test.ts @@ -63,6 +63,7 @@ const publicOfficialCatalogSkills = [ "spend", "sql-analyst", "stripe-pay", + "structured-extraction", "taste-profile", "vault-unseal", "vuln-scan", diff --git a/skills/structured-extraction/README.md b/skills/structured-extraction/README.md new file mode 100644 index 000000000..8e6dc7c9d --- /dev/null +++ b/skills/structured-extraction/README.md @@ -0,0 +1,21 @@ +# Structured Extraction Skill + +This skill extracts schema-validated JSON from messy HTML or text fixtures. The +default harness uses the real RFC 9110 HTML document as a deterministic input. + +It emits `runx.structured_extraction.result.v1` and includes artifact +references for: + +- input fixture SHA-256 +- JSON Schema SHA-256 +- validated output payload SHA-256 + +Reproduce: + +```powershell +runx harness . --receipt-dir .\receipts --json +``` + +The Frantic #22 delivery evidence was generated from +`fixtures/rfc9110-http-semantics.html` with source URL +`https://www.rfc-editor.org/rfc/rfc9110.html`. diff --git a/skills/structured-extraction/SKILL.md b/skills/structured-extraction/SKILL.md new file mode 100644 index 000000000..b2dc81b51 --- /dev/null +++ b/skills/structured-extraction/SKILL.md @@ -0,0 +1,34 @@ +--- +name: structured-extraction +description: Extract schema-validated JSON from messy HTML or text fixtures with digest-bound provenance. +source: + type: cli-tool + command: node + args: + - tools/structured/extract/run.mjs +runx: + tags: + - extraction + - schema-validation + - provenance +--- + +# Structured Extraction + +Use this skill to turn messy HTML or text into schema-validated JSON with +reproducible input and output digests. + +The default harness extracts a compact API-reference summary from the RFC 9110 +HTML document. It records the source URL, fixture byte count, input digest, +schema digest, extracted items, validation status, and artifact ids that the +runx receipt can bind as references. + +Inputs: + +- `input_path`: package-relative path to an HTML or text fixture. +- `schema_path`: package-relative JSON Schema path. +- `source_url`: canonical public source URL for the fixture. +- `content_type`: `text/html` or `text/plain`. +- `max_items`: maximum extracted items to include. + +The output packet is `runx.structured_extraction.result.v1`. diff --git a/skills/structured-extraction/X.yaml b/skills/structured-extraction/X.yaml new file mode 100644 index 000000000..0ff54732a --- /dev/null +++ b/skills/structured-extraction/X.yaml @@ -0,0 +1,83 @@ +skill: structured-extraction +version: "0.1.0" + +catalog: + kind: skill + audience: public + visibility: public + role: canonical + runtime_path: local + +policy: + allow: + - provider: local-fixture + method: READ + scope: runx:fixture:read + - provider: local-schema + method: READ + scope: runx:schema:read + deny: + - network_mutation + - credential_material + - private_user_data + +emits: + - name: structured_extraction_result + packet: runx.structured_extraction.result.v1 + +harness: + cases: + - name: rfc9110-http-semantics + runner: extract + inputs: + input_path: "fixtures/rfc9110-http-semantics.html" + schema_path: "schemas/extraction.schema.json" + source_url: "https://www.rfc-editor.org/rfc/rfc9110.html" + content_type: "text/html" + max_items: 18 + expect: + status: sealed + outputs: + structured_extraction_result: + matches_packet: runx.structured_extraction.result.v1 + receipt: + schema: runx.receipt.v1 + +runners: + extract: + default: true + type: graph + inputs: + input_path: + type: string + required: true + description: "Package-relative messy HTML or text fixture." + schema_path: + type: string + required: true + description: "Package-relative JSON Schema used to validate output." + source_url: + type: string + required: true + description: "Canonical source URL for the fixture bytes." + content_type: + type: string + required: false + default: "text/html" + description: "Input content type: text/html or text/plain." + max_items: + type: number + required: false + default: 20 + description: "Maximum extracted items to include in output." + graph: + name: structured-extraction + steps: + - id: extract_structured_json + tool: structured.extract + inputs: + input_path: "$input.input_path" + schema_path: "$input.schema_path" + source_url: "$input.source_url" + content_type: "$input.content_type" + max_items: "$input.max_items" diff --git a/skills/structured-extraction/fixtures/rfc9110-http-semantics.html b/skills/structured-extraction/fixtures/rfc9110-http-semantics.html new file mode 100644 index 000000000..10fbf5da9 --- /dev/null +++ b/skills/structured-extraction/fixtures/rfc9110-http-semantics.html @@ -0,0 +1,19015 @@ + + + + + + +RFC 9110: HTTP Semantics + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
RFC 9110HTTP SemanticsJune 2022
Fielding, et al.Standards Track[Page]
+
+
+
+
Stream:
+
Internet Engineering Task Force (IETF)
+
RFC:
+
9110
+
STD:
+
97
+
Obsoletes:
+
+2818, 7230, 7231, 7232, 7233, 7235, 7538, 7615, 7694
+
Updates:
+
+3864
+
Category:
+
Standards Track
+
Published:
+
+ +
+
ISSN:
+
2070-1721
+
Authors:
+
+
+
R. Fielding, Ed. +
+
Adobe
+
+
+
M. Nottingham, Ed. +
+
Fastly
+
+
+
J. Reschke, Ed. +
+
greenbytes
+
+
+
+
+

RFC 9110

+

HTTP Semantics

+
+

Abstract

+

+ The Hypertext Transfer Protocol (HTTP) is a stateless application-level + protocol for distributed, collaborative, hypertext information systems. + This document describes the overall architecture of HTTP, establishes common + terminology, and defines aspects of the protocol that are shared by all + versions. In this definition are core protocol elements, extensibility + mechanisms, and the "http" and "https" Uniform Resource Identifier (URI) + schemes.¶

+

+ This document updates RFC 3864 and + obsoletes RFCs 2818, 7231, 7232, 7233, + 7235, 7538, 7615, 7694, and portions of 7230.¶

+
+
+
+

+Status of This Memo +

+

+ This is an Internet Standards Track document.¶

+

+ This document is a product of the Internet Engineering Task Force + (IETF). It represents the consensus of the IETF community. It has + received public review and has been approved for publication by + the Internet Engineering Steering Group (IESG). Further + information on Internet Standards is available in Section 2 of + RFC 7841.¶

+

+ Information about the current status of this document, any + errata, and how to provide feedback on it may be obtained at + https://www.rfc-editor.org/info/rfc9110.¶

+
+
+ +
+
+ ▲

+Table of Contents +

+ +
+
+
+
+

+1. Introduction +

+
+
+

+1.1. Purpose +

+

+ The Hypertext Transfer Protocol (HTTP) is a family of stateless, + application-level, request/response protocols that share a generic interface, + extensible semantics, and self-descriptive messages to enable flexible + interaction with network-based hypertext information systems.¶

+

+ HTTP hides the details of how a service is implemented by presenting a + uniform interface to clients that is independent of the types of resources + provided. Likewise, servers do not need to be aware of each client's + purpose: a request can be considered in isolation rather than being + associated with a specific type of client or a predetermined sequence of + application steps. This allows general-purpose implementations to be used + effectively in many different contexts, reduces interaction complexity, and + enables independent evolution over time.¶

+

+ HTTP is also designed for use as an intermediation protocol, wherein + proxies and gateways can translate non-HTTP information systems into a + more generic interface.¶

+

+ One consequence of this flexibility is that the protocol cannot be + defined in terms of what occurs behind the interface. Instead, we + are limited to defining the syntax of communication, the intent + of received communication, and the expected behavior of recipients. + If the communication is considered in isolation, then successful + actions ought to be reflected in corresponding changes to the + observable interface provided by servers. However, since multiple + clients might act in parallel and perhaps at cross-purposes, we + cannot require that such changes be observable beyond the scope + of a single response.¶

+
+
+
+
+

+1.2. History and Evolution +

+

+ HTTP has been the primary information transfer protocol for the World + Wide Web since its introduction in 1990. It began as a trivial + mechanism for low-latency requests, with a single method (GET) to + request transfer of a presumed hypertext document identified by a given pathname. + As the Web grew, HTTP was extended to enclose requests and responses within + messages, transfer arbitrary data formats using MIME-like media types, and + route requests through intermediaries. These protocols were eventually + defined as HTTP/0.9 and HTTP/1.0 (see [HTTP/1.0]).¶

+

+ HTTP/1.1 was designed to refine the protocol's features while retaining + compatibility with the existing text-based messaging syntax, improving + its interoperability, scalability, and robustness across the Internet. + This included length-based data delimiters for both fixed and dynamic + (chunked) content, a consistent framework for content negotiation, + opaque validators for conditional requests, cache controls for better + cache consistency, range requests for partial updates, and default + persistent connections. HTTP/1.1 was introduced in 1995 and published on + the Standards Track in 1997 [RFC2068], revised in + 1999 [RFC2616], and revised again in 2014 + ([RFC7230] through [RFC7235]).¶

+

+ HTTP/2 ([HTTP/2]) introduced a multiplexed session layer + on top of the existing TLS and TCP protocols for exchanging concurrent + HTTP messages with efficient field compression and server push. + HTTP/3 ([HTTP/3]) provides greater independence for concurrent + messages by using QUIC as a secure multiplexed transport over UDP instead of + TCP.¶

+

+ All three major versions of HTTP rely on the semantics defined by + this document. They have not obsoleted each other because each one has + specific benefits and limitations depending on the context of use. + Implementations are expected to choose the most appropriate transport and + messaging syntax for their particular context.¶

+

+ This revision of HTTP separates the definition of semantics (this document) + and caching ([CACHING]) from the current HTTP/1.1 messaging + syntax ([HTTP/1.1]) to allow each major protocol version + to progress independently while referring to the same core semantics.¶

+
+
+
+
+

+1.3. Core Semantics +

+

+ HTTP provides a uniform interface for interacting with a resource + (Section 3.1) -- regardless of its type, nature, or + implementation -- by sending messages that manipulate or transfer + representations (Section 3.2).¶

+

+ Each message is either a request or a response. A client constructs request + messages that communicate its intentions and routes those messages toward + an identified origin server. A server listens for requests, parses each + message received, interprets the message semantics in relation to the + identified target resource, and responds to that request with one or more + response messages. The client examines received responses to see if its + intentions were carried out, determining what to do next based on the + status codes and content received.¶

+

+ HTTP semantics include the intentions defined by each request method + (Section 9), extensions to those semantics that might be + described in request header fields, + status codes that describe the response (Section 15), and + other control data and resource metadata that might be given in response + fields.¶

+

+ + Semantics also include representation metadata that describe how + content is intended to be interpreted by a recipient, request header + fields that might influence content selection, and the various selection + algorithms that are collectively referred to as + "content negotiation" (Section 12).¶

+
+
+
+
+

+1.4. Specifications Obsoleted by This Document +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 1
TitleReferenceSee
HTTP Over TLS + [RFC2818] + + B.1 +
HTTP/1.1 Message Syntax and Routing [*] + [RFC7230] + + B.2 +
HTTP/1.1 Semantics and Content + [RFC7231] + + B.3 +
HTTP/1.1 Conditional Requests + [RFC7232] + + B.4 +
HTTP/1.1 Range Requests + [RFC7233] + + B.5 +
HTTP/1.1 Authentication + [RFC7235] + + B.6 +
HTTP Status Code 308 (Permanent Redirect) + [RFC7538] + + B.7 +
HTTP Authentication-Info and Proxy-Authentication-Info + Response Header Fields + [RFC7615] + + B.8 +
HTTP Client-Initiated Content-Encoding + [RFC7694] + + B.9 +
+

+ [*] This document only obsoletes the portions of + RFC 7230 that are independent of + the HTTP/1.1 messaging syntax and connection management; the remaining + bits of RFC 7230 are + obsoleted by "HTTP/1.1" [HTTP/1.1].¶

+
+
+
+
+
+
+

+2. Conformance +

+
+
+

+2.1. Syntax Notation +

+ + + + + + + + + + + + +

+ This specification uses the Augmented Backus-Naur Form (ABNF) notation of + [RFC5234], extended with the notation for case-sensitivity + in strings defined in [RFC7405].¶

+

+ It also uses a list extension, defined in Section 5.6.1, + that allows for compact definition of comma-separated lists using a "#" + operator (similar to how the "*" operator indicates repetition). Appendix A shows the collected grammar with all list + operators expanded to standard ABNF notation.¶

+

+ As a convention, ABNF rule names prefixed with "obs-" denote + obsolete grammar rules that appear for historical reasons.¶

+
+

+ + + + + + + + + + + + + The following core rules are included by + reference, as defined in Appendix B.1 of [RFC5234]: + ALPHA (letters), CR (carriage return), CRLF (CR LF), CTL (controls), + DIGIT (decimal 0-9), DQUOTE (double quote), + HEXDIG (hexadecimal 0-9/A-F/a-f), HTAB (horizontal tab), LF (line feed), + OCTET (any 8-bit sequence of data), SP (space), and + VCHAR (any visible US-ASCII character).¶

+
+

+ Section 5.6 defines some generic syntactic + components for field values.¶

+

+ This specification uses the terms + "character", + "character encoding scheme", + "charset", and + "protocol element" + as they are defined in [RFC6365].¶

+
+
+
+
+

+2.2. Requirements Notation +

+

+ The key words "MUST", "MUST NOT", + "REQUIRED", "SHALL", "SHALL NOT", + "SHOULD", "SHOULD NOT", + "RECOMMENDED", "NOT RECOMMENDED", + "MAY", and "OPTIONAL" in this document are to be + interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as + shown here.¶

+

+ This specification targets conformance criteria according to the role of + a participant in HTTP communication. Hence, requirements are placed + on senders, recipients, clients, servers, user agents, intermediaries, + origin servers, proxies, gateways, or caches, depending on what behavior + is being constrained by the requirement. Additional requirements + are placed on implementations, resource owners, and protocol element + registrations when they apply beyond the scope of a single communication.¶

+

+ The verb "generate" is used instead of "send" where a requirement applies + only to implementations that create the protocol element, rather than an + implementation that forwards a received element downstream.¶

+

+ An implementation is considered conformant if it complies with all of the + requirements associated with the roles it partakes in HTTP.¶

+

+ A sender MUST NOT generate protocol elements that do not match the grammar + defined by the corresponding ABNF rules. + Within a given message, a sender MUST NOT generate protocol elements or + syntax alternatives that are only allowed to be generated by participants in + other roles (i.e., a role that the sender does not have for that message).¶

+

+ Conformance to HTTP includes both conformance to the particular messaging + syntax of the protocol version in use and conformance to the semantics of + protocol elements sent. For example, a client that claims conformance to + HTTP/1.1 but fails to recognize the features required of HTTP/1.1 + recipients will fail to interoperate with servers that adjust their + responses in accordance with those claims. + Features that reflect user choices, such as content negotiation and + user-selected extensions, can impact application behavior beyond the + protocol stream; sending protocol elements that inaccurately reflect a + user's choices will confuse the user and inhibit choice.¶

+

+ When an implementation fails semantic conformance, recipients of that + implementation's messages will eventually develop workarounds to adjust + their behavior accordingly. A recipient MAY employ such workarounds while + remaining conformant to this protocol if the workarounds are limited to the + implementations at fault. For example, servers often scan portions of the + User-Agent field value, and user agents often scan the Server field value, + to adjust their own behavior with respect to known bugs or poorly chosen + defaults.¶

+
+
+
+
+

+2.3. Length Requirements +

+

+ A recipient SHOULD parse a received protocol element defensively, with + only marginal expectations that the element will conform to its ABNF + grammar and fit within a reasonable buffer size.¶

+

+ HTTP does not have specific length limitations for many of its protocol + elements because the lengths that might be appropriate will vary widely, + depending on the deployment context and purpose of the implementation. + Hence, interoperability between senders and recipients depends on shared + expectations regarding what is a reasonable length for each protocol + element. Furthermore, what is commonly understood to be a reasonable length + for some protocol elements has changed over the course of the past three + decades of HTTP use and is expected to continue changing in the future.¶

+

+ At a minimum, a recipient MUST be able to parse and process protocol + element lengths that are at least as long as the values that it generates + for those same protocol elements in other messages. For example, an origin + server that publishes very long URI references to its own resources needs + to be able to parse and process those same references when received as a + target URI.¶

+

+ Many received protocol elements are only parsed to the extent necessary to + identify and forward that element downstream. For example, an intermediary + might parse a received field into its field name and field value components, + but then forward the field without further parsing inside the field value.¶

+
+
+
+
+

+2.4. Error Handling +

+

+ A recipient MUST interpret a received protocol element according to the + semantics defined for it by this specification, including extensions to + this specification, unless the recipient has determined (through experience + or configuration) that the sender incorrectly implements what is implied by + those semantics. + For example, an origin server might disregard the contents of a received + Accept-Encoding header field if inspection of the + User-Agent header field indicates a specific implementation + version that is known to fail on receipt of certain content codings.¶

+

+ Unless noted otherwise, a recipient MAY attempt to recover a usable + protocol element from an invalid construct. HTTP does not define + specific error handling mechanisms except when they have a direct impact + on security, since different applications of the protocol require + different error handling strategies. For example, a Web browser might + wish to transparently recover from a response where the + Location header field doesn't parse according to the ABNF, + whereas a systems control client might consider any form of error recovery + to be dangerous.¶

+

+ Some requests can be automatically retried by a client in the event of + an underlying connection failure, as described in + Section 9.2.2.¶

+
+
+
+
+

+2.5. Protocol Version +

+

+ HTTP's version number consists of two decimal digits separated by a "." + (period or decimal point). The first digit (major version) indicates the + messaging syntax, whereas the second digit (minor version) + indicates the highest minor version within that major version to which the + sender is conformant (able to understand for future communication).¶

+

+ While HTTP's core semantics don't change between protocol versions, their + expression "on the wire" can change, and so the + HTTP version number changes when incompatible changes are made to the wire + format. Additionally, HTTP allows incremental, backwards-compatible + changes to be made to the protocol without changing its version through + the use of defined extension points (Section 16).¶

+

+ The protocol version as a whole indicates the sender's conformance with + the set of requirements laid out in that version's corresponding + specification(s). + For example, the version "HTTP/1.1" is defined by the combined + specifications of this document, "HTTP Caching" [CACHING], + and "HTTP/1.1" [HTTP/1.1].¶

+

+ HTTP's major version number is incremented when an incompatible message + syntax is introduced. The minor number is incremented when changes made to + the protocol have the effect of adding to the message semantics or + implying additional capabilities of the sender.¶

+

+ The minor version advertises the sender's communication capabilities even + when the sender is only using a backwards-compatible subset of the + protocol, thereby letting the recipient know that more advanced features + can be used in response (by servers) or in future requests (by clients).¶

+

+ When a major version of HTTP does not define any minor versions, the minor + version "0" is implied. The "0" is used when referring to that protocol + within elements that require a minor version identifier.¶

+
+
+
+
+
+
+

+3. Terminology and Core Concepts +

+

+ HTTP was created for the World Wide Web (WWW) architecture + and has evolved over time to support the scalability needs of a worldwide + hypertext system. Much of that architecture is reflected in the terminology + used to define HTTP.¶

+
+
+

+3.1. Resources +

+ +

+ The target of an HTTP request is called a "resource". + HTTP does not limit the nature of a resource; it merely + defines an interface that might be used to interact with resources. + Most resources are identified by a Uniform Resource Identifier (URI), as + described in Section 4.¶

+

+ One design goal of HTTP is to separate resource identification from + request semantics, which is made possible by vesting the request + semantics in the request method (Section 9) and a few + request-modifying header fields. + A resource cannot treat a request in a manner inconsistent with the + semantics of the method of the request. For example, though the URI of a + resource might imply semantics that are not safe, a client can expect the + resource to avoid actions that are unsafe when processing a request with a + safe method (see Section 9.2.1).¶

+

+ HTTP relies upon the Uniform Resource Identifier (URI) + standard [URI] to indicate the target resource + (Section 7.1) and relationships between resources.¶

+
+
+
+
+

+3.2. Representations +

+ +

+ A "representation" is information + that is intended to reflect a past, current, or desired state of a given + resource, in a format that can be readily communicated via the protocol. + A representation consists of a set of representation metadata and a + potentially unbounded stream of representation data + (Section 8).¶

+

+ HTTP allows "information hiding" behind its uniform interface by defining + communication with respect to a transferable representation of the resource + state, rather than transferring the resource itself. This allows the + resource identified by a URI to be anything, including temporal functions + like "the current weather in Laguna Beach", while potentially providing + information that represents that resource at the time a message is + generated [REST].¶

+

+ The uniform interface is similar to a window through which one can observe + and act upon a thing only through the communication of messages to an + independent actor on the other side. A shared abstraction is needed to + represent ("take the place of") the current or desired state of that thing + in our communications. When a representation is hypertext, it can provide + both a representation of the resource state and processing instructions + that help guide the recipient's future interactions.¶

+
+

+ + A target resource might be provided with, or be capable of + generating, multiple representations that are each intended to reflect the + resource's current state. An algorithm, usually based on + content negotiation (Section 12), + would be used to select one of those representations as being most + applicable to a given request. + This "selected representation" provides the data and metadata + for evaluating conditional requests (Section 13) + and constructing the content for 200 (OK), + 206 (Partial Content), and + 304 (Not Modified) responses to GET (Section 9.3.1).¶

+
+
+
+
+
+

+3.3. Connections, Clients, and Servers +

+ + + +

+ HTTP is a client/server protocol that operates over a reliable + transport- or session-layer "connection".¶

+

+ An HTTP "client" is a program that establishes a connection + to a server for the purpose of sending one or more HTTP requests. + An HTTP "server" is a program that accepts connections + in order to service HTTP requests by sending HTTP responses.¶

+

+ The terms client and server refer only to the roles that + these programs perform for a particular connection. The same program + might act as a client on some connections and a server on others.¶

+

+ HTTP is defined as a stateless protocol, meaning that each request message's semantics + can be understood in isolation, and that the relationship between connections + and messages on them has no impact on the interpretation of those messages. + For example, a CONNECT request (Section 9.3.6) or a request with + the Upgrade header field (Section 7.8) can occur at any time, + not just in the first message on a connection. Many implementations depend on + HTTP's stateless design in order to reuse proxied connections or dynamically + load balance requests across multiple servers.¶

+

+ As a result, a server MUST NOT + assume that two requests on the same connection are from the same user + agent unless the connection is secured and specific to that agent. + Some non-standard HTTP extensions (e.g., [RFC4559]) have + been known to violate this requirement, resulting in security and + interoperability problems.¶

+
+
+
+
+

+3.4. Messages +

+ + + + + + +

+ HTTP is a stateless request/response protocol for exchanging + "messages" across a connection. + The terms "sender" and "recipient" refer to + any implementation that sends or receives a given message, respectively.¶

+

+ A client sends requests to a server in the form of a "request" + message with a method (Section 9) and request target + (Section 7.1). The request might also contain + header fields (Section 6.3) for request modifiers, + client information, and representation metadata, + content (Section 6.4) intended for processing + in accordance with the method, and + trailer fields (Section 6.5) to communicate information + collected while sending the content.¶

+

+ A server responds to a client's request by sending one or more + "response" messages, each including a status + code (Section 15). The response might also contain + header fields for server information, resource metadata, and representation + metadata, content to be interpreted in accordance with the status + code, and trailer fields to communicate information + collected while sending the content.¶

+
+
+
+
+

+3.5. User Agents +

+ + + +

+ The term "user agent" refers to any of the various + client programs that initiate a request.¶

+

+ The most familiar form of user agent is the general-purpose Web browser, but + that's only a small percentage of implementations. Other common user agents + include spiders (web-traversing robots), command-line tools, billboard + screens, household appliances, scales, light bulbs, firmware update scripts, + mobile apps, and communication devices in a multitude of shapes and sizes.¶

+

+ Being a user agent does not imply that there is a human user directly + interacting with the software agent at the time of a request. In many + cases, a user agent is installed or configured to run in the background + and save its results for later inspection (or save only a subset of those + results that might be interesting or erroneous). Spiders, for example, are + typically given a start URI and configured to follow certain behavior while + crawling the Web as a hypertext graph.¶

+

+ Many user agents cannot, or choose not to, + make interactive suggestions to their user or provide adequate warning for + security or privacy concerns. In the few cases where this + specification requires reporting of errors to the user, it is acceptable + for such reporting to only be observable in an error console or log file. + Likewise, requirements that an automated action be confirmed by the user + before proceeding might be met via advance configuration choices, + run-time options, or simple avoidance of the unsafe action; confirmation + does not imply any specific user interface or interruption of normal + processing if the user has already made that choice.¶

+
+
+
+
+

+3.6. Origin Server +

+ +

+ The term "origin server" refers to a program that can + originate authoritative responses for a given target resource.¶

+

+ The most familiar form of origin server are large public websites. + However, like user agents being equated with browsers, it is easy to be + misled into thinking that all origin servers are alike. + Common origin servers also include home automation units, configurable + networking components, office machines, autonomous robots, news feeds, + traffic cameras, real-time ad selectors, and video-on-demand platforms.¶

+

+ Most HTTP communication consists of a retrieval request (GET) for + a representation of some resource identified by a URI. In the + simplest case, this might be accomplished via a single bidirectional + connection (===) between the user agent (UA) and the origin server (O).¶

+
+
+
+         request   >
+    UA ======================================= O
+                                <   response
+
+
+
Figure 1
+
+
+
+
+

+3.7. Intermediaries +

+ +

+ HTTP enables the use of intermediaries to satisfy requests through + a chain of connections. There are three common forms of HTTP + "intermediary": proxy, gateway, and tunnel. In some cases, + a single intermediary might act as an origin server, proxy, gateway, + or tunnel, switching behavior based on the nature of each request.¶

+
+
+
+         >             >             >             >
+    UA =========== A =========== B =========== C =========== O
+               <             <             <             <
+
+
+
Figure 2
+

+ The figure above shows three intermediaries (A, B, and C) between the + user agent and origin server. A request or response message that + travels the whole chain will pass through four separate connections. + Some HTTP communication options + might apply only to the connection with the nearest, non-tunnel + neighbor, only to the endpoints of the chain, or to all connections + along the chain. Although the diagram is linear, each participant might + be engaged in multiple, simultaneous communications. For example, B + might be receiving requests from many clients other than A, and/or + forwarding requests to servers other than C, at the same time that it + is handling A's request. Likewise, later requests might be sent through a + different path of connections, often based on dynamic configuration for + load balancing.¶

+

+ + + + + The terms "upstream" and "downstream" are + used to describe directional requirements in relation to the message flow: + all messages flow from upstream to downstream. + The terms "inbound" and "outbound" are used to describe directional + requirements in relation to the request route: + inbound means "toward the origin server", whereas + outbound means "toward the user agent".¶

+

+ + A "proxy" is a message-forwarding agent that is chosen by the + client, usually via local configuration rules, to receive requests + for some type(s) of absolute URI and attempt to satisfy those + requests via translation through the HTTP interface. Some translations + are minimal, such as for proxy requests for "http" URIs, whereas + other requests might require translation to and from entirely different + application-level protocols. Proxies are often used to group an + organization's HTTP requests through a common intermediary for the + sake of security services, annotation services, or shared caching. Some + proxies are designed to apply transformations to selected messages or + content while they are being forwarded, as described in + Section 7.7.¶

+

+ + + + A "gateway" (a.k.a. "reverse proxy") is an + intermediary that acts as an origin server for the outbound connection but + translates received requests and forwards them inbound to another server or + servers. Gateways are often used to encapsulate legacy or untrusted + information services, to improve server performance through + "accelerator" caching, and to enable partitioning or load + balancing of HTTP services across multiple machines.¶

+

+ All HTTP requirements applicable to an origin server + also apply to the outbound communication of a gateway. + A gateway communicates with inbound servers using any protocol that + it desires, including private extensions to HTTP that are outside + the scope of this specification. However, an HTTP-to-HTTP gateway + that wishes to interoperate with third-party HTTP servers needs to conform + to user agent requirements on the gateway's inbound connection.¶

+

+ + A "tunnel" acts as a blind relay between two connections + without changing the messages. Once active, a tunnel is not + considered a party to the HTTP communication, though the tunnel might + have been initiated by an HTTP request. A tunnel ceases to exist when + both ends of the relayed connection are closed. Tunnels are used to + extend a virtual connection through an intermediary, such as when + Transport Layer Security (TLS, [TLS13]) is used to + establish confidential communication through a shared firewall proxy.¶

+

+ The above categories for intermediary only consider those acting as + participants in the HTTP communication. There are also intermediaries + that can act on lower layers of the network protocol stack, filtering or + redirecting HTTP traffic without the knowledge or permission of message + senders. Network intermediaries are indistinguishable (at a protocol level) + from an on-path attacker, often introducing security flaws or + interoperability problems due to mistakenly violating HTTP semantics.¶

+

+ + + For example, an "interception proxy" [RFC3040] (also commonly + known as a "transparent proxy" [RFC1919]) + differs from an HTTP proxy because it is not chosen by the client. + Instead, an interception proxy filters or redirects outgoing TCP port 80 + packets (and occasionally other common port traffic). + Interception proxies are commonly found on public network access points, + as a means of enforcing account subscription prior to allowing use of + non-local Internet services, and within corporate firewalls to enforce + network usage policies.¶

+
+
+
+
+

+3.8. Caches +

+ +

+ A "cache" is a local store of previous response messages and the + subsystem that controls its message storage, retrieval, and deletion. + A cache stores cacheable responses in order to reduce the response + time and network bandwidth consumption on future, equivalent + requests. Any client or server MAY employ a cache, though a cache + cannot be used while acting as a tunnel.¶

+

+ The effect of a cache is that the request/response chain is shortened + if one of the participants along the chain has a cached response + applicable to that request. The following illustrates the resulting + chain if B has a cached copy of an earlier response from O (via C) + for a request that has not been cached by UA or A.¶

+
+
+
+            >             >
+       UA =========== A =========== B - - - - - - C - - - - - - O
+                  <             <
+
+
+
Figure 3
+

+ + A response is "cacheable" if a cache is allowed to store a copy of + the response message for use in answering subsequent requests. + Even when a response is cacheable, there might be additional + constraints placed by the client or by the origin server on when + that cached response can be used for a particular request. HTTP + requirements for cache behavior and cacheable responses are + defined in [CACHING].¶

+

+ There is a wide variety of architectures and configurations + of caches deployed across the World Wide Web and + inside large organizations. These include national hierarchies + of proxy caches to save bandwidth and reduce latency, content delivery + networks that use gateway caching to optimize regional and global distribution of popular sites, + collaborative systems that + broadcast or multicast cache entries, archives of pre-fetched cache + entries for use in off-line or high-latency environments, and so on.¶

+
+
+
+
+

+3.9. Example Message Exchange +

+

+ The following example illustrates a typical HTTP/1.1 message exchange for a + GET request (Section 9.3.1) on the URI "http://www.example.com/hello.txt":¶

+

+Client request:¶

+
+
GET /hello.txt HTTP/1.1
+User-Agent: curl/7.64.1
+Host: www.example.com
+Accept-Language: en, mi
+
+
¶ +
+

+Server response:¶

+
+
HTTP/1.1 200 OK
+Date: Mon, 27 Jul 2009 12:28:53 GMT
+Server: Apache
+Last-Modified: Wed, 22 Jul 2009 19:15:56 GMT
+ETag: "34aa387-d-1568eb00"
+Accept-Ranges: bytes
+Content-Length: 51
+Vary: Accept-Encoding
+Content-Type: text/plain
+
+Hello World! My content includes a trailing CRLF.
+
¶ +
+
+
+
+
+
+
+

+4. Identifiers in HTTP +

+ + +

+ Uniform Resource Identifiers (URIs) [URI] are used + throughout HTTP as the means for identifying resources (Section 3.1).¶

+
+
+

+4.1. URI References +

+ +

+ URI references are used to target requests, indicate redirects, and define + relationships.¶

+

+ The definitions of "URI-reference", + "absolute-URI", "relative-part", "authority", "port", "host", + "path-abempty", "segment", and "query" are adopted from the + URI generic syntax. + An "absolute-path" rule is defined for protocol elements that can contain a + non-empty path component. (This rule differs slightly from the path-abempty + rule of RFC 3986, which allows for an empty path, + and path-absolute rule, which does not allow paths that begin with "//".) + A "partial-URI" rule is defined for protocol elements + that can contain a relative URI but not a fragment component.¶

+ + + + + + + + + +
+
  URI-reference = <URI-reference, see [URI], Section 4.1>
+  absolute-URI  = <absolute-URI, see [URI], Section 4.3>
+  relative-part = <relative-part, see [URI], Section 4.2>
+  authority     = <authority, see [URI], Section 3.2>
+  uri-host      = <host, see [URI], Section 3.2.2>
+  port          = <port, see [URI], Section 3.2.3>
+  path-abempty  = <path-abempty, see [URI], Section 3.3>
+  segment       = <segment, see [URI], Section 3.3>
+  query         = <query, see [URI], Section 3.4>
+
+  absolute-path = 1*( "/" segment )
+  partial-URI   = relative-part [ "?" query ]
+
¶ +
+

+ Each protocol element in HTTP that allows a URI reference will indicate + in its ABNF production whether the element allows any form of reference + (URI-reference), only a URI in absolute form (absolute-URI), only the + path and optional query components (partial-URI), + or some combination of the above. + Unless otherwise indicated, URI references are parsed + relative to the target URI (Section 7.1).¶

+

+ It is RECOMMENDED that all senders and recipients support, at a minimum, + URIs with lengths of 8000 octets in protocol elements. Note that this + implies some structures and on-wire representations (for example, the + request line in HTTP/1.1) will necessarily be larger in some cases.¶

+
+
+
+
+ +

+ IANA maintains the registry of URI Schemes [BCP35] at + <https://www.iana.org/assignments/uri-schemes/>. + Although requests might target any URI scheme, the following schemes are + inherent to HTTP servers:¶

+
+ + + + + + + + + + + + + + + + + + + + + +
Table 2
URI SchemeDescriptionSection
httpHypertext Transfer Protocol + 4.2.1 +
httpsHypertext Transfer Protocol Secure + 4.2.2 +
+
+

+ Note that the presence of an "http" or "https" URI does not imply that + there is always an HTTP server at the identified origin listening for + connections. Anyone can mint a URI, whether or not a server exists and + whether or not that server currently maps that identifier to a resource. + The delegated nature of registered names and IP addresses creates a + federated namespace whether or not an HTTP server is present.¶

+
+
+

+4.2.1. http URI Scheme +

+ + +

+ The "http" URI scheme is hereby defined for minting identifiers within the + hierarchical namespace governed by a potential HTTP origin server + listening for TCP ([TCP]) connections on a given port.¶

+ +
+
  http-URI = "http" "://" authority path-abempty [ "?" query ]
+
¶ +
+

+ The origin server for an "http" URI is identified by the + authority component, which includes a host identifier + ([URI], Section 3.2.2) + and optional port number ([URI], Section 3.2.3). + If the port subcomponent is empty or not given, TCP port 80 (the + reserved port for WWW services) is the default. + The origin determines who has the right to respond authoritatively to + requests that target the identified resource, as defined in + Section 4.3.2.¶

+

+ A sender MUST NOT generate an "http" URI with an empty host identifier. + A recipient that processes such a URI reference MUST reject it as invalid.¶

+

+ The hierarchical path component and optional query component identify the + target resource within that origin server's namespace.¶

+
+
+
+
+

+4.2.2. https URI Scheme +

+ + + +

+ The "https" URI scheme is hereby defined for minting identifiers within the + hierarchical namespace governed by a potential origin server listening for + TCP connections on a given port and capable of establishing a TLS + ([TLS13]) connection that has been secured for HTTP + communication. In this context, "secured" specifically + means that the server has been authenticated as acting on behalf of the + identified authority and all HTTP communication with that server has + confidentiality and integrity protection that is acceptable to both client + and server.¶

+ +
+
  https-URI = "https" "://" authority path-abempty [ "?" query ]
+
¶ +
+

+ The origin server for an "https" URI is identified by the + authority component, which includes a host identifier + ([URI], Section 3.2.2) + and optional port number ([URI], Section 3.2.3). + If the port subcomponent is empty or not given, TCP port 443 + (the reserved port for HTTP over TLS) is the default. + The origin determines who has the right to respond authoritatively to + requests that target the identified resource, as defined in + Section 4.3.3.¶

+

+ A sender MUST NOT generate an "https" URI with an empty host identifier. + A recipient that processes such a URI reference MUST reject it as invalid.¶

+

+ The hierarchical path component and optional query component identify the + target resource within that origin server's namespace.¶

+

+ A client MUST ensure that its HTTP requests for an "https" resource are + secured, prior to being communicated, and that it only accepts secured + responses to those requests. Note that the definition of what cryptographic + mechanisms are acceptable to client and server are usually negotiated and + can change over time.¶

+

+ Resources made available via the "https" scheme have no shared identity + with the "http" scheme. They are distinct origins with separate namespaces. + However, extensions to HTTP that are defined as applying to all origins with + the same host, such as the Cookie protocol [COOKIE], + allow information set by one service to impact communication with other + services within a matching group of host domains. Such extensions ought to + be designed with great care to prevent information obtained from a secured + connection being inadvertently exchanged within an unsecured context.¶

+
+
+
+
+

+4.2.3. http(s) Normalization and Comparison +

+

+ URIs with an "http" or "https" scheme are normalized and compared according to the + methods defined in Section 6 of [URI], using + the defaults described above for each scheme.¶

+

+ HTTP does not require the use of a specific method for determining + equivalence. For example, a cache key might be compared as a simple + string, after syntax-based normalization, or after scheme-based + normalization.¶

+

+ Scheme-based normalization (Section 6.2.3 of [URI]) of "http" and "https" URIs involves the following + additional rules:¶

+
    +
  • If the port is equal to the default port for a scheme, the normal form + is to omit the port subcomponent.¶ +
    • +
  • When not being used as the target of an OPTIONS request, an empty path + component is equivalent to an absolute path of "/", so the normal form is + to provide a path of "/" instead.¶ +
    • +
  • The scheme and host are case-insensitive and normally provided in + lowercase; all other components are compared in a case-sensitive + manner.¶ +
    • +
  • Characters other than those in the "reserved" set are equivalent to + their percent-encoded octets: the normal form is to not encode them (see + Sections 2.1 and 2.2 of [URI]).¶ +
    • +
+

+ For example, the following three URIs are equivalent:¶

+
+
+   http://example.com:80/~smith/home.html
+   http://EXAMPLE.com/%7Esmith/home.html
+   http://EXAMPLE.com:/%7esmith/home.html
+
¶ +
+

+ Two HTTP URIs that are equivalent after normalization (using any method) + can be assumed to identify the same resource, and any HTTP component MAY + perform normalization. As a result, distinct resources SHOULD NOT be + identified by HTTP URIs that are equivalent after normalization (using any + method defined in Section 6.2 of [URI]).¶

+
+
+
+
+

+4.2.4. Deprecation of userinfo in http(s) URIs +

+

+ The URI generic syntax for authority also includes a userinfo subcomponent + ([URI], Section 3.2.1) for including user + authentication information in the URI. In that subcomponent, the + use of the format "user:password" is deprecated.¶

+

+ Some implementations make use of the userinfo component for internal + configuration of authentication information, such as within command + invocation options, configuration files, or bookmark lists, even + though such usage might expose a user identifier or password.¶

+

+ A sender MUST NOT generate the userinfo subcomponent (and its "@" + delimiter) when an "http" or "https" URI reference is generated within a + message as a target URI or field value.¶

+

+ Before making use of an "http" or "https" URI reference received from an untrusted + source, a recipient SHOULD parse for userinfo and treat its presence as + an error; it is likely being used to obscure the authority for the sake of + phishing attacks.¶

+
+
+
+
+

+4.2.5. http(s) References with Fragment Identifiers +

+ +

+ Fragment identifiers allow for indirect identification + of a secondary resource, independent of the URI scheme, as defined in + Section 3.5 of [URI]. + Some protocol elements that refer to a URI allow inclusion of a fragment, + while others do not. They are distinguished by use of the ABNF rule for + elements where fragment is allowed; otherwise, a specific rule that excludes + fragments is used.¶

+ +
+
+
+
+
+
+

+4.3. Authoritative Access +

+

+ Authoritative access refers to dereferencing a given identifier, + for the sake of access to the identified resource, in a way that the client + believes is authoritative (controlled by the resource owner). The process + for determining whether access is granted is defined by the URI scheme and often uses + data within the URI components, such as the authority component when + the generic syntax is used. However, authoritative access is not limited to + the identified mechanism.¶

+

+ Section 4.3.1 defines the concept of an origin as an aid to + such uses, and the subsequent subsections explain how to establish that a + peer has the authority to represent an origin.¶

+

+ See Section 17.1 for security considerations + related to establishing authority.¶

+
+
+

+4.3.1. URI Origin +

+ + +

+ The "origin" for a given URI is the triple of scheme, host, + and port after normalizing the scheme and host to lowercase and + normalizing the port to remove any leading zeros. If port is elided from + the URI, the default port for that scheme is used. For example, the URI¶

+
+
+   https://Example.Com/happy.js
+
¶ +
+

+ would have the origin¶

+
+
+   { "https", "example.com", "443" }
+
¶ +
+

+ which can also be described as the normalized URI prefix with port always + present:¶

+
+
+   https://example.com:443
+
¶ +
+

+ Each origin defines its own namespace and controls how identifiers + within that namespace are mapped to resources. In turn, how the origin + responds to valid requests, consistently over time, determines the + semantics that users will associate with a URI, and the usefulness of + those semantics is what ultimately transforms these mechanisms into a + resource for users to reference and access in the future.¶

+

+ Two origins are distinct if they differ in scheme, host, or port. Even + when it can be verified that the same entity controls two distinct origins, + the two namespaces under those origins are distinct unless explicitly + aliased by a server authoritative for that origin.¶

+

+ Origin is also used within HTML and related Web protocols, beyond the + scope of this document, as described in [RFC6454].¶

+
+
+
+
+

+4.3.2. http Origins +

+

+ Although HTTP is independent of the transport protocol, the "http" scheme + (Section 4.2.1) is specific to associating authority with + whomever controls the origin + server listening for TCP connections on the indicated port of whatever + host is identified within the authority component. This is a very weak + sense of authority because it depends on both client-specific name + resolution mechanisms and communication that might not be secured from + an on-path attacker. Nevertheless, it is a sufficient minimum for + binding "http" identifiers to an origin server for consistent resolution + within a trusted environment.¶

+

+ If the host identifier is provided as an IP address, the origin server is + the listener (if any) on the indicated TCP port at that IP address. + If host is a registered name, the registered name is an indirect identifier + for use with a name resolution service, such as DNS, to find an address for + an appropriate origin server.¶

+

+ When an "http" URI is used within a context that calls for access to the + indicated resource, a client MAY attempt access by resolving the host + identifier to an IP address, establishing a TCP connection to that + address on the indicated port, and sending over that connection an HTTP + request message containing a request target that matches the client's + target URI (Section 7.1).¶

+

+ If the server responds to such a request with a non-interim HTTP response + message, as described in Section 15, then that response + is considered an authoritative answer to the client's request.¶

+

+ Note, however, that the above is not the only means for obtaining an + authoritative response, nor does it imply that an authoritative response + is always necessary (see [CACHING]). + For example, the Alt-Svc header field [ALTSVC] allows an + origin server to identify other services that are also authoritative for + that origin. Access to "http" identified resources might also be provided + by protocols outside the scope of this document.¶

+
+
+
+
+

+4.3.3. https Origins +

+

+ The "https" scheme (Section 4.2.2) associates authority based + on the ability of a server to use the private key corresponding to a + certificate that the client considers to be trustworthy for the identified + origin server. The client usually relies upon a chain of trust, conveyed + from some prearranged or configured trust anchor, to deem a certificate + trustworthy (Section 4.3.4).¶

+

+ In HTTP/1.1 and earlier, a client will only attribute authority to a server + when they are communicating over a successfully established and secured + connection specifically to that URI origin's host. The connection + establishment and certificate verification are used as proof of authority.¶

+

+ In HTTP/2 and HTTP/3, a client will attribute authority to a server when + they are communicating over a successfully established and secured + connection if the URI origin's host matches any of the hosts present in the + server's certificate and the client believes that it could open a connection + to that host for that URI. In practice, a client will make a DNS query to + check that the origin's host contains the same server IP address as the + established connection. This restriction can be removed by the origin server + sending an equivalent ORIGIN frame [RFC8336].¶

+

+ The request target's host and port value are passed within each HTTP + request, identifying the origin and distinguishing it from other namespaces + that might be controlled by the same server (Section 7.2). + It is the origin's responsibility to ensure that any services provided with + control over its certificate's private key are equally responsible for + managing the corresponding "https" namespaces or at least prepared to + reject requests that appear to have been misdirected + (Section 7.4).¶

+

+ An origin server might be unwilling to process requests for certain target + URIs even when they have the authority to do so. For example, when a host + operates distinct services on different ports (e.g., 443 and 8000), checking + the target URI at the origin server is necessary (even after the connection + has been secured) because a network attacker might cause connections for one + port to be received at some other port. Failing to check the target URI + might allow such an attacker to replace a response to one target URI + (e.g., "https://example.com/foo") with a seemingly authoritative response + from the other port (e.g., "https://example.com:8000/foo").¶

+

+ Note that the "https" scheme does not rely on TCP and the connected port + number for associating authority, since both are outside the secured + communication and thus cannot be trusted as definitive. Hence, the HTTP + communication might take place over any channel that has been secured, + as defined in Section 4.2.2, including protocols that don't + use TCP.¶

+

+ When an "https" URI is used within a context that calls for access to + the indicated resource, a client MAY attempt access by resolving the + host identifier to an IP address, establishing a TCP connection to that + address on the indicated port, securing the connection end-to-end by + successfully initiating TLS over TCP with confidentiality and integrity + protection, and sending over that connection an HTTP request message + containing a request target that matches the client's target URI + (Section 7.1).¶

+

+ If the server responds to such a request with a non-interim HTTP response + message, as described in Section 15, then that response + is considered an authoritative answer to the client's request.¶

+

+ Note, however, that the above is not the only means for obtaining an + authoritative response, nor does it imply that an authoritative response + is always necessary (see [CACHING]).¶

+
+
+
+
+

+4.3.4. https Certificate Verification +

+

+ To establish a secured connection to dereference a URI, + a client MUST verify that the service's identity is an acceptable + match for the URI's origin server. Certificate verification is used to + prevent server impersonation by an on-path attacker or by an attacker + that controls name resolution. This process requires that a client be + configured with a set of trust anchors.¶

+

+ In general, a client MUST verify the service identity using the + verification process defined in + Section 6 of [RFC6125]. The client MUST construct + a reference identity from the service's host: if the host is a literal IP address + (Section 4.3.5), the reference identity is an IP-ID, otherwise + the host is a name and the reference identity is a DNS-ID.¶

+

+ A reference identity of type CN-ID MUST NOT be used by clients. As noted + in Section 6.2.1 of [RFC6125], a reference + identity of type CN-ID might be used by older clients.¶

+

+ A client might be specially configured to accept an alternative form of + server identity verification. For example, a client might be connecting + to a server whose address and hostname are dynamic, with an expectation that + the service will present a specific certificate (or a certificate matching + some externally defined reference identity) rather than one matching the + target URI's origin.¶

+

+ In special cases, it might be appropriate for + a client to simply ignore the server's identity, but it must be + understood that this leaves a connection open to active attack.¶

+

+ If the certificate is not valid for the target URI's origin, + a user agent MUST either obtain confirmation from the user + before proceeding (see Section 3.5) or + terminate the connection with a bad certificate error. Automated + clients MUST log the error to an appropriate audit log (if available) + and SHOULD terminate the connection (with a bad certificate error). + Automated clients MAY provide a configuration setting that disables + this check, but MUST provide a setting which enables it.¶

+
+
+
+
+

+4.3.5. IP-ID Reference Identity +

+

+ A server that is identified using an IP address literal in the "host" field + of an "https" URI has a reference identity of type IP-ID. An IP version 4 + address uses the "IPv4address" ABNF rule, and an IP version 6 address uses + the "IP-literal" production with the "IPv6address" option; see + Section 3.2.2 of [URI]. A reference identity of + IP-ID contains the decoded bytes of the IP address.¶

+

+ An IP version 4 address is 4 octets, and an IP version 6 address is 16 octets. + Use of IP-ID is not defined for any other IP version. The iPAddress + choice in the certificate subjectAltName extension does not explicitly + include the IP version and so relies on the length of the address to + distinguish versions; see + Section 4.2.1.6 of [RFC5280].¶

+

+ A reference identity of type IP-ID matches if the address is identical to + an iPAddress value of the subjectAltName extension of the certificate.¶

+
+
+
+
+
+
+
+
+

+5. Fields +

+ +

+ HTTP uses "fields" to provide data in the form of extensible + name/value pairs with a registered key namespace. Fields are sent and + received within the header and trailer sections of messages + (Section 6).¶

+
+
+

+5.1. Field Names +

+

+ A field name labels the corresponding field value as having the + semantics defined by that name. For example, the Date + header field is defined in Section 6.6.1 as containing the + origination timestamp for the message in which it appears.¶

+ +
+
  field-name     = token
+
¶ +
+

+ Field names are case-insensitive and ought to be registered within the + "Hypertext Transfer Protocol (HTTP) Field Name Registry"; see Section 16.3.1.¶

+

+ The interpretation of a field does not change between minor + versions of the same major HTTP version, though the default behavior of a + recipient in the absence of such a field can change. Unless specified + otherwise, fields are defined for all versions of HTTP. + In particular, the Host and Connection + fields ought to be recognized by all HTTP implementations + whether or not they advertise conformance with HTTP/1.1.¶

+

+ New fields can be introduced without changing the protocol version if + their defined semantics allow them to be safely ignored by recipients + that do not recognize them; see Section 16.3.¶

+

+ A proxy MUST forward unrecognized header fields unless the + field name is listed in the Connection header field + (Section 7.6.1) or the proxy is specifically + configured to block, or otherwise transform, such fields. + Other recipients SHOULD ignore unrecognized header and trailer fields. + Adhering to these requirements allows HTTP's functionality to be extended + without updating or removing deployed intermediaries.¶

+
+
+
+
+

+5.2. Field Lines and Combined Field Value +

+

+ + + + Field sections are composed of any number of "field lines", + each with a "field name" (see Section 5.1) + identifying the field, and a "field line value" that conveys + data for that instance of the field.¶

+

+ + When a field name is only present once in a section, the combined + "field value" for that field consists of the corresponding + field line value. + When a field name is repeated within a section, its combined field value + consists of the list of corresponding field line values within that section, + concatenated in order, with each field line value separated by a comma.¶

+

+ For example, this section:¶

+
+
Example-Field: Foo, Bar
+Example-Field: Baz
+
¶ +
+

+ contains two field lines, both with the field name "Example-Field". The + first field line has a field line value of "Foo, Bar", while the second + field line value is "Baz". The field value for "Example-Field" is the list + "Foo, Bar, Baz".¶

+
+
+
+
+

+5.3. Field Order +

+

+ A recipient MAY combine multiple field lines within a field section that + have the same field name + into one field line, without changing the semantics of the message, by + appending each subsequent field line value to the initial field line value + in order, separated by a comma (",") and optional whitespace + (OWS, defined in Section 5.6.3). + For consistency, use comma SP.¶

+

+ The order in which field lines with the + same name are received is therefore significant to the interpretation of + the field value; a proxy MUST NOT change the order of these field line + values when forwarding a message.¶

+

+ This means that, aside from the well-known exception noted below, a sender + MUST NOT generate multiple field lines with the same name in a message + (whether in the headers or trailers) or append a field line when a field + line of the same name already exists in the message, unless that field's + definition allows multiple field line values to be recombined as a + comma-separated list (i.e., at least one alternative of the field's + definition allows a comma-separated list, such as an ABNF rule of + #(values) defined in Section 5.6.1).¶

+ +

+ The order in which field lines with differing field names are received in a + section is not significant. However, it is good practice to send header + fields that contain additional control data first, such as + Host on requests and Date on responses, so + that implementations can decide when not to handle a message as early as + possible.¶

+

+ A server MUST NOT apply a request to the target resource until it + receives the entire request header section, since later header field lines + might include conditionals, authentication credentials, or deliberately + misleading duplicate header fields that could impact request processing.¶

+
+
+
+
+

+5.4. Field Limits +

+

+ HTTP does not place a predefined limit on the length of each field line, field value, + or on the length of a header or trailer section as a whole, as described in + Section 2. Various ad hoc limitations on individual + lengths are found in practice, often depending on the specific + field's semantics.¶

+

+ A server that receives a request header field line, field value, or set of + fields larger than it wishes to process MUST respond with an appropriate + 4xx (Client Error) status code. Ignoring such header fields + would increase the server's vulnerability to request smuggling attacks + (Section 11.2 of [HTTP/1.1]).¶

+

+ A client MAY discard or truncate received field lines that are larger + than the client wishes to process if the field semantics are such that the + dropped value(s) can be safely ignored without changing the + message framing or response semantics.¶

+
+
+
+
+

+5.5. Field Values +

+

+ HTTP field values consist of a sequence of characters in a format defined + by the field's grammar. Each field's grammar is usually defined using + ABNF ([RFC5234]).¶

+ + + + +
+
  field-value    = *field-content
+  field-content  = field-vchar
+                   [ 1*( SP / HTAB / field-vchar ) field-vchar ]
+  field-vchar    = VCHAR / obs-text
+  obs-text       = %x80-FF
+
¶ +
+

+ A field value does not include leading or trailing whitespace. When a + specific version of HTTP allows such whitespace to appear in a message, + a field parsing implementation MUST exclude such whitespace prior to + evaluating the field value.¶

+

+ Field values are usually constrained to the range of US-ASCII characters + [USASCII]. + Fields needing a greater range of characters can use an encoding, + such as the one defined in [RFC8187]. + Historically, HTTP allowed field content with text in the ISO-8859-1 + charset [ISO-8859-1], supporting other charsets only + through use of [RFC2047] encoding. + Specifications for newly defined fields SHOULD limit their values to + visible US-ASCII octets (VCHAR), SP, and HTAB. + A recipient SHOULD treat other allowed octets in field content + (i.e., obs-text) as opaque data.¶

+

+ Field values containing CR, LF, or NUL characters are invalid and dangerous, + due to the varying ways that implementations might parse and interpret + those characters; a recipient of CR, LF, or NUL within a field value MUST + either reject the message or replace each of those characters with SP + before further processing or forwarding of that message. Field values + containing other CTL characters are also invalid; however, + recipients MAY retain such characters for the sake of robustness when + they appear within a safe context (e.g., an application-specific quoted + string that will not be processed by any downstream HTTP parser).¶

+

+ + Fields that only anticipate a single member as the field value are + referred to as "singleton fields".¶

+

+ + Fields that allow multiple members as the field value are referred to as + "list-based fields". The list operator extension of + Section 5.6.1 is used as a common notation for defining + field values that can contain multiple members.¶

+

+ Because commas (",") are used as the delimiter between members, they need + to be treated with care if they are allowed as data within a member. This + is true for both list-based and singleton fields, since a singleton field + might be erroneously sent with multiple members and detecting such errors + improves interoperability. Fields that expect to contain a + comma within a member, such as within an HTTP-date or + URI-reference + element, ought to be defined with delimiters around that element to + distinguish any comma within that data from potential list separators.¶

+

+ For example, a textual date and a URI (either of which might contain a comma) + could be safely carried in list-based field values like these:¶

+
+
Example-URIs: "http://example.com/a.html,foo",
+              "http://without-a-comma.example.com/"
+Example-Dates: "Sat, 04 May 1996", "Wed, 14 Sep 2005"
+
¶ +
+

+ Note that double-quote delimiters are almost always used with the + quoted-string production (Section 5.6.4); using a different syntax inside double-quotes + will likely cause unnecessary confusion.¶

+

+ Many fields (such as Content-Type, defined in + Section 8.3) use a common syntax for parameters + that allows both unquoted (token) and quoted (quoted-string) syntax for + a parameter value (Section 5.6.6). Use of common syntax + allows recipients to reuse existing parser components. When allowing both + forms, the meaning of a parameter value ought to be the same whether it + was received as a token or a quoted string.¶

+ +
+
+
+
+

+5.6. Common Rules for Defining Field Values +

+
+
+

+5.6.1. Lists (#rule ABNF Extension) +

+

+ A #rule extension to the ABNF rules of [RFC5234] is used to + improve readability in the definitions of some list-based field values.¶

+

+ A construct "#" is defined, similar to "*", for defining comma-delimited + lists of elements. The full form is "<n>#<m>element" indicating + at least <n> and at most <m> elements, each separated by a single + comma (",") and optional whitespace (OWS, + defined in Section 5.6.3).¶

+
+
+
+5.6.1.1. Sender Requirements +
+

+ In any production that uses the list construct, a sender MUST NOT + generate empty list elements. In other words, a sender has to generate + lists that satisfy the following syntax:¶

+
+
+  1#element => element *( OWS "," OWS element )
+
¶ +
+

+ and:¶

+
+
+  #element => [ 1#element ]
+
¶ +
+

+ and for n >= 1 and m > 1:¶

+
+
+  <n>#<m>element => element <n-1>*<m-1>( OWS "," OWS element )
+
¶ +
+

+ Appendix A shows the collected ABNF for senders + after the list constructs have been expanded.¶

+
+
+
+
+
+5.6.1.2. Recipient Requirements +
+

+ Empty elements do not contribute to the count of elements present. + A recipient MUST parse and ignore + a reasonable number of empty list elements: enough to handle common mistakes + by senders that merge values, but not so much that they could be used as a + denial-of-service mechanism. In other words, a recipient MUST accept lists + that satisfy the following syntax:¶

+
+
+  #element => [ element ] *( OWS "," OWS [ element ] )
+
¶ +
+

+ Note that because of the potential presence of empty list elements, the + RFC 5234 ABNF cannot enforce the cardinality of list elements, and + consequently all cases are mapped as if there was no cardinality specified.¶

+

+ For example, given these ABNF productions:¶

+
+
+  example-list      = 1#example-list-elmt
+  example-list-elmt = token ; see Section 5.6.2
+
¶ +
+

+ Then the following are valid values for example-list (not including the + double quotes, which are present for delimitation only):¶

+
+
+  "foo,bar"
+  "foo ,bar,"
+  "foo , ,bar,charlie"
+
¶ +
+

+ In contrast, the following values would be invalid, since at least one + non-empty element is required by the example-list production:¶

+
+
+  ""
+  ","
+  ",   ,"
+
¶ +
+
+
+
+
+
+
+

+5.6.2. Tokens +

+
+

+ + + Tokens are short textual identifiers that do not include whitespace or + delimiters.¶

+
+ + +
+
  token          = 1*tchar
+
+  tchar          = "!" / "#" / "$" / "%" / "&" / "'" / "*"
+                 / "+" / "-" / "." / "^" / "_" / "`" / "|" / "~"
+                 / DIGIT / ALPHA
+                 ; any VCHAR, except delimiters
+
¶ +
+
+

+ + Many HTTP field values are defined using common syntax + components, separated by whitespace or specific delimiting characters. + Delimiters are chosen from the set of US-ASCII visual characters not + allowed in a token (DQUOTE and "(),/:;<=>?@[\]{}").¶

+
+
+
+
+
+

+5.6.3. Whitespace +

+

+ This specification uses three rules to denote the use of linear + whitespace: OWS (optional whitespace), RWS (required whitespace), and + BWS ("bad" whitespace).¶

+

+ The OWS rule is used where zero or more linear whitespace octets might + appear. For protocol elements where optional whitespace is preferred to + improve readability, a sender SHOULD generate the optional whitespace + as a single SP; otherwise, a sender SHOULD NOT generate optional + whitespace except as needed to overwrite invalid or unwanted protocol + elements during in-place message filtering.¶

+

+ The RWS rule is used when at least one linear whitespace octet is required + to separate field tokens. A sender SHOULD generate RWS as a single SP.¶

+

+ OWS and RWS have the same semantics as a single SP. Any content known to + be defined as OWS or RWS MAY be replaced with a single SP before + interpreting it or forwarding the message downstream.¶

+

+ The BWS rule is used where the grammar allows optional whitespace only for + historical reasons. A sender MUST NOT generate BWS in messages. + A recipient MUST parse for such bad whitespace and remove it before + interpreting the protocol element.¶

+

+ BWS has no semantics. Any content known to be + defined as BWS MAY be removed before interpreting it or forwarding the + message downstream.¶

+ + + +
+
  OWS            = *( SP / HTAB )
+                 ; optional whitespace
+  RWS            = 1*( SP / HTAB )
+                 ; required whitespace
+  BWS            = OWS
+                 ; "bad" whitespace
+
¶ +
+
+
+
+
+

+5.6.4. Quoted Strings +

+
+

+ + + A string of text is parsed as a single value if it is quoted using + double-quote marks.¶

+
+ + +
+
  quoted-string  = DQUOTE *( qdtext / quoted-pair ) DQUOTE
+  qdtext         = HTAB / SP / %x21 / %x23-5B / %x5D-7E / obs-text
+
¶ +
+
+

+ + The backslash octet ("\") can be used as a single-octet + quoting mechanism within quoted-string and comment constructs. + Recipients that process the value of a quoted-string MUST handle a + quoted-pair as if it were replaced by the octet following the backslash.¶

+
+ +
+
  quoted-pair    = "\" ( HTAB / SP / VCHAR / obs-text )
+
¶ +
+

+ A sender SHOULD NOT generate a quoted-pair in a quoted-string except + where necessary to quote DQUOTE and backslash octets occurring within that + string. + A sender SHOULD NOT generate a quoted-pair in a comment except + where necessary to quote parentheses ["(" and ")"] and backslash octets + occurring within that comment.¶

+
+
+
+
+

+5.6.5. Comments +

+
+

+ + + Comments can be included in some HTTP fields by surrounding + the comment text with parentheses. Comments are only allowed in + fields containing "comment" as part of their field value definition.¶

+
+ + +
+
  comment        = "(" *( ctext / quoted-pair / comment ) ")"
+  ctext          = HTAB / SP / %x21-27 / %x2A-5B / %x5D-7E / obs-text
+
¶ +
+
+
+
+
+

+5.6.6. Parameters +

+
+

+ + + + Parameters are instances of name/value pairs; they are often used in field + values as a common syntax for appending auxiliary information to an item. + Each parameter is usually delimited by an immediately preceding semicolon.¶

+
+ + + + +
+
  parameters      = *( OWS ";" OWS [ parameter ] )
+  parameter       = parameter-name "=" parameter-value
+  parameter-name  = token
+  parameter-value = ( token / quoted-string )
+
¶ +
+

+ Parameter names are case-insensitive. Parameter values might or might + not be case-sensitive, depending on the semantics of the parameter + name. Examples of parameters and some equivalent forms can be seen in + media types (Section 8.3.1) and the Accept header field + (Section 12.5.1).¶

+

+ A parameter value that matches the token production can be + transmitted either as a token or within a quoted-string. The quoted and + unquoted values are equivalent.¶

+ +
+
+
+
+

+5.6.7. Date/Time Formats +

+ +

+ Prior to 1995, there were three different formats commonly used by servers + to communicate timestamps. For compatibility with old implementations, all + three are defined here. The preferred format is a fixed-length and + single-zone subset of the date and time specification used by the + Internet Message Format [RFC5322].¶

+ +
+
  HTTP-date    = IMF-fixdate / obs-date
+
¶ +
+

+ An example of the preferred format is¶

+
+
+  Sun, 06 Nov 1994 08:49:37 GMT    ; IMF-fixdate
+
¶ +
+

+ Examples of the two obsolete formats are¶

+
+
+  Sunday, 06-Nov-94 08:49:37 GMT   ; obsolete RFC 850 format
+  Sun Nov  6 08:49:37 1994         ; ANSI C's asctime() format
+
¶ +
+

+ A recipient that parses a timestamp value in an HTTP field MUST + accept all three HTTP-date formats. When a sender generates a field + that contains one or more timestamps defined as HTTP-date, + the sender MUST generate those timestamps in the IMF-fixdate format.¶

+

+ An HTTP-date value represents time as an instance of Coordinated + Universal Time (UTC). The first two formats indicate UTC by the + three-letter abbreviation for Greenwich Mean Time, "GMT", a predecessor + of the UTC name; values in the asctime format are assumed to be in UTC.¶

+

+ A "clock" is an implementation capable of providing a + reasonable approximation of the current instant in UTC. + A clock implementation ought to use NTP ([RFC5905]), + or some similar protocol, to synchronize with UTC.¶

+
+

+ + + + + + + + + + + Preferred format:¶

+
+ + + + + + + + + + + + +
+
  IMF-fixdate  = day-name "," SP date1 SP time-of-day SP GMT
+  ; fixed length/zone/capitalization subset of the format
+  ; see Section 3.3 of [RFC5322]
+
+  day-name     = %s"Mon" / %s"Tue" / %s"Wed"
+               / %s"Thu" / %s"Fri" / %s"Sat" / %s"Sun"
+
+  date1        = day SP month SP year
+               ; e.g., 02 Jun 1982
+
+  day          = 2DIGIT
+  month        = %s"Jan" / %s"Feb" / %s"Mar" / %s"Apr"
+               / %s"May" / %s"Jun" / %s"Jul" / %s"Aug"
+               / %s"Sep" / %s"Oct" / %s"Nov" / %s"Dec"
+  year         = 4DIGIT
+
+  GMT          = %s"GMT"
+
+  time-of-day  = hour ":" minute ":" second
+               ; 00:00:00 - 23:59:60 (leap second)
+
+  hour         = 2DIGIT
+  minute       = 2DIGIT
+  second       = 2DIGIT
+
¶ +
+
+

+ + + + + + + + Obsolete formats:¶

+
+ +
+
  obs-date     = rfc850-date / asctime-date
+
¶ +
+ +
+
  rfc850-date  = day-name-l "," SP date2 SP time-of-day SP GMT
+  date2        = day "-" month "-" 2DIGIT
+               ; e.g., 02-Jun-82
+
+  day-name-l   = %s"Monday" / %s"Tuesday" / %s"Wednesday"
+               / %s"Thursday" / %s"Friday" / %s"Saturday"
+               / %s"Sunday"
+
¶ +
+ +
+
  asctime-date = day-name SP date3 SP time-of-day SP year
+  date3        = month SP ( 2DIGIT / ( SP 1DIGIT ))
+               ; e.g., Jun  2
+
¶ +
+

+ HTTP-date is case sensitive. Note that Section 4.2 of [CACHING] relaxes this for cache recipients.¶

+

+ A sender MUST NOT generate additional whitespace in an HTTP-date beyond + that specifically included as SP in the grammar. + The semantics of day-name, day, + month, year, and time-of-day + are the same as those defined for the Internet Message Format constructs + with the corresponding name ([RFC5322], Section 3.3).¶

+

+ Recipients of a timestamp value in rfc850-date format, which uses a + two-digit year, MUST interpret a timestamp that appears to be more + than 50 years in the future as representing the most recent year in the + past that had the same last two digits.¶

+

+ Recipients of timestamp values are encouraged to be robust in parsing + timestamps unless otherwise restricted by the field definition. + For example, messages are occasionally forwarded over HTTP from a non-HTTP + source that might generate any of the date and time specifications defined + by the Internet Message Format.¶

+ +
+
+
+
+
+
+
+
+

+6. Message Abstraction +

+ + + +

+ Each major version of HTTP defines its own syntax for communicating + messages. This section defines an abstract data type for HTTP messages + based on a generalization of those message characteristics, common structure, + and capacity for conveying semantics. This abstraction is used to define + requirements on senders and recipients that are independent of the HTTP + version, such that a message in one version can be relayed through other + versions without changing its meaning.¶

+

+ A "message" consists of the following:¶

+
    +
  • control data to describe and route the message,¶ +
    • +
  • a headers lookup table of name/value pairs for extending that control + data and conveying additional information about the sender, message, + content, or context,¶ +
    • +
  • a potentially unbounded stream of content, and¶ +
    • +
  • a trailers lookup table of name/value pairs for communicating information + obtained while sending the content.¶ +
    • +
+

+ Framing and control data is sent first, followed by a header section + containing fields for the headers table. When a message includes content, + the content is sent after the header section, potentially followed by a + trailer section that might contain fields for the trailers table.¶

+

+ Messages are expected to be processed as a stream, wherein the purpose of + that stream and its continued processing is revealed while being read. + Hence, control data describes what the recipient needs to know immediately, + header fields describe what needs to be known before receiving content, + the content (when present) presumably contains what the recipient wants or + needs to fulfill the message semantics, and trailer fields provide + optional metadata that was unknown prior to sending the content.¶

+

+ Messages are intended to be "self-descriptive": + everything a recipient needs to know about the message can be determined by + looking at the message itself, after decoding or reconstituting parts that + have been compressed or elided in transit, without requiring an + understanding of the sender's current application state (established via + prior messages). However, a client MUST retain knowledge of the request when + parsing, interpreting, or caching a corresponding response. For example, + responses to the HEAD method look just like the beginning of a + response to GET but cannot be parsed in the same manner.¶

+

+ Note that this message abstraction is a generalization across many versions + of HTTP, including features that might not be found in some versions. For + example, trailers were introduced within the HTTP/1.1 chunked transfer + coding as a trailer section after the content. An equivalent feature is + present in HTTP/2 and HTTP/3 within the header block that terminates each + stream.¶

+
+
+

+6.1. Framing and Completeness +

+ + +

+ Message framing indicates how each message begins and ends, such that each + message can be distinguished from other messages or noise on the same + connection. Each major version of HTTP defines its own framing mechanism.¶

+

+ HTTP/0.9 and early deployments of HTTP/1.0 used closure of the underlying + connection to end a response. For backwards compatibility, this implicit + framing is also allowed in HTTP/1.1. However, implicit framing can fail to + distinguish an incomplete response if the connection closes early. For + that reason, almost all modern implementations use explicit framing in + the form of length-delimited sequences of message data.¶

+

+ A message is considered "complete" when all of the octets + indicated by its framing are available. Note that, + when no explicit framing is used, a response message that is ended + by the underlying connection's close is considered complete even though it + might be indistinguishable from an incomplete response, unless a + transport-level error indicates that it is not complete.¶

+
+
+
+
+

+6.2. Control Data +

+ +

+ Messages start with control data that describe its primary purpose. Request + message control data includes a request method (Section 9), + request target (Section 7.1), and protocol version + (Section 2.5). Response message control data includes + a status code (Section 15), optional reason phrase, and + protocol version.¶

+

+ In HTTP/1.1 ([HTTP/1.1]) and earlier, control data is sent + as the first line of a message. In HTTP/2 ([HTTP/2]) and + HTTP/3 ([HTTP/3]), control data is sent as pseudo-header + fields with a reserved name prefix (e.g., ":authority").¶

+

+ Every HTTP message has a protocol version. Depending on the version in use, + it might be identified within the message explicitly or inferred by the + connection over which the message is received. Recipients use that version + information to determine limitations or potential for later communication + with that sender.¶

+

+ When a message is forwarded by an intermediary, the protocol version is + updated to reflect the version used by that intermediary. + The Via header field (Section 7.6.3) is used to + communicate upstream protocol information within a forwarded message.¶

+

+ A client SHOULD send a request version equal to the highest + version to which the client is conformant and + whose major version is no higher than the highest version supported + by the server, if this is known. A client MUST NOT send a + version to which it is not conformant.¶

+

+ A client MAY send a lower request version if it is known that + the server incorrectly implements the HTTP specification, but only + after the client has attempted at least one normal request and determined + from the response status code or header fields (e.g., Server) that + the server improperly handles higher request versions.¶

+

+ A server SHOULD send a response version equal to the highest version to + which the server is conformant that has a major version less than or equal + to the one received in the request. + A server MUST NOT send a version to which it is not conformant. + A server can send a 505 (HTTP Version Not Supported) + response if it wishes, for any reason, to refuse service of the client's + major protocol version.¶

+

+ A recipient that receives a message with a major version number that it + implements and a minor version number higher than what it implements + SHOULD process the message as if it + were in the highest minor version within that major version to which the + recipient is conformant. A recipient can assume that a message with a + higher minor version, when sent to a recipient that has not yet indicated + support for that higher version, is sufficiently backwards-compatible to be + safely processed by any implementation of the same major version.¶

+
+
+
+
+

+6.3. Header Fields +

+ + +

+ Fields (Section 5) that are sent or received before the content + are referred to as "header fields" (or just "headers", colloquially).¶

+

+ The "header section" of a message consists of a sequence of + header field lines. Each header field might modify or extend message + semantics, describe the sender, define the content, or provide additional + context.¶

+ +
+
+
+
+

+6.4. Content +

+ +

+ HTTP messages often transfer a complete or partial representation as the + message "content": a stream of octets sent after the header + section, as delineated by the message framing.¶

+

+ This abstract definition of content reflects the data after it has been + extracted from the message framing. For example, an HTTP/1.1 message body + (Section 6 of [HTTP/1.1]) might consist of a stream of data encoded + with the chunked transfer coding -- a sequence of data chunks, one + zero-length chunk, and a trailer section -- whereas + the content of that same message + includes only the data stream after the transfer coding has been decoded; + it does not include the chunk lengths, chunked framing syntax, nor the + trailer fields (Section 6.5).¶

+ +
+
+

+6.4.1. Content Semantics +

+

+ The purpose of content in a request is defined by the method semantics + (Section 9).¶

+

+ For example, a representation in the content of a PUT request + (Section 9.3.4) represents the desired state of the + target resource after the request is successfully applied, + whereas a representation in the content of a POST request + (Section 9.3.3) represents information to be processed by the + target resource.¶

+

+ In a response, the content's purpose is defined by the request method, + response status code (Section 15), and response + fields describing that content. + For example, the content of a 200 (OK) response to GET + (Section 9.3.1) represents the current state of the + target resource, as observed at the time of the message + origination date (Section 6.6.1), whereas the content of + the same status code in a response to POST might represent either the + processing result or the new state of the target resource after applying + the processing.¶

+

+ The content of a 206 (Partial Content) response to GET + contains either a single part of the selected representation or a + multipart message body containing multiple parts of that representation, + as described in Section 15.3.7.¶

+

+ Response messages with an error status code usually contain content that + represents the error condition, such that the content describes the + error state and what steps are suggested for resolving it.¶

+

+ Responses to the HEAD request method (Section 9.3.2) never include + content; the associated response header fields indicate only + what their values would have been if the request method had been GET + (Section 9.3.1).¶

+

+ 2xx (Successful) responses to a CONNECT request method + (Section 9.3.6) switch the connection to tunnel mode instead of + having content.¶

+

+ All 1xx (Informational), 204 (No Content), and + 304 (Not Modified) responses do not include content.¶

+

+ All other responses do include content, although that content + might be of zero length.¶

+
+
+
+
+

+6.4.2. Identifying Content +

+

+ When a complete or partial representation is transferred as message + content, it is often desirable for the sender to supply, or the recipient + to determine, an identifier for a resource corresponding to that specific + representation. For example, a client making a GET request on a resource + for "the current weather report" might want an identifier specific to the + content returned (e.g., "weather report for Laguna Beach at 20210720T1711"). + This can be useful for sharing or bookmarking content from resources that + are expected to have changing representations over time.¶

+

+ For a request message:¶

+
    +
  • If the request has a Content-Location header field, + then the sender asserts that the content is a representation of the + resource identified by the Content-Location field value. However, + such an assertion cannot be trusted unless it can be verified by + other means (not defined by this specification). The information + might still be useful for revision history links.¶ +
    • +
  • Otherwise, the content is unidentified by HTTP, but a more specific + identifier might be supplied within the content itself.¶ +
    • +
+

+ For a response message, the following rules are applied in order until a + match is found:¶

+
    +
  1. If the request method is HEAD or the response status code is + 204 (No Content) or 304 (Not Modified), + there is no content in the response.¶ +
    2. +
  2. If the request method is GET and the response status code is + 200 (OK), + the content is a representation of the target resource (Section 7.1).¶ +
    3. +
  3. If the request method is GET and the response status code is + 203 (Non-Authoritative Information), the content is + a potentially modified or enhanced representation of the + target resource as provided by an intermediary.¶ +
    4. +
  4. If the request method is GET and the response status code is + 206 (Partial Content), + the content is one or more parts of a representation of the + target resource.¶ +
    5. +
  5. If the response has a Content-Location header field + and its field value is a reference to the same URI as the target URI, + the content is a representation of the target resource.¶ +
    6. +
  6. If the response has a Content-Location header field + and its field value is a reference to a URI different from the + target URI, then the sender asserts that the content is a + representation of the resource identified by the Content-Location + field value. However, such an assertion cannot be trusted unless + it can be verified by other means (not defined by this specification).¶ +
    7. +
  7. Otherwise, the content is unidentified by HTTP, but a more specific + identifier might be supplied within the content itself.¶ +
    8. +
+
+
+
+
+
+
+

+6.5. Trailer Fields +

+ + + +

+ Fields (Section 5) that are located within a + "trailer section" are referred to as "trailer fields" + (or just "trailers", colloquially). + Trailer fields can be useful for supplying message integrity checks, digital + signatures, delivery metrics, or post-processing status information.¶

+

+ Trailer fields ought to be processed and stored separately from the fields + in the header section to avoid contradicting message semantics known at + the time the header section was complete. The presence or absence of + certain header fields might impact choices made for the routing or + processing of the message as a whole before the trailers are received; + those choices cannot be unmade by the later discovery of trailer fields.¶

+
+
+

+6.5.1. Limitations on Use of Trailers +

+

+ A trailer section is only possible when supported by the version + of HTTP in use and enabled by an explicit framing mechanism. + For example, the chunked transfer coding in HTTP/1.1 allows a trailer section to be + sent after the content (Section 7.1.2 of [HTTP/1.1]).¶

+

+ Many fields cannot be processed outside the header section because + their evaluation is necessary prior to receiving the content, such as + those that describe message framing, routing, authentication, + request modifiers, response controls, or content format. + A sender MUST NOT generate a trailer field unless the sender knows the + corresponding header field name's definition permits the field to be sent + in trailers.¶

+

+ Trailer fields can be difficult to process by intermediaries that forward + messages from one protocol version to another. If the entire message can be + buffered in transit, some intermediaries could merge trailer fields into + the header section (as appropriate) before it is forwarded. However, in + most cases, the trailers are simply discarded. + A recipient MUST NOT merge a trailer field into a header section unless + the recipient understands the corresponding header field definition and + that definition explicitly permits and defines how trailer field values + can be safely merged.¶

+

+ The presence of the keyword "trailers" in the TE header field (Section 10.1.4) of a request indicates that the client is willing to + accept trailer fields, on behalf of itself and any downstream clients. For + requests from an intermediary, this implies that all + downstream clients are willing to accept trailer fields in the forwarded + response. Note that the presence of "trailers" does not mean that the + client(s) will process any particular trailer field in the response; only + that the trailer section(s) will not be dropped by any of the clients.¶

+

+ Because of the potential for trailer fields to be discarded in transit, a + server SHOULD NOT generate trailer fields that it believes are necessary + for the user agent to receive.¶

+
+
+
+
+

+6.5.2. Processing Trailer Fields +

+

+ The "Trailer" header field (Section 6.6.2) can be sent + to indicate fields likely to be sent in the trailer section, which allows + recipients to prepare for their receipt before processing the content. + For example, this could be useful if a field name indicates that a dynamic + checksum should be calculated as the content is received and then + immediately checked upon receipt of the trailer field value.¶

+

+ Like header fields, trailer fields with the same name are processed in the + order received; multiple trailer field lines with the same name have the + equivalent semantics as appending the multiple values as a list of members. + Trailer fields that might be generated more than once during a message + MUST be defined as a list-based field even if each member value is only + processed once per field line received.¶

+

+ At the end of a message, a recipient MAY treat the set of received + trailer fields as a data structure of name/value pairs, similar to (but + separate from) the header fields. Additional processing expectations, if + any, can be defined within the field specification for a field intended + for use in trailers.¶

+
+
+
+
+
+
+

+6.6. Message Metadata +

+

+ Fields that describe the message itself, such as when and how the + message has been generated, can appear in both requests and responses.¶

+
+
+

+6.6.1. Date +

+ + + +

+ The "Date" header field represents the date and time at which + the message was originated, having the same semantics as the Origination + Date Field (orig-date) defined in Section 3.6.1 of [RFC5322]. + The field value is an HTTP-date, as defined in Section 5.6.7.¶

+ +
+
  Date = HTTP-date
+
¶ +
+

+ An example is¶

+
+
Date: Tue, 15 Nov 1994 08:12:31 GMT
+
¶ +
+

+ A sender that generates a Date header field SHOULD generate its + field value as the best available approximation of the date and time of + message generation. In theory, the date ought to represent the moment just + before generating the message content. In practice, a sender can generate + the date value at any time during message origination.¶

+

+ An origin server with a clock (as defined in + Section 5.6.7) MUST generate a Date header field in + all 2xx (Successful), 3xx (Redirection), + and 4xx (Client Error) responses, + and MAY generate a Date header field in + 1xx (Informational) and + 5xx (Server Error) responses.¶

+

+ An origin server without a clock MUST NOT generate a Date header field.¶

+

+ A recipient with a clock that receives a response message without a Date + header field MUST record the time it was received and append a + corresponding Date header field to the message's header section if it is + cached or forwarded downstream.¶

+

+ A recipient with a clock that receives a response with an invalid Date + header field value MAY replace that value with the time that + response was received.¶

+

+ A user agent MAY send a Date header field in a request, though generally + will not do so unless it is believed to convey useful information to the + server. For example, custom applications of HTTP might convey a Date if + the server is expected to adjust its interpretation of the user's request + based on differences between the user agent and server clocks.¶

+
+
+
+
+

+6.6.2. Trailer +

+ + + +

+ The "Trailer" header field provides a list of field names that the sender + anticipates sending as trailer fields within that message. This allows a + recipient to prepare for receipt of the indicated metadata before it starts + processing the content.¶

+ + +
+
  Trailer = #field-name
+
¶ +
+

+ For example, a sender might indicate that a signature will + be computed as the content is being streamed and provide the final + signature as a trailer field. This allows a recipient to perform the same + check on the fly as it receives the content.¶

+

+ A sender that intends to generate one or more trailer fields in a message + SHOULD generate a Trailer header field in the header + section of that message to indicate which fields might be present in the + trailers.¶

+

+ If an intermediary discards the trailer section in transit, the + Trailer field could provide a hint of what metadata + was lost, though there is no guarantee that a sender of Trailer + will always follow through by sending the named fields.¶

+
+
+
+
+
+
+
+
+

+7. Routing HTTP Messages +

+

+ HTTP request message routing is determined by each client based on the + target resource, the client's proxy configuration, and + establishment or reuse of an inbound connection. The corresponding + response routing follows the same connection chain back to the client.¶

+
+
+

+7.1. Determining the Target Resource +

+ + + +

+ Although HTTP is used in a wide variety of applications, most clients rely + on the same resource identification mechanism and configuration techniques + as general-purpose Web browsers. Even when communication options are + hard-coded in a client's configuration, we can think of their combined + effect as a URI reference (Section 4.1).¶

+

+ A URI reference is resolved to its absolute form in order to obtain the + "target URI". The target URI excludes the reference's + fragment component, if any, since fragment identifiers are reserved for + client-side processing ([URI], Section 3.5).¶

+

+ To perform an action on a "target resource", the client sends + a request message containing enough components of its parsed target URI to + enable recipients to identify that same resource. For historical reasons, + the parsed target URI components, collectively referred to as the + "request target", are sent within the message control data + and the Host header field (Section 7.2).¶

+

+ There are two unusual cases for which the request target components are in + a method-specific form:¶

+
    +
  • + For CONNECT (Section 9.3.6), the request target is the host + name and port number of the tunnel destination, separated by a colon.¶ +
    • +
  • + For OPTIONS (Section 9.3.7), the request target can be a + single asterisk ("*").¶ +
    • +
+

+ See the respective method definitions for details. These forms MUST NOT + be used with other methods.¶

+

+ Upon receipt of a client's request, a server reconstructs the target URI + from the received components in accordance with their local configuration + and incoming connection context. This reconstruction is specific to each + major protocol version. For example, + Section 3.3 of [HTTP/1.1] defines how a server + determines the target URI of an HTTP/1.1 request.¶

+
+ +
+
+
+
+
+

+7.2. Host and :authority +

+ + + +

+ The "Host" header field in a request provides the host and port + information from the target URI, enabling the origin + server to distinguish among resources while servicing requests + for multiple host names.¶

+

+ In HTTP/2 [HTTP/2] and HTTP/3 [HTTP/3], the + Host header field is, in some cases, supplanted by the ":authority" + pseudo-header field of a request's control data.¶

+ +
+
  Host = uri-host [ ":" port ] ; Section 4
+
¶ +
+

+ The target URI's authority information is critical for handling a + request. A user agent MUST generate a Host header field in a request + unless it sends that information as an ":authority" pseudo-header field. + A user agent that sends Host SHOULD send it as the first field in the + header section of a request.¶

+

+ For example, a GET request to the origin server for + <http://www.example.org/pub/WWW/> would begin with:¶

+
+
GET /pub/WWW/ HTTP/1.1
+Host: www.example.org
+
¶ +
+

+ Since the host and port information acts as an application-level routing + mechanism, it is a frequent target for malware seeking to poison + a shared cache or redirect a request to an unintended server. + An interception proxy is particularly vulnerable if it relies on + the host and port information for redirecting requests to internal + servers, or for use as a cache key in a shared cache, without + first verifying that the intercepted connection is targeting a + valid IP address for that host.¶

+
+
+
+
+

+7.3. Routing Inbound Requests +

+

+ Once the target URI and its origin are determined, a client decides whether + a network request is necessary to accomplish the desired semantics and, + if so, where that request is to be directed.¶

+
+
+

+7.3.1. To a Cache +

+

+ If the client has a cache [CACHING] and the request can be + satisfied by it, then the request is + usually directed there first.¶

+
+
+
+
+

+7.3.2. To a Proxy +

+

+ If the request is not satisfied by a cache, then a typical client will + check its configuration to determine whether a proxy is to be used to + satisfy the request. Proxy configuration is implementation-dependent, + but is often based on URI prefix matching, selective authority matching, + or both, and the proxy itself is usually identified by an "http" or + "https" URI.¶

+

+ If an "http" or "https" proxy is applicable, the client connects + inbound by establishing (or reusing) a connection to that proxy and + then sending it an HTTP request message containing a request target + that matches the client's target URI.¶

+
+
+
+
+

+7.3.3. To the Origin +

+

+ If no proxy is applicable, a typical client will invoke a handler + routine (specific to the target URI's scheme) to obtain access to the + identified resource. How that is accomplished is dependent on the + target URI scheme and defined by its associated specification.¶

+

+ Section 4.3.2 defines how to obtain access to an + "http" resource by establishing (or reusing) an inbound connection to + the identified origin server and then sending it an HTTP request message + containing a request target that matches the client's target URI.¶

+

+ Section 4.3.3 defines how to obtain access to an + "https" resource by establishing (or reusing) an inbound secured + connection to an origin server that is authoritative for the identified + origin and then sending it an HTTP request message containing a request + target that matches the client's target URI.¶

+
+
+
+
+
+
+

+7.4. Rejecting Misdirected Requests +

+

+ Once a request is received by a server and parsed sufficiently to determine + its target URI, the server decides whether to process the request itself, + forward the request to another server, redirect the client to a different + resource, respond with an error, or drop the connection. This decision can + be influenced by anything about the request or connection context, but is + specifically directed at whether the server has been configured to process + requests for that target URI and whether the connection context is + appropriate for that request.¶

+

+ For example, a request might have been misdirected, + deliberately or accidentally, such that the information within a received + Host header field differs from the connection's host or port. + If the connection is from a trusted gateway, such inconsistency might + be expected; otherwise, it might indicate an attempt to bypass security + filters, trick the server into delivering non-public content, or poison a + cache. See Section 17 for security + considerations regarding message routing.¶

+

+ Unless the connection is from a trusted gateway, + an origin server MUST reject a request if any scheme-specific requirements + for the target URI are not met. In particular, + a request for an "https" resource MUST be rejected unless it has been + received over a connection that has been secured via a certificate + valid for that target URI's origin, as defined by Section 4.2.2.¶

+

+ The 421 (Misdirected Request) status code in a response + indicates that the origin server has rejected the request because it + appears to have been misdirected (Section 15.5.20).¶

+
+
+
+
+

+7.5. Response Correlation +

+

+ A connection might be used for multiple request/response exchanges. The + mechanism used to correlate between request and response messages is + version dependent; some versions of HTTP use implicit ordering of + messages, while others use an explicit identifier.¶

+

+ All responses, regardless of the status code (including interim + responses) can be sent at any time after a request is received, even if the + request is not yet complete. A response can complete before its + corresponding request is complete (Section 6.1). Likewise, clients are not expected + to wait any specific amount of time for a response. Clients + (including intermediaries) might abandon a request if the response is not + received within a reasonable period of time.¶

+

+ A client that receives a response while it is still sending the associated + request SHOULD continue sending that request unless it receives + an explicit indication to the contrary (see, e.g., Section 9.5 of [HTTP/1.1] and Section 6.4 of [HTTP/2]).¶

+
+
+
+
+

+7.6. Message Forwarding +

+

+ As described in Section 3.7, intermediaries can serve + a variety of roles in the processing of HTTP requests and responses. + Some intermediaries are used to improve performance or availability. + Others are used for access control or to filter content. + Since an HTTP stream has characteristics similar to a pipe-and-filter + architecture, there are no inherent limits to the extent an intermediary + can enhance (or interfere) with either direction of the stream.¶

+

+ Intermediaries are expected to forward messages even when protocol elements + are not recognized (e.g., new methods, status codes, or field names) since that + preserves extensibility for downstream recipients.¶

+

+ An intermediary not acting as a tunnel MUST implement the + Connection header field, as specified in + Section 7.6.1, and exclude fields from being forwarded + that are only intended for the incoming connection.¶

+

+ An intermediary MUST NOT forward a message to itself unless it is + protected from an infinite request loop. In general, an intermediary ought + to recognize its own server names, including any aliases, local variations, + or literal IP addresses, and respond to such requests directly.¶

+

+ An HTTP message can be parsed as a stream for incremental processing or + forwarding downstream. + However, senders and recipients cannot rely on incremental + delivery of partial messages, since some implementations will buffer or + delay message forwarding for the sake of network efficiency, security + checks, or content transformations.¶

+
+
+

+7.6.1. Connection +

+ + + + + +

+ The "Connection" header field allows the sender to list desired + control options for the current connection.¶

+
+
  Connection        = #connection-option
+  connection-option = token
+
¶ +
+

+ Connection options are case-insensitive.¶

+

+ When a field aside from Connection is used to supply control + information for or about the current connection, the sender MUST list + the corresponding field name within the Connection header field. + Note that some versions of HTTP prohibit the use of fields for such + information, and therefore do not allow the Connection field.¶

+

+ Intermediaries MUST parse a received Connection + header field before a message is forwarded and, for each + connection-option in this field, remove any header or trailer field(s) from + the message with the same name as the connection-option, and then + remove the Connection header field itself (or replace it with the + intermediary's own control options for the forwarded message).¶

+

+ Hence, the Connection header field provides a declarative way of + distinguishing fields that are only intended for the + immediate recipient ("hop-by-hop") from those fields that are + intended for all recipients on the chain ("end-to-end"), enabling the + message to be self-descriptive and allowing future connection-specific + extensions to be deployed without fear that they will be blindly + forwarded by older intermediaries.¶

+

+ Furthermore, intermediaries SHOULD remove or replace fields + that are known to require removal before forwarding, whether or not they appear as a + connection-option, after applying those fields' semantics. This includes but is not limited to:¶

+ +

+ A sender MUST NOT send a connection option corresponding to a + field that is intended for all recipients of the content. + For example, Cache-Control is never appropriate as a + connection option (Section 5.2 of [CACHING]).¶

+

+ Connection options do not always correspond to a field + present in the message, since a connection-specific field + might not be needed if there are no parameters associated with a + connection option. In contrast, a connection-specific field + received without a corresponding connection option usually indicates + that the field has been improperly forwarded by an intermediary and + ought to be ignored by the recipient.¶

+

+ When defining a new connection option that does not correspond to a field, + specification authors ought to reserve the corresponding field name + anyway in order to avoid later collisions. Such reserved field names are + registered in the "Hypertext Transfer Protocol (HTTP) Field Name Registry" + (Section 16.3.1).¶

+
+
+
+
+

+7.6.2. Max-Forwards +

+ + + +

+ The "Max-Forwards" header field provides a mechanism with the + TRACE (Section 9.3.8) and OPTIONS (Section 9.3.7) + request methods to limit the number of times that the request is forwarded by + proxies. This can be useful when the client is attempting to + trace a request that appears to be failing or looping mid-chain.¶

+ +
+
  Max-Forwards = 1*DIGIT
+
¶ +
+

+ The Max-Forwards value is a decimal integer indicating the remaining + number of times this request message can be forwarded.¶

+

+ Each intermediary that receives a TRACE or OPTIONS request containing a + Max-Forwards header field MUST check and update its value prior to + forwarding the request. If the received value is zero (0), the intermediary + MUST NOT forward the request; instead, the intermediary MUST respond as + the final recipient. If the received Max-Forwards value is greater than + zero, the intermediary MUST generate an updated Max-Forwards field in the + forwarded message with a field value that is the lesser of a) the received + value decremented by one (1) or b) the recipient's maximum supported value + for Max-Forwards.¶

+

+ A recipient MAY ignore a Max-Forwards header field received with any + other request methods.¶

+
+
+
+
+

+7.6.3. Via +

+ + + +

+ The "Via" header field indicates the presence of intermediate protocols and + recipients between the user agent and the server (on requests) or between + the origin server and the client (on responses), similar to the + "Received" header field in email + (Section 3.6.7 of [RFC5322]). + Via can be used for tracking message forwards, + avoiding request loops, and identifying the protocol capabilities of + senders along the request/response chain.¶

+ + + + + + +
+
  Via = #( received-protocol RWS received-by [ RWS comment ] )
+
+  received-protocol = [ protocol-name "/" ] protocol-version
+                    ; see Section 7.8
+  received-by       = pseudonym [ ":" port ]
+  pseudonym         = token
+
¶ +
+

+ Each member of the Via field value represents a proxy or gateway that has + forwarded the message. Each intermediary appends its own information + about how the message was received, such that the end result is ordered + according to the sequence of forwarding recipients.¶

+

+ A proxy MUST send an appropriate Via header field, as described below, in + each message that it forwards. + An HTTP-to-HTTP gateway MUST send an appropriate Via header field in + each inbound request message and MAY send a Via header field in + forwarded response messages.¶

+

+ For each intermediary, the received-protocol indicates the protocol and + protocol version used by the upstream sender of the message. Hence, the + Via field value records the advertised protocol capabilities of the + request/response chain such that they remain visible to downstream + recipients; this can be useful for determining what backwards-incompatible + features might be safe to use in response, or within a later request, as + described in Section 2.5. For brevity, the protocol-name + is omitted when the received protocol is HTTP.¶

+

+ The received-by portion is normally the host and optional + port number of a recipient server or client that subsequently forwarded the + message. + However, if the real host is considered to be sensitive information, a + sender MAY replace it with a pseudonym. If a port is not provided, + a recipient MAY interpret that as meaning it was received on the default + port, if any, for the received-protocol.¶

+

+ A sender MAY generate comments to identify the + software of each recipient, analogous to the User-Agent and + Server header fields. However, comments in Via + are optional, and a recipient MAY remove them prior to forwarding the + message.¶

+

+ For example, a request message could be sent from an HTTP/1.0 user + agent to an internal proxy code-named "fred", which uses HTTP/1.1 to + forward the request to a public proxy at p.example.net, which completes + the request by forwarding it to the origin server at www.example.com. + The request received by www.example.com would then have the following + Via header field:¶

+
+
Via: 1.0 fred, 1.1 p.example.net
+
¶ +
+

+ An intermediary used as a portal through a network firewall + SHOULD NOT forward the names and ports of hosts within the firewall + region unless it is explicitly enabled to do so. If not enabled, such an + intermediary SHOULD replace each received-by host of any host behind the + firewall by an appropriate pseudonym for that host.¶

+

+ An intermediary MAY combine an ordered subsequence of Via header + field list members into a single member if the entries have identical + received-protocol values. For example,¶

+
+
Via: 1.0 ricky, 1.1 ethel, 1.1 fred, 1.0 lucy
+
¶ +
+

+ could be collapsed to¶

+
+
Via: 1.0 ricky, 1.1 mertz, 1.0 lucy
+
¶ +
+

+ A sender SHOULD NOT combine multiple list members unless they are all + under the same organizational control and the hosts have already been + replaced by pseudonyms. A sender MUST NOT combine members that + have different received-protocol values.¶

+
+
+
+
+
+
+

+7.7. Message Transformations +

+ + +

+ Some intermediaries include features for transforming messages and their + content. A proxy might, for example, convert between image formats in + order to save cache space or to reduce the amount of traffic on a slow + link. However, operational problems might occur when these transformations + are applied to content intended for critical applications, such as medical + imaging or scientific data analysis, particularly when integrity checks or + digital signatures are used to ensure that the content received is + identical to the original.¶

+

+ An HTTP-to-HTTP proxy is called a "transforming proxy" + if it is designed or configured to modify messages in a semantically + meaningful way (i.e., modifications, beyond those required by normal + HTTP processing, that change the message in a way that would be + significant to the original sender or potentially significant to + downstream recipients). For example, a transforming proxy might be + acting as a shared annotation server (modifying responses to include + references to a local annotation database), a malware filter, a + format transcoder, or a privacy filter. Such transformations are presumed + to be desired by whichever client (or client organization) chose the + proxy.¶

+

+ If a proxy receives a target URI with a host name that is not a + fully qualified domain name, it MAY add its own domain to the host name + it received when forwarding the request. A proxy MUST NOT change the + host name if the target URI contains a fully qualified domain name.¶

+

+ A proxy MUST NOT modify the "absolute-path" and "query" parts of the + received target URI when forwarding it to the next inbound server except + as required by that forwarding protocol. For example, a proxy forwarding + a request to an origin server via HTTP/1.1 will replace an empty path with + "/" (Section 3.2.1 of [HTTP/1.1]) or "*" (Section 3.2.4 of [HTTP/1.1]), + depending on the request method.¶

+

+ A proxy MUST NOT transform the content (Section 6.4) of a + response message that contains a no-transform cache directive + (Section 5.2.2.6 of [CACHING]). Note that this + does not apply to message transformations that do not change the content, + such as the addition or removal of transfer codings + (Section 7 of [HTTP/1.1]).¶

+

+ A proxy MAY transform the content of a message + that does not contain a no-transform cache directive. + A proxy that transforms the content of a 200 (OK) response + can inform downstream recipients that a transformation has been + applied by changing the response status code to + 203 (Non-Authoritative Information) (Section 15.3.4).¶

+

+ A proxy SHOULD NOT modify header fields that provide information about + the endpoints of the communication chain, the resource state, or the + selected representation (other than the content) unless the field's + definition specifically allows such modification or the modification is + deemed necessary for privacy or security.¶

+
+
+
+
+

+7.8. Upgrade +

+ + + +

+ The "Upgrade" header field is intended to provide a simple mechanism + for transitioning from HTTP/1.1 to some other protocol on the same + connection.¶

+

+ A client MAY send a list of protocol names in the Upgrade header field + of a request to invite the server to switch to one or more of the named + protocols, in order of descending preference, before sending + the final response. A server MAY ignore a received Upgrade header field + if it wishes to continue using the current protocol on that connection. + Upgrade cannot be used to insist on a protocol change.¶

+ +
+
  Upgrade          = #protocol
+
+  protocol         = protocol-name ["/" protocol-version]
+  protocol-name    = token
+  protocol-version = token
+
¶ +
+

+ Although protocol names are registered with a preferred case, + recipients SHOULD use case-insensitive comparison when matching each + protocol-name to supported protocols.¶

+

+ A server that sends a 101 (Switching Protocols) response + MUST send an Upgrade header field to indicate the new protocol(s) to + which the connection is being switched; if multiple protocol layers are + being switched, the sender MUST list the protocols in layer-ascending + order. A server MUST NOT switch to a protocol that was not indicated by + the client in the corresponding request's Upgrade header field. + A server MAY choose to ignore the order of preference indicated by the + client and select the new protocol(s) based on other factors, such as the + nature of the request or the current load on the server.¶

+

+ A server that sends a 426 (Upgrade Required) response + MUST send an Upgrade header field to indicate the acceptable protocols, + in order of descending preference.¶

+

+ A server MAY send an Upgrade header field in any other response to + advertise that it implements support for upgrading to the listed protocols, + in order of descending preference, when appropriate for a future request.¶

+

+ The following is a hypothetical example sent by a client:¶

+
+
GET /hello HTTP/1.1
+Host: www.example.com
+Connection: upgrade
+Upgrade: websocket, IRC/6.9, RTA/x11
+
+
¶ +
+

+ The capabilities and nature of the + application-level communication after the protocol change is entirely + dependent upon the new protocol(s) chosen. However, immediately after + sending the 101 (Switching Protocols) response, the server is expected to continue responding to + the original request as if it had received its equivalent within the new + protocol (i.e., the server still has an outstanding request to satisfy + after the protocol has been changed, and is expected to do so without + requiring the request to be repeated).¶

+

+ For example, if the Upgrade header field is received in a GET request + and the server decides to switch protocols, it first responds + with a 101 (Switching Protocols) message in HTTP/1.1 and + then immediately follows that with the new protocol's equivalent of a + response to a GET on the target resource. This allows a connection to be + upgraded to protocols with the same semantics as HTTP without the + latency cost of an additional round trip. A server MUST NOT switch + protocols unless the received message semantics can be honored by the new + protocol; an OPTIONS request can be honored by any protocol.¶

+

+ The following is an example response to the above hypothetical request:¶

+
+
HTTP/1.1 101 Switching Protocols
+Connection: upgrade
+Upgrade: websocket
+
+[... data stream switches to websocket with an appropriate response
+(as defined by new protocol) to the "GET /hello" request ...]
+
¶ +
+

+ A sender of Upgrade MUST also send an "Upgrade" connection option in the + Connection header field (Section 7.6.1) + to inform intermediaries not to forward this field. + A server that receives an Upgrade header field in an HTTP/1.0 request + MUST ignore that Upgrade field.¶

+

+ A client cannot begin using an upgraded protocol on the connection until + it has completely sent the request message (i.e., the client can't change + the protocol it is sending in the middle of a message). + If a server receives both an Upgrade and an Expect header field + with the "100-continue" expectation (Section 10.1.1), the + server MUST send a 100 (Continue) response before sending + a 101 (Switching Protocols) response.¶

+

+ The Upgrade header field only applies to switching protocols on top of the + existing connection; it cannot be used to switch the underlying connection + (transport) protocol, nor to switch the existing communication to a + different connection. For those purposes, it is more appropriate to use a + 3xx (Redirection) response (Section 15.4).¶

+

+ This specification only defines the protocol name "HTTP" for use by + the family of Hypertext Transfer Protocols, as defined by the HTTP + version rules of Section 2.5 and future updates to this + specification. Additional protocol names ought to be registered using the + registration procedure defined in Section 16.7.¶

+
+
+
+
+
+
+

+8. Representation Data and Metadata +

+
+
+

+8.1. Representation Data +

+

+ The representation data associated with an HTTP message is + either provided as the content of the message or + referred to by the message semantics and the target + URI. The representation data is in a format and encoding defined by + the representation metadata header fields.¶

+

+ The data type of the representation data is determined via the header fields + Content-Type and Content-Encoding. + These define a two-layer, ordered encoding model:¶

+
+
+  representation-data := Content-Encoding( Content-Type( data ) )
+
¶ +
+
+
+
+
+

+8.2. Representation Metadata +

+

+ Representation header fields provide metadata about the representation. + When a message includes content, the representation header fields + describe how to interpret that data. In a response to a HEAD request, the + representation header fields describe the representation data that would + have been enclosed in the content if the same request had been a GET.¶

+
+
+
+
+

+8.3. Content-Type +

+ + + +

+ The "Content-Type" header field indicates the media type of the + associated representation: either the representation enclosed in + the message content or the selected representation, as determined by the + message semantics. The indicated media type defines both the data format + and how that data is intended to be processed by a recipient, within the + scope of the received message semantics, after any content codings + indicated by Content-Encoding are decoded.¶

+ +
+
  Content-Type = media-type
+
¶ +
+

+ Media types are defined in Section 8.3.1. An example of the + field is¶

+
+
Content-Type: text/html; charset=ISO-8859-4
+
¶ +
+

+ A sender that generates a message containing content SHOULD + generate a Content-Type header field in that message unless the intended + media type of the enclosed representation is unknown to the sender. + If a Content-Type header field is not present, the recipient MAY either + assume a media type of + "application/octet-stream" ([RFC2046], Section 4.5.1) + or examine the data to determine its type.¶

+

+ In practice, resource owners do not always properly configure their origin + server to provide the correct Content-Type for a given representation. + Some user agents examine the content and, in certain cases, + override the received type (for example, see [Sniffing]). + This "MIME sniffing" risks drawing incorrect conclusions about the data, + which might expose the user to additional security risks + (e.g., "privilege escalation"). + Furthermore, distinct media types often share a common data format, + differing only in how the data is intended to be processed, which is + impossible to distinguish by inspecting the data alone. + When sniffing is implemented, implementers are encouraged to provide a + means for the user to disable it.¶

+

+ Although Content-Type is defined as a singleton field, it is + sometimes incorrectly generated multiple times, resulting in a combined + field value that appears to be a list. + Recipients often attempt to handle this error by using the last + syntactically valid member of the list, leading to potential + interoperability and security issues if different implementations + have different error handling behaviors.¶

+
+
+

+8.3.1. Media Type +

+

+ HTTP uses media types [RFC2046] in the + Content-Type (Section 8.3) + and Accept (Section 12.5.1) header fields in + order to provide open and extensible data typing and type negotiation. + Media types define both a data format and various processing models: + how to process that data in accordance with the message context.¶

+ + + +
+
  media-type = type "/" subtype parameters
+  type       = token
+  subtype    = token
+
¶ +
+

+ The type and subtype tokens are case-insensitive.¶

+

+ The type/subtype MAY be followed by semicolon-delimited parameters + (Section 5.6.6) in the form of name/value pairs. + The presence or absence of a parameter might be significant to the + processing of a media type, depending on its definition within the media + type registry. + Parameter values might or might not be case-sensitive, depending on the + semantics of the parameter name.¶

+

+ For example, the following media types are equivalent in describing HTML + text data encoded in the UTF-8 character encoding scheme, but the first is + preferred for consistency (the "charset" parameter value is defined as + being case-insensitive in [RFC2046], Section 4.1.2):¶

+
+
+  text/html;charset=utf-8
+  Text/HTML;Charset="utf-8"
+  text/html; charset="utf-8"
+  text/html;charset=UTF-8
+
¶ +
+

+ Media types ought to be registered with IANA according to the + procedures defined in [BCP13].¶

+
+
+
+
+

+8.3.2. Charset +

+

+ HTTP uses "charset" names to indicate or negotiate the + character encoding scheme ([RFC6365], Section 2) + of a textual representation. In the fields defined by this document, + charset names appear either in parameters (Content-Type), + or, for Accept-Encoding, in the form of a plain token. + In both cases, charset names are matched case-insensitively.¶

+

+ Charset names ought to be registered in the IANA "Character Sets" registry + (<https://www.iana.org/assignments/character-sets>) + according to the procedures defined in Section 2 of [RFC2978].¶

+ +
+
+
+
+

+8.3.3. Multipart Types +

+

+ MIME provides for a number of "multipart" types -- encapsulations of + one or more representations within a single message body. All multipart + types share a common syntax, as defined in Section 5.1.1 of [RFC2046], + and include a boundary parameter as part of the media type + value. The message body is itself a protocol element; a sender MUST + generate only CRLF to represent line breaks between body parts.¶

+

+ HTTP message framing does not use the multipart boundary as an indicator + of message body length, though it might be used by implementations that + generate or process the content. For example, the "multipart/form-data" + type is often used for carrying form data in a request, as described in + [RFC7578], and the "multipart/byteranges" type is defined + by this specification for use in some 206 (Partial Content) + responses (see Section 15.3.7).¶

+
+
+
+
+
+
+

+8.4. Content-Encoding +

+ + + +

+ The "Content-Encoding" header field indicates what content codings + have been applied to the representation, beyond those inherent in the media + type, and thus what decoding mechanisms have to be applied in order to + obtain data in the media type referenced by the Content-Type + header field. + Content-Encoding is primarily used to allow a representation's data to be + compressed without losing the identity of its underlying media type.¶

+ +
+
  Content-Encoding = #content-coding
+
¶ +
+

+ An example of its use is¶

+
+
Content-Encoding: gzip
+
¶ +
+

+ If one or more encodings have been applied to a representation, the sender + that applied the encodings MUST generate a Content-Encoding header field + that lists the content codings in the order in which they were applied. + Note that the coding named "identity" is reserved for its special role + in Accept-Encoding and thus SHOULD NOT be included.¶

+

+ Additional information about the encoding parameters can be provided + by other header fields not defined by this specification.¶

+

+ Unlike Transfer-Encoding (Section 6.1 of [HTTP/1.1]), the codings listed + in Content-Encoding are a characteristic of the representation; the + representation is defined in terms of the coded form, and all other + metadata about the representation is about the coded form unless otherwise + noted in the metadata definition. Typically, the representation is only + decoded just prior to rendering or analogous usage.¶

+

+ If the media type includes an inherent encoding, such as a data format + that is always compressed, then that encoding would not be restated in + Content-Encoding even if it happens to be the same algorithm as one + of the content codings. Such a content coding would only be listed if, + for some bizarre reason, it is applied a second time to form the + representation. Likewise, an origin server might choose to publish the + same data as multiple representations that differ only in whether + the coding is defined as part of Content-Type or + Content-Encoding, since some user agents will behave differently in their + handling of each response (e.g., open a "Save as ..." dialog instead of + automatic decompression and rendering of content).¶

+

+ An origin server MAY respond with a status code of + 415 (Unsupported Media Type) if a representation in the + request message has a content coding that is not acceptable.¶

+
+
+

+8.4.1. Content Codings +

+ + + + + + +

+ Content coding values indicate an encoding transformation that has + been or can be applied to a representation. Content codings are primarily + used to allow a representation to be compressed or otherwise usefully + transformed without losing the identity of its underlying media type + and without loss of information. Frequently, the representation is stored + in coded form, transmitted directly, and only decoded by the final recipient.¶

+ +
+
  content-coding   = token
+
¶ +
+

+ All content codings are case-insensitive and ought to be registered + within the "HTTP Content Coding Registry", as described in + Section 16.6¶

+

+ Content-coding values are used in the + Accept-Encoding (Section 12.5.3) + and Content-Encoding (Section 8.4) + header fields.¶

+
+
+
+8.4.1.1. Compress Coding +
+ +

+ The "compress" coding is an adaptive Lempel-Ziv-Welch (LZW) coding + [Welch] that is commonly produced by the UNIX file + compression program "compress". + A recipient SHOULD consider "x-compress" to be equivalent to "compress".¶

+
+
+
+
+
+8.4.1.2. Deflate Coding +
+ +

+ The "deflate" coding is a "zlib" data format [RFC1950] + containing a "deflate" compressed data stream [RFC1951] + that uses a combination of the Lempel-Ziv (LZ77) compression algorithm and + Huffman coding.¶

+ +
+
+
+
+
+8.4.1.3. Gzip Coding +
+ +

+ The "gzip" coding is an LZ77 coding with a 32-bit Cyclic Redundancy Check + (CRC) that is commonly + produced by the gzip file compression program [RFC1952]. + A recipient SHOULD consider "x-gzip" to be equivalent to "gzip".¶

+
+
+
+
+
+
+
+
+

+8.5. Content-Language +

+ + + +

+ The "Content-Language" header field describes the natural + language(s) of the intended audience for the representation. Note that this might + not be equivalent to all the languages used within the representation.¶

+ +
+
  Content-Language = #language-tag
+
¶ +
+

+ Language tags are defined in Section 8.5.1. The primary purpose of + Content-Language is to allow a user to identify and differentiate + representations according to the users' own preferred language. Thus, if the + content is intended only for a Danish-literate audience, the + appropriate field is¶

+
+
Content-Language: da
+
¶ +
+

+ If no Content-Language is specified, the default is that the content + is intended for all language audiences. This might mean that the + sender does not consider it to be specific to any natural language, + or that the sender does not know for which language it is intended.¶

+

+ Multiple languages MAY be listed for content that is intended for + multiple audiences. For example, a rendition of the "Treaty of + Waitangi", presented simultaneously in the original Maori and English + versions, would call for¶

+
+
Content-Language: mi, en
+
¶ +
+

+ However, just because multiple languages are present within a representation + does not mean that it is intended for multiple linguistic audiences. + An example would be a beginner's language primer, such as "A First + Lesson in Latin", which is clearly intended to be used by an + English-literate audience. In this case, the Content-Language would + properly only include "en".¶

+

+ Content-Language MAY be applied to any media type -- it is not + limited to textual documents.¶

+
+
+

+8.5.1. Language Tags +

+

+ A language tag, as defined in [RFC5646], identifies a + natural language spoken, written, or otherwise conveyed by human beings for + communication of information to other human beings. Computer languages are + explicitly excluded.¶

+

+ HTTP uses language tags within the Accept-Language and + Content-Language header fields. + Accept-Language uses the broader language-range production + defined in Section 12.5.4, whereas + Content-Language uses the language-tag production defined + below.¶

+ +
+
  language-tag = <Language-Tag, see [RFC5646], Section 2.1>
+
¶ +
+

+ A language tag is a sequence of one or more case-insensitive subtags, each + separated by a hyphen character ("-", %x2D). In most cases, a language tag + consists of a primary language subtag that identifies a broad family of + related languages (e.g., "en" = English), which is optionally followed by a + series of subtags that refine or narrow that language's range (e.g., + "en-CA" = the variety of English as communicated in Canada). + Whitespace is not allowed within a language tag. + Example tags include:¶

+
+
+  fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN
+
¶ +
+

+ See [RFC5646] for further information.¶

+
+
+
+
+
+
+

+8.6. Content-Length +

+ + + +

+ The "Content-Length" header field indicates the associated representation's + data length as a decimal non-negative integer number of octets. + When transferring a representation as content, Content-Length refers + specifically to the amount of data enclosed so that it can be used to + delimit framing (e.g., Section 6.2 of [HTTP/1.1]). + In other cases, Content-Length indicates the selected representation's + current length, which can be used by recipients to estimate transfer time + or to compare with previously stored representations.¶

+ +
+
  Content-Length = 1*DIGIT
+
¶ +
+

+ An example is¶

+
+
Content-Length: 3495
+
¶ +
+

+ A user agent SHOULD send Content-Length in a request when the method + defines a meaning for enclosed content and it is not sending + Transfer-Encoding. + For example, a user agent normally sends Content-Length in a POST request + even when the value is 0 (indicating empty content). + A user agent SHOULD NOT send a + Content-Length header field when the request message does not contain + content and the method semantics do not anticipate such data.¶

+

+ A server MAY send a Content-Length header field in a response to a HEAD + request (Section 9.3.2); a server MUST NOT send Content-Length in such a + response unless its field value equals the decimal number of octets that + would have been sent in the content of a response if the same + request had used the GET method.¶

+

+ A server MAY send a Content-Length header field in a + 304 (Not Modified) response to a conditional GET request + (Section 15.4.5); a server MUST NOT send Content-Length in such a + response unless its field value equals the decimal number of octets that + would have been sent in the content of a 200 (OK) + response to the same request.¶

+

+ A server MUST NOT send a Content-Length header field in any response + with a status code of + 1xx (Informational) or 204 (No Content). + A server MUST NOT send a Content-Length header field in any + 2xx (Successful) response to a CONNECT request (Section 9.3.6).¶

+

+ Aside from the cases defined above, in the absence of Transfer-Encoding, + an origin server SHOULD send a Content-Length header field when the + content size is known prior to sending the complete header section. + This will allow downstream recipients to measure transfer progress, + know when a received message is complete, and potentially reuse the + connection for additional requests.¶

+

+ Any Content-Length field value greater than or equal to zero is valid. + Since there is no predefined limit to the length of content, a + recipient MUST anticipate potentially large decimal numerals and + prevent parsing errors due to integer conversion overflows + or precision loss due to integer conversion + (Section 17.5).¶

+

+ Because Content-Length is used for message delimitation in HTTP/1.1, + its field value can impact how the message is parsed by downstream + recipients even when the immediate connection is not using HTTP/1.1. + If the message is forwarded by a downstream intermediary, a Content-Length + field value that is inconsistent with the received message framing might + cause a security failure due to request smuggling or response splitting.¶

+

+ As a result, a sender MUST NOT forward a message with a + Content-Length header field value that is known to be incorrect.¶

+

+ Likewise, a sender MUST NOT forward a message with a Content-Length + header field value that does not match the ABNF above, with one exception: + a recipient of a Content-Length header field value consisting of the same + decimal value repeated as a comma-separated list (e.g, + "Content-Length: 42, 42") MAY either reject the message as invalid or + replace that invalid field value with a single instance of the decimal + value, since this likely indicates that a duplicate was generated or + combined by an upstream message processor.¶

+
+
+
+
+

+8.7. Content-Location +

+ + + +

+ The "Content-Location" header field references a URI that can be used + as an identifier for a specific resource corresponding to the + representation in this message's content. + In other words, if one were to perform a GET request on this URI at the time + of this message's generation, then a 200 (OK) response would + contain the same representation that is enclosed as content in this message.¶

+ +
+
  Content-Location = absolute-URI / partial-URI
+
¶ +
+

+ The field value is either an absolute-URI or a + partial-URI. In the latter case (Section 4), + the referenced URI is relative to the target URI + ([URI], Section 5).¶

+

+ The Content-Location value is not a replacement for the target URI + (Section 7.1). It is representation metadata. + It has the same syntax and semantics as the header field of the same name + defined for MIME body parts in Section 4 of [RFC2557]. + However, its appearance in an HTTP message has some special implications + for HTTP recipients.¶

+

+ If Content-Location is included in a 2xx (Successful) + response message and its value refers (after conversion to absolute form) + to a URI that is the same as the target URI, then + the recipient MAY consider the content to be a current representation of + that resource at the time indicated by the message origination date. + For a GET (Section 9.3.1) or HEAD (Section 9.3.2) request, + this is the same as the default semantics when no Content-Location is + provided by the server. + For a state-changing request like PUT (Section 9.3.4) or + POST (Section 9.3.3), it implies that the server's response + contains the new representation of that resource, thereby distinguishing it + from representations that might only report about the action + (e.g., "It worked!"). + This allows authoring applications to update their local copies without + the need for a subsequent GET request.¶

+

+ If Content-Location is included in a 2xx (Successful) + response message and its field value refers to a URI that differs from the + target URI, then the origin server claims that the URI + is an identifier for a different resource corresponding to the enclosed + representation. Such a claim can only be trusted if both identifiers share + the same resource owner, which cannot be programmatically determined via + HTTP.¶

+
    +
  • For a response to a GET or HEAD request, this is an indication that the + target URI refers to a resource that is subject to content + negotiation and the Content-Location field value is a more specific + identifier for the selected representation.¶ +
    • +
  • For a 201 (Created) response to a state-changing method, + a Content-Location field value that is identical to the + Location field value indicates that this content is a + current representation of the newly created resource.¶ +
    • +
  • Otherwise, such a Content-Location indicates that this content is a + representation reporting on the requested action's status and that the + same report is available (for future access with GET) at the given URI. + For example, a purchase transaction made via a POST request might + include a receipt document as the content of the 200 (OK) + response; the Content-Location field value provides an identifier for + retrieving a copy of that same receipt in the future.¶ +
    • +
+

+ A user agent that sends Content-Location in a request message is stating + that its value refers to where the user agent originally obtained the + content of the enclosed representation (prior to any modifications made by + that user agent). In other words, the user agent is providing a back link + to the source of the original representation.¶

+

+ An origin server that receives a Content-Location field in a request + message MUST treat the information as transitory request context rather + than as metadata to be saved verbatim as part of the representation. + An origin server MAY use that context to guide in processing the + request or to save it for other uses, such as within source links or + versioning metadata. However, an origin server MUST NOT use such context + information to alter the request semantics.¶

+

+ For example, if a client makes a PUT request on a negotiated resource and + the origin server accepts that PUT (without redirection), then the new + state of that resource is expected to be consistent with the one + representation supplied in that PUT; the Content-Location cannot be used as + a form of reverse content selection identifier to update only one of the + negotiated representations. If the user agent had wanted the latter + semantics, it would have applied the PUT directly to the Content-Location + URI.¶

+
+
+
+
+

+8.8. Validator Fields +

+ + + +

+ Resource metadata is referred to as a "validator" if it + can be used within a precondition (Section 13.1) to + make a conditional request (Section 13). + Validator fields convey a current validator for the + selected representation + (Section 3.2).¶

+

+ In responses to safe requests, validator fields describe the selected + representation chosen by the origin server while handling the response. + Note that, depending on the method and status code semantics, the + selected representation for a given response is not + necessarily the same as the representation enclosed as response content.¶

+

+ In a successful response to a state-changing request, validator fields + describe the new representation that has replaced the prior + selected representation as a result of processing the + request.¶

+

+ For example, an ETag field in a 201 (Created) response + communicates the entity tag of the newly created resource's + representation, so that the entity tag can be used as a validator in + later conditional requests to prevent the "lost update" problem.¶

+

+ This specification defines two forms of metadata that are commonly used + to observe resource state and test for preconditions: modification dates + (Section 8.8.2) and opaque entity tags + (Section 8.8.3). + Additional metadata that reflects resource state + has been defined by various extensions of HTTP, such as Web Distributed + Authoring and Versioning [WEBDAV], that are beyond the + scope of this specification.¶

+
+
+

+8.8.1. Weak versus Strong +

+ + +

+ Validators come in two flavors: strong or weak. Weak validators are easy + to generate but are far less useful for comparisons. Strong validators + are ideal for comparisons but can be very difficult (and occasionally + impossible) to generate efficiently. Rather than impose that all forms + of resource adhere to the same strength of validator, HTTP exposes the + type of validator in use and imposes restrictions on when weak validators + can be used as preconditions.¶

+

+ A "strong validator" is representation metadata that changes value whenever + a change occurs to the representation data that would be observable in the + content of a 200 (OK) response to GET.¶

+

+ A strong validator might change for reasons other than a change to the + representation data, such as when a + semantically significant part of the representation metadata is changed + (e.g., Content-Type), but it is in the best interests of the + origin server to only change the value when it is necessary to invalidate + the stored responses held by remote caches and authoring tools.¶

+

+ Cache entries might persist for arbitrarily long periods, regardless + of expiration times. Thus, a cache might attempt to validate an + entry using a validator that it obtained in the distant past. + A strong validator is unique across all versions of all + representations associated with a particular resource over time. + However, there is no implication of uniqueness across representations + of different resources (i.e., the same strong validator might be + in use for representations of multiple resources at the same time + and does not imply that those representations are equivalent).¶

+

+ There are a variety of strong validators used in practice. The best are + based on strict revision control, wherein each change to a representation + always results in a unique node name and revision identifier being assigned + before the representation is made accessible to GET. + A collision-resistant hash + function applied to the representation data is also sufficient if the data + is available prior to the response header fields being sent and the digest + does not need to be recalculated every time a validation request is + received. However, if a resource has distinct representations that differ + only in their metadata, such as might occur with content negotiation over + media types that happen to share the same data format, then the origin + server needs to incorporate additional information in the validator to + distinguish those representations.¶

+

+ In contrast, a "weak validator" is representation metadata + that might not change for every change to the representation data. This + weakness might be due to limitations in how the value is calculated + (e.g., clock resolution), an inability to ensure uniqueness for all + possible representations of the resource, or a desire of the resource + owner to group representations by some self-determined set of + equivalency rather than unique sequences of data.¶

+

+ An origin server SHOULD change a weak entity tag whenever it + considers prior representations to be unacceptable as a substitute for + the current representation. In other words, a weak entity tag ought to + change whenever the origin server wants caches to invalidate old + responses.¶

+

+ For example, the representation of a weather report that changes in + content every second, based on dynamic measurements, might be grouped + into sets of equivalent representations (from the origin server's + perspective) with the same weak validator in order to allow cached + representations to be valid for a reasonable period of time (perhaps + adjusted dynamically based on server load or weather quality). + Likewise, a representation's modification time, if defined with only + one-second resolution, might be a weak validator if it is possible + for the representation to be modified twice during a single second and + retrieved between those modifications.¶

+

+ Likewise, a validator is weak if it is shared by two or more + representations of a given resource at the same time, unless those + representations have identical representation data. For example, if the + origin server sends the same validator for a representation with a gzip + content coding applied as it does for a representation with no content + coding, then that validator is weak. However, two simultaneous + representations might share the same strong validator if they differ only + in the representation metadata, such as when two different media types are + available for the same representation data.¶

+

+ Strong validators are usable for all conditional requests, including cache + validation, partial content ranges, and "lost update" avoidance. + Weak validators are only usable when the client does not require exact + equality with previously obtained representation data, such as when + validating a cache entry or limiting a web traversal to recent changes.¶

+
+
+
+
+

+8.8.2. Last-Modified +

+ + + +

+ The "Last-Modified" header field in a response provides a timestamp + indicating the date and time at which the origin server believes the + selected representation was last modified, as determined at the conclusion + of handling the request.¶

+ +
+
  Last-Modified = HTTP-date
+
¶ +
+

+ An example of its use is¶

+
+
Last-Modified: Tue, 15 Nov 1994 12:45:26 GMT
+
¶ +
+
+
+
+8.8.2.1. Generation +
+

+ An origin server SHOULD send Last-Modified for any selected + representation for which a last modification date can be reasonably + and consistently determined, since its use in conditional requests + and evaluating cache freshness ([CACHING]) can + substantially reduce unnecessary transfers and significantly + improve service availability and scalability.¶

+

+ A representation is typically the sum of many parts behind the + resource interface. The last-modified time would usually be + the most recent time that any of those parts were changed. + How that value is determined for any given resource is an + implementation detail beyond the scope of this specification.¶

+

+ An origin server SHOULD obtain the Last-Modified value of the + representation as close as possible to the time that it generates the + Date field value for its response. This allows a recipient to + make an accurate assessment of the representation's modification time, + especially if the representation changes near the time that the + response is generated.¶

+

+ An origin server with a clock (as defined in Section 5.6.7) + MUST NOT generate a Last-Modified date that is later than the + server's time of message origination + (Date, Section 6.6.1). + If the last modification time is derived from implementation-specific + metadata that evaluates to some time in the future, according to the + origin server's clock, then the origin server MUST replace that + value with the message origination date. This prevents a future + modification date from having an adverse impact on cache validation.¶

+

+ An origin server without a clock MUST NOT generate a Last-Modified + date for a response unless that date value was assigned to the resource + by some other system (presumably one with a clock).¶

+
+
+
+
+
+8.8.2.2. Comparison +
+

+ A Last-Modified time, when used as a validator in a request, is + implicitly weak unless it is possible to deduce that it is strong, + using the following rules:¶

+
    +
  • The validator is being compared by an origin server to the + actual current validator for the representation and,¶ +
    • +
  • That origin server reliably knows that the associated representation did + not change twice during the second covered by the presented + validator;¶ +
    • +
+

+ or¶

+
    +
  • The validator is about to be used by a client in an + If-Modified-Since, + If-Unmodified-Since, or If-Range header + field, because the client has a cache entry for the associated + representation, and¶ +
    • +
  • That cache entry includes a Date value which is + at least one second after the Last-Modified value and + the client has reason to believe that they were generated by the + same clock or that there is enough difference between the Last-Modified + and Date values to make clock synchronization issues unlikely;¶ +
    • +
+

+ or¶

+
    +
  • The validator is being compared by an intermediate cache to the + validator stored in its cache entry for the representation, and¶ +
    • +
  • That cache entry includes a Date value which is + at least one second after the Last-Modified value and + the cache has reason to believe that they were generated by the + same clock or that there is enough difference between the Last-Modified + and Date values to make clock synchronization issues unlikely.¶ +
    • +
+

+ This method relies on the fact that if two different responses were + sent by the origin server during the same second, but both had the + same Last-Modified time, then at least one of those responses would + have a Date value equal to its Last-Modified time.¶

+
+
+
+
+
+
+

+8.8.3. ETag +

+ + + + +

+ The "ETag" field in a response provides the current entity tag for + the selected representation, as determined at the conclusion of handling + the request. + An entity tag is an opaque validator for differentiating between + multiple representations of the same resource, regardless of whether + those multiple representations are due to resource state changes over + time, content negotiation resulting in multiple representations being + valid at the same time, or both. An entity tag consists of an opaque + quoted string, possibly prefixed by a weakness indicator.¶

+ + + + + +
+
  ETag       = entity-tag
+
+  entity-tag = [ weak ] opaque-tag
+  weak       = %s"W/"
+  opaque-tag = DQUOTE *etagc DQUOTE
+  etagc      = %x21 / %x23-7E / obs-text
+             ; VCHAR except double quotes, plus obs-text
+
¶ +
+ +

+ An entity tag can be more reliable for validation than a modification + date in situations where it is inconvenient to store modification + dates, where the one-second resolution of HTTP-date values is not + sufficient, or where modification dates are not consistently maintained.¶

+

+ Examples:¶

+
+
ETag: "xyzzy"
+ETag: W/"xyzzy"
+ETag: ""
+
¶ +
+

+ An entity tag can be either a weak or strong validator, with + strong being the default. If an origin server provides an entity tag + for a representation and the generation of that entity tag does not satisfy + all of the characteristics of a strong validator + (Section 8.8.1), then the origin server + MUST mark the entity tag as weak by prefixing its opaque value + with "W/" (case-sensitive).¶

+

+ A sender MAY send the ETag field in a trailer section (see + Section 6.5). However, since trailers are often + ignored, it is preferable to send ETag as a header field unless the + entity tag is generated while sending the content.¶

+
+
+
+8.8.3.1. Generation +
+

+ The principle behind entity tags is that only the service author + knows the implementation of a resource well enough to select the + most accurate and efficient validation mechanism for that resource, + and that any such mechanism can be mapped to a simple sequence of + octets for easy comparison. Since the value is opaque, there is no + need for the client to be aware of how each entity tag is constructed.¶

+

+ For example, a resource that has implementation-specific versioning + applied to all changes might use an internal revision number, perhaps + combined with a variance identifier for content negotiation, to + accurately differentiate between representations. + Other implementations might use a collision-resistant hash of + representation content, a combination of various file attributes, or + a modification timestamp that has sub-second resolution.¶

+

+ An origin server SHOULD send an ETag for any selected representation + for which detection of changes can be reasonably and consistently + determined, since the entity tag's use in conditional requests and + evaluating cache freshness ([CACHING]) can + substantially reduce unnecessary transfers and significantly + improve service availability, scalability, and reliability.¶

+
+
+
+
+
+8.8.3.2. Comparison +
+

+ There are two entity tag comparison functions, depending on whether or not + the comparison context allows the use of weak validators:¶

+
+
+ "Strong comparison": +
+
+ two entity tags are equivalent if both are not weak and their opaque-tags + match character-by-character.¶ +
+
+
+ "Weak comparison": +
+
+ two entity tags are equivalent if their opaque-tags match + character-by-character, regardless of either or both being tagged as "weak".¶ +
+
+
+

+ The example below shows the results for a set of entity tag pairs and both + the weak and strong comparison function results:¶

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 3
ETag 1ETag 2Strong ComparisonWeak Comparison
W/"1"W/"1"no matchmatch
W/"1"W/"2"no matchno match
W/"1""1"no matchmatch
"1""1"matchmatch
+
+
+
+
+
+8.8.3.3. Example: Entity Tags Varying on Content-Negotiated Resources +
+

+ Consider a resource that is subject to content negotiation + (Section 12), and where the representations sent in response to + a GET request vary based on the Accept-Encoding request + header field (Section 12.5.3):¶

+

+ >> Request:¶

+
+
GET /index HTTP/1.1
+Host: www.example.com
+Accept-Encoding: gzip
+
+
¶ +
+

+ In this case, the response might or might not use the gzip content coding. + If it does not, the response might look like:¶

+

+ >> Response:¶

+
+
HTTP/1.1 200 OK
+Date: Fri, 26 Mar 2010 00:05:00 GMT
+ETag: "123-a"
+Content-Length: 70
+Vary: Accept-Encoding
+Content-Type: text/plain
+
+Hello World!
+Hello World!
+Hello World!
+Hello World!
+Hello World!
+
¶ +
+

+ An alternative representation that does use gzip content coding would be:¶

+

+ >> Response:¶

+
+
HTTP/1.1 200 OK
+Date: Fri, 26 Mar 2010 00:05:00 GMT
+ETag: "123-b"
+Content-Length: 43
+Vary: Accept-Encoding
+Content-Type: text/plain
+Content-Encoding: gzip
+
+...binary data...
¶ +
+ +
+
+
+
+
+
+
+
+
+
+

+9. Methods +

+
+
+

+9.1. Overview +

+

+ The request method token is the primary source of request semantics; + it indicates the purpose for which the client has made this request + and what is expected by the client as a successful result.¶

+

+ The request method's semantics might be further specialized by the + semantics of some header fields when present in a request + if those additional semantics do not conflict with the method. + For example, a client can send conditional request header fields + (Section 13.1) to make the requested + action conditional on the current state of the target resource.¶

+

+ HTTP is designed to be usable as an interface to distributed + object systems. The request method invokes an action to be applied to + a target resource in much the same way that a remote + method invocation can be sent to an identified object.¶

+ +
+
  method = token
+
¶ +
+

+ The method token is case-sensitive because it might be used as a gateway + to object-based systems with case-sensitive method names. By convention, + standardized methods are defined in all-uppercase US-ASCII letters.¶

+

+ Unlike distributed objects, the standardized request methods in HTTP are + not resource-specific, since uniform interfaces provide for better + visibility and reuse in network-based systems [REST]. + Once defined, a standardized method ought to have the same semantics when + applied to any resource, though each resource determines for itself + whether those semantics are implemented or allowed.¶

+

+ This specification defines a number of standardized methods that are + commonly used in HTTP, as outlined by the following table.¶

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 4
Method NameDescriptionSection
GETTransfer a current representation of the target resource. + 9.3.1 +
HEADSame as GET, but do not transfer the response content. + 9.3.2 +
POSTPerform resource-specific processing on the request content. + 9.3.3 +
PUTReplace all current representations of the target resource with + the request content. + 9.3.4 +
DELETERemove all current representations of the target resource. + 9.3.5 +
CONNECTEstablish a tunnel to the server identified by the target resource. + 9.3.6 +
OPTIONSDescribe the communication options for the target resource. + 9.3.7 +
TRACEPerform a message loop-back test along the path to the target resource. + 9.3.8 +
+
+

+ All general-purpose servers MUST support the methods GET and HEAD. + All other methods are OPTIONAL.¶

+

+ The set of methods allowed by a target resource can be listed in an + Allow header field (Section 10.2.1). + However, the set of allowed methods can change dynamically. + An origin server that receives a request method that is unrecognized or + not implemented SHOULD respond with the + 501 (Not Implemented) status code. + An origin server that receives a request method that is recognized and + implemented, but not allowed for the target resource, SHOULD respond + with the 405 (Method Not Allowed) status code.¶

+

+ Additional methods, outside the scope of this specification, have been + specified for use in HTTP. All such methods ought to be registered + within the "Hypertext Transfer Protocol (HTTP) Method Registry", + as described in Section 16.1.¶

+
+
+
+
+

+9.2. Common Method Properties +

+
+
+

+9.2.1. Safe Methods +

+ +

+ Request methods are considered "safe" if + their defined semantics are essentially read-only; i.e., the client does + not request, and does not expect, any state change on the origin server + as a result of applying a safe method to a target resource. Likewise, + reasonable use of a safe method is not expected to cause any harm, + loss of property, or unusual burden on the origin server.¶

+

+ This definition of safe methods does not prevent an implementation from + including behavior that is potentially harmful, that is not entirely read-only, + or that causes side effects while invoking a safe method. What is + important, however, is that the client did not request that additional + behavior and cannot be held accountable for it. For example, + most servers append request information to access log files at the + completion of every response, regardless of the method, and that is + considered safe even though the log storage might become full and cause + the server to fail. Likewise, a safe request initiated by selecting an + advertisement on the Web will often have the side effect of charging an + advertising account.¶

+

+ Of the request methods defined by this specification, the + GET, HEAD, OPTIONS, and + TRACE methods are defined to be safe.¶

+

+ The purpose of distinguishing between safe and unsafe methods is to + allow automated retrieval processes (spiders) and cache performance + optimization (pre-fetching) to work without fear of causing harm. + In addition, it allows a user agent to apply appropriate constraints + on the automated use of unsafe methods when processing potentially + untrusted content.¶

+

+ A user agent SHOULD distinguish between safe and unsafe methods when + presenting potential actions to a user, such that the user can be made + aware of an unsafe action before it is requested.¶

+

+ When a resource is constructed such that parameters within the target URI + have the effect of selecting an action, it is the resource + owner's responsibility to ensure that the action is consistent with the + request method semantics. + For example, it is common for Web-based content editing software + to use actions within query parameters, such as "page?do=delete". + If the purpose of such a resource is to perform an unsafe action, then + the resource owner MUST disable or disallow that action when it is + accessed using a safe request method. Failure to do so will result in + unfortunate side effects when automated processes perform a GET on + every URI reference for the sake of link maintenance, pre-fetching, + building a search index, etc.¶

+
+
+
+
+

+9.2.2. Idempotent Methods +

+ +

+ A request method is considered "idempotent" + if the intended effect on the server of multiple identical requests with + that method is the same as the effect for a single such request. + Of the request methods defined by this + specification, PUT, DELETE, and safe request + methods are idempotent.¶

+

+ Like the definition of safe, the idempotent property only applies to + what has been requested by the user; a server is free to log each request + separately, retain a revision control history, or implement other + non-idempotent side effects for each idempotent request.¶

+

+ Idempotent methods are distinguished because the request can be repeated + automatically if a communication failure occurs before the client is + able to read the server's response. For example, if a client sends a PUT + request and the underlying connection is closed before any response is + received, then the client can establish a new connection and retry the + idempotent request. It knows that repeating the request will have + the same intended effect, even if the original request succeeded, though + the response might differ.¶

+

+ A client SHOULD NOT automatically retry a request with a non-idempotent + method unless it has some means to know that the request semantics are + actually idempotent, regardless of the method, or some means to detect that + the original request was never applied.¶

+

+ For example, a user agent can repeat a POST request automatically if it + knows (through design or configuration) that the request is safe for that + resource. Likewise, a user agent designed specifically to operate on + a version control repository might be able to recover from partial failure + conditions by checking the target resource revision(s) after a failed + connection, reverting or fixing any changes that were partially applied, + and then automatically retrying the requests that failed.¶

+

+ Some clients take a riskier approach and attempt to guess when an + automatic retry is possible. For example, a client might automatically + retry a POST request if the underlying transport connection closed before + any part of a response is received, particularly if an idle persistent + connection was used.¶

+

+ A proxy MUST NOT automatically retry non-idempotent requests. + A client SHOULD NOT automatically retry a failed automatic retry.¶

+
+
+
+
+

+9.2.3. Methods and Caching +

+

+ For a cache to store and use a response, the associated method needs to + explicitly allow caching and to detail under what conditions a response can + be used to satisfy subsequent requests; a method definition that does not + do so cannot be cached. For additional requirements see [CACHING].¶

+

+ This specification defines caching semantics for GET, HEAD, and POST, + although the overwhelming majority of cache implementations only support + GET and HEAD.¶

+
+
+
+
+
+
+

+9.3. Method Definitions +

+
+
+

+9.3.1. GET +

+ + +

+ The GET method requests transfer of a current + selected representation for the + target resource. + A successful response reflects the quality of "sameness" identified by + the target URI (Section 1.2.2 of [URI]). Hence, + retrieving identifiable information via HTTP is usually performed by + making a GET request on an identifier associated with the potential for + providing that information in a 200 (OK) response.¶

+

+ GET is the primary mechanism of information retrieval and the focus of + almost all performance optimizations. Applications that produce a URI for + each important resource can benefit from those optimizations while enabling + their reuse by other applications, creating a network effect that promotes + further expansion of the Web.¶

+

+ It is tempting to think of resource identifiers as remote file system + pathnames and of representations as being a copy of the contents of such + files. In fact, that is how many resources are implemented (see + Section 17.3 for related security considerations). + However, there are no such limitations in practice.¶

+

+ The HTTP interface for + a resource is just as likely to be implemented as a tree of content + objects, a programmatic view on various database records, or a gateway to + other information systems. Even when the URI mapping mechanism is tied to a + file system, an origin server might be configured to execute the files with + the request as input and send the output as the representation rather than + transfer the files directly. Regardless, only the origin server needs to + know how each resource identifier corresponds to an implementation + and how that implementation manages to select and send a current + representation of the target resource.¶

+

+ A client can alter the semantics of GET to be a "range request", requesting + transfer of only some part(s) of the selected representation, by sending a + Range header field in the request (Section 14.2).¶

+

+ Although request message framing is independent of the method used, + content received in a GET request has no generally defined semantics, + cannot alter the meaning or target of the request, and might lead some + implementations to reject the request and close the connection because of + its potential as a request smuggling attack + (Section 11.2 of [HTTP/1.1]). + A client SHOULD NOT generate content in a GET request unless it is + made directly to an origin server that has previously indicated, + in or out of band, that such a request has a purpose and will be adequately + supported. An origin server SHOULD NOT rely on private agreements to + receive content, since participants in HTTP communication are often + unaware of intermediaries along the request chain.¶

+

+ The response to a GET request is cacheable; a cache MAY use it to satisfy + subsequent GET and HEAD requests unless otherwise indicated by the + Cache-Control header field (Section 5.2 of [CACHING]).¶

+

+ When information retrieval is performed with a mechanism that constructs a + target URI from user-provided information, such as the query fields of a + form using GET, potentially sensitive data might be provided that would not + be appropriate for disclosure within a URI + (see Section 17.9). In some cases, the + data can be filtered or transformed such that it would not reveal such + information. In others, particularly when there is no benefit from caching + a response, using the POST method (Section 9.3.3) instead of GET + can transmit such information in the request content rather than within + the target URI.¶

+
+
+ +
+
+

+9.3.3. POST +

+ + +

+ The POST method requests that the target resource process + the representation enclosed in the request according to the resource's own + specific semantics. For example, POST is used for the following functions + (among others):¶

+
    +
  • Providing a block of data, such as the fields entered into an HTML + form, to a data-handling process;¶ +
    • +
  • Posting a message to a bulletin board, newsgroup, mailing list, blog, + or similar group of articles;¶ +
    • +
  • Creating a new resource that has yet to be identified by the origin + server; and¶ +
    • +
  • Appending data to a resource's existing representation(s).¶ +
    • +
+

+ An origin server indicates response semantics by choosing an appropriate + status code depending on the result of processing the POST request; + almost all of the status codes defined by this specification could be + received in a response to POST (the exceptions being 206 (Partial Content), + 304 (Not Modified), and 416 (Range Not Satisfiable)).¶

+

+ If one or more resources has been created on the origin server as a result + of successfully processing a POST request, the origin server SHOULD send + a 201 (Created) response containing a Location + header field that provides an identifier for the primary resource created + (Section 10.2.2) and a representation that describes the + status of the request while referring to the new resource(s).¶

+

+ Responses to POST requests are only cacheable when they include explicit + freshness information (see Section 4.2.1 of [CACHING]) and a + Content-Location header field that has the same value as + the POST's target URI (Section 8.7). A cached POST response can be reused + to satisfy a later GET or HEAD request. In contrast, a POST request cannot + be satisfied by a cached POST response because POST is potentially unsafe; + see Section 4 of [CACHING].¶

+

+ If the result of processing a POST would be equivalent to a representation + of an existing resource, an origin server MAY redirect the user agent to + that resource by sending a 303 (See Other) response with the + existing resource's identifier in the Location field. + This has the benefits of providing the user agent a resource identifier + and transferring the representation via a method more amenable to shared + caching, though at the cost of an extra request if the user agent does not + already have the representation cached.¶

+
+
+
+
+

+9.3.4. PUT +

+ + +

+ The PUT method requests that the state of the target resource + be created or replaced with the state defined by the representation + enclosed in the request message content. A successful PUT of a given + representation would suggest that a subsequent GET on that same target + resource will result in an equivalent representation being sent in + a 200 (OK) response. However, there is no guarantee that + such a state change will be observable, since the target resource might be + acted upon by other user agents in parallel, or might be subject to dynamic + processing by the origin server, before any subsequent GET is received. + A successful response only implies that the user agent's intent was + achieved at the time of its processing by the origin server.¶

+

+ If the target resource does not have a current representation and + the PUT successfully creates one, then the origin server MUST inform + the user agent by sending a 201 (Created) response. If the + target resource does have a current representation and that representation is + successfully modified in accordance with the state of the enclosed + representation, then the origin server MUST send either a + 200 (OK) or a 204 (No Content) response to + indicate successful completion of the request.¶

+

+ An origin server SHOULD verify that the PUT representation is consistent + with its configured constraints for the target resource. For example, if + an origin server determines a resource's representation metadata based on + the URI, then the origin server needs to ensure that the content received + in a successful PUT request is consistent with that metadata. When a PUT + representation is inconsistent with the target resource, the origin + server SHOULD either make them consistent, by transforming the + representation or changing the resource configuration, or respond + with an appropriate error message containing sufficient information + to explain why the representation is unsuitable. The + 409 (Conflict) or 415 (Unsupported Media Type) + status codes are suggested, with the latter being specific to constraints on + Content-Type values.¶

+

+ For example, if the target resource is configured to always have a + Content-Type of "text/html" and the representation being PUT + has a Content-Type of "image/jpeg", the origin server ought to do one of:¶

+
    +
  1. reconfigure the target resource to reflect the new media type;¶ +
    2. +
  2. transform the PUT representation to a format consistent with that + of the resource before saving it as the new resource state; or,¶ +
    3. +
  3. reject the request with a 415 (Unsupported Media Type) + response indicating that the target resource is limited to "text/html", + perhaps including a link to a different resource that would be a + suitable target for the new representation.¶ +
    4. +
+

+ HTTP does not define exactly how a PUT method affects the state + of an origin server beyond what can be expressed by the intent of + the user agent request and the semantics of the origin server response. + It does not define what a resource might be, in any sense of that + word, beyond the interface provided via HTTP. It does not define + how resource state is "stored", nor how such storage might change + as a result of a change in resource state, nor how the origin server + translates resource state into representations. Generally speaking, + all implementation details behind the resource interface are + intentionally hidden by the server.¶

+

+ This extends to how header and trailer fields are stored; while common + header fields like Content-Type will typically be stored + and returned upon subsequent GET requests, header and trailer field + handling is specific to the resource that received the request. As a result, + an origin server SHOULD ignore unrecognized header and trailer fields + received in a PUT request (i.e., not save them as part of the resource + state).¶

+

+ An origin server MUST NOT send a validator field + (Section 8.8), such as an ETag or + Last-Modified field, in a successful response to PUT unless + the request's representation data was saved without any transformation + applied to the content (i.e., the resource's new representation data is + identical to the content received in the PUT request) and the + validator field value reflects the new representation. + This requirement allows a user agent to know when the representation it + sent (and retains in memory) is the result of the PUT, and thus it doesn't + need to be retrieved again from the origin server. The new validator(s) + received in the response can be used for future conditional requests in + order to prevent accidental overwrites (Section 13.1).¶

+

+ The fundamental difference between the POST and PUT methods is + highlighted by the different intent for the enclosed representation. + The target resource in a POST request is intended to handle the + enclosed representation according to the resource's own semantics, + whereas the enclosed representation in a PUT request is defined as + replacing the state of the target resource. Hence, the intent of PUT is + idempotent and visible to intermediaries, even though the exact effect is + only known by the origin server.¶

+

+ Proper interpretation of a PUT request presumes that the user agent knows + which target resource is desired. A service that selects a proper URI on + behalf of the client, after receiving a state-changing request, SHOULD be + implemented using the POST method rather than PUT. If the origin server + will not make the requested PUT state change to the target resource and + instead wishes to have it applied to a different resource, such as when the + resource has been moved to a different URI, then the origin server MUST + send an appropriate 3xx (Redirection) response; the + user agent MAY then make its own decision regarding whether or not to + redirect the request.¶

+

+ A PUT request applied to the target resource can have side effects + on other resources. For example, an article might have a URI for + identifying "the current version" (a resource) that is separate + from the URIs identifying each particular version (different + resources that at one point shared the same state as the current version + resource). A successful PUT request on "the current version" URI might + therefore create a new version resource in addition to changing the + state of the target resource, and might also cause links to be added + between the related resources.¶

+

+ Some origin servers support use of the Content-Range header + field (Section 14.4) as a request modifier to + perform a partial PUT, as described in Section 14.5.¶

+

+ Responses to the PUT method are not cacheable. If a successful PUT request + passes through a cache that has one or more stored responses for the + target URI, those stored responses will be invalidated + (see Section 4.4 of [CACHING]).¶

+
+
+
+
+

+9.3.5. DELETE +

+ + +

+ The DELETE method requests that the origin server remove the association + between the target resource and its current functionality. + In effect, this method is similar to the "rm" command in UNIX: it expresses a + deletion operation on the URI mapping of the origin server rather than an + expectation that the previously associated information be deleted.¶

+

+ If the target resource has one or more current representations, they might + or might not be destroyed by the origin server, and the associated storage + might or might not be reclaimed, depending entirely on the nature of the + resource and its implementation by the origin server (which are beyond the + scope of this specification). Likewise, other implementation aspects of a + resource might need to be deactivated or archived as a result of a DELETE, + such as database or gateway connections. In general, it is assumed that the + origin server will only allow DELETE on resources for which it has a + prescribed mechanism for accomplishing the deletion.¶

+

+ Relatively few resources allow the DELETE method -- its primary use + is for remote authoring environments, where the user has some direction + regarding its effect. For example, a resource that was previously created + using a PUT request, or identified via the Location header field after a + 201 (Created) response to a POST request, might allow a + corresponding DELETE request to undo those actions. Similarly, custom + user agent implementations that implement an authoring function, such as + revision control clients using HTTP for remote operations, might use + DELETE based on an assumption that the server's URI space has been crafted + to correspond to a version repository.¶

+

+ If a DELETE method is successfully applied, the origin server SHOULD send¶

+
    +
  • a 202 (Accepted) status code if the action will likely succeed but + has not yet been enacted,¶ +
    • +
  • a 204 (No Content) status code if the action has been + enacted and no further information is to be supplied, or¶ +
    • +
  • a 200 (OK) status code if the action has been enacted and + the response message includes a representation describing the status.¶ +
    • +
+

+ Although request message framing is independent of the method used, + content received in a DELETE request has no generally defined semantics, + cannot alter the meaning or target of the request, and might lead some + implementations to reject the request and close the connection because of + its potential as a request smuggling attack + (Section 11.2 of [HTTP/1.1]). + A client SHOULD NOT generate content in a DELETE request unless it is + made directly to an origin server that has previously indicated, + in or out of band, that such a request has a purpose and will be adequately + supported. An origin server SHOULD NOT rely on private agreements to + receive content, since participants in HTTP communication are often + unaware of intermediaries along the request chain.¶

+

+ Responses to the DELETE method are not cacheable. If a successful DELETE + request passes through a cache that has one or more stored responses for + the target URI, those stored responses will be invalidated (see + Section 4.4 of [CACHING]).¶

+
+
+
+
+

+9.3.6. CONNECT +

+ + +

+ The CONNECT method requests that the recipient establish a tunnel to the + destination origin server identified by the request target and, if + successful, thereafter restrict its behavior to blind forwarding of + data, in both directions, until the tunnel is closed. + Tunnels are commonly used to create an end-to-end virtual connection, + through one or more proxies, which can then be secured using TLS + (Transport Layer Security, [TLS13]).¶

+

+ CONNECT uses a special form of request target, unique to this method, + consisting of only the host and port number of the tunnel destination, + separated by a colon. There is no default port; a client MUST send the + port number even if the CONNECT request is based on a URI reference that + contains an authority component with an elided port + (Section 4.1). For example,¶

+
+
CONNECT server.example.com:80 HTTP/1.1
+Host: server.example.com
+
+
¶ +
+

+ A server MUST reject a CONNECT request that targets an empty or invalid + port number, typically by responding with a 400 (Bad Request) status code.¶

+

+ Because CONNECT changes the request/response nature of an HTTP connection, + specific HTTP versions might have different ways of mapping its semantics + into the protocol's wire format.¶

+

+ CONNECT is intended for use in requests to a proxy. + The recipient can establish a tunnel either by directly connecting to + the server identified by the request target or, if configured to use + another proxy, by forwarding the CONNECT request to the next inbound proxy. + An origin server MAY accept a CONNECT request, but most origin servers + do not implement CONNECT.¶

+

+ Any 2xx (Successful) response indicates + that the sender (and all inbound proxies) will switch to tunnel mode + immediately after the response header section; data received after that + header section is from the server identified by the request target. + Any response other than a successful response indicates that the tunnel + has not yet been formed.¶

+

+ A tunnel is closed when a tunnel intermediary detects that either side + has closed its connection: the intermediary MUST attempt to send any + outstanding data that came from the closed side to the other side, close + both connections, and then discard any remaining data left undelivered.¶

+

+ Proxy authentication might be used to establish the + authority to create a tunnel. For example,¶

+
+
CONNECT server.example.com:443 HTTP/1.1
+Host: server.example.com:443
+Proxy-Authorization: basic aGVsbG86d29ybGQ=
+
+
¶ +
+

+ There are significant risks in establishing a tunnel to arbitrary servers, + particularly when the destination is a well-known or reserved TCP port that + is not intended for Web traffic. For example, a CONNECT to + "example.com:25" would suggest that the proxy connect to the reserved + port for SMTP traffic; if allowed, that could trick the proxy into + relaying spam email. Proxies that support CONNECT SHOULD restrict its + use to a limited set of known ports or a configurable list of safe + request targets.¶

+

+ A server MUST NOT send any Transfer-Encoding or + Content-Length header fields in a + 2xx (Successful) response to CONNECT. + A client MUST ignore any Content-Length or Transfer-Encoding header + fields received in a successful response to CONNECT.¶

+

+ A CONNECT request message does not have content. The interpretation of + data sent after the header section of the CONNECT request message is + specific to the version of HTTP in use.¶

+

+ Responses to the CONNECT method are not cacheable.¶

+
+
+
+
+

+9.3.7. OPTIONS +

+ + +

+ The OPTIONS method requests information about the communication options + available for the target resource, at either the origin server or an + intervening intermediary. This method allows a client to determine the + options and/or requirements associated with a resource, or the capabilities + of a server, without implying a resource action.¶

+

+ An OPTIONS request with an asterisk ("*") as the request target + (Section 7.1) applies to the server in general rather than to a + specific resource. Since a server's communication options typically depend + on the resource, the "*" request is only useful as a "ping" or "no-op" + type of method; it does nothing beyond allowing the client to test + the capabilities of the server. For example, this can be used to test + a proxy for HTTP/1.1 conformance (or lack thereof).¶

+

+ If the request target is not an asterisk, the OPTIONS request applies + to the options that are available when communicating with the target + resource.¶

+

+ A server generating a successful response to OPTIONS SHOULD send any + header that might indicate optional features implemented by the + server and applicable to the target resource (e.g., Allow), + including potential extensions not defined by this specification. + The response content, if any, might also describe the communication options + in a machine or human-readable representation. A standard format for such a + representation is not defined by this specification, but might be defined by + future extensions to HTTP.¶

+

+ A client MAY send a Max-Forwards header field in an + OPTIONS request to target a specific recipient in the request chain (see + Section 7.6.2). A proxy MUST NOT generate a + Max-Forwards header field while forwarding a request unless that request + was received with a Max-Forwards field.¶

+

+ A client that generates an OPTIONS request containing content + MUST send a valid Content-Type header field describing + the representation media type. Note that this specification does not define + any use for such content.¶

+

+ Responses to the OPTIONS method are not cacheable.¶

+
+
+
+
+

+9.3.8. TRACE +

+ + +

+ The TRACE method requests a remote, application-level loop-back of the + request message. The final recipient of the request SHOULD reflect the + message received, excluding some fields described below, back to the client + as the content of a 200 (OK) response. The "message/http" + format (Section 10.1 of [HTTP/1.1]) is one way to do so. + The final recipient is either the origin server or the first server to + receive a Max-Forwards value of zero (0) in the request + (Section 7.6.2).¶

+

+ A client MUST NOT generate fields in a TRACE request containing + sensitive data that might be disclosed by the response. For example, it + would be foolish for a user agent to send stored user credentials + (Section 11) or cookies [COOKIE] in a TRACE + request. The final recipient of the request SHOULD exclude any request + fields that are likely to contain sensitive data when that recipient + generates the response content.¶

+

+ TRACE allows the client to see what is being received at the other + end of the request chain and use that data for testing or diagnostic + information. The value of the Via header field (Section 7.6.3) + is of particular interest, since it acts as a trace of the request chain. + Use of the Max-Forwards header field allows the client to + limit the length of the request chain, which is useful for testing a chain + of proxies forwarding messages in an infinite loop.¶

+

+ A client MUST NOT send content in a TRACE request.¶

+

+ Responses to the TRACE method are not cacheable.¶

+
+
+
+
+
+
+
+
+

+10. Message Context +

+
+
+

+10.1. Request Context Fields +

+

+ The request header fields below provide additional information about the + request context, including information about the user, user agent, and + resource behind the request.¶

+
+
+

+10.1.1. Expect +

+ + + + +

+ The "Expect" header field in a request indicates a certain set of + behaviors (expectations) that need to be supported by the server in + order to properly handle this request.¶

+ +
+
  Expect =      #expectation
+  expectation = token [ "=" ( token / quoted-string ) parameters ]
+
¶ +
+

+ The Expect field value is case-insensitive.¶

+

+ The only expectation defined by this specification is "100-continue" + (with no defined parameters).¶

+

+ A server that receives an Expect field value containing a member other than + 100-continue + MAY respond with a + 417 (Expectation Failed) status code to indicate that the + unexpected expectation cannot be met.¶

+

+ A "100-continue" expectation informs recipients that the + client is about to send (presumably large) content in this request + and wishes to receive a 100 (Continue) interim response if + the method, target URI, and header fields are not sufficient to cause an immediate + success, redirect, or error response. This allows the client to wait for an + indication that it is worthwhile to send the content before actually + doing so, which can improve efficiency when the data is huge or + when the client anticipates that an error is likely (e.g., when sending a + state-changing method, for the first time, without previously verified + authentication credentials).¶

+

+ For example, a request that begins with¶

+
+
PUT /somewhere/fun HTTP/1.1
+Host: origin.example.com
+Content-Type: video/h264
+Content-Length: 1234567890987
+Expect: 100-continue
+
+
¶ +
+

+ allows the origin server to immediately respond with an error message, such + as 401 (Unauthorized) or 405 (Method Not Allowed), + before the client starts filling the pipes with an unnecessary data + transfer.¶

+

+ Requirements for clients:¶

+
    +
  • + A client MUST NOT generate a 100-continue expectation in a request that + does not include content.¶ +
    • +
  • + A client that will wait for a 100 (Continue) response + before sending the request content MUST send an + Expect header field containing a 100-continue expectation.¶ +
    • +
  • + A client that sends a 100-continue expectation is not required to wait + for any specific length of time; such a client MAY proceed to send the + content even if it has not yet received a response. Furthermore, + since 100 (Continue) responses cannot be sent through an + HTTP/1.0 intermediary, such a client SHOULD NOT wait for an indefinite + period before sending the content.¶ +
    • +
  • + A client that receives a 417 (Expectation Failed) status + code in response to a request containing a 100-continue expectation + SHOULD repeat that request without a 100-continue expectation, since + the 417 response merely indicates that the response chain does not + support expectations (e.g., it passes through an HTTP/1.0 server).¶ +
    • +
+

+ Requirements for servers:¶

+
    +
  • + A server that receives a 100-continue expectation in an HTTP/1.0 request + MUST ignore that expectation.¶ +
    • +
  • + A server MAY omit sending a 100 (Continue) response if + it has already received some or all of the content for the + corresponding request, or if the framing indicates that there is no + content.¶ +
    • +
  • + A server that sends a 100 (Continue) response MUST + ultimately send a final status code, once it receives and processes the + request content, unless the connection is closed prematurely.¶ +
    • +
  • + A server that responds with a final status code before reading the + entire request content SHOULD indicate whether it intends to + close the connection (e.g., see Section 9.6 of [HTTP/1.1]) or + continue reading the request content.¶ +
    • +
+

+ Upon receiving an HTTP/1.1 (or later) request that has a method, target URI, + and complete header section that contains a 100-continue expectation and + an indication that request content will follow, an origin server MUST + send either:¶

+
    +
  • an immediate response with a final status code, if that status can be + determined by examining just the method, target URI, and header fields, or¶ +
    • +
  • an immediate 100 (Continue) response to encourage the client + to send the request content.¶ +
    • +
+

+ The origin server MUST NOT wait for the content + before sending the 100 (Continue) response.¶

+

+ Upon receiving an HTTP/1.1 (or later) request that has a method, target URI, + and complete header section that contains a 100-continue expectation and + indicates a request content will follow, a proxy MUST either:¶

+
    +
  • send an immediate + response with a final status code, if that status can be determined by + examining just the method, target URI, and header fields, or¶ +
    • +
  • forward the request toward the origin server by sending a corresponding + request-line and header section to the next inbound server.¶ +
    • +
+

+ If the proxy believes (from configuration or past interaction) that the + next inbound server only supports HTTP/1.0, the proxy MAY generate an + immediate 100 (Continue) response to encourage the client to + begin sending the content.¶

+
+
+
+
+

+10.1.2. From +

+ + + +

+ The "From" header field contains an Internet email address for a human + user who controls the requesting user agent. The address ought to be + machine-usable, as defined by "mailbox" + in Section 3.4 of [RFC5322]:¶

+ +
+
  From    = mailbox
+
+  mailbox = <mailbox, see [RFC5322], Section 3.4>
+
¶ +
+

+ An example is:¶

+
+
From: spider-admin@example.org
+
¶ +
+

+ The From header field is rarely sent by non-robotic user agents. + A user agent SHOULD NOT send a From header field without explicit + configuration by the user, since that might conflict with the user's + privacy interests or their site's security policy.¶

+

+ A robotic user agent SHOULD send a valid From header field so that the + person responsible for running the robot can be contacted if problems + occur on servers, such as if the robot is sending excessive, unwanted, + or invalid requests.¶

+

+ A server SHOULD NOT use the From header field for access control or + authentication, since its value is expected to be visible to anyone + receiving or observing the request and is often recorded within logfiles + and error reports without any expectation of privacy.¶

+
+
+
+
+

+10.1.3. Referer +

+ + + +

+ The "Referer" [sic] header field allows the user agent to specify a URI + reference for the resource from which the target URI was + obtained (i.e., the "referrer", though the field name is misspelled). + A user agent MUST NOT include the fragment and userinfo components + of the URI reference [URI], if any, when generating the + Referer field value.¶

+ +
+
  Referer = absolute-URI / partial-URI
+
¶ +
+

+ The field value is either an absolute-URI or a + partial-URI. In the latter case (Section 4), + the referenced URI is relative to the target URI + ([URI], Section 5).¶

+

+ The Referer header field allows servers to generate back-links to other + resources for simple analytics, logging, optimized caching, etc. It also + allows obsolete or mistyped links to be found for maintenance. Some servers + use the Referer header field as a means of denying links from other sites + (so-called "deep linking") or restricting cross-site request forgery (CSRF), + but not all requests contain it.¶

+

+ Example:¶

+
+
Referer: http://www.example.org/hypertext/Overview.html
+
¶ +
+

+ If the target URI was obtained from a source that does not have its own + URI (e.g., input from the user keyboard, or an entry within the user's + bookmarks/favorites), the user agent MUST either exclude the Referer header field + or send it with a value of "about:blank".¶

+

+ The Referer header field value need not convey the full URI of the referring + resource; a user agent MAY truncate parts other than the referring origin.¶

+

+ The Referer header field has the potential to reveal information about the request + context or browsing history of the user, which is a privacy concern if the + referring resource's identifier reveals personal information (such as an + account name) or a resource that is supposed to be confidential (such as + behind a firewall or internal to a secured service). Most general-purpose + user agents do not send the Referer header field when the referring + resource is a local "file" or "data" URI. A user agent SHOULD NOT send a + Referer header field if the referring resource was accessed with + a secure protocol and the request target has an origin differing from that + of the referring resource, unless the referring resource explicitly allows + Referer to be sent. A user agent MUST NOT send a + Referer header field in an unsecured HTTP request if the + referring resource was accessed with a secure protocol. + See Section 17.9 for additional + security considerations.¶

+

+ Some intermediaries have been known to indiscriminately remove Referer + header fields from outgoing requests. This has the unfortunate side effect + of interfering with protection against CSRF attacks, which can be far + more harmful to their users. Intermediaries and user agent extensions that + wish to limit information disclosure in Referer ought to restrict their + changes to specific edits, such as replacing internal domain names with + pseudonyms or truncating the query and/or path components. + An intermediary SHOULD NOT modify or delete the Referer header field when + the field value shares the same scheme and host as the target URI.¶

+
+
+
+
+

+10.1.4. TE +

+ + + +

+ The "TE" header field describes capabilities of the client with regard to + transfer codings and trailer sections.¶

+

+ As described in Section 6.5, + a TE field with a "trailers" member sent in a request indicates that the + client will not discard trailer fields.¶

+

+ TE is also used within HTTP/1.1 to advise servers about which transfer + codings the client is able to accept in a response. + As of publication, only HTTP/1.1 uses transfer codings + (see Section 7 of [HTTP/1.1]).¶

+

+ The TE field value is a list of members, with each member (aside from + "trailers") consisting of a transfer coding name token with an optional + weight indicating the client's relative preference for that + transfer coding (Section 12.4.2) and + optional parameters for that transfer coding.¶

+ + + + +
+
  TE                 = #t-codings
+  t-codings          = "trailers" / ( transfer-coding [ weight ] )
+  transfer-coding    = token *( OWS ";" OWS transfer-parameter )
+  transfer-parameter = token BWS "=" BWS ( token / quoted-string )
+
¶ +
+

+ A sender of TE MUST also send a "TE" connection option within the + Connection header field (Section 7.6.1) + to inform intermediaries not to forward this field.¶

+
+
+
+
+

+10.1.5. User-Agent +

+ + + +

+ The "User-Agent" header field contains information about the user agent + originating the request, which is often used by servers to help identify + the scope of reported interoperability problems, to work around or tailor + responses to avoid particular user agent limitations, and for analytics + regarding browser or operating system use. A user agent SHOULD send + a User-Agent header field in each request unless specifically configured not + to do so.¶

+ +
+
  User-Agent = product *( RWS ( product / comment ) )
+
¶ +
+

+ The User-Agent field value consists of one or more product identifiers, + each followed by zero or more comments (Section 5.6.5), which together + identify the user agent software and its significant subproducts. + By convention, the product identifiers are listed in decreasing order of + their significance for identifying the user agent software. Each product + identifier consists of a name and optional version.¶

+ + +
+
  product         = token ["/" product-version]
+  product-version = token
+
¶ +
+

+ A sender SHOULD limit generated product identifiers to what is necessary + to identify the product; a sender MUST NOT generate advertising or other + nonessential information within the product identifier. + A sender SHOULD NOT generate information in product-version + that is not a version identifier (i.e., successive versions of the same + product name ought to differ only in the product-version portion of the + product identifier).¶

+

+ Example:¶

+
+
User-Agent: CERN-LineMode/2.15 libwww/2.17b3
+
¶ +
+

+ A user agent SHOULD NOT generate a User-Agent header field containing needlessly + fine-grained detail and SHOULD limit the addition of subproducts by third + parties. Overly long and detailed User-Agent field values increase request + latency and the risk of a user being identified against their wishes + ("fingerprinting").¶

+

+ Likewise, implementations are encouraged not to use the product tokens of + other implementations in order to declare compatibility with them, as this + circumvents the purpose of the field. If a user agent masquerades as a + different user agent, recipients can assume that the user intentionally + desires to see responses tailored for that identified user agent, even + if they might not work as well for the actual user agent being used.¶

+
+
+
+
+
+
+

+10.2. Response Context Fields +

+

+ The response header fields below provide additional information about the + response, beyond what is implied by the status code, including information + about the server, about the target resource, or about related + resources.¶

+
+
+

+10.2.1. Allow +

+ + + +

+ The "Allow" header field lists the set of methods advertised as + supported by the target resource. The purpose of this field + is strictly to inform the recipient of valid request methods associated + with the resource.¶

+ +
+
  Allow = #method
+
¶ +
+

+ Example of use:¶

+
+
Allow: GET, HEAD, PUT
+
¶ +
+

+ The actual set of allowed methods is defined by the origin server at the + time of each request. An origin server MUST generate an Allow header field in a + 405 (Method Not Allowed) response and MAY do so in any + other response. An empty Allow field value indicates that the resource + allows no methods, which might occur in a 405 response if the resource has + been temporarily disabled by configuration.¶

+

+ A proxy MUST NOT modify the Allow header field -- it does not need + to understand all of the indicated methods in order to handle them + according to the generic message handling rules.¶

+
+
+
+
+

+10.2.2. Location +

+ + + +

+ The "Location" header field is used in some responses to refer to a + specific resource in relation to the response. The type of relationship is + defined by the combination of request method and status code semantics.¶

+ +
+
  Location = URI-reference
+
¶ +
+

+ The field value consists of a single URI-reference. When it has the form + of a relative reference ([URI], Section 4.2), + the final value is computed by resolving it against the target + URI ([URI], Section 5).¶

+

+ For 201 (Created) responses, the Location value refers to + the primary resource created by the request. + For 3xx (Redirection) responses, the Location value refers + to the preferred target resource for automatically redirecting the request.¶

+

+ If the Location value provided in a 3xx (Redirection) + response does not have a fragment component, a user agent MUST process the + redirection as if the value inherits the fragment component of the URI + reference used to generate the target URI (i.e., the redirection + inherits the original reference's fragment, if any).¶

+

+ For example, a GET request generated for the URI reference + "http://www.example.org/~tim" might result in a + 303 (See Other) response containing the header field:¶

+
+
Location: /People.html#tim
+
¶ +
+

+ which suggests that the user agent redirect to + "http://www.example.org/People.html#tim"¶

+

+ Likewise, a GET request generated for the URI reference + "http://www.example.org/index.html#larry" might result in a + 301 (Moved Permanently) response containing the header + field:¶

+
+
Location: http://www.example.net/index.html
+
¶ +
+

+ which suggests that the user agent redirect to + "http://www.example.net/index.html#larry", preserving the original fragment + identifier.¶

+

+ There are circumstances in which a fragment identifier in a Location + value would not be appropriate. For example, the Location header field in a + 201 (Created) response is supposed to provide a URI that is + specific to the created resource.¶

+ + +
+
+
+
+

+10.2.3. Retry-After +

+ + + +

+ Servers send the "Retry-After" header field to indicate how long the user + agent ought to wait before making a follow-up request. When sent with a + 503 (Service Unavailable) response, Retry-After indicates + how long the service is expected to be unavailable to the client. + When sent with any 3xx (Redirection) response, Retry-After + indicates the minimum time that the user agent is asked to wait before + issuing the redirected request.¶

+

+ The Retry-After field value can be either an HTTP-date or a number + of seconds to delay after receiving the response.¶

+ +
+
  Retry-After = HTTP-date / delay-seconds
+
¶ +
+
+

+ + A delay-seconds value is a non-negative decimal integer, representing time + in seconds.¶

+
+ +
+
  delay-seconds  = 1*DIGIT
+
¶ +
+

+ Two examples of its use are¶

+
+
Retry-After: Fri, 31 Dec 1999 23:59:59 GMT
+Retry-After: 120
+
¶ +
+

+ In the latter example, the delay is 2 minutes.¶

+
+
+
+
+

+10.2.4. Server +

+ + + +

+ The "Server" header field contains information about the + software used by the origin server to handle the request, which is often + used by clients to help identify the scope of reported interoperability + problems, to work around or tailor requests to avoid particular server + limitations, and for analytics regarding server or operating system use. + An origin server MAY generate a Server header field in its responses.¶

+ +
+
  Server = product *( RWS ( product / comment ) )
+
¶ +
+

+ The Server header field value consists of one or more product identifiers, each + followed by zero or more comments (Section 5.6.5), which together + identify the origin server software and its significant subproducts. + By convention, the product identifiers are listed in decreasing order of + their significance for identifying the origin server software. Each product + identifier consists of a name and optional version, as defined in + Section 10.1.5.¶

+

+ Example:¶

+
+
Server: CERN/3.0 libwww/2.17
+
¶ +
+

+ An origin server SHOULD NOT generate a Server header field containing needlessly + fine-grained detail and SHOULD limit the addition of subproducts by third + parties. Overly long and detailed Server field values increase response + latency and potentially reveal internal implementation details that might + make it (slightly) easier for attackers to find and exploit known security + holes.¶

+
+
+
+
+
+
+
+
+

+11. HTTP Authentication +

+
+
+

+11.1. Authentication Scheme +

+

+ HTTP provides a general framework for access control and authentication, + via an extensible set of challenge-response authentication schemes, which + can be used by a server to challenge a client request and by a client to + provide authentication information. It uses a case-insensitive + token to identify the authentication scheme:¶

+ +
+
  auth-scheme    = token
+
¶ +
+

+ Aside from the general framework, this document does not specify any + authentication schemes. New and existing authentication schemes are + specified independently and ought to be registered within the + "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry". + For example, the "basic" and "digest" authentication schemes are defined by + [RFC7617] and + [RFC7616], respectively.¶

+
+
+
+
+

+11.2. Authentication Parameters +

+

+ The authentication scheme is followed by additional information necessary + for achieving authentication via that scheme as either a + comma-separated list of parameters or a single sequence of characters + capable of holding base64-encoded information.¶

+ +
+
  token68        = 1*( ALPHA / DIGIT /
+                       "-" / "." / "_" / "~" / "+" / "/" ) *"="
+
¶ +
+

+ The token68 syntax allows the 66 unreserved URI characters + ([URI]), plus a few others, so that it can hold a + base64, base64url (URL and filename safe alphabet), base32, or base16 (hex) + encoding, with or without padding, but excluding whitespace + ([RFC4648]).¶

+

+ Authentication parameters are name/value pairs, where the name token is + matched case-insensitively + and each parameter name MUST only occur once per challenge.¶

+ +
+
  auth-param     = token BWS "=" BWS ( token / quoted-string )
+
¶ +
+

+ Parameter values can be expressed either as "token" or as "quoted-string" + (Section 5.6). + Authentication scheme definitions need to accept both notations, both for + senders and recipients, to allow recipients to use generic parsing + components regardless of the authentication scheme.¶

+

+ For backwards compatibility, authentication scheme definitions can restrict + the format for senders to one of the two variants. This can be important + when it is known that deployed implementations will fail when encountering + one of the two formats.¶

+
+
+
+
+

+11.3. Challenge and Response +

+

+ A 401 (Unauthorized) response message is used by an origin + server to challenge the authorization of a user agent, including a + WWW-Authenticate header field containing at least one + challenge applicable to the requested resource.¶

+

+ A 407 (Proxy Authentication Required) response message is + used by a proxy to challenge the authorization of a client, including a + Proxy-Authenticate header field containing at least one + challenge applicable to the proxy for the requested resource.¶

+ +
+
  challenge   = auth-scheme [ 1*SP ( token68 / #auth-param ) ]
+
¶ +
+ +

+ A user agent that wishes to authenticate itself with an origin server + -- usually, but not necessarily, after receiving a + 401 (Unauthorized) -- can do so by including an + Authorization header field with the request.¶

+

+ A client that wishes to authenticate itself with a proxy -- usually, + but not necessarily, after receiving a + 407 (Proxy Authentication Required) -- can do so by + including a Proxy-Authorization header field with the + request.¶

+
+
+
+
+

+11.4. Credentials +

+

+ Both the Authorization field value and the + Proxy-Authorization field value contain the client's + credentials for the realm of the resource being requested, based upon a + challenge received in a response (possibly at some point in the past). + When creating their values, the user agent ought to do so by selecting the + challenge with what it considers to be the most secure auth-scheme that it + understands, obtaining credentials from the user as appropriate. + Transmission of credentials within header field values implies significant + security considerations regarding the confidentiality of the underlying + connection, as described in + Section 17.16.1.¶

+ +
+
  credentials = auth-scheme [ 1*SP ( token68 / #auth-param ) ]
+
¶ +
+

+ Upon receipt of a request for a protected resource that omits credentials, + contains invalid credentials (e.g., a bad password) or partial credentials + (e.g., when the authentication scheme requires more than one round trip), + an origin server SHOULD send a 401 (Unauthorized) response + that contains a WWW-Authenticate header field with at least + one (possibly new) challenge applicable to the requested resource.¶

+

+ Likewise, upon receipt of a request that omits proxy credentials or + contains invalid or partial proxy credentials, a proxy that requires + authentication SHOULD generate a + 407 (Proxy Authentication Required) response that contains + a Proxy-Authenticate header field with at least one + (possibly new) challenge applicable to the proxy.¶

+

+ A server that receives valid credentials that are not adequate to gain + access ought to respond with the 403 (Forbidden) status + code (Section 15.5.4).¶

+

+ HTTP does not restrict applications to this simple challenge-response + framework for access authentication. Additional mechanisms can be used, + such as authentication at the transport level or via message encapsulation, + and with additional header fields specifying authentication information. + However, such additional mechanisms are not defined by this specification.¶

+

+ Note that various custom mechanisms for user authentication use the + Set-Cookie and Cookie header fields, defined in [COOKIE], + for passing tokens related to authentication.¶

+
+
+
+
+

+11.5. Establishing a Protection Space (Realm) +

+ + + +

+ The "realm" authentication parameter is reserved for use by + authentication schemes that wish to indicate a scope of protection.¶

+

+ A "protection space" is defined by the origin (see + Section 4.3.1) of the + server being accessed, in combination with the realm value if present. + These realms allow the protected resources on a server to be + partitioned into a set of protection spaces, each with its own + authentication scheme and/or authorization database. The realm value + is a string, generally assigned by the origin server, that can have + additional semantics specific to the authentication scheme. Note that a + response can have multiple challenges with the same auth-scheme but + with different realms.¶

+

+ The protection space determines the domain over which credentials can + be automatically applied. If a prior request has been authorized, the + user agent MAY reuse the same credentials for all other requests within + that protection space for a period of time determined by the authentication + scheme, parameters, and/or user preferences (such as a configurable + inactivity timeout).¶

+

+ The extent of a protection space, and therefore the requests to which + credentials might be automatically applied, is not necessarily known to + clients without additional information. An authentication scheme might + define parameters that describe the extent of a protection space. Unless + specifically allowed by the authentication scheme, a single protection + space cannot extend outside the scope of its server.¶

+

+ For historical reasons, a sender MUST only generate the quoted-string syntax. + Recipients might have to support both token and quoted-string syntax for + maximum interoperability with existing clients that have been accepting both + notations for a long time.¶

+
+
+
+
+

+11.6. Authenticating Users to Origin Servers +

+
+
+

+11.6.1. WWW-Authenticate +

+ + + +

+ The "WWW-Authenticate" response header field indicates the authentication + scheme(s) and parameters applicable to the target resource.¶

+ +
+
  WWW-Authenticate = #challenge
+
¶ +
+

+ A server generating a 401 (Unauthorized) response + MUST send a WWW-Authenticate header field containing at least one + challenge. A server MAY generate a WWW-Authenticate header field + in other response messages to indicate that supplying credentials + (or different credentials) might affect the response.¶

+

+ A proxy forwarding a response MUST NOT modify any + WWW-Authenticate header fields in that response.¶

+

+ User agents are advised to take special care in parsing the field value, as + it might contain more than one challenge, and each challenge can contain a + comma-separated list of authentication parameters. Furthermore, the header + field itself can occur multiple times.¶

+

+ For instance:¶

+
+
WWW-Authenticate: Basic realm="simple", Newauth realm="apps",
+                 type=1, title="Login to \"apps\""
+
¶ +
+

+ This header field contains two challenges, one for the "Basic" scheme with + a realm value of "simple" and another for the "Newauth" scheme with a + realm value of "apps". It also contains two additional parameters, "type" and "title".¶

+

+ Some user agents do not recognize this form, however. As a result, sending + a WWW-Authenticate field value with more than one member on the same field + line might not be interoperable.¶

+ +
+
+
+
+

+11.6.2. Authorization +

+ + + +

+ The "Authorization" header field allows a user agent to authenticate itself + with an origin server -- usually, but not necessarily, after receiving + a 401 (Unauthorized) response. Its value consists of + credentials containing the authentication information of the user agent for + the realm of the resource being requested.¶

+ +
+
  Authorization = credentials
+
¶ +
+

+ If a request is authenticated and a realm specified, the same credentials + are presumed to be valid for all other requests within this realm (assuming + that the authentication scheme itself does not require otherwise, such as + credentials that vary according to a challenge value or using synchronized + clocks).¶

+

+ A proxy forwarding a request MUST NOT modify any + Authorization header fields in that request. + See Section 3.5 of [CACHING] for details of and requirements + pertaining to handling of the Authorization header field by HTTP caches.¶

+
+
+
+
+

+11.6.3. Authentication-Info +

+ + + +

+ HTTP authentication schemes can use the "Authentication-Info" response + field to communicate information after the client's authentication credentials have been accepted. + This information can include a finalization message from the server (e.g., it can contain the + server authentication).¶

+

+ The field value is a list of parameters (name/value pairs), using the "auth-param" + syntax defined in Section 11.3. + This specification only describes the generic format; authentication schemes + using Authentication-Info will define the individual parameters. The "Digest" + Authentication Scheme, for instance, defines multiple parameters in + Section 3.5 of [RFC7616].¶

+ +
+
  Authentication-Info = #auth-param
+
¶ +
+

+ The Authentication-Info field can be used in any HTTP response, + independently of request method and status code. Its semantics are defined + by the authentication scheme indicated by the Authorization header field + (Section 11.6.2) of the corresponding request.¶

+

+ A proxy forwarding a response is not allowed to modify the field value in any + way.¶

+

+ Authentication-Info can be sent as a trailer field + (Section 6.5) + when the authentication scheme explicitly allows this.¶

+
+
+
+
+
+
+

+11.7. Authenticating Clients to Proxies +

+
+
+

+11.7.1. Proxy-Authenticate +

+ + + +

+ The "Proxy-Authenticate" header field consists of at least one + challenge that indicates the authentication scheme(s) and parameters + applicable to the proxy for this request. + A proxy MUST send at least one Proxy-Authenticate header field in + each 407 (Proxy Authentication Required) response that it + generates.¶

+ +
+
  Proxy-Authenticate = #challenge
+
¶ +
+

+ Unlike WWW-Authenticate, the Proxy-Authenticate header field + applies only to the next outbound client on the response chain. + This is because only the client that chose a given proxy is likely to have + the credentials necessary for authentication. However, when multiple + proxies are used within the same administrative domain, such as office and + regional caching proxies within a large corporate network, it is common + for credentials to be generated by the user agent and passed through the + hierarchy until consumed. Hence, in such a configuration, it will appear + as if Proxy-Authenticate is being forwarded because each proxy will send + the same challenge set.¶

+

+ Note that the parsing considerations for WWW-Authenticate + apply to this header field as well; see Section 11.6.1 + for details.¶

+
+
+
+
+

+11.7.2. Proxy-Authorization +

+ + + +

+ The "Proxy-Authorization" header field allows the client to + identify itself (or its user) to a proxy that requires + authentication. Its value consists of credentials containing the + authentication information of the client for the proxy and/or realm of the + resource being requested.¶

+ +
+
  Proxy-Authorization = credentials
+
¶ +
+

+ Unlike Authorization, the Proxy-Authorization header field + applies only to the next inbound proxy that demanded authentication using + the Proxy-Authenticate header field. When multiple proxies are used + in a chain, the Proxy-Authorization header field is consumed by the first + inbound proxy that was expecting to receive credentials. A proxy MAY + relay the credentials from the client request to the next proxy if that is + the mechanism by which the proxies cooperatively authenticate a given + request.¶

+
+
+
+
+

+11.7.3. Proxy-Authentication-Info +

+ + + +

+ The "Proxy-Authentication-Info" response header field is equivalent to + Authentication-Info, except that it applies to proxy authentication (Section 11.3) + and its semantics are defined by the + authentication scheme indicated by the Proxy-Authorization header field + (Section 11.7.2) + of the corresponding request:¶

+ +
+
  Proxy-Authentication-Info = #auth-param
+
¶ +
+

+ However, unlike Authentication-Info, the Proxy-Authentication-Info header + field applies only to the next outbound client on the response chain. This is + because only the client that chose a given proxy is likely to have the + credentials necessary for authentication. However, when multiple proxies are + used within the same administrative domain, such as office and regional + caching proxies within a large corporate network, it is common for + credentials to be generated by the user agent and passed through the + hierarchy until consumed. Hence, in such a configuration, it will appear as + if Proxy-Authentication-Info is being forwarded because each proxy will send + the same field value.¶

+

+ Proxy-Authentication-Info can be sent as a trailer field + (Section 6.5) + when the authentication scheme explicitly allows this.¶

+
+
+
+
+
+
+
+
+

+12. Content Negotiation +

+

+ When responses convey content, whether indicating a success or + an error, the origin server often has different ways of representing that + information; for example, in different formats, languages, or encodings. + Likewise, different users or user agents might have differing capabilities, + characteristics, or preferences that could influence which representation, + among those available, would be best to deliver. For this reason, HTTP + provides mechanisms for content negotiation.¶

+

+ This specification defines three patterns of content negotiation that can + be made visible within the protocol: + "proactive" negotiation, where the server selects the representation based + upon the user agent's stated preferences; "reactive" negotiation, + where the server provides a list of representations for the user agent to + choose from; and "request content" negotiation, where the user agent + selects the representation for a future request based upon the server's + stated preferences in past responses.¶

+

+ Other patterns of content negotiation include + "conditional content", where the representation consists of multiple + parts that are selectively rendered based on user agent parameters, + "active content", where the representation contains a script that + makes additional (more specific) requests based on the user agent + characteristics, and "Transparent Content Negotiation" + ([RFC2295]), where content selection is performed by + an intermediary. These patterns are not mutually exclusive, and each has + trade-offs in applicability and practicality.¶

+

+ Note that, in all cases, HTTP is not aware of the resource semantics. + The consistency with which an origin server responds to requests, over time + and over the varying dimensions of content negotiation, and thus the + "sameness" of a resource's observed representations over time, is + determined entirely by whatever entity or algorithm selects or generates + those responses.¶

+
+
+

+12.1. Proactive Negotiation +

+

+ When content negotiation preferences are sent by the user agent in a + request to encourage an algorithm located at the server to + select the preferred representation, it is called + "proactive negotiation" + (a.k.a., "server-driven negotiation"). Selection is based on + the available representations for a response (the dimensions over which it + might vary, such as language, content coding, etc.) compared to various + information supplied in the request, including both the explicit + negotiation header fields below and implicit + characteristics, such as the client's network address or parts of the + User-Agent field.¶

+

+ Proactive negotiation is advantageous when the algorithm for + selecting from among the available representations is difficult to + describe to a user agent, or when the server desires to send its + "best guess" to the user agent along with the first response (when that + "best guess" is good enough for the user, this avoids the round-trip + delay of a subsequent request). In order to improve the server's + guess, a user agent MAY send request header fields that describe + its preferences.¶

+

+ Proactive negotiation has serious disadvantages:¶

+
    +
  • + It is impossible for the server to accurately determine what + might be "best" for any given user, since that would require + complete knowledge of both the capabilities of the user agent + and the intended use for the response (e.g., does the user want + to view it on screen or print it on paper?);¶ +
    • +
  • + Having the user agent describe its capabilities in every + request can be both very inefficient (given that only a small + percentage of responses have multiple representations) and a + potential risk to the user's privacy;¶ +
    • +
  • + It complicates the implementation of an origin server and the + algorithms for generating responses to a request; and,¶ +
    • +
  • + It limits the reusability of responses for shared caching.¶ +
    • +
+

+ A user agent cannot rely on proactive negotiation preferences being + consistently honored, since the origin server might not implement proactive + negotiation for the requested resource or might decide that sending a + response that doesn't conform to the user agent's preferences is better + than sending a 406 (Not Acceptable) response.¶

+

+ A Vary header field (Section 12.5.5) is + often sent in a response subject to proactive negotiation to indicate what + parts of the request information were used in the selection algorithm.¶

+

+ The request header fields Accept, + Accept-Charset, Accept-Encoding, and + Accept-Language are defined below for a user agent to engage + in proactive negotiation of the response content. + The preferences sent in these + fields apply to any content in the response, including representations of + the target resource, representations of error or processing status, and + potentially even the miscellaneous text strings that might appear within + the protocol.¶

+
+
+
+
+

+12.2. Reactive Negotiation +

+

+ With "reactive negotiation" (a.k.a., "agent-driven negotiation"), selection of + content (regardless of the status code) is performed by + the user agent after receiving an initial response. The mechanism for + reactive negotiation might be as simple as a list of references to + alternative representations.¶

+

+ If the user agent is not satisfied by the initial response content, + it can perform a GET request on one or more of the alternative resources + to obtain a different representation. Selection of such alternatives might + be performed automatically (by the user agent) or manually (e.g., by the + user selecting from a hypertext menu).¶

+

+ A server might choose not to send an initial representation, other than + the list of alternatives, and thereby indicate that reactive + negotiation by the user agent is preferred. For example, the alternatives + listed in responses with the 300 (Multiple Choices) and + 406 (Not Acceptable) status codes include information about + available representations so that the user or user agent can react by + making a selection.¶

+

+ Reactive negotiation is advantageous when the response would vary + over commonly used dimensions (such as type, language, or encoding), + when the origin server is unable to determine a user agent's + capabilities from examining the request, and generally when public + caches are used to distribute server load and reduce network usage.¶

+

+ Reactive negotiation suffers from the disadvantages of transmitting + a list of alternatives to the user agent, which degrades user-perceived + latency if transmitted in the header section, and needing a second request + to obtain an alternate representation. Furthermore, this specification + does not define a mechanism for supporting automatic selection, though it + does not prevent such a mechanism from being developed.¶

+
+
+
+
+

+12.3. Request Content Negotiation +

+

+ When content negotiation preferences are sent in a server's response, the + listed preferences are called "request content negotiation" + because they intend to influence selection of an appropriate content for + subsequent requests to that resource. For example, + the Accept (Section 12.5.1) and + Accept-Encoding (Section 12.5.3) + header fields can be sent in a response to indicate preferred media types + and content codings for subsequent requests to that resource.¶

+

+ Similarly, Section 3.1 of [RFC5789] defines + the "Accept-Patch" response header field, which allows discovery of + which content types are accepted in PATCH requests.¶

+
+
+
+
+

+12.4. Content Negotiation Field Features +

+
+
+

+12.4.1. Absence +

+

+ For each of the content negotiation fields, a request that does not contain + the field implies that the sender has no preference on that dimension of + negotiation.¶

+

+ If a content negotiation header field is present in a request and none of + the available + representations for the response can be considered acceptable according to + it, the origin server can either honor the header field by sending a + 406 (Not Acceptable) response or disregard the header field + by treating the response as if it is not subject to content negotiation + for that request header field. This does not imply, however, that the + client will be able to use the representation.¶

+ +
+
+
+
+

+12.4.2. Quality Values +

+

+ The content negotiation fields defined by this specification + use a common parameter, named "q" (case-insensitive), to assign a relative + "weight" to the preference for that associated kind of content. + This weight is referred to as a "quality value" (or "qvalue") because + the same parameter name is often used within server configurations to + assign a weight to the relative quality of the various representations + that can be selected for a resource.¶

+

+ The weight is normalized to a real number in the range 0 through 1, + where 0.001 is the least preferred and 1 is the most preferred; + a value of 0 means "not acceptable". If no "q" parameter is present, + the default weight is 1.¶

+ + +
+
  weight = OWS ";" OWS "q=" qvalue
+  qvalue = ( "0" [ "." 0*3DIGIT ] )
+         / ( "1" [ "." 0*3("0") ] )
+
¶ +
+

+ A sender of qvalue MUST NOT generate more than three digits after the + decimal point. User configuration of these values ought to be limited in + the same fashion.¶

+
+
+
+
+

+12.4.3. Wildcard Values +

+

+ Most of these header fields, where indicated, define a wildcard value ("*") + to select unspecified values. If no wildcard is present, values that are + not explicitly mentioned in the field are considered unacceptable. + Within Vary, the wildcard value means that the variance + is unlimited.¶

+ +
+
+
+
+
+
+

+12.5. Content Negotiation Fields +

+
+
+

+12.5.1. Accept +

+ + + +

+ The "Accept" header field can be used by user agents to specify their + preferences regarding response media types. For example, Accept header + fields can be used to indicate that the request is specifically limited to + a small set of desired types, as in the case of a request for an in-line + image.¶

+

+ When sent by a server in a response, Accept provides information + about which content types are preferred in the content of a subsequent + request to the same resource.¶

+ + +
+
  Accept = #( media-range [ weight ] )
+
+  media-range    = ( "*/*"
+                     / ( type "/" "*" )
+                     / ( type "/" subtype )
+                   ) parameters
+
¶ +
+

+ The asterisk "*" character is used to group media types into ranges, + with "*/*" indicating all media types and "type/*" indicating all + subtypes of that type. The media-range can include media type + parameters that are applicable to that range.¶

+

+ Each media-range might be followed by optional applicable media type + parameters (e.g., charset), followed by an optional "q" + parameter for indicating a relative weight (Section 12.4.2).¶

+

+ Previous specifications allowed additional extension parameters to appear + after the weight parameter. The accept extension grammar (accept-params, accept-ext) has + been removed because it had a complicated definition, was not being used in + practice, and is more easily deployed through new header fields. Senders + using weights SHOULD send "q" last (after all media-range parameters). + Recipients SHOULD process any parameter named "q" as weight, regardless of + parameter ordering.¶

+ +

+ The example¶

+
+
Accept: audio/*; q=0.2, audio/basic
+
¶ +
+

+ is interpreted as "I prefer audio/basic, but send me any audio + type if it is the best available after an 80% markdown in quality".¶

+

+ A more elaborate example is¶

+
+
Accept: text/plain; q=0.5, text/html,
+       text/x-dvi; q=0.8, text/x-c
+
¶ +
+

+ Verbally, this would be interpreted as "text/html and text/x-c are + the equally preferred media types, but if they do not exist, then send the + text/x-dvi representation, and if that does not exist, send the text/plain + representation".¶

+

+ Media ranges can be overridden by more specific media ranges or + specific media types. If more than one media range applies to a given + type, the most specific reference has precedence. For example,¶

+
+
Accept: text/*, text/plain, text/plain;format=flowed, */*
+
¶ +
+

+ have the following precedence:¶

+
    +
  1. text/plain;format=flowed¶ +
    2. +
  2. text/plain¶ +
    3. +
  3. text/*¶ +
    4. +
  4. */*¶ +
    5. +
+

+ The media type quality factor associated with a given type is + determined by finding the media range with the highest precedence + that matches the type. For example,¶

+
+
Accept: text/*;q=0.3, text/plain;q=0.7, text/plain;format=flowed,
+       text/plain;format=fixed;q=0.4, */*;q=0.5
+
¶ +
+

+ would cause the following values to be associated:¶

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 5
Media TypeQuality Value
text/plain;format=flowed1
text/plain0.7
text/html0.3
image/jpeg0.5
text/plain;format=fixed0.4
text/html;level=30.7
+ +
+
+
+
+

+12.5.2. Accept-Charset +

+ + + +

+ The "Accept-Charset" header field can be sent by a user agent to indicate + its preferences for charsets in textual response content. For example, + this field allows user agents capable of understanding more comprehensive + or special-purpose charsets to signal that capability to an origin server + that is capable of representing information in those charsets.¶

+ +
+
  Accept-Charset = #( ( token / "*" ) [ weight ] )
+
¶ +
+

+ Charset names are defined in Section 8.3.2. + A user agent MAY associate a quality value with each charset to indicate + the user's relative preference for that charset, as defined in Section 12.4.2. + An example is¶

+
+
Accept-Charset: iso-8859-5, unicode-1-1;q=0.8
+
¶ +
+

+ The special value "*", if present in the Accept-Charset header field, + matches every charset that is not mentioned elsewhere in the + field.¶

+ +
+
+
+
+

+12.5.3. Accept-Encoding +

+ + + +

+ The "Accept-Encoding" header field can be used to indicate preferences + regarding the use of content codings (Section 8.4.1).¶

+

+ When sent by a user agent in a request, Accept-Encoding indicates the + content codings acceptable in a response.¶

+

+ When sent by a server in a response, Accept-Encoding provides information + about which content codings are preferred in the content of a subsequent + request to the same resource.¶

+

+ An "identity" token is used as a synonym for + "no encoding" in order to communicate when no encoding is preferred.¶

+ + +
+
  Accept-Encoding  = #( codings [ weight ] )
+  codings          = content-coding / "identity" / "*"
+
¶ +
+

+ Each codings value MAY be given an associated quality value (weight) + representing the preference for that encoding, as defined in Section 12.4.2. + The asterisk "*" symbol in an Accept-Encoding field matches any available + content coding not explicitly listed in the field.¶

+

+ Examples:¶

+
+
Accept-Encoding: compress, gzip
+Accept-Encoding:
+Accept-Encoding: *
+Accept-Encoding: compress;q=0.5, gzip;q=1.0
+Accept-Encoding: gzip;q=1.0, identity; q=0.5, *;q=0
+
¶ +
+

+ A server tests whether a content coding for a given representation is + acceptable using these rules:¶

+
    +
  1. If no Accept-Encoding header field is in the request, any content coding is + considered acceptable by the user agent.¶ +
    2. +
  2. If the representation has no content coding, then it is acceptable + by default unless specifically excluded by the Accept-Encoding header field + stating either "identity;q=0" or "*;q=0" without a more specific + entry for "identity".¶ +
    3. +
  3. If the representation's content coding is one of the content codings + listed in the Accept-Encoding field value, then it is acceptable unless + it is accompanied by a qvalue of 0. (As defined in Section 12.4.2, a + qvalue of 0 means "not acceptable".)¶ +
    4. +
+

+ A representation could be encoded with multiple content codings. However, most + content codings are alternative ways to accomplish the same purpose + (e.g., data compression). When selecting between multiple content codings that + have the same purpose, the acceptable content coding with the highest + non-zero qvalue is preferred.¶

+

+ An Accept-Encoding header field with a field value that is empty + implies that the user agent does not want any content coding in response. + If a non-empty Accept-Encoding header field is present in a request and none of the + available representations for the response have a content coding that + is listed as acceptable, the origin server SHOULD send a response + without any content coding unless the identity coding is indicated as unacceptable.¶

+

+ When the Accept-Encoding header field is present in a response, it indicates + what content codings the resource was willing to accept in the associated + request. The field value is evaluated the same way as in a request.¶

+

+ Note that this information is specific to the associated request; the set of + supported encodings might be different for other resources on the same + server and could change over time or depend on other aspects of the request + (such as the request method).¶

+

+ Servers that fail a request due to an unsupported content coding ought to + respond with a 415 (Unsupported Media Type) status and + include an Accept-Encoding header field in that response, allowing + clients to distinguish between issues related to content codings and media + types. In order to avoid confusion with issues related to media types, + servers that fail a request with a 415 status for reasons unrelated to + content codings MUST NOT include the Accept-Encoding header + field.¶

+

+ The most common use of Accept-Encoding is in responses with a + 415 (Unsupported Media Type) status code, in response to + optimistic use of a content coding by clients. However, the header field + can also be used to indicate to clients that content codings are supported in order + to optimize future interactions. For example, a resource might include it + in a 2xx (Successful) response when the request content was + big enough to justify use of a compression coding but the client failed do + so.¶

+
+
+
+
+

+12.5.4. Accept-Language +

+ + + +

+ The "Accept-Language" header field can be used by user agents to + indicate the set of natural languages that are preferred in the response. + Language tags are defined in Section 8.5.1.¶

+ + +
+
  Accept-Language = #( language-range [ weight ] )
+  language-range  =
+            <language-range, see [RFC4647], Section 2.1>
+
¶ +
+

+ Each language-range can be given an associated quality value + representing an estimate of the user's preference for the languages + specified by that range, as defined in Section 12.4.2. For example,¶

+
+
Accept-Language: da, en-gb;q=0.8, en;q=0.7
+
¶ +
+

+ would mean: "I prefer Danish, but will accept British English and + other types of English".¶

+

+ Note that some recipients treat the order in which language tags are listed + as an indication of descending priority, particularly for tags that are + assigned equal quality values (no value is the same as q=1). However, this + behavior cannot be relied upon. For consistency and to maximize + interoperability, many user agents assign each language tag a unique + quality value while also listing them in order of decreasing quality. + Additional discussion of language priority lists can be found in + Section 2.3 of [RFC4647].¶

+

+ For matching, Section 3 of [RFC4647] defines + several matching schemes. Implementations can offer the most appropriate + matching scheme for their requirements. The "Basic Filtering" scheme + ([RFC4647], Section 3.3.1) is identical to the + matching scheme that was previously defined for HTTP in + Section 14.4 of [RFC2616].¶

+

+ It might be contrary to the privacy expectations of the user to send + an Accept-Language header field with the complete linguistic preferences of + the user in every request (Section 17.13).¶

+

+ Since intelligibility is highly dependent on the individual user, user + agents need to allow user control over the linguistic preference (either + through configuration of the user agent itself or by defaulting to a user + controllable system setting). + A user agent that does not provide such control to the user MUST NOT + send an Accept-Language header field.¶

+ +
+
+
+
+

+12.5.5. Vary +

+ + + +

+ The "Vary" header field in a response describes what parts of a request + message, aside from the method and target URI, might have influenced the + origin server's process for selecting the content of this response.¶

+ +
+
  Vary = #( "*" / field-name )
+
¶ +
+

+ A Vary field value is either the wildcard member "*" or a list of + request field names, known as the selecting header fields, that might + have had a role in selecting the representation for this response. + Potential selecting header fields are not limited to fields defined by + this specification.¶

+

+ A list containing the member "*" signals that other aspects of the + request might have played a role in selecting the response representation, + possibly including aspects outside the message syntax (e.g., the + client's network address). + A recipient will not be able to determine whether this response is + appropriate for a later request without forwarding the request to the + origin server. A proxy MUST NOT generate "*" in a Vary field value.¶

+

+ For example, a response that contains¶

+
+
Vary: accept-encoding, accept-language
+
¶ +
+

+ indicates that the origin server might have used the request's + Accept-Encoding and Accept-Language + header fields (or lack thereof) as determining factors while choosing + the content for this response.¶

+

+ A Vary field containing a list of field names has two purposes:¶

+
    +
  1. +

    + To inform cache recipients that they MUST NOT use this response + to satisfy a later request unless the later request has the + same values for the listed header fields as the original request + (Section 4.1 of [CACHING]) or reuse of the + response has been validated by the origin server. + In other words, Vary expands the cache key + required to match a new request to the stored cache entry.¶

    +
    2. +
  2. +

    + To inform user agent recipients that this response was subject to + content negotiation (Section 12) and a + different representation might be sent in a subsequent request if + other values are provided in the listed header fields + (proactive negotiation).¶

    +
    3. +
+

+ An origin server SHOULD generate a Vary header field on a cacheable + response when it wishes that response to be selectively reused for + subsequent requests. Generally, that is the case when the response + content has been tailored to better fit the preferences expressed by + those selecting header fields, such as when an origin server has + selected the response's language based on the request's + Accept-Language header field.¶

+

+ Vary might be elided when an origin server considers variance in + content selection to be less significant than Vary's performance impact + on caching, particularly when reuse is already limited by cache + response directives (Section 5.2 of [CACHING]).¶

+

+ There is no need to send the Authorization field name in Vary because + reuse of that response for a different user is prohibited by the field + definition (Section 11.6.2). + Likewise, if the response content has been selected or influenced by + network region, but the origin server wants the cached response to be + reused even if recipients move from one region to another, then there + is no need for the origin server to indicate such variance in Vary.¶

+
+
+
+
+
+
+
+
+

+13. Conditional Requests +

+ +

+ A conditional request is an HTTP request with one or more request header + fields that indicate a precondition to be tested before + applying the request method to the target resource. + Section 13.2 defines when to evaluate preconditions and + their order of precedence when more than one precondition is present.¶

+

+ Conditional GET requests are the most efficient mechanism for HTTP + cache updates [CACHING]. Conditionals can also be + applied to state-changing methods, such as PUT and DELETE, to prevent + the "lost update" problem: one client accidentally overwriting + the work of another client that has been acting in parallel.¶

+
+
+

+13.1. Preconditions +

+ +

+ Preconditions are usually defined with respect to a state of the target + resource as a whole (its current value set) or the state as observed in a + previously obtained representation (one value in that set). If a resource + has multiple current representations, each with its own observable state, + a precondition will assume that the mapping of each request to a + selected representation (Section 3.2) + is consistent over time. + Regardless, if the mapping is inconsistent or the server is unable to + select an appropriate representation, then no harm will result when the + precondition evaluates to false.¶

+

+ Each precondition defined below consists of a comparison between a + set of validators obtained from prior representations of the target + resource to the current state of validators for the selected + representation (Section 8.8). Hence, these + preconditions evaluate whether the state of the target resource has + changed since a given state known by the client. The effect of such an + evaluation depends on the method semantics and choice of conditional, as + defined in Section 13.2.¶

+

+ Other preconditions, defined by other specifications as extension fields, + might place conditions on all recipients, on the state of the target + resource in general, or on a group of resources. For instance, the "If" + header field in WebDAV can make a request conditional on various aspects + of multiple resources, such as locks, if the recipient understands and + implements that field ([WEBDAV], Section 10.4).¶

+

+ Extensibility of preconditions is only possible when the precondition can + be safely ignored if unknown (like If-Modified-Since), when + deployment can be assumed for a given use case, or when implementation + is signaled by some other property of the target resource. This encourages + a focus on mutually agreed deployment of common standards.¶

+
+
+

+13.1.1. If-Match +

+ + + +

+ The "If-Match" header field makes the request method conditional on the + recipient origin server either having at least one current + representation of the target resource, when the field value is "*", or + having a current representation of the target resource that has an + entity tag matching a member of the list of entity tags provided in the + field value.¶

+

+ An origin server MUST use the strong comparison function when comparing + entity tags for If-Match (Section 8.8.3.2), since + the client intends this precondition to prevent the method from being + applied if there have been any changes to the representation data.¶

+ +
+
  If-Match = "*" / #entity-tag
+
¶ +
+

+ Examples:¶

+
+
If-Match: "xyzzy"
+If-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+If-Match: *
+
¶ +
+

+ If-Match is most often used with state-changing methods (e.g., POST, PUT, + DELETE) to prevent accidental overwrites when multiple user agents might be + acting in parallel on the same resource (i.e., to prevent the "lost update" + problem). In general, it can be used with any method that involves the + selection or modification of a representation to abort the request if the + selected representation's current entity tag is not a + member within the If-Match field value.¶

+

+ When an origin server receives a request that selects a representation + and that request includes an If-Match header field, + the origin server MUST evaluate the If-Match condition per + Section 13.2 prior to performing the method.¶

+

+ To evaluate a received If-Match header field:¶

+
    +
  1. + If the field value is "*", the condition is true if the origin server + has a current representation for the target resource.¶ +
    2. +
  2. + If the field value is a list of entity tags, the condition is true if + any of the listed tags match the entity tag of the selected representation.¶ +
    3. +
  3. + Otherwise, the condition is false.¶ +
    4. +
+

+ An origin server that evaluates an If-Match condition MUST NOT perform + the requested method if the condition evaluates to false. Instead, + the origin server MAY + indicate that the conditional request failed by responding with a + 412 (Precondition Failed) status code. Alternatively, + if the request is a state-changing operation that appears to have already + been applied to the selected representation, the origin server MAY respond + with a 2xx (Successful) status code + (i.e., the change requested by the user agent has already succeeded, but + the user agent might not be aware of it, perhaps because the prior response + was lost or an equivalent change was made by some other user agent).¶

+

+ Allowing an origin server to send a success response when a change request + appears to have already been applied is more efficient for many authoring + use cases, but comes with some risk if multiple user agents are making + change requests that are very similar but not cooperative. + For example, multiple user agents writing to a common resource as a + semaphore (e.g., a nonatomic increment) are likely to collide and + potentially lose important state transitions. For those kinds of resources, + an origin server is better off being stringent in sending 412 for every + failed precondition on an unsafe method. + In other cases, excluding the ETag field from a success response might + encourage the user agent to perform a GET as its next request to eliminate + confusion about the resource's current state.¶

+

+ A client MAY send an If-Match header field in a + GET request to indicate that it would prefer a + 412 (Precondition Failed) response if the selected + representation does not match. However, this is only useful in range + requests (Section 14) for completing a previously + received partial representation when there is no desire for a new + representation. If-Range (Section 13.1.5) + is better suited for range requests when the client prefers to receive a + new representation.¶

+

+ A cache or intermediary MAY ignore If-Match because its + interoperability features are only necessary for an origin server.¶

+

+ Note that an If-Match header field with a list value containing "*" and + other values (including other instances of "*") is syntactically + invalid (therefore not allowed to be generated) and furthermore is + unlikely to be interoperable.¶

+
+
+
+
+

+13.1.2. If-None-Match +

+ + + +

+ The "If-None-Match" header field makes the request method conditional on + a recipient cache or origin server either not having any current + representation of the target resource, when the field value is "*", or + having a selected representation with an entity tag that does not match any + of those listed in the field value.¶

+

+ A recipient MUST use the weak comparison function when comparing + entity tags for If-None-Match (Section 8.8.3.2), + since weak entity tags can be used for cache validation even if there have + been changes to the representation data.¶

+ +
+
  If-None-Match = "*" / #entity-tag
+
¶ +
+

+ Examples:¶

+
+
If-None-Match: "xyzzy"
+If-None-Match: W/"xyzzy"
+If-None-Match: "xyzzy", "r2d2xxxx", "c3piozzzz"
+If-None-Match: W/"xyzzy", W/"r2d2xxxx", W/"c3piozzzz"
+If-None-Match: *
+
¶ +
+

+ If-None-Match is primarily used in conditional GET requests to enable + efficient updates of cached information with a minimum amount of + transaction overhead. When a client desires to update one or more stored + responses that have entity tags, the client SHOULD generate an + If-None-Match header field containing a list of those entity tags when + making a GET request; this allows recipient servers to send a + 304 (Not Modified) response to indicate when one of those + stored responses matches the selected representation.¶

+

+ If-None-Match can also be used with a value of "*" to prevent an unsafe + request method (e.g., PUT) from inadvertently modifying an existing + representation of the target resource when the client believes that + the resource does not have a current representation (Section 9.2.1). + This is a variation on the "lost update" problem that might arise if more + than one client attempts to create an initial representation for the target + resource.¶

+

+ When an origin server receives a request that selects a representation + and that request includes an If-None-Match header field, + the origin server MUST evaluate the If-None-Match condition per + Section 13.2 prior to performing the method.¶

+

+ To evaluate a received If-None-Match header field:¶

+
    +
  1. + If the field value is "*", the condition is false if the origin server + has a current representation for the target resource.¶ +
    2. +
  2. + If the field value is a list of entity tags, the condition is false if + one of the listed tags matches the entity tag of the selected representation.¶ +
    3. +
  3. + Otherwise, the condition is true.¶ +
    4. +
+

+ An origin server that evaluates an If-None-Match condition MUST NOT + perform the requested method if the condition evaluates to false; instead, + the origin server MUST respond with either + a) the 304 (Not Modified) status code if the request method + is GET or HEAD or b) the 412 (Precondition Failed) status + code for all other request methods.¶

+

+ Requirements on cache handling of a received If-None-Match header field + are defined in Section 4.3.2 of [CACHING].¶

+

+ Note that an If-None-Match header field with a list value containing "*" and + other values (including other instances of "*") is syntactically + invalid (therefore not allowed to be generated) and furthermore is + unlikely to be interoperable.¶

+
+
+
+
+

+13.1.3. If-Modified-Since +

+ + + +

+ The "If-Modified-Since" header field makes a GET or HEAD request method + conditional on the selected representation's modification + date being more + recent than the date provided in the field value. Transfer of the selected + representation's data is avoided if that data has not changed.¶

+ +
+
  If-Modified-Since = HTTP-date
+
¶ +
+

+ An example of the field is:¶

+
+
If-Modified-Since: Sat, 29 Oct 1994 19:43:31 GMT
+
¶ +
+

+ A recipient MUST ignore If-Modified-Since if the request contains an + If-None-Match header field; the condition in + If-None-Match is considered to be a more accurate + replacement for the condition in If-Modified-Since, and the two are only + combined for the sake of interoperating with older intermediaries that + might not implement If-None-Match.¶

+

+ A recipient MUST ignore the If-Modified-Since header field if the + received field value is not a valid HTTP-date, the field value has more than + one member, or if the request method is neither GET nor HEAD.¶

+

+ A recipient MUST ignore the If-Modified-Since header field if the + resource does not have a modification date available.¶

+

+ A recipient MUST interpret an If-Modified-Since field value's timestamp + in terms of the origin server's clock.¶

+

+ If-Modified-Since is typically used for two distinct purposes: + 1) to allow efficient updates of a cached representation that does not + have an entity tag and 2) to limit the scope of a web traversal to resources + that have recently changed.¶

+

+ When used for cache updates, a cache will typically use the value of the + cached message's Last-Modified header field to generate the field + value of If-Modified-Since. This behavior is most interoperable for cases + where clocks are poorly synchronized or when the server has chosen to only + honor exact timestamp matches (due to a problem with Last-Modified dates + that appear to go "back in time" when the origin server's clock is + corrected or a representation is restored from an archived backup). + However, caches occasionally generate the field value based on other data, + such as the Date header field of the cached message or the + clock time at which the message was received, particularly when the + cached message does not contain a Last-Modified header field.¶

+

+ When used for limiting the scope of retrieval to a recent time window, a + user agent will generate an If-Modified-Since field value based on either + its own clock or a Date header field received from the + server in a prior response. Origin servers that choose an exact + timestamp match based on the selected representation's + Last-Modified + header field will not be able to help the user agent limit its data + transfers to only those changed during the specified window.¶

+

+ When an origin server receives a request that selects a representation + and that request includes an If-Modified-Since header field without an + If-None-Match header field, the origin server SHOULD + evaluate the If-Modified-Since condition per + Section 13.2 prior to performing the method.¶

+

+ To evaluate a received If-Modified-Since header field:¶

+
    +
  1. + If the selected representation's last modification date is earlier or + equal to the date provided in the field value, the condition is false.¶ +
    2. +
  2. + Otherwise, the condition is true.¶ +
    3. +
+

+ An origin server that evaluates an If-Modified-Since condition + SHOULD NOT perform the requested method if the condition evaluates to + false; instead, + the origin server SHOULD generate a 304 (Not Modified) + response, including only those metadata that are useful for identifying or + updating a previously cached response.¶

+

+ Requirements on cache handling of a received If-Modified-Since header field + are defined in Section 4.3.2 of [CACHING].¶

+
+
+
+
+

+13.1.4. If-Unmodified-Since +

+ + + +

+ The "If-Unmodified-Since" header field makes the request method conditional + on the selected representation's last modification date being + earlier than or equal to the date provided in the field value. + This field accomplishes the + same purpose as If-Match for cases where the user agent does + not have an entity tag for the representation.¶

+ +
+
  If-Unmodified-Since = HTTP-date
+
¶ +
+

+ An example of the field is:¶

+
+
If-Unmodified-Since: Sat, 29 Oct 1994 19:43:31 GMT
+
¶ +
+

+ A recipient MUST ignore If-Unmodified-Since if the request contains an + If-Match header field; the condition in + If-Match is considered to be a more accurate replacement for + the condition in If-Unmodified-Since, and the two are only combined for the + sake of interoperating with older intermediaries that might not implement + If-Match.¶

+

+ A recipient MUST ignore the If-Unmodified-Since header field if the + received field value is not a valid HTTP-date (including when the field + value appears to be a list of dates).¶

+

+ A recipient MUST ignore the If-Unmodified-Since header field if the + resource does not have a modification date available.¶

+

+ A recipient MUST interpret an If-Unmodified-Since field value's timestamp + in terms of the origin server's clock.¶

+

+ If-Unmodified-Since is most often used with state-changing methods + (e.g., POST, PUT, DELETE) to prevent accidental overwrites when multiple + user agents might be acting in parallel on a resource that does + not supply entity tags with its representations (i.e., to prevent the + "lost update" problem). + In general, it can be used with any method that involves the selection + or modification of a representation to abort the request if the + selected representation's last modification date has + changed since the date provided in the If-Unmodified-Since field value.¶

+

+ When an origin server receives a request that selects a representation + and that request includes an If-Unmodified-Since header field without + an If-Match header field, + the origin server MUST evaluate the If-Unmodified-Since condition per + Section 13.2 prior to performing the method.¶

+

+ To evaluate a received If-Unmodified-Since header field:¶

+
    +
  1. + If the selected representation's last modification date is earlier than or + equal to the date provided in the field value, the condition is true.¶ +
    2. +
  2. + Otherwise, the condition is false.¶ +
    3. +
+

+ An origin server that evaluates an If-Unmodified-Since condition MUST NOT + perform the requested method if the condition evaluates to false. + Instead, the origin server MAY indicate that the conditional request + failed by responding with a 412 (Precondition Failed) + status code. Alternatively, if the request is a state-changing operation + that appears to have already been applied to the selected representation, + the origin server MAY respond with a 2xx (Successful) + status code + (i.e., the change requested by the user agent has already succeeded, but + the user agent might not be aware of it, perhaps because the prior response + was lost or an equivalent change was made by some other user agent).¶

+

+ Allowing an origin server to send a success response when a change request + appears to have already been applied is more efficient for many authoring + use cases, but comes with some risk if multiple user agents are making + change requests that are very similar but not cooperative. + In those cases, an origin server is better off being stringent in sending + 412 for every failed precondition on an unsafe method.¶

+

+ A client MAY send an If-Unmodified-Since header field in a + GET request to indicate that it would prefer a + 412 (Precondition Failed) response if the selected + representation has been modified. However, this is only useful in range + requests (Section 14) for completing a previously + received partial representation when there is no desire for a new + representation. If-Range (Section 13.1.5) + is better suited for range requests when the client prefers to receive a + new representation.¶

+

+ A cache or intermediary MAY ignore If-Unmodified-Since because its + interoperability features are only necessary for an origin server.¶

+
+
+
+
+

+13.1.5. If-Range +

+ + + +

+ The "If-Range" header field provides a special conditional request + mechanism that is similar to the If-Match and + If-Unmodified-Since header fields but that instructs the + recipient to ignore the Range header field if the validator + doesn't match, resulting in transfer of the new selected representation + instead of a 412 (Precondition Failed) response.¶

+

+ If a client has a partial copy of a representation and wishes + to have an up-to-date copy of the entire representation, it could use the + Range header field with a conditional GET (using + either or both of If-Unmodified-Since and + If-Match.) However, if the precondition fails because the + representation has been modified, the client would then have to make a + second request to obtain the entire current representation.¶

+

+ The "If-Range" header field allows a client to "short-circuit" the second + request. Informally, its meaning is as follows: if the representation is unchanged, + send me the part(s) that I am requesting in Range; otherwise, send me the + entire representation.¶

+ +
+
  If-Range = entity-tag / HTTP-date
+
¶ +
+

+ A valid entity-tag can be distinguished from a valid + HTTP-date by examining the first three characters for a + DQUOTE.¶

+

+ A client MUST NOT generate an If-Range header field in a request that + does not contain a Range header field. + A server MUST ignore an If-Range header field received in a request that + does not contain a Range header field. + An origin server MUST ignore an If-Range header field received in a + request for a target resource that does not support Range requests.¶

+

+ A client MUST NOT generate an If-Range header field containing an + entity tag that is marked as weak. + A client MUST NOT generate an If-Range header field containing an + HTTP-date unless the client has no entity tag for + the corresponding representation and the date is a strong validator + in the sense defined by Section 8.8.2.2.¶

+

+ A server that receives an If-Range header field on a Range request MUST + evaluate the condition per Section 13.2 prior to + performing the method.¶

+

+ To evaluate a received If-Range header field containing an + HTTP-date:¶

+
    +
  1. If the HTTP-date validator provided is not a + strong validator in the sense defined by + Section 8.8.2.2, the condition is false.¶ +
    2. +
  2. If the HTTP-date validator provided exactly matches + the Last-Modified field value for the selected + representation, the condition is true.¶ +
    3. +
  3. Otherwise, the condition is false.¶ +
    4. +
+

+ To evaluate a received If-Range header field containing an + entity-tag:¶

+
    +
  1. If the entity-tag validator provided exactly matches + the ETag field value for the selected representation + using the strong comparison function + (Section 8.8.3.2), the condition is true.¶ +
    2. +
  2. Otherwise, the condition is false.¶ +
    3. +
+

+ A recipient of an If-Range header field MUST ignore the + Range header field if the If-Range condition + evaluates to false. Otherwise, the recipient SHOULD process the + Range header field as requested.¶

+

+ Note that the If-Range comparison is by exact match, including when the + validator is an HTTP-date, and so it + differs from the "earlier than or equal to" comparison used when evaluating + an If-Unmodified-Since conditional.¶

+
+
+
+
+
+
+

+13.2. Evaluation of Preconditions +

+
+
+

+13.2.1. When to Evaluate +

+

+ Except when excluded below, a recipient cache or origin server MUST + evaluate received request preconditions after it has successfully performed + its normal request checks and just before it would process the request content + (if any) or perform the action associated with the request method. + A server MUST ignore all received preconditions if its response to the + same request without those conditions, prior to processing the request content, + would have been a status code other than a 2xx (Successful) + or 412 (Precondition Failed). + In other words, redirects and failures that can be detected before + significant processing occurs take precedence over the evaluation + of preconditions.¶

+

+ A server that is not the origin server for the target resource and cannot + act as a cache for requests on the target resource MUST NOT evaluate the + conditional request header fields defined by this specification, and it + MUST forward them if the request is forwarded, since the generating + client intends that they be evaluated by a server that can provide a + current representation. + Likewise, a server MUST ignore the conditional request header fields + defined by this specification when received with a request method that does + not involve the selection or modification of a + selected representation, such as CONNECT, OPTIONS, or TRACE.¶

+

+ Note that protocol extensions can modify the conditions under which + preconditions are evaluated or the consequences of their evaluation. + For example, the immutable cache directive + (defined by [RFC8246]) instructs caches to forgo + forwarding conditional requests when they hold a fresh response.¶

+

+ Although conditional request header fields are defined as being usable with + the HEAD method (to keep HEAD's semantics consistent with those of GET), + there is no point in sending a conditional HEAD because a successful + response is around the same size as a 304 (Not Modified) + response and more useful than a 412 (Precondition Failed) + response.¶

+
+
+
+
+

+13.2.2. Precedence of Preconditions +

+

+ When more than one conditional request header field is present in a request, + the order in which the fields are evaluated becomes important. In practice, + the fields defined in this document are consistently implemented in a + single, logical order, since "lost update" preconditions have more strict + requirements than cache validation, a validated cache is more efficient + than a partial response, and entity tags are presumed to be more accurate + than date validators.¶

+

+ A recipient cache or origin server MUST evaluate the request + preconditions defined by this specification in the following order:¶

+
    +
  1. +
    +

    When recipient is the origin server and + If-Match is present, + evaluate the If-Match precondition:¶

    + +
    +
    2. +
  2. +
    +

    When recipient is the origin server, + If-Match is not present, and + If-Unmodified-Since is present, + evaluate the If-Unmodified-Since precondition:¶

    + +
    +
    3. +
  3. +
    +

    When If-None-Match is present, + evaluate the If-None-Match precondition:¶

    + +
    +
    4. +
  4. +
    +

    When the method is GET or HEAD, + If-None-Match is not present, and + If-Modified-Since is present, + evaluate the If-Modified-Since precondition:¶

    + +
    +
    5. +
  5. +
    +

    When the method is GET and both + Range and If-Range are present, + evaluate the If-Range precondition:¶

    + +
    +
    6. +
  6. +
    +

    Otherwise,¶

    +
      +
    • perform the requested method and + respond according to its success or failure.¶ +
      • +
    +
    +
    7. +
+

+ Any extension to HTTP that defines additional conditional request + header fields ought to define the order + for evaluating such fields in relation to those defined in this document + and other conditionals that might be found in practice.¶

+
+
+
+
+
+
+
+
+

+14. Range Requests +

+

+ Clients often encounter interrupted data + transfers as a result of canceled requests or dropped connections. When a + client has stored a partial representation, it is desirable to request the + remainder of that representation in a subsequent request rather than + transfer the entire representation. Likewise, devices with limited local + storage might benefit from being able to request only a subset of a larger + representation, such as a single page of a very large document, or the + dimensions of an embedded image.¶

+

+ Range requests are an OPTIONAL feature + of HTTP, designed so that recipients not implementing this feature (or not + supporting it for the target resource) can respond as if it is a normal + GET request without impacting interoperability. Partial responses are + indicated by a distinct status code to not be mistaken for full responses + by caches that might not implement the feature.¶

+
+
+

+14.1. Range Units +

+

+ Representation data can be partitioned into subranges when there are + addressable structural units inherent to that data's content coding or + media type. For example, octet (a.k.a. byte) boundaries are a structural + unit common to all representation data, allowing partitions of the data to + be identified as a range of bytes at some offset from the start or end of + that data.¶

+

+ This general notion of a "range unit" is used + in the Accept-Ranges (Section 14.3) + response header field to advertise support for range requests, the + Range (Section 14.2) request header field + to delineate the parts of a representation that are requested, and the + Content-Range (Section 14.4) + header field to describe which part of a representation is being + transferred.¶

+ +
+
  range-unit       = token
+
¶ +
+

+ All range unit names are case-insensitive and ought to be registered + within the "HTTP Range Unit Registry", as defined in + Section 16.5.1.¶

+

+ Range units are intended to be extensible, as described in + Section 16.5.¶

+
+
+

+14.1.1. Range Specifiers +

+ + +

+ Ranges are expressed in terms of a range unit paired with a set of range + specifiers. The range unit name determines what kinds of range-spec + are applicable to its own specifiers. Hence, the following grammar is + generic: each range unit is expected to specify requirements on when + int-range, suffix-range, and + other-range are allowed.¶

+
+

+ + + + A range request can specify a single range or a set + of ranges within a single representation.¶

+
+ + + +
+
  ranges-specifier = range-unit "=" range-set
+  range-set        = 1#range-spec
+  range-spec       = int-range
+                   / suffix-range
+                   / other-range
+
¶ +
+
+

+ + + + An int-range is a range expressed as two non-negative + integers or as one non-negative integer through to the end of the + representation data. + The range unit specifies what the integers mean (e.g., they might indicate + unit offsets from the beginning, inclusive numbered parts, etc.).¶

+
+ + + +
+
  int-range     = first-pos "-" [ last-pos ]
+  first-pos     = 1*DIGIT
+  last-pos      = 1*DIGIT
+
¶ +
+

+ An int-range is invalid if the + last-pos value is present and less than the + first-pos.¶

+
+

+ + + A suffix-range is a range expressed as a suffix of the + representation data with the provided non-negative integer maximum length + (in range units). In other words, the last N units of the representation + data.¶

+
+ + +
+
  suffix-range  = "-" suffix-length
+  suffix-length = 1*DIGIT
+
¶ +
+
+

+ + To provide for extensibility, the other-range rule is a + mostly unconstrained grammar that allows application-specific or future + range units to define additional range specifiers.¶

+
+ +
+
  other-range   = 1*( %x21-2B / %x2D-7E )
+                ; 1*(VCHAR excluding comma)
+
¶ +
+

+ A ranges-specifier is invalid if it contains any + range-spec that is invalid or undefined for the indicated + range-unit.¶

+
+

+ A valid ranges-specifier is "satisfiable" + if it contains at least one range-spec that is + satisfiable, as defined by the indicated range-unit. + Otherwise, the ranges-specifier is + "unsatisfiable".¶

+
+
+
+
+
+

+14.1.2. Byte Ranges +

+

+ The "bytes" range unit is used to express subranges of a representation + data's octet sequence. + Each byte range is expressed as an integer range at some offset, relative + to either the beginning (int-range) or end + (suffix-range) of the representation data. + Byte ranges do not use the other-range specifier.¶

+

+ The first-pos value in a bytes int-range + gives the offset of the first byte in a range. + The last-pos value gives the offset of the last + byte in the range; that is, the byte positions specified are inclusive. + Byte offsets start at zero.¶

+

+ If the representation data has a content coding applied, each byte range is + calculated with respect to the encoded sequence of bytes, not the sequence + of underlying bytes that would be obtained after decoding.¶

+

+ Examples of bytes range specifiers:¶

+
    +
  • +

    The first 500 bytes (byte offsets 0-499, inclusive):¶

    +
    +
    +     bytes=0-499
+
    ¶ +
    +
    • +
  • +

    The second 500 bytes (byte offsets 500-999, inclusive):¶

    +
    +
    +     bytes=500-999
+
    ¶ +
    +
    • +
+

+ A client can limit the number of bytes requested without knowing the size + of the selected representation. + If the last-pos value is absent, or if the value is + greater than or equal to the current length of the representation data, the + byte range is interpreted as the remainder of the representation (i.e., the + server replaces the value of last-pos with a value that + is one less than the current length of the selected representation).¶

+

+ A client can refer to the last N bytes (N > 0) of the selected + representation using a suffix-range. + If the selected representation is shorter than the specified + suffix-length, the entire representation is used.¶

+

+ Additional examples, assuming a representation of length 10000:¶

+
    +
  • +

    The final 500 bytes (byte offsets 9500-9999, inclusive):¶

    +
    +
    +     bytes=-500
+
    ¶ +
    +

    Or:¶

    +
    +
    +     bytes=9500-
+
    ¶ +
    +
    • +
  • +

    The first and last bytes only (bytes 0 and 9999):¶

    +
    +
    +     bytes=0-0,-1
+
    ¶ +
    +
    • +
  • +

    The first, middle, and last 1000 bytes:¶

    +
    +
    +     bytes= 0-999, 4500-5499, -1000
+
    ¶ +
    +
    • +
  • +

    Other valid (but not canonical) specifications of the second 500 + bytes (byte offsets 500-999, inclusive):¶

    +
    +
    +     bytes=500-600,601-999
+     bytes=500-700,601-999
+
    ¶ +
    +
    • +
+

+ For a GET request, a valid bytes range-spec + is satisfiable if it is either:¶

+ +

+ When a selected representation has zero length, the only + satisfiable form of range-spec in a + GET request is a suffix-range with a + non-zero suffix-length.¶

+

+ In the byte-range syntax, first-pos, + last-pos, and suffix-length are + expressed as decimal number of octets. Since there is no predefined limit + to the length of content, recipients MUST anticipate potentially + large decimal numerals and prevent parsing errors due to integer conversion + overflows.¶

+
+
+
+
+
+
+

+14.2. Range +

+ + + +

+ The "Range" header field on a GET request modifies the method semantics to + request transfer of only one or more subranges of the + selected representation data (Section 8.1), + rather than the entire selected representation.¶

+ +
+
  Range = ranges-specifier
+
¶ +
+

+ A server MAY ignore the Range header field. However, origin servers and + intermediate caches ought to support byte ranges when possible, since they + support efficient recovery from partially failed transfers and partial + retrieval of large representations.¶

+

+ A server MUST ignore a Range header field received with a request method + that is unrecognized or for which range handling is not defined. For this + specification, GET is the only method for which range handling + is defined.¶

+

+ An origin server MUST ignore a Range header field that contains a range + unit it does not understand. A proxy MAY discard a Range header + field that contains a range unit it does not understand.¶

+

+ A server that supports range requests MAY ignore or reject a + Range header field that contains an invalid + ranges-specifier (Section 14.1.1), + a ranges-specifier with more than two overlapping ranges, + or a set of many small ranges that are not listed in ascending order, + since these are indications of either a broken client or a deliberate + denial-of-service attack (Section 17.15). + A client SHOULD NOT request multiple ranges that are inherently less + efficient to process and transfer than a single range that encompasses the + same data.¶

+

+ A server that supports range requests MAY ignore a Range + header field when the selected representation has no content + (i.e., the selected representation's data is of zero length).¶

+

+ A client that is requesting multiple ranges SHOULD list those ranges in + ascending order (the order in which they would typically be received in a + complete representation) unless there is a specific need to request a later + part earlier. For example, a user agent processing a large representation + with an internal catalog of parts might need to request later parts first, + particularly if the representation consists of pages stored in reverse + order and the user agent wishes to transfer one page at a time.¶

+

+ The Range header field is evaluated after evaluating the precondition header + fields defined in Section 13.1, and only if the result in absence + of the Range header field would be a 200 (OK) response. In + other words, Range is ignored when a conditional GET would result in a + 304 (Not Modified) response.¶

+

+ The If-Range header field (Section 13.1.5) can be used as + a precondition to applying the Range header field.¶

+

+ If all of the preconditions are true, the server supports the Range header + field for the target resource, the received Range field-value contains a + valid ranges-specifier with a range-unit + supported for that target resource, and that + ranges-specifier is satisfiable with respect + to the selected representation, + the server SHOULD send a 206 (Partial Content) response + with content containing one or more partial representations + that correspond to the satisfiable range-spec(s) requested.¶

+

+ The above does not imply that a server will send all requested ranges. + In some cases, it may only be possible (or efficient) to send a portion of + the requested ranges first, while expecting the client to re-request the + remaining portions later if they are still desired + (see Section 15.3.7).¶

+

+ If all of the preconditions are true, the server supports the Range header + field for the target resource, the received Range field-value contains a + valid ranges-specifier, and either the + range-unit is not supported for that target resource or + the ranges-specifier is unsatisfiable with respect to + the selected representation, the server SHOULD send a + 416 (Range Not Satisfiable) response.¶

+
+
+
+
+

+14.3. Accept-Ranges +

+ + + +

+ The "Accept-Ranges" field in a response indicates whether an upstream + server supports range requests for the target resource.¶

+ + +
+
  Accept-Ranges     = acceptable-ranges
+  acceptable-ranges = 1#range-unit
+
¶ +
+

+ For example, a server that supports + byte-range requests (Section 14.1.2) can send the field¶

+
+
Accept-Ranges: bytes
+
¶ +
+

+ to indicate that it supports byte range requests for that target resource, + thereby encouraging its use by the client for future partial requests on + the same request path. + Range units are defined in Section 14.1.¶

+

+ A client MAY generate range requests regardless of having received an + Accept-Ranges field. The information only provides advice for the sake of + improving performance and reducing unnecessary network transfers.¶

+

+ Conversely, a client MUST NOT assume that receiving an Accept-Ranges field + means that future range requests will return partial responses. The content might + change, the server might only support range requests at certain times or under + certain conditions, or a different intermediary might process the next request.¶

+

+ A server that does not support any kind of range request for the target + resource MAY send¶

+
+
Accept-Ranges: none
+
¶ +
+

+ to advise the client not to attempt a range request on the same request path. + The range unit "none" is reserved for this purpose.¶

+

+ The Accept-Ranges field MAY be sent in a trailer section, but is preferred + to be sent as a header field because the information is particularly useful + for restarting large information transfers that have failed in mid-content + (before the trailer section is received).¶

+
+
+
+
+

+14.4. Content-Range +

+ + + +

+ The "Content-Range" header field is sent in a single part + 206 (Partial Content) response to indicate the partial range + of the selected representation enclosed as the message content, sent in + each part of a multipart 206 response to indicate the range enclosed within + each body part (Section 14.6), and sent in 416 (Range Not Satisfiable) + responses to provide information about the selected representation.¶

+ + + + + + + +
+
  Content-Range       = range-unit SP
+                        ( range-resp / unsatisfied-range )
+
+  range-resp          = incl-range "/" ( complete-length / "*" )
+  incl-range          = first-pos "-" last-pos
+  unsatisfied-range   = "*/" complete-length
+
+  complete-length     = 1*DIGIT
+
¶ +
+

+ If a 206 (Partial Content) response contains a + Content-Range header field with a range unit + (Section 14.1) that the recipient does not understand, the + recipient MUST NOT attempt to recombine it with a stored representation. + A proxy that receives such a message SHOULD forward it downstream.¶

+

+ Content-Range might also be sent as a request modifier to request a + partial PUT, as described in Section 14.5, based on private + agreements between client and origin server. + A server MUST ignore a Content-Range header field received in a request + with a method for which Content-Range support is not defined.¶

+

+ For byte ranges, a sender SHOULD indicate the complete length of the + representation from which the range has been extracted, unless the complete + length is unknown or difficult to determine. An asterisk character ("*") in + place of the complete-length indicates that the representation length was + unknown when the header field was generated.¶

+

+ The following example illustrates when the complete length of the selected + representation is known by the sender to be 1234 bytes:¶

+
+
Content-Range: bytes 42-1233/1234
+
¶ +
+

+ and this second example illustrates when the complete length is unknown:¶

+
+
Content-Range: bytes 42-1233/*
+
¶ +
+

+ A Content-Range field value is invalid if it contains a + range-resp that has a last-pos + value less than its first-pos value, or a + complete-length value less than or equal to its + last-pos value. The recipient of an invalid + Content-Range + MUST NOT attempt to recombine the received + content with a stored representation.¶

+

+ A server generating a 416 (Range Not Satisfiable) response + to a byte-range request SHOULD send a Content-Range header field with an + unsatisfied-range value, as in the following example:¶

+
+
Content-Range: bytes */1234
+
¶ +
+

+ The complete-length in a 416 response indicates the current length of the + selected representation.¶

+

+ The Content-Range header field has no meaning for status codes that do + not explicitly describe its semantic. For this specification, only the + 206 (Partial Content) and + 416 (Range Not Satisfiable) status codes describe a meaning + for Content-Range.¶

+

+ The following are examples of Content-Range values in which the + selected representation contains a total of 1234 bytes:¶

+
    +
  • +

    The first 500 bytes:¶

    +
    +
    Content-Range: bytes 0-499/1234
+
    ¶ +
    +
    • +
  • +

    The second 500 bytes:¶

    +
    +
    Content-Range: bytes 500-999/1234
+
    ¶ +
    +
    • +
  • +

    All except for the first 500 bytes:¶

    +
    +
    Content-Range: bytes 500-1233/1234
+
    ¶ +
    +
    • +
  • +

    The last 500 bytes:¶

    +
    +
    Content-Range: bytes 734-1233/1234
+
    ¶ +
    +
    • +
+
+
+
+
+

+14.5. Partial PUT +

+ + + +

+ Some origin servers support PUT of a partial representation + when the user agent sends a Content-Range header field + (Section 14.4) in the request, though + such support is inconsistent and depends on private agreements with + user agents. In general, it requests that the state of the + target resource be partly replaced with the enclosed content + at an offset and length indicated by the Content-Range value, where the + offset is relative to the current selected representation.¶

+

+ An origin server SHOULD respond with a 400 (Bad Request) + status code if it receives Content-Range on a PUT for a + target resource that does not support partial PUT requests.¶

+

+ Partial PUT is not backwards compatible with the original definition of PUT. + It may result in the content being written as a complete replacement for the + current representation.¶

+

+ Partial resource updates are also possible by targeting a separately + identified resource with state that overlaps or extends a portion of the + larger resource, or by using a different method that has been specifically + defined for partial updates (for example, the PATCH method defined in + [RFC5789]).¶

+
+
+
+
+

+14.6. Media Type multipart/byteranges +

+ + +

+ When a 206 (Partial Content) response message includes the + content of multiple ranges, they are transmitted as body parts in a + multipart message body ([RFC2046], Section 5.1) + with the media type of "multipart/byteranges".¶

+

+ The "multipart/byteranges" media type includes one or more body parts, each + with its own Content-Type and Content-Range + fields. The required boundary parameter specifies the boundary string used + to separate each body part.¶

+

+ Implementation Notes:¶

+
    +
  1. Additional CRLFs might precede the first boundary string in the body.¶ +
    2. +
  2. Although [RFC2046] permits the boundary string to be + quoted, some existing implementations handle a quoted boundary + string incorrectly.¶ +
    3. +
  3. A number of clients and servers were coded to an early draft + of the byteranges specification that used a media type of + "multipart/x-byteranges", + which is almost (but not quite) compatible with this type.¶ +
    4. +
+

+ Despite the name, the "multipart/byteranges" media type is not limited to + byte ranges. The following example uses an "exampleunit" range unit:¶

+
+
HTTP/1.1 206 Partial Content
+Date: Tue, 14 Nov 1995 06:25:24 GMT
+Last-Modified: Tue, 14 July 04:58:08 GMT
+Content-Length: 2331785
+Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
+
+--THIS_STRING_SEPARATES
+Content-Type: video/example
+Content-Range: exampleunit 1.2-4.3/25
+
+...the first range...
+--THIS_STRING_SEPARATES
+Content-Type: video/example
+Content-Range: exampleunit 11.2-14.3/25
+
+...the second range
+--THIS_STRING_SEPARATES--
+
¶ +
+

+ The following information serves as the registration form for the + "multipart/byteranges" media type.¶

+
+
Type name:
+
multipart¶ +
+
+
Subtype name:
+
byteranges¶ +
+
+
Required parameters:
+
boundary¶ +
+
+
Optional parameters:
+
N/A¶ +
+
+
Encoding considerations:
+
only "7bit", "8bit", or "binary" are permitted¶ +
+
+
Security considerations:
+
see Section 17¶ +
+
+
Interoperability considerations:
+
N/A¶ +
+
+
Published specification:
+
RFC 9110 (see Section 14.6)¶ +
+
+
Applications that use this media type:
+
HTTP components supporting multiple ranges in a single request¶ +
+
+
Fragment identifier considerations:
+
N/A¶ +
+
+
Additional information:
+
+
+
Deprecated alias names for this type:
+
N/A¶ +
+
+
Magic number(s):
+
N/A¶ +
+
+
File extension(s):
+
N/A¶ +
+
+
Macintosh file type code(s):
+
N/A¶ +
+
+
+
+
+
Person and email address to contact for further information:
+
See Authors' Addresses section.¶ +
+
+
Intended usage:
+
COMMON¶ +
+
+
Restrictions on usage:
+
N/A¶ +
+
+
Author:
+
See Authors' Addresses section.¶ +
+
+
Change controller:
+
IESG¶ +
+
+
+
+
+
+
+
+
+

+15. Status Codes +

+ +

+ The status code of a response is a three-digit integer code that describes + the result of the request and the semantics of the response, including + whether the request was successful and what content is enclosed (if any). + All valid status codes are within the range of 100 to 599, inclusive.¶

+

+ The first digit of the status code defines the class of response. The + last two digits do not have any categorization role. There are five + values for the first digit:¶

+ +

+ HTTP status codes are extensible. A client is not required to understand + the meaning of all registered status codes, though such understanding is + obviously desirable. However, a client MUST understand the class of any + status code, as indicated by the first digit, and treat an unrecognized + status code as being equivalent to the x00 status code of that class.¶

+

+ For example, if a client receives an unrecognized status code of 471, + it can see from the first digit that there was something wrong with its + request and treat the response as if it had received a + 400 (Bad Request) status code. The response + message will usually contain a representation that explains the status.¶

+

+ Values outside the range 100..599 are invalid. Implementations often use + three-digit integer values outside of that range (i.e., 600..999) for + internal communication of non-HTTP status (e.g., library errors). A client + that receives a response with an invalid status code SHOULD process the + response as if it had a 5xx (Server Error) status code.¶

+
+

+ + + + A single request can have multiple associated responses: zero or more + "interim" (non-final) responses with status codes in the + "informational" (1xx) range, followed by exactly one + "final" response with a status code in one of the other ranges.¶

+
+
+
+

+15.1. Overview of Status Codes +

+

+ The status codes listed below are defined in this specification. + The reason phrases listed here are only recommendations -- they can be + replaced by local equivalents or left out altogether without affecting the + protocol.¶

+

+ Responses with status codes that are defined as heuristically cacheable + (e.g., 200, 203, 204, 206, 300, 301, 308, 404, 405, 410, 414, and 501 in this + specification) can be reused by a cache with heuristic expiration unless + otherwise indicated by the method definition or explicit cache controls + [CACHING]; all other status codes are not heuristically cacheable.¶

+

+ Additional status codes, outside the scope of this specification, have been + specified for use in HTTP. All such status codes ought to be registered + within the "Hypertext Transfer Protocol (HTTP) Status Code Registry", + as described in Section 16.2.¶

+
+
+
+
+

+15.2. Informational 1xx +

+ + +

+ The 1xx (Informational) class of status code indicates an + interim response for communicating connection status or request progress + prior to completing the requested action and sending a final response. + Since HTTP/1.0 did not define any 1xx status codes, a server MUST NOT send + a 1xx response to an HTTP/1.0 client.¶

+

+ A 1xx response is terminated by the end of the header section; + it cannot contain content or trailers.¶

+

+ A client MUST be able to parse one or more 1xx responses received + prior to a final response, even if the client does not expect one. + A user agent MAY ignore unexpected 1xx responses.¶

+

+ A proxy MUST forward 1xx responses unless the proxy itself + requested the generation of the 1xx response. For example, if a + proxy adds an "Expect: 100-continue" header field when it forwards a request, + then it need not forward the corresponding 100 (Continue) + response(s).¶

+
+
+

+15.2.1. 100 Continue +

+ +

+ The 100 (Continue) status code indicates that the initial + part of a request has been received and has not yet been rejected by the + server. The server intends to send a final response after the request has + been fully received and acted upon.¶

+

+ When the request contains an Expect header field that + includes a 100-continue expectation, the 100 response + indicates that the server wishes to receive the request content, + as described in Section 10.1.1. The client + ought to continue sending the request and discard the 100 response.¶

+

+ If the request did not contain an Expect header field + containing the 100-continue expectation, + the client can simply discard this interim response.¶

+
+
+
+
+

+15.2.2. 101 Switching Protocols +

+ +

+ The 101 (Switching Protocols) status code indicates that the + server understands and is willing to comply with the client's request, + via the Upgrade header field (Section 7.8), for + a change in the application protocol being used on this connection. + The server MUST generate an Upgrade header field in the response that + indicates which protocol(s) will be in effect after this response.¶

+

+ It is assumed that the server will only agree to switch protocols when + it is advantageous to do so. For example, switching to a newer version of + HTTP might be advantageous over older versions, and switching to a + real-time, synchronous protocol might be advantageous when delivering + resources that use such features.¶

+
+
+
+
+
+
+

+15.3. Successful 2xx +

+ + +

+ The 2xx (Successful) class of status code indicates that + the client's request was successfully received, understood, and accepted.¶

+
+
+

+15.3.1. 200 OK +

+ +

+ The 200 (OK) status code indicates that the request has + succeeded. The content sent in a 200 response depends on the request + method. For the methods defined by this specification, the intended meaning + of the content can be summarized as:¶

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 6
Request MethodResponse content is a representation of:
GETthe target resource +
HEADthe target resource, like GET, but without + transferring the representation data
POSTthe status of, or results obtained from, the action
PUT, DELETEthe status of the action
OPTIONScommunication options for the target resource
TRACEthe request message as received by the server returning the + trace
+

+ Aside from responses to CONNECT, a 200 response is expected to contain + message content unless the message framing explicitly indicates that the + content has zero length. If some aspect of the request indicates a + preference for no content upon success, the origin server ought to send a + 204 (No Content) response instead. + For CONNECT, there is no content because the successful result is a + tunnel, which begins immediately after the 200 response header section.¶

+

+ A 200 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+

+ In 200 responses to GET or HEAD, an origin server SHOULD send any + available validator fields (Section 8.8) for the + selected representation, with both a strong entity tag and + a Last-Modified date being preferred.¶

+

+ In 200 responses to state-changing methods, any validator fields + (Section 8.8) sent in the response convey the + current validators for the new representation formed as a result of + successfully applying the request semantics. Note that the PUT method + (Section 9.3.4) has additional requirements that might preclude + sending such validators.¶

+
+
+
+
+

+15.3.2. 201 Created +

+ +

+ The 201 (Created) status code indicates that the request has + been fulfilled and has resulted in one or more new resources being created. + The primary resource created by the request is identified by either a + Location header field in the response or, if no + Location header field is received, by the target URI.¶

+

+ The 201 response content typically describes and links to the resource(s) + created. Any validator fields (Section 8.8) + sent in the response convey the current validators for a new + representation created by the request. Note that the PUT method + (Section 9.3.4) has additional requirements that might preclude + sending such validators.¶

+
+
+
+
+

+15.3.3. 202 Accepted +

+ +

+ The 202 (Accepted) status code indicates that the request + has been accepted for processing, but the processing has not been + completed. The request might or might not eventually be acted upon, as it + might be disallowed when processing actually takes place. There is no + facility in HTTP for re-sending a status code from an asynchronous + operation.¶

+

+ The 202 response is intentionally noncommittal. Its purpose is to + allow a server to accept a request for some other process (perhaps a + batch-oriented process that is only run once per day) without + requiring that the user agent's connection to the server persist + until the process is completed. The representation sent with this + response ought to describe the request's current status and point to + (or embed) a status monitor that can provide the user with an estimate of + when the request will be fulfilled.¶

+
+
+
+
+

+15.3.4. 203 Non-Authoritative Information +

+ +

+ The 203 (Non-Authoritative Information) status code + indicates that the request was successful but the enclosed content has been + modified from that of the origin server's 200 (OK) response + by a transforming proxy (Section 7.7). This status code allows the + proxy to notify recipients when a transformation has been applied, since + that knowledge might impact later decisions regarding the content. For + example, future cache validation requests for the content might only be + applicable along the same request path (through the same proxies).¶

+

+ A 203 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+
+
+
+
+

+15.3.5. 204 No Content +

+ +

+ The 204 (No Content) status code indicates that the server + has successfully fulfilled the request and that there is no additional + content to send in the response content. Metadata in the response + header fields refer to the target resource and its + selected representation after the requested action was applied.¶

+

+ For example, if a 204 status code is received in response to a PUT + request and the response contains an ETag field, then + the PUT was successful and the ETag field value contains the entity tag for + the new representation of that target resource.¶

+

+ The 204 response allows a server to indicate that the action has been + successfully applied to the target resource, while implying that the + user agent does not need to traverse away from its current "document view" + (if any). The server assumes that the user agent will provide some + indication of the success to its user, in accord with its own interface, + and apply any new or updated metadata in the response to its active + representation.¶

+

+ For example, a 204 status code is commonly used with document editing + interfaces corresponding to a "save" action, such that the document + being saved remains available to the user for editing. It is also + frequently used with interfaces that expect automated data transfers + to be prevalent, such as within distributed version control systems.¶

+

+ A 204 response is terminated by the end of the header section; + it cannot contain content or trailers.¶

+

+ A 204 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+
+
+
+
+

+15.3.6. 205 Reset Content +

+ +

+ The 205 (Reset Content) status code indicates that the + server has fulfilled the request and desires that the user agent reset the + "document view", which caused the request to be sent, to its original state + as received from the origin server.¶

+

+ This response is intended to support a common data entry use case where + the user receives content that supports data entry (a form, notepad, + canvas, etc.), enters or manipulates data in that space, causes the entered + data to be submitted in a request, and then the data entry mechanism is + reset for the next entry so that the user can easily initiate another + input action.¶

+

+ Since the 205 status code implies that no additional content will be + provided, a server MUST NOT generate content in a 205 response.¶

+
+
+
+
+

+15.3.7. 206 Partial Content +

+ +

+ The 206 (Partial Content) status code indicates that the + server is successfully fulfilling a range request for the target resource + by transferring one or more parts of the + selected representation.¶

+

+ A server that supports range requests (Section 14) will + usually attempt to satisfy all of the requested ranges, since sending + less data will likely result in another client request for the remainder. + However, a server might want to send only a subset of the data requested + for reasons of its own, such as temporary unavailability, cache efficiency, + load balancing, etc. Since a 206 response is self-descriptive, the client + can still understand a response that only partially satisfies its range + request.¶

+

+ A client MUST inspect a 206 response's Content-Type and + Content-Range field(s) to determine what parts are enclosed + and whether additional requests are needed.¶

+

+ A server that generates a 206 response MUST generate the following + header fields, in addition to those required in the subsections below, + if the field would + have been sent in a 200 (OK) response to the same request: + Date, Cache-Control, ETag, + Expires, Content-Location, and + Vary.¶

+

+ A Content-Length header field present in a 206 response + indicates the number of octets in the content of this message, which is + usually not the complete length of the selected representation. + Each Content-Range header field includes information about the + selected representation's complete length.¶

+

+ A sender that generates a 206 response to a request with an If-Range + header field SHOULD NOT generate other representation header + fields beyond those required because the client + already has a prior response containing those header fields. + Otherwise, a sender MUST generate all of the representation header + fields that would have been sent in a 200 (OK) response + to the same request.¶

+

+ A 206 response is heuristically cacheable; i.e., unless otherwise indicated by + explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+
+
+
+15.3.7.1. Single Part +
+

+ If a single part is being transferred, the server generating the 206 + response MUST generate a Content-Range header field, + describing what range of the selected representation is enclosed, and a + content consisting of the range. For example:¶

+
+
HTTP/1.1 206 Partial Content
+Date: Wed, 15 Nov 1995 06:25:24 GMT
+Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
+Content-Range: bytes 21010-47021/47022
+Content-Length: 26012
+Content-Type: image/gif
+
+... 26012 bytes of partial image data ...
+
¶ +
+
+
+
+
+
+15.3.7.2. Multiple Parts +
+

+ If multiple parts are being transferred, the server generating the 206 + response MUST generate "multipart/byteranges" content, as defined + in Section 14.6, and a + Content-Type header field containing the + "multipart/byteranges" media type and its required boundary parameter. + To avoid confusion with single-part responses, a server MUST NOT generate + a Content-Range header field in the HTTP header section of a + multiple part response (this field will be sent in each part instead).¶

+

+ Within the header area of each body part in the multipart content, the + server MUST generate a Content-Range header field + corresponding to the range being enclosed in that body part. + If the selected representation would have had a Content-Type + header field in a 200 (OK) response, the server SHOULD + generate that same Content-Type header field in the header area of + each body part. For example:¶

+
+
HTTP/1.1 206 Partial Content
+Date: Wed, 15 Nov 1995 06:25:24 GMT
+Last-Modified: Wed, 15 Nov 1995 04:58:08 GMT
+Content-Length: 1741
+Content-Type: multipart/byteranges; boundary=THIS_STRING_SEPARATES
+
+--THIS_STRING_SEPARATES
+Content-Type: application/pdf
+Content-Range: bytes 500-999/8000
+
+...the first range...
+--THIS_STRING_SEPARATES
+Content-Type: application/pdf
+Content-Range: bytes 7000-7999/8000
+
+...the second range
+--THIS_STRING_SEPARATES--
+
¶ +
+

+ When multiple ranges are requested, a server MAY coalesce any of the + ranges that overlap, or that are separated by a gap that is smaller than the + overhead of sending multiple parts, regardless of the order in which the + corresponding range-spec appeared in the received Range + header field. Since the typical overhead between each part of a + "multipart/byteranges" is around 80 bytes, depending on the selected + representation's media type and the chosen boundary parameter length, it + can be less efficient to transfer many small disjoint parts than it is to + transfer the entire selected representation.¶

+

+ A server MUST NOT generate a multipart response to a request for a single + range, since a client that does not request multiple parts might not + support multipart responses. However, a server MAY generate a + "multipart/byteranges" response with only a single body part if multiple + ranges were requested and only one range was found to be satisfiable or + only one range remained after coalescing. + A client that cannot process a "multipart/byteranges" response MUST NOT + generate a request that asks for multiple ranges.¶

+

+ A server that generates a multipart response SHOULD send + the parts in the same order that the corresponding range-spec appeared + in the received Range header field, excluding those ranges + that were deemed unsatisfiable or that were coalesced into other ranges. + A client that receives a multipart response MUST inspect the + Content-Range header field present in each body part in + order to determine which range is contained in that body part; a client + cannot rely on receiving the same ranges that it requested, nor the same + order that it requested.¶

+
+
+
+
+
+15.3.7.3. Combining Parts +
+

+ A response might transfer only a subrange of a representation if the + connection closed prematurely or if the request used one or more Range + specifications. After several such transfers, a client might have + received several ranges of the same representation. These ranges can only + be safely combined if they all have in common the same strong validator + (Section 8.8.1).¶

+

+ A client that has received multiple partial responses to GET requests on a + target resource MAY combine those responses into a larger continuous + range if they share the same strong validator.¶

+

+ If the most recent response is an incomplete 200 (OK) + response, then the header fields of that response are used for any + combined response and replace those of the matching stored responses.¶

+

+ If the most recent response is a 206 (Partial Content) + response and at least one of the matching stored responses is a + 200 (OK), then the combined response header fields consist + of the most recent 200 response's header fields. If all of the matching + stored responses are 206 responses, then the stored response with the most + recent header fields is used as the source of header fields for the + combined response, except that the client MUST use other header fields + provided in the new response, aside from Content-Range, to + replace all instances of the corresponding header fields in the stored + response.¶

+

+ The combined response content consists of the union of partial content + ranges within the new response and all of the matching stored responses. + If the union consists of the entire range of the representation, then the + client MUST process the combined response as if it were a complete + 200 (OK) response, including a Content-Length + header field that reflects the complete length. + Otherwise, the client MUST process the set of continuous ranges as one of + the following: + an incomplete 200 (OK) response if the combined response is + a prefix of the representation, + a single 206 (Partial Content) response containing + "multipart/byteranges" content, or + multiple 206 (Partial Content) responses, each with one + continuous range that is indicated by a Content-Range header + field.¶

+
+
+
+
+
+
+
+
+

+15.4. Redirection 3xx +

+ + +

+ The 3xx (Redirection) class of status code indicates that + further action needs to be taken by the user agent in order to fulfill the + request. There are several types of redirects:¶

+
    +
  1. + Redirects that indicate this resource might be available at a + different URI, as provided by the Location header field, + as in the status codes 301 (Moved Permanently), + 302 (Found), 307 (Temporary Redirect), and + 308 (Permanent Redirect).¶ +
    2. +
  2. + Redirection that offers a choice among matching resources capable + of representing this resource, as in the + 300 (Multiple Choices) status code.¶ +
    3. +
  3. + Redirection to a different resource, identified by the + Location header field, that can represent an indirect + response to the request, as in the 303 (See Other) + status code.¶ +
    4. +
  4. + Redirection to a previously stored result, as in the + 304 (Not Modified) status code.¶ +
    5. +
+ +

+ If a Location header field + (Section 10.2.2) is provided, the user agent MAY + automatically redirect its request to the URI referenced by the Location + field value, even if the specific status code is not understood. + Automatic redirection needs to be done with care for methods not known to be + safe, as defined in Section 9.2.1, since + the user might not wish to redirect an unsafe request.¶

+

+ When automatically following a redirected request, the user agent SHOULD + resend the original request message with the following modifications:¶

+
    +
  1. +

    + Replace the target URI with the URI referenced by the redirection response's + Location header field value after resolving it relative to the original + request's target URI.¶

    +
    2. +
  2. +

    + Remove header fields that were automatically generated by the implementation, + replacing them with updated values as appropriate to the new request. This + includes:¶

    +
      +
    1. Connection-specific header fields (see Section 7.6.1),¶ +
      2. +
    2. Header fields specific to the client's proxy configuration, + including (but not limited to) Proxy-Authorization,¶ +
      3. +
    3. Origin-specific header fields (if any), including (but not + limited to) Host,¶ +
      4. +
    4. Validating header fields that were added by the implementation's + cache (e.g., If-None-Match, + If-Modified-Since), and¶ +
      5. +
    5. Resource-specific header fields, including (but not limited to) + Referer, Origin, + Authorization, and Cookie.¶ +
      6. +
    +
    3. +
  3. +

    + Consider removing header fields that were not automatically generated by the + implementation (i.e., those present in the request because they were added + by the calling context) where there are security implications; this + includes but is not limited to Authorization and Cookie.¶

    +
    4. +
  4. +

    + Change the request method according to the redirecting status code's + semantics, if applicable.¶

    +
    5. +
  5. +

    + If the request method has been changed to GET or HEAD, remove + content-specific header fields, including (but not limited to) + Content-Encoding, + Content-Language, Content-Location, + Content-Type, Content-Length, + Digest, Last-Modified.¶

    +
    6. +
+

+ A client SHOULD detect and intervene in cyclical redirections (i.e., + "infinite" redirection loops).¶

+ +
+
+

+15.4.1. 300 Multiple Choices +

+ +

+ The 300 (Multiple Choices) status code indicates that the + target resource has more than one representation, each with + its own more specific identifier, and information about the alternatives is + being provided so that the user (or user agent) can select a preferred + representation by redirecting its request to one or more of those + identifiers. In other words, the server desires that the user agent engage + in reactive negotiation to select the most appropriate representation(s) + for its needs (Section 12).¶

+

+ If the server has a preferred choice, the server SHOULD generate a + Location header field containing a preferred choice's URI + reference. The user agent MAY use the Location field value for automatic + redirection.¶

+

+ For request methods other than HEAD, the server SHOULD generate content + in the 300 response containing a list of representation metadata and URI + reference(s) from which the user or user agent can choose the one most + preferred. The user agent MAY make a selection from that list + automatically if it understands the provided media type. A specific format + for automatic selection is not defined by this specification because HTTP + tries to remain orthogonal to the definition of its content. + In practice, the representation is provided in some easily parsed format + believed to be acceptable to the user agent, as determined by shared design + or content negotiation, or in some commonly accepted hypertext format.¶

+

+ A 300 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+ +
+
+
+
+

+15.4.2. 301 Moved Permanently +

+ +

+ The 301 (Moved Permanently) status code indicates that the + target resource has been assigned a new permanent URI and + any future references to this resource ought to use one of the enclosed + URIs. The server is suggesting that a user agent with link-editing capability + can permanently replace references to the target URI with one of the + new references sent by the server. However, this suggestion is usually + ignored unless the user agent is actively editing references + (e.g., engaged in authoring content), the connection is secured, and + the origin server is a trusted authority for the content being edited.¶

+

+ The server SHOULD generate a Location header field in the + response containing a preferred URI reference for the new permanent URI. + The user agent MAY use the Location field value for automatic redirection. + The server's response content usually contains a short hypertext note with + a hyperlink to the new URI(s).¶

+ +

+ A 301 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+
+
+
+
+

+15.4.3. 302 Found +

+ +

+ The 302 (Found) status code indicates that the target + resource resides temporarily under a different URI. Since the redirection + might be altered on occasion, the client ought to continue to use the + target URI for future requests.¶

+

+ The server SHOULD generate a Location header field in the + response containing a URI reference for the different URI. + The user agent MAY use the Location field value for automatic redirection. + The server's response content usually contains a short hypertext note with + a hyperlink to the different URI(s).¶

+ +
+
+
+
+

+15.4.4. 303 See Other +

+ +

+ The 303 (See Other) status code indicates that the server is + redirecting the user agent to a different resource, as indicated by a URI + in the Location header field, which is intended to provide + an indirect response to the original request. A user agent can perform a + retrieval request targeting that URI (a GET or HEAD request if using HTTP), + which might also be redirected, and present the eventual result as an + answer to the original request. Note that the new URI in the Location + header field is not considered equivalent to the target URI.¶

+

+ This status code is applicable to any HTTP method. It is + primarily used to allow the output of a POST action to redirect + the user agent to a different resource, since doing so provides the + information corresponding to the POST response as a resource that + can be separately identified, bookmarked, and cached.¶

+

+ A 303 response to a GET request indicates that the origin server does not + have a representation of the target resource that can be + transferred by the server over HTTP. However, the + Location field value refers to a resource that is + descriptive of the target resource, such that making a retrieval request + on that other resource might result in a representation that is useful to + recipients without implying that it represents the original target resource. + Note that answers to the questions of what can be represented, what + representations are adequate, and what might be a useful description are + outside the scope of HTTP.¶

+

+ Except for responses to a HEAD request, the representation of a 303 + response ought to contain a short hypertext note with a hyperlink to the + same URI reference provided in the Location header field.¶

+
+
+
+
+

+15.4.5. 304 Not Modified +

+ +

+ The 304 (Not Modified) status code indicates that a + conditional GET or HEAD request has been + received and would have resulted in a 200 (OK) response + if it were not for the fact that the condition evaluated to false. + In other words, there is no need for the server to transfer a + representation of the target resource because the request indicates that + the client, which made the request conditional, already has a valid + representation; the server is therefore redirecting the client to make + use of that stored representation as if it were the content of a + 200 (OK) response.¶

+

+ The server generating a 304 response MUST generate any of the following + header fields that would have been sent in a 200 (OK) + response to the same request:¶

+ +

+ Since the goal of a 304 response is to minimize information transfer + when the recipient already has one or more cached representations, + a sender SHOULD NOT generate representation metadata other + than the above listed fields unless said metadata exists for the + purpose of guiding cache updates (e.g., Last-Modified might + be useful if the response does not have an ETag field).¶

+

+ Requirements on a cache that receives a 304 response are defined in + Section 4.3.4 of [CACHING]. If the conditional request originated with an + outbound client, such as a user agent with its own cache sending a + conditional GET to a shared proxy, then the proxy SHOULD forward the + 304 response to that client.¶

+

+ A 304 response is terminated by the end of the header section; + it cannot contain content or trailers.¶

+
+
+
+
+

+15.4.6. 305 Use Proxy +

+ +

+ The 305 (Use Proxy) status code was defined in a previous + version of this specification and is now deprecated (Appendix B of [RFC7231]).¶

+
+
+
+
+

+15.4.7. 306 (Unused) +

+ +

+ The 306 status code was defined in a previous version of this + specification, is no longer used, and the code is reserved.¶

+
+
+
+
+

+15.4.8. 307 Temporary Redirect +

+ +

+ The 307 (Temporary Redirect) status code indicates that the + target resource resides temporarily under a different URI + and the user agent MUST NOT change the request method if it performs an + automatic redirection to that URI. + Since the redirection can change over time, the client ought to continue + using the original target URI for future requests.¶

+

+ The server SHOULD generate a Location header field in the + response containing a URI reference for the different URI. + The user agent MAY use the Location field value for automatic redirection. + The server's response content usually contains a short hypertext note with + a hyperlink to the different URI(s).¶

+
+
+
+
+

+15.4.9. 308 Permanent Redirect +

+ +

+ The 308 (Permanent Redirect) status code indicates that the + target resource has been assigned a new permanent URI and + any future references to this resource ought to use one of the enclosed + URIs. The server is suggesting that a user agent with link-editing capability + can permanently replace references to the target URI with one of the + new references sent by the server. However, this suggestion is usually + ignored unless the user agent is actively editing references + (e.g., engaged in authoring content), the connection is secured, and + the origin server is a trusted authority for the content being edited.¶

+

+ The server SHOULD generate a Location header field in the + response containing a preferred URI reference for the new permanent URI. + The user agent MAY use the Location field value for automatic redirection. + The server's response content usually contains a short hypertext note with + a hyperlink to the new URI(s).¶

+

+ A 308 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+ +
+
+
+
+
+
+

+15.5. Client Error 4xx +

+ + +

+ The 4xx (Client Error) class of status code indicates that + the client seems to have erred. Except when responding to a HEAD request, + the server SHOULD send a representation containing an explanation of + the error situation, and whether it is a temporary or permanent condition. + These status codes are applicable to any request method. User agents + SHOULD display any included representation to the user.¶

+
+
+

+15.5.1. 400 Bad Request +

+ +

+ The 400 (Bad Request) status code indicates that the server + cannot or will not process the request due to something that is perceived + to be a client error (e.g., malformed request syntax, invalid request + message framing, or deceptive request routing).¶

+
+
+
+
+

+15.5.2. 401 Unauthorized +

+ +

+ The 401 (Unauthorized) status code indicates that the + request has not been applied because it lacks valid authentication + credentials for the target resource. + The server generating a 401 response MUST send a + WWW-Authenticate header field + (Section 11.6.1) + containing at least one challenge applicable to the target resource.¶

+

+ If the request included authentication credentials, then the 401 response + indicates that authorization has been refused for those credentials. + The user agent MAY repeat the request with a new or replaced + Authorization header field (Section 11.6.2). + If the 401 response contains the same challenge as the prior response, and + the user agent has already attempted authentication at least once, then the + user agent SHOULD present the enclosed representation to the user, since + it usually contains relevant diagnostic information.¶

+
+
+
+
+

+15.5.3. 402 Payment Required +

+ +

+ The 402 (Payment Required) status code is reserved for + future use.¶

+
+
+
+
+

+15.5.4. 403 Forbidden +

+ +

+ The 403 (Forbidden) status code indicates that the + server understood the request but refuses to fulfill it. + A server that wishes to make public why the request has been forbidden + can describe that reason in the response content (if any).¶

+

+ If authentication credentials were provided in the request, the + server considers them insufficient to grant access. + The client SHOULD NOT automatically repeat the request with the same + credentials. + The client MAY repeat the request with new or different credentials. + However, a request might be forbidden for reasons unrelated to the + credentials.¶

+

+ An origin server that wishes to "hide" the current existence of a forbidden + target resource + MAY instead respond with a status + code of 404 (Not Found).¶

+
+
+
+
+

+15.5.5. 404 Not Found +

+ +

+ The 404 (Not Found) status code indicates that the origin + server did not find a current representation for the + target resource or is not willing to disclose that one + exists. A 404 status code does not indicate whether this lack of representation + is temporary or permanent; the 410 (Gone) status code is + preferred over 404 if the origin server knows, presumably through some + configurable means, that the condition is likely to be permanent.¶

+

+ A 404 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+
+
+
+
+

+15.5.6. 405 Method Not Allowed +

+ +

+ The 405 (Method Not Allowed) status code indicates that the + method received in the request-line is known by the origin server but + not supported by the target resource. + The origin server MUST generate an Allow header field in + a 405 response containing a list of the target resource's currently + supported methods.¶

+

+ A 405 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+
+
+
+
+

+15.5.7. 406 Not Acceptable +

+ +

+ The 406 (Not Acceptable) status code indicates that the + target resource does not have a current representation that + would be acceptable to the user agent, according to the + proactive negotiation header fields received in the request + (Section 12.1), and the server is unwilling to supply a + default representation.¶

+

+ The server SHOULD generate content containing a list of available + representation characteristics and corresponding resource identifiers from + which the user or user agent can choose the one most appropriate. + A user agent MAY automatically select the most appropriate choice from + that list. However, this specification does not define any standard for + such automatic selection, as described in Section 15.4.1.¶

+
+
+
+
+

+15.5.8. 407 Proxy Authentication Required +

+ +

+ The 407 (Proxy Authentication Required) status code is + similar to 401 (Unauthorized), but it indicates that the client + needs to authenticate itself in order to use a proxy for this request. + The proxy MUST send a Proxy-Authenticate header field + (Section 11.7.1) containing a challenge + applicable to that proxy for the request. The client MAY repeat + the request with a new or replaced Proxy-Authorization + header field (Section 11.7.2).¶

+
+
+
+
+

+15.5.9. 408 Request Timeout +

+ +

+ The 408 (Request Timeout) status code indicates + that the server did not receive a complete request message within the time + that it was prepared to wait.¶

+

+ If the client has an outstanding request in transit, it MAY repeat that + request. If the current connection is not usable (e.g., as it would be in + HTTP/1.1 because request delimitation is lost), a new connection will be + used.¶

+
+
+
+
+

+15.5.10. 409 Conflict +

+ +

+ The 409 (Conflict) status code indicates that the request + could not be completed due to a conflict with the current state of the target + resource. This code is used in situations where the user might be able to + resolve the conflict and resubmit the request. The server SHOULD generate + content that includes enough information for a user to recognize the + source of the conflict.¶

+

+ Conflicts are most likely to occur in response to a PUT request. For + example, if versioning were being used and the representation being PUT + included changes to a resource that conflict with those made by an + earlier (third-party) request, the origin server might use a 409 response + to indicate that it can't complete the request. In this case, the response + representation would likely contain information useful for merging the + differences based on the revision history.¶

+
+
+
+
+

+15.5.11. 410 Gone +

+ +

+ The 410 (Gone) status code indicates that access to the + target resource is no longer available at the origin + server and that this condition is likely to be permanent. If the origin + server does not know, or has no facility to determine, whether or not the + condition is permanent, the status code 404 (Not Found) + ought to be used instead.¶

+

+ The 410 response is primarily intended to assist the task of web + maintenance by notifying the recipient that the resource is + intentionally unavailable and that the server owners desire that + remote links to that resource be removed. Such an event is common for + limited-time, promotional services and for resources belonging to + individuals no longer associated with the origin server's site. It is not + necessary to mark all permanently unavailable resources as "gone" or + to keep the mark for any length of time -- that is left to the + discretion of the server owner.¶

+

+ A 410 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+
+
+
+
+

+15.5.12. 411 Length Required +

+ +

+ The 411 (Length Required) status code indicates that the + server refuses to accept the request without a defined + Content-Length (Section 8.6). + The client MAY repeat the request if it adds a valid Content-Length + header field containing the length of the request content.¶

+
+
+
+
+

+15.5.13. 412 Precondition Failed +

+ +

+ The 412 (Precondition Failed) status code indicates that one + or more conditions given in the request header fields evaluated to false + when tested on the server (Section 13). This + response status code allows the client to place preconditions on the + current resource state (its current representations and metadata) and, + thus, prevent the request method from being applied if the target resource + is in an unexpected state.¶

+
+
+
+
+

+15.5.14. 413 Content Too Large +

+ +

+ The 413 (Content Too Large) status code indicates + that the server is refusing to process a request because the request + content is larger than the server is willing or able to process. + The server MAY terminate the request, if the protocol version in use + allows it; otherwise, the server MAY close the connection.¶

+

+ If the condition is temporary, the server SHOULD generate a + Retry-After header field to indicate that it is temporary + and after what time the client MAY try again.¶

+
+
+
+
+

+15.5.15. 414 URI Too Long +

+ +

+ The 414 (URI Too Long) status code indicates that the server + is refusing to service the request because the + target URI is longer than the server is willing to + interpret. This rare condition is only likely to occur when a client has + improperly converted a POST request to a GET request with long query + information, when the client has descended into an infinite loop of + redirection (e.g., a redirected URI prefix that points to a suffix of + itself) or when the server is under attack by a client attempting to + exploit potential security holes.¶

+

+ A 414 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+
+
+
+
+

+15.5.16. 415 Unsupported Media Type +

+ +

+ The 415 (Unsupported Media Type) status code indicates that + the origin server is refusing to service the request because the content is + in a format not supported by this method on the target resource.¶

+

+ The format problem might be due to the request's indicated + Content-Type or Content-Encoding, or as a + result of inspecting the data directly.¶

+

+ If the problem was caused by an unsupported content coding, the + Accept-Encoding response header field + (Section 12.5.3) ought to be + used to indicate which (if any) content codings would have been accepted + in the request.¶

+

+ On the other hand, if the cause was an unsupported media type, the + Accept response header field (Section 12.5.1) + can be used to indicate which media types would have been accepted + in the request.¶

+
+
+
+
+

+15.5.17. 416 Range Not Satisfiable +

+ +

+ The 416 (Range Not Satisfiable) status code indicates that + the set of ranges in the request's Range header field + (Section 14.2) has been rejected either because none of + the requested ranges are satisfiable or because the client has requested + an excessive number of small or overlapping ranges (a potential denial of + service attack).¶

+

+ Each range unit defines what is required for its own range sets to be + satisfiable. For example, Section 14.1.2 defines what makes + a bytes range set satisfiable.¶

+

+ A server that generates a 416 response to a byte-range request SHOULD + generate a Content-Range header field + specifying the current length of the selected representation + (Section 14.4).¶

+

+ For example:¶

+
+
HTTP/1.1 416 Range Not Satisfiable
+Date: Fri, 20 Jan 2012 15:41:54 GMT
+Content-Range: bytes */47022
+
¶ +
+ +
+
+
+
+

+15.5.18. 417 Expectation Failed +

+ +

+ The 417 (Expectation Failed) status code indicates that the + expectation given in the request's Expect header field + (Section 10.1.1) could not be met by at least one of the + inbound servers.¶

+
+
+
+
+

+15.5.19. 418 (Unused) +

+ +

+ [RFC2324] was an April 1 RFC that lampooned the various ways + HTTP was abused; one such abuse was the definition of an + application-specific 418 status code, which has been deployed as a joke + often enough for the code to be unusable for any future use.¶

+

+ Therefore, the 418 status code is reserved in the IANA HTTP Status Code + Registry. This indicates that the status code cannot be assigned to other + applications currently. If future circumstances require its use (e.g., + exhaustion of 4NN status codes), it can be re-assigned to another use.¶

+
+
+
+
+

+15.5.20. 421 Misdirected Request +

+ +

+ The 421 (Misdirected Request) status code indicates that the request was + directed at a server that is unable or unwilling to produce an + authoritative response for the target URI. An origin server (or gateway + acting on behalf of the origin server) sends 421 to reject a target URI + that does not match an origin for which the server has been + configured (Section 4.3.1) or does not match the connection + context over which the request was received + (Section 7.4).¶

+

+ A client that receives a 421 (Misdirected Request) response MAY retry the + request, whether or not the request method is idempotent, over a different + connection, such as a fresh connection specific to the target resource's + origin, or via an alternative service [ALTSVC].¶

+

+ A proxy MUST NOT generate a 421 response.¶

+
+
+
+
+

+15.5.21. 422 Unprocessable Content +

+ +

+ The 422 (Unprocessable Content) status code indicates that the server + understands the content type of the request content (hence a + 415 (Unsupported Media Type) status code is inappropriate), + and the syntax of the request content is correct, but it was unable to process + the contained instructions. For example, this status code can be sent if + an XML request content contains well-formed (i.e., syntactically correct), but + semantically erroneous XML instructions.¶

+
+
+
+
+

+15.5.22. 426 Upgrade Required +

+ +

+ The 426 (Upgrade Required) status code indicates that the + server refuses to perform the request using the current protocol but might + be willing to do so after the client upgrades to a different protocol. + The server MUST send an Upgrade header field in a 426 + response to indicate the required protocol(s) (Section 7.8).¶

+

+ Example:¶

+
+
HTTP/1.1 426 Upgrade Required
+Upgrade: HTTP/3.0
+Connection: Upgrade
+Content-Length: 53
+Content-Type: text/plain
+
+This service requires use of the HTTP/3.0 protocol.
+
¶ +
+
+
+
+
+
+
+

+15.6. Server Error 5xx +

+ + +

+ The 5xx (Server Error) class of status code indicates that + the server is aware that it has erred or is incapable of performing the + requested method. + Except when responding to a HEAD request, the server SHOULD send a + representation containing an explanation of the error situation, and + whether it is a temporary or permanent condition. + A user agent SHOULD display any included representation to the user. + These status codes are applicable to any request method.¶

+
+
+

+15.6.1. 500 Internal Server Error +

+ +

+ The 500 (Internal Server Error) status code indicates that + the server encountered an unexpected condition that prevented it from + fulfilling the request.¶

+
+
+
+
+

+15.6.2. 501 Not Implemented +

+ +

+ The 501 (Not Implemented) status code indicates that the + server does not support the functionality required to fulfill the request. + This is the appropriate response when the server does not recognize the + request method and is not capable of supporting it for any resource.¶

+

+ A 501 response is heuristically cacheable; i.e., unless otherwise indicated by + the method definition or explicit cache controls (see Section 4.2.2 of [CACHING]).¶

+
+
+
+
+

+15.6.3. 502 Bad Gateway +

+ +

+ The 502 (Bad Gateway) status code indicates that the server, + while acting as a gateway or proxy, received an invalid response from an + inbound server it accessed while attempting to fulfill the request.¶

+
+
+
+
+

+15.6.4. 503 Service Unavailable +

+ +

+ The 503 (Service Unavailable) status code indicates that the + server is currently unable to handle the request due to a temporary overload + or scheduled maintenance, which will likely be alleviated after some delay. + The server MAY send a Retry-After header field + (Section 10.2.3) to suggest an appropriate + amount of time for the client to wait before retrying the request.¶

+ +
+
+
+
+

+15.6.5. 504 Gateway Timeout +

+ +

+ The 504 (Gateway Timeout) status code indicates that the + server, while acting as a gateway or proxy, did not receive a timely + response from an upstream server it needed to access in order to + complete the request.¶

+
+
+
+
+

+15.6.6. 505 HTTP Version Not Supported +

+ +

+ The 505 (HTTP Version Not Supported) status code indicates + that the server does not support, or refuses to support, the major version + of HTTP that was used in the request message. The server is indicating that + it is unable or unwilling to complete the request using the same major + version as the client, as described in Section 2.5, other than with this + error message. The server SHOULD generate a representation for the 505 + response that describes why that version is not supported and what other + protocols are supported by that server.¶

+
+
+
+
+
+
+
+
+

+16. Extending HTTP +

+

+ HTTP defines a number of generic extension points that can be used to + introduce capabilities to the protocol without introducing a new version, + including methods, status codes, field names, and further extensibility + points within defined fields, such as authentication schemes and + cache directives (see Cache-Control extensions in Section 5.2.3 of [CACHING]). Because the semantics of HTTP are + not versioned, these extension points are persistent; the version of the + protocol in use does not affect their semantics.¶

+

+ Version-independent extensions are discouraged from depending on or + interacting with the specific version of the protocol in use. When this is + unavoidable, careful consideration needs to be given to how the extension + can interoperate across versions.¶

+

+ Additionally, specific versions of HTTP might have their own extensibility + points, such as transfer codings in HTTP/1.1 (Section 6.1 of [HTTP/1.1]) and HTTP/2 SETTINGS or frame types + ([HTTP/2]). These extension points are specific to the + version of the protocol they occur within.¶

+

+ Version-specific extensions cannot override or modify the semantics of + a version-independent mechanism or extension point (like a method or + header field) without explicitly being allowed by that protocol element. For + example, the CONNECT method (Section 9.3.6) allows this.¶

+

+ These guidelines assure that the protocol operates correctly and + predictably, even when parts of the path implement different versions of + HTTP.¶

+
+
+

+16.1. Method Extensibility +

+
+
+

+16.1.1. Method Registry +

+

+ The "Hypertext Transfer Protocol (HTTP) Method Registry", maintained by + IANA at <https://www.iana.org/assignments/http-methods>, + registers method names.¶

+

+ HTTP method registrations MUST include the following fields:¶

+ +

+ Values to be added to this namespace require IETF Review + (see [RFC8126], Section 4.8).¶

+
+
+
+
+

+16.1.2. Considerations for New Methods +

+

+ Standardized methods are generic; that is, they are potentially + applicable to any resource, not just one particular media type, kind of + resource, or application. As such, it is preferred that new methods + be registered in a document that isn't specific to a single application or + data format, since orthogonal technologies deserve orthogonal specification.¶

+

+ Since message parsing (Section 6) needs to be + independent of method + semantics (aside from responses to HEAD), definitions of new methods + cannot change the parsing algorithm or prohibit the presence of content + on either the request or the response message. + Definitions of new methods can specify that only a zero-length content + is allowed by requiring a Content-Length header field with a value of "0".¶

+

+ Likewise, new methods cannot use the special host:port and asterisk forms of + request target that are allowed for CONNECT and + OPTIONS, respectively (Section 7.1). + A full URI in absolute form is needed for the target URI, which means either + the request target needs to be sent in absolute form or the target URI will + be reconstructed from the request context in the same way it is for other + methods.¶

+

+ A new method definition needs to indicate whether it is safe (Section 9.2.1), idempotent (Section 9.2.2), + cacheable (Section 9.2.3), what + semantics are to be associated with the request content (if any), and what + refinements the method makes to header field or status code semantics. + If the new method is cacheable, its definition ought to describe how, and + under what conditions, a cache can store a response and use it to satisfy a + subsequent request. + The new method ought to describe whether it can be made conditional + (Section 13.1) and, if so, how a server responds + when the condition is false. + Likewise, if the new method might have some use for partial response + semantics (Section 14.2), it ought to document this, too.¶

+ +
+
+
+
+
+
+

+16.2. Status Code Extensibility +

+
+
+

+16.2.1. Status Code Registry +

+

+ The "Hypertext Transfer Protocol (HTTP) Status Code Registry", maintained + by IANA at <https://www.iana.org/assignments/http-status-codes>, + registers status code numbers.¶

+

+ A registration MUST include the following fields:¶

+
    +
  • Status Code (3 digits)¶ +
    • +
  • Short Description¶ +
    • +
  • Pointer to specification text¶ +
    • +
+

+ Values to be added to the HTTP status code namespace require IETF Review + (see [RFC8126], Section 4.8).¶

+
+
+
+
+

+16.2.2. Considerations for New Status Codes +

+

+ When it is necessary to express semantics for a response that are not + defined by current status codes, a new status code can be registered. + Status codes are generic; they are potentially applicable to any resource, + not just one particular media type, kind of resource, or application of + HTTP. As such, it is preferred that new status codes be registered in a + document that isn't specific to a single application.¶

+

+ New status codes are required to fall under one of the categories + defined in Section 15. To allow existing parsers to + process the response message, new status codes cannot disallow content, + although they can mandate a zero-length content.¶

+

+ Proposals for new status codes that are not yet widely deployed ought to + avoid allocating a specific number for the code until there is clear + consensus that it will be registered; instead, early drafts can use a + notation such as "4NN", or "3N0" .. "3N9", to indicate the class + of the proposed status code(s) without consuming a number prematurely.¶

+

+ The definition of a new status code ought to explain the request + conditions that would cause a response containing that status code (e.g., + combinations of request header fields and/or method(s)) along with any + dependencies on response header fields (e.g., what fields are required, + what fields can modify the semantics, and what field semantics are + further refined when used with the new status code).¶

+

+ By default, a status code applies only to the request corresponding to the + response it occurs within. If a status code applies to a larger scope of + applicability -- for example, all requests to the resource in question or + all requests to a server -- this must be explicitly specified. When doing + so, it should be noted that not all clients can be expected to + consistently apply a larger scope because they might not understand the + new status code.¶

+

+ The definition of a new final status code ought to specify whether or not it + is heuristically cacheable. Note that any response with a final status code + can be cached if the response has explicit freshness information. A status + code defined as heuristically cacheable is allowed to be cached without + explicit freshness information. + Likewise, the definition of a status code can place + constraints upon cache behavior if the must-understand cache + directive is used. See [CACHING] for more information.¶

+

+ Finally, the definition of a new status code ought to indicate whether the + content has any implied association with an identified resource (Section 6.4.2).¶

+
+
+
+
+
+
+

+16.3. Field Extensibility +

+

+ HTTP's most widely used extensibility point is the definition of new header and + trailer fields.¶

+

+ New fields can be defined such that, when they are understood by a + recipient, they override or enhance the interpretation of previously + defined fields, define preconditions on request evaluation, or + refine the meaning of responses.¶

+

+ However, defining a field doesn't guarantee its deployment or recognition + by recipients. Most fields are designed with the expectation that a recipient + can safely ignore (but forward downstream) any field not recognized. + In other cases, the sender's ability to understand a given field might be + indicated by its prior communication, perhaps in the protocol version + or fields that it sent in prior messages, or its use of a specific media type. + Likewise, direct inspection of support might be possible through an + OPTIONS request or by interacting with a defined well-known URI + [RFC8615] if such inspection is defined along with + the field being introduced.¶

+
+
+

+16.3.1. Field Name Registry +

+

+ The "Hypertext Transfer Protocol (HTTP) Field Name Registry" defines the + namespace for HTTP field names.¶

+

+ Any party can request registration of an HTTP field. See Section 16.3.2 for considerations to take + into account when creating a new HTTP field.¶

+

+ The "Hypertext Transfer Protocol (HTTP) Field Name Registry" is located at + <https://www.iana.org/assignments/http-fields/>. + Registration requests can be made by following the instructions located + there or by sending an email to the "ietf-http-wg@w3.org" mailing list.¶

+

+ Field names are registered on the advice of a designated expert + (appointed by the IESG or their delegate). Fields with the status + 'permanent' are Specification Required + ([RFC8126], Section 4.6).¶

+

+ Registration requests consist of the following information:¶

+
+
Field name:
+
+ The requested field name. It MUST conform to the + field-name syntax defined in Section 5.1, and it SHOULD be + restricted to just letters, digits, and hyphen ('-') + characters, with the first character being a letter.¶ +
+
+
Status:
+
+ "permanent", "provisional", "deprecated", or "obsoleted".¶ +
+
+
Specification document(s):
+
+ Reference to the document that specifies + the field, preferably including a URI that can be used to retrieve + a copy of the document. Optional but encouraged for provisional registrations. + An indication of the relevant section(s) can also be included, but is not required.¶ +
+
+
+

+ And optionally:¶

+
+
Comments:
+
+ Additional information, such as about reserved entries.¶ +
+
+
+

+ The expert(s) can define additional fields to be collected in the + registry, in consultation with the community.¶

+

+ Standards-defined names have a status of "permanent". Other names can also + be registered as permanent if the expert(s) finds that they are in use, in + consultation with the community. Other names should be registered as + "provisional".¶

+

+ Provisional entries can be removed by the expert(s) if -- in consultation + with the community -- the expert(s) find that they are not in use. The + expert(s) can change a provisional entry's status to permanent at any time.¶

+

+ Note that names can be registered by third parties (including the + expert(s)) if the expert(s) determines that an unregistered name is widely + deployed and not likely to be registered in a timely manner otherwise.¶

+
+
+
+
+

+16.3.2. Considerations for New Fields +

+

+ HTTP header and trailer fields are a widely used extension point for the protocol. + While they can be used in an ad hoc fashion, fields that are intended for + wider use need to be carefully documented to ensure interoperability.¶

+

+ In particular, authors of specifications defining new fields are advised to consider + and, where appropriate, document the following aspects:¶

+
    +
  • Under what conditions the field can be used; e.g., only in + responses or requests, in all messages, only on responses to a + particular request method, etc.¶ +
    • +
  • Whether the field semantics are further refined by their context, + such as their use with certain request methods or status codes.¶ +
    • +
  • The scope of applicability for the information conveyed. + By default, fields apply only to the message they are + associated with, but some response fields are designed to apply to all + representations of a resource, the resource itself, or an even broader + scope. Specifications that expand the scope of a response field will + need to carefully consider issues such as content negotiation, the time + period of applicability, and (in some cases) multi-tenant server + deployments.¶ +
    • +
  • Under what conditions intermediaries are allowed to insert, + delete, or modify the field's value.¶ +
    • +
  • If the field is allowable in trailers; by + default, it will not be (see Section 6.5.1).¶ +
    • +
  • Whether it is appropriate or even required to list the field name in the + Connection header field (i.e., if the field is to + be hop-by-hop; see Section 7.6.1).¶ +
    • +
  • Whether the field introduces any additional security considerations, such + as disclosure of privacy-related data.¶ +
    • +
+

+ Request header fields have additional considerations that need to be documented + if the default behavior is not appropriate:¶

+
    +
  • If it is appropriate to list the field name in a + Vary response header field (e.g., when the request header + field is used by an origin server's content selection algorithm; see + Section 12.5.5).¶ +
    • +
  • If the field is intended to be stored when received in a PUT + request (see Section 9.3.4).¶ +
    • +
  • If the field ought to be removed when automatically redirecting a + request due to security concerns (see Section 15.4).¶ +
    • +
+
+
+
+16.3.2.1. Considerations for New Field Names +
+

+ Authors of specifications defining new fields are advised to choose a short + but descriptive field name. Short names avoid needless data transmission; + descriptive names avoid confusion and "squatting" on names that might have + broader uses.¶

+

+ To that end, limited-use fields (such as a header confined to a single + application or use case) are encouraged to use a name that includes that use + (or an abbreviation) as a prefix; for example, if the Foo Application needs + a Description field, it might use "Foo-Desc"; "Description" is too generic, + and "Foo-Description" is needlessly long.¶

+

+ While the field-name syntax is defined to allow any token character, in + practice some implementations place limits on the characters they accept + in field-names. To be interoperable, new field names SHOULD constrain + themselves to alphanumeric characters, "-", and ".", and SHOULD + begin with a letter. For example, the underscore + ("_") character can be problematic when passed through non-HTTP + gateway interfaces (see Section 17.10).¶

+

+ Field names ought not be prefixed with "X-"; see + [BCP178] for further information.¶

+

+ Other prefixes are sometimes used in HTTP field names; for example, + "Accept-" is used in many content negotiation headers, and "Content-" is used + as explained in Section 6.4. These prefixes are + only an aid to recognizing the purpose of a field and do not + trigger automatic processing.¶

+
+
+
+
+
+16.3.2.2. Considerations for New Field Values +
+

+ A major task in the definition of a new HTTP field is the specification of + the field value syntax: what senders should generate, and how recipients + should infer semantics from what is received.¶

+

+ Authors are encouraged (but not required) to use either the ABNF rules in + this specification or those in [RFC8941] to define the syntax + of new field values.¶

+

+ Authors are advised to carefully consider how the combination of multiple + field lines will impact them (see Section 5.3). Because + senders might erroneously send multiple values, and both intermediaries + and HTTP libraries can perform combination automatically, this applies to + all field values -- even when only a single value is anticipated.¶

+

+ Therefore, authors are advised to delimit or encode values that contain + commas (e.g., with the quoted-string rule of + Section 5.6.4, the String data type of + [RFC8941], or a field-specific encoding). + This ensures that commas within field data are not confused + with the commas that delimit a list value.¶

+

+ For example, the Content-Type field value only allows commas + inside quoted strings, which can be reliably parsed even when multiple + values are present. The Location field value provides a + counter-example that should not be emulated: because URIs can include + commas, it is not possible to reliably distinguish between a single value + that includes a comma from two values.¶

+

+ Authors of fields with a singleton value (see Section 5.5) are additionally advised to document how to treat + messages where the multiple members are present (a sensible default would + be to ignore the field, but this might not always be the right choice).¶

+
+
+
+
+
+
+
+
+

+16.4. Authentication Scheme Extensibility +

+
+
+

+16.4.1. Authentication Scheme Registry +

+

+ The "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" + defines the namespace for the authentication schemes in challenges and + credentials. It is maintained + at <https://www.iana.org/assignments/http-authschemes>.¶

+

+ Registrations MUST include the following fields:¶

+
    +
  • Authentication Scheme Name¶ +
    • +
  • Pointer to specification text¶ +
    • +
  • Notes (optional)¶ +
    • +
+

+ Values to be added to this namespace require IETF Review + (see [RFC8126], Section 4.8).¶

+
+
+
+
+

+16.4.2. Considerations for New Authentication Schemes +

+

+ There are certain aspects of the HTTP Authentication framework that put + constraints on how new authentication schemes can work:¶

+
    +
  • +

    + HTTP authentication is presumed to be stateless: all of the information + necessary to authenticate a request MUST be provided in the request, + rather than be dependent on the server remembering prior requests. + Authentication based on, or bound to, the underlying connection is + outside the scope of this specification and inherently flawed unless + steps are taken to ensure that the connection cannot be used by any + party other than the authenticated user + (see Section 3.3).¶

    +
    • +
  • +

    + The authentication parameter "realm" is reserved for defining protection + spaces as described in Section 11.5. New schemes + MUST NOT use it in a way incompatible with that definition.¶

    +
    • +
  • +

    + The "token68" notation was introduced for compatibility with existing + authentication schemes and can only be used once per challenge or credential. + Thus, new schemes ought to use the auth-param syntax instead, because + otherwise future extensions will be impossible.¶

    +
    • +
  • +

    + The parsing of challenges and credentials is defined by this specification + and cannot be modified by new authentication schemes. When the auth-param + syntax is used, all parameters ought to support both token and + quoted-string syntax, and syntactical constraints ought to be defined on + the field value after parsing (i.e., quoted-string processing). This is + necessary so that recipients can use a generic parser that applies to + all authentication schemes.¶

    +

    + Note: The fact that the value syntax for the "realm" parameter + is restricted to quoted-string was a bad design choice not to be repeated + for new parameters.¶

    +
    • +
  • +

    + Definitions of new schemes ought to define the treatment of unknown + extension parameters. In general, a "must-ignore" rule is preferable + to a "must-understand" rule, because otherwise it will be hard to introduce + new parameters in the presence of legacy recipients. Furthermore, + it's good to describe the policy for defining new parameters (such + as "update the specification" or "use this registry").¶

    +
    • +
  • +

    + Authentication schemes need to document whether they are usable in + origin-server authentication (i.e., using WWW-Authenticate), + and/or proxy authentication (i.e., using Proxy-Authenticate).¶

    +
    • +
  • +

    + The credentials carried in an Authorization header field are specific to + the user agent and, therefore, have the same effect on HTTP caches as the + "private" cache response directive (Section 5.2.2.7 of [CACHING]), + within the scope of the request in which they appear.¶

    +

    + Therefore, new authentication schemes that choose not to carry + credentials in the Authorization header field (e.g., using a newly defined + header field) will need to explicitly disallow caching, by mandating the use of + cache response directives (e.g., "private").¶

    +
    • +
  • +

    + Schemes using Authentication-Info, Proxy-Authentication-Info, + or any other authentication related response header field need to + consider and document the related security considerations (see + Section 17.16.4).¶

    +
    • +
+
+
+
+
+
+
+

+16.5. Range Unit Extensibility +

+
+
+

+16.5.1. Range Unit Registry +

+

+ The "HTTP Range Unit Registry" defines the namespace for the range + unit names and refers to their corresponding specifications. + It is maintained at + <https://www.iana.org/assignments/http-parameters>.¶

+

+ Registration of an HTTP Range Unit MUST include the following fields:¶

+
    +
  • Name¶ +
    • +
  • Description¶ +
    • +
  • Pointer to specification text¶ +
    • +
+

+ Values to be added to this namespace require IETF Review + (see [RFC8126], Section 4.8).¶

+
+
+
+
+

+16.5.2. Considerations for New Range Units +

+

+ Other range units, such as format-specific boundaries like pages, + sections, records, rows, or time, are potentially usable in HTTP for + application-specific purposes, but are not commonly used in practice. + Implementors of alternative range units ought to consider how they would + work with content codings and general-purpose intermediaries.¶

+
+
+
+
+
+
+

+16.6. Content Coding Extensibility +

+
+
+

+16.6.1. Content Coding Registry +

+

+ The "HTTP Content Coding Registry", maintained by + IANA at <https://www.iana.org/assignments/http-parameters/>, + registers content-coding names.¶

+

+ Content coding registrations MUST include the following fields:¶

+
    +
  • Name¶ +
    • +
  • Description¶ +
    • +
  • Pointer to specification text¶ +
    • +
+

+ Names of content codings MUST NOT overlap with names of transfer codings + (per the "HTTP Transfer Coding Registry" located at + <https://www.iana.org/assignments/http-parameters/>) unless + the encoding transformation is + identical (as is the case for the compression codings defined in + Section 8.4.1).¶

+

+ Values to be added to this namespace require IETF Review + (see Section 4.8 of [RFC8126]) and MUST + conform to the purpose of content coding defined in + Section 8.4.1.¶

+
+
+
+
+

+16.6.2. Considerations for New Content Codings +

+

+ New content codings ought to be self-descriptive whenever possible, with + optional parameters discoverable within the coding format itself, rather + than rely on external metadata that might be lost during transit.¶

+
+
+
+
+
+
+

+16.7. Upgrade Token Registry +

+

+ The "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry" defines + the namespace for protocol-name tokens used to identify protocols in the + Upgrade header field. The registry is maintained at + <https://www.iana.org/assignments/http-upgrade-tokens>.¶

+

+ Each registered protocol name is associated with contact information + and an optional set of specifications that details how the connection + will be processed after it has been upgraded.¶

+

+ Registrations happen on a "First Come First Served" basis (see + Section 4.4 of [RFC8126]) and are subject to the + following rules:¶

+
    +
  1. A protocol-name token, once registered, stays registered forever.¶ +
    2. +
  2. A protocol-name token is case-insensitive and registered with the + preferred case to be generated by senders.¶ +
    3. +
  3. The registration MUST name a responsible party for the + registration.¶ +
    4. +
  4. The registration MUST name a point of contact.¶ +
    5. +
  5. The registration MAY name a set of specifications associated with + that token. Such specifications need not be publicly available.¶ +
    6. +
  6. The registration SHOULD name a set of expected "protocol-version" + tokens associated with that token at the time of registration.¶ +
    7. +
  7. The responsible party MAY change the registration at any time. + The IANA will keep a record of all such changes, and make them + available upon request.¶ +
    8. +
  8. The IESG MAY reassign responsibility for a protocol token. + This will normally only be used in the case when a + responsible party cannot be contacted.¶ +
    9. +
+
+
+
+
+
+
+

+17. Security Considerations +

+

+ This section is meant to inform developers, information providers, and + users of known security concerns relevant to HTTP semantics and its + use for transferring information over the Internet. Considerations related + to caching are discussed in Section 7 of [CACHING], + and considerations related to HTTP/1.1 message syntax and parsing are + discussed in Section 11 of [HTTP/1.1].¶

+

+ The list of considerations below is not exhaustive. Most security concerns + related to HTTP semantics are about securing server-side applications (code + behind the HTTP interface), securing user agent processing of content + received via HTTP, or secure use of the Internet in general, rather than + security of the protocol. The security considerations for URIs, which + are fundamental to HTTP operation, are discussed in + Section 7 of [URI]. Various organizations maintain + topical information and links to current research on Web application + security (e.g., [OWASP]).¶

+
+
+

+17.1. Establishing Authority +

+ + +

+ HTTP relies on the notion of an "authoritative response": a + response that has been determined by (or at the direction of) the origin + server identified within the target URI to be the most appropriate response + for that request given the state of the target resource at the time of + response message origination.¶

+

+ When a registered name is used in the authority component, the "http" URI + scheme (Section 4.2.1) relies on the user's local name + resolution service to determine where it can find authoritative responses. + This means that any attack on a user's network host table, cached names, + or name resolution libraries becomes an avenue for attack on establishing + authority for "http" URIs. Likewise, the user's choice of server for + Domain Name Service (DNS), and the hierarchy of servers from which it + obtains resolution results, could impact the authenticity of address + mappings; DNS Security Extensions (DNSSEC, [RFC4033]) are + one way to improve authenticity, as are the various mechanisms for making + DNS requests over more secure transfer protocols.¶

+

+ Furthermore, after an IP address is obtained, establishing authority for + an "http" URI is vulnerable to attacks on Internet Protocol routing.¶

+

+ The "https" scheme (Section 4.2.2) is intended to prevent + (or at least reveal) many of these potential attacks on establishing + authority, provided that the negotiated connection is secured and + the client properly verifies that the communicating server's identity + matches the target URI's authority component + (Section 4.3.4). Correctly implementing such verification + can be difficult (see [Georgiev]).¶

+

+ Authority for a given origin server can be delegated through protocol + extensions; for example, [ALTSVC]. Likewise, the set of + servers for which a connection is considered authoritative can be changed + with a protocol extension like [RFC8336].¶

+

+ Providing a response from a non-authoritative source, such as a shared + proxy cache, is often useful to improve performance and availability, but + only to the extent that the source can be trusted or the distrusted + response can be safely used.¶

+

+ Unfortunately, communicating authority to users can be difficult. + For example, "phishing" is an attack on the user's perception + of authority, where that perception can be misled by presenting similar + branding in hypertext, possibly aided by userinfo obfuscating the authority + component (see Section 4.2.1). + User agents can reduce the impact of phishing attacks by enabling users to + easily inspect a target URI prior to making an action, by prominently + distinguishing (or rejecting) userinfo when present, and by not sending + stored credentials and cookies when the referring document is from an + unknown or untrusted source.¶

+
+
+
+
+

+17.2. Risks of Intermediaries +

+

+ HTTP intermediaries are inherently situated for on-path attacks. + Compromise of + the systems on which the intermediaries run can result in serious security + and privacy problems. Intermediaries might have access to security-related + information, personal information about individual users and + organizations, and proprietary information belonging to users and + content providers. A compromised intermediary, or an intermediary + implemented or configured without regard to security and privacy + considerations, might be used in the commission of a wide range of + potential attacks.¶

+

+ Intermediaries that contain a shared cache are especially vulnerable + to cache poisoning attacks, as described in Section 7 of [CACHING].¶

+

+ Implementers need to consider the privacy and security + implications of their design and coding decisions, and of the + configuration options they provide to operators (especially the + default configuration).¶

+

+ Intermediaries are no more trustworthy than the people and policies + under which they operate; HTTP cannot solve this problem.¶

+
+
+
+
+

+17.3. Attacks Based on File and Path Names +

+

+ Origin servers frequently make use of their local file system to manage the + mapping from target URI to resource representations. + Most file systems are not designed to protect against malicious file + or path names. Therefore, an origin server needs to avoid accessing + names that have a special significance to the system when mapping the + target resource to files, folders, or directories.¶

+

+ For example, UNIX, Microsoft Windows, and other operating systems use ".." + as a path component to indicate a directory level above the current one, + and they use specially named paths or file names to send data to system devices. + Similar naming conventions might exist within other types of storage + systems. Likewise, local storage systems have an annoying tendency to + prefer user-friendliness over security when handling invalid or unexpected + characters, recomposition of decomposed characters, and case-normalization + of case-insensitive names.¶

+

+ Attacks based on such special names tend to focus on either denial-of-service + (e.g., telling the server to read from a COM port) or disclosure + of configuration and source files that are not meant to be served.¶

+
+
+
+
+

+17.4. Attacks Based on Command, Code, or Query Injection +

+

+ Origin servers often use parameters within the URI as a + means of identifying system services, selecting database entries, or + choosing a data source. However, data received in a request cannot be + trusted. An attacker could construct any of the request data elements + (method, target URI, header fields, or content) to contain data that might + be misinterpreted as a command, code, or query when passed through a + command invocation, language interpreter, or database interface.¶

+

+ For example, SQL injection is a common attack wherein additional query + language is inserted within some part of the target URI or header + fields (e.g., Host, Referer, etc.). + If the received data is used directly within a SELECT statement, the + query language might be interpreted as a database command instead of a + simple string value. This type of implementation vulnerability is extremely + common, in spite of being easy to prevent.¶

+

+ In general, resource implementations ought to avoid use of request data + in contexts that are processed or interpreted as instructions. Parameters + ought to be compared to fixed strings and acted upon as a result of that + comparison, rather than passed through an interface that is not prepared + for untrusted data. Received data that isn't based on fixed parameters + ought to be carefully filtered or encoded to avoid being misinterpreted.¶

+

+ Similar considerations apply to request data when it is stored and later + processed, such as within log files, monitoring tools, or when included + within a data format that allows embedded scripts.¶

+
+
+
+
+

+17.5. Attacks via Protocol Element Length +

+

+ Because HTTP uses mostly textual, character-delimited fields, parsers are + often vulnerable to attacks based on sending very long (or very slow) + streams of data, particularly where an implementation is expecting a + protocol element with no predefined length + (Section 2.3).¶

+

+ To promote interoperability, specific recommendations are made for minimum + size limits on fields (Section 5.4). These are + minimum recommendations, chosen to be supportable even by implementations + with limited resources; it is expected that most implementations will + choose substantially higher limits.¶

+

+ A server can reject a message that + has a target URI that is too long (Section 15.5.15) or request content + that is too large (Section 15.5.14). Additional status codes related to + capacity limits have been defined by extensions to HTTP + [RFC6585].¶

+

+ Recipients ought to carefully limit the extent to which they process other + protocol elements, including (but not limited to) request methods, response + status phrases, field names, numeric values, and chunk lengths. + Failure to limit such processing can result in arbitrary code execution due to + buffer or arithmetic + overflows, and increased vulnerability to denial-of-service attacks.¶

+
+
+
+
+

+17.6. Attacks Using Shared-Dictionary Compression +

+

+ Some attacks on encrypted protocols use the differences in size created by + dynamic compression to reveal confidential information; for example, [BREACH]. These attacks rely on creating a redundancy between + attacker-controlled content and the confidential information, such that a + dynamic compression algorithm using the same dictionary for both content + will compress more efficiently when the attacker-controlled content matches + parts of the confidential content.¶

+

+ HTTP messages can be compressed in a number of ways, including using TLS + compression, content codings, transfer codings, and other extension or + version-specific mechanisms.¶

+

+ The most effective mitigation for this risk is to disable compression on + sensitive data, or to strictly separate sensitive data from attacker-controlled + data so that they cannot share the same compression dictionary. With + careful design, a compression scheme can be designed in a way that is not + considered exploitable in limited use cases, such as HPACK ([HPACK]).¶

+
+
+
+
+

+17.7. Disclosure of Personal Information +

+

+ Clients are often privy to large amounts of personal information, + including both information provided by the user to interact with resources + (e.g., the user's name, location, mail address, passwords, encryption + keys, etc.) and information about the user's browsing activity over + time (e.g., history, bookmarks, etc.). Implementations need to + prevent unintentional disclosure of personal information.¶

+
+
+
+
+

+17.8. Privacy of Server Log Information +

+

+ A server is in the position to save personal data about a user's requests + over time, which might identify their reading patterns or subjects of + interest. In particular, log information gathered at an intermediary + often contains a history of user agent interaction, across a multitude + of sites, that can be traced to individual users.¶

+

+ HTTP log information is confidential in nature; its handling is often + constrained by laws and regulations. Log information needs to be securely + stored and appropriate guidelines followed for its analysis. + Anonymization of personal information within individual entries helps, + but it is generally not sufficient to prevent real log traces from being + re-identified based on correlation with other access characteristics. + As such, access traces that are keyed to a specific client are unsafe to + publish even if the key is pseudonymous.¶

+

+ To minimize the risk of theft or accidental publication, log information + ought to be purged of personally identifiable information, including + user identifiers, IP addresses, and user-provided query parameters, + as soon as that information is no longer necessary to support operational + needs for security, auditing, or fraud control.¶

+
+
+
+
+

+17.9. Disclosure of Sensitive Information in URIs +

+

+ URIs are intended to be shared, not secured, even when they identify secure + resources. URIs are often shown on displays, added to templates when a page + is printed, and stored in a variety of unprotected bookmark lists. + Many servers, proxies, and user agents log or display the target URI + in places where it might be visible to third parties. + It is therefore unwise to include information within a URI that + is sensitive, personally identifiable, or a risk to disclose.¶

+

+ When an application uses client-side mechanisms to construct a target URI + out of user-provided information, such as the query fields of a form using + GET, potentially sensitive data might be provided that would not be + appropriate for disclosure within a URI. POST is often preferred in such + cases because it usually doesn't construct a URI; instead, POST of a form + transmits the potentially sensitive data in the request content. However, this + hinders caching and uses an unsafe method for what would otherwise be a safe + request. Alternative workarounds include transforming the user-provided data + prior to constructing the URI or filtering the data to only include common + values that are not sensitive. Likewise, redirecting the result of a query + to a different (server-generated) URI can remove potentially sensitive data + from later links and provide a cacheable response for later reuse.¶

+

+ Since the Referer header field tells a target site about the + context that resulted in a request, it has the potential to reveal + information about the user's immediate browsing history and any personal + information that might be found in the referring resource's URI. + Limitations on the Referer header field are described in Section 10.1.3 to + address some of its security considerations.¶

+
+
+
+
+

+17.10. Application Handling of Field Names +

+

+ Servers often use non-HTTP gateway interfaces and frameworks to process a received + request and produce content for the response. For historical reasons, such interfaces + often pass received field names as external variable names, using a name mapping + suitable for environment variables.¶

+

+ For example, the Common Gateway Interface (CGI) mapping of protocol-specific + meta-variables, defined by Section 4.1.18 of [RFC3875], + is applied to received header fields that do not correspond to one of CGI's + standard variables; the mapping consists of prepending "HTTP_" to each name + and changing all instances of hyphen ("-") to underscore ("_"). This same mapping + has been inherited by many other application frameworks in order to simplify + moving applications from one platform to the next.¶

+

+ In CGI, a received Content-Length field would be passed + as the meta-variable "CONTENT_LENGTH" with a string value matching the + received field's value. In contrast, a received "Content_Length" header field would + be passed as the protocol-specific meta-variable "HTTP_CONTENT_LENGTH", + which might lead to some confusion if an application mistakenly reads the + protocol-specific meta-variable instead of the default one. (This historical practice + is why Section 16.3.2.1 discourages the creation + of new field names that contain an underscore.)¶

+

+ Unfortunately, mapping field names to different interface names can lead to + security vulnerabilities if the mapping is incomplete or ambiguous. For example, + if an attacker were to send a field named "Transfer_Encoding", a naive interface + might map that to the same variable name as the "Transfer-Encoding" field, resulting + in a potential request smuggling vulnerability (Section 11.2 of [HTTP/1.1]).¶

+

+ To mitigate the associated risks, implementations that perform such + mappings are advised to make the mapping unambiguous and complete + for the full range of potential octets received as a name (including those + that are discouraged or forbidden by the HTTP grammar). + For example, a field with an unusual name character might + result in the request being blocked, the specific field being removed, + or the name being passed with a different prefix to distinguish it from + other fields.¶

+
+
+
+
+

+17.11. Disclosure of Fragment after Redirects +

+

+ Although fragment identifiers used within URI references are not sent + in requests, implementers ought to be aware that they will be visible to + the user agent and any extensions or scripts running as a result of the + response. In particular, when a redirect occurs and the original request's + fragment identifier is inherited by the new reference in + Location (Section 10.2.2), this might + have the effect of disclosing one site's fragment to another site. + If the first site uses personal information in fragments, it ought to + ensure that redirects to other sites include a (possibly empty) fragment + component in order to block that inheritance.¶

+
+
+
+
+

+17.12. Disclosure of Product Information +

+

+ The User-Agent (Section 10.1.5), + Via (Section 7.6.3), and + Server (Section 10.2.4) header fields often + reveal information about the respective sender's software systems. + In theory, this can make it easier for an attacker to exploit known + security holes; in practice, attackers tend to try all potential holes + regardless of the apparent software versions being used.¶

+

+ Proxies that serve as a portal through a network firewall ought to take + special precautions regarding the transfer of header information that might + identify hosts behind the firewall. The Via header field + allows intermediaries to replace sensitive machine names with pseudonyms.¶

+
+
+
+
+

+17.13. Browser Fingerprinting +

+

+ Browser fingerprinting is a set of techniques for identifying a specific + user agent over time through its unique set of characteristics. These + characteristics might include information related to how it uses the underlying + transport protocol, + feature capabilities, and scripting environment, though of particular + interest here is the set of unique characteristics that might be + communicated via HTTP. Fingerprinting is considered a privacy concern + because it enables tracking of a user agent's behavior over time + ([Bujlow]) without + the corresponding controls that the user might have over other forms of + data collection (e.g., cookies). Many general-purpose user agents + (i.e., Web browsers) have taken steps to reduce their fingerprints.¶

+

+ There are a number of request header fields that might reveal information + to servers that is sufficiently unique to enable fingerprinting. + The From header field is the most obvious, though it is + expected that From will only be sent when self-identification is desired by + the user. Likewise, Cookie header fields are deliberately designed to + enable re-identification, so fingerprinting concerns only apply to + situations where cookies are disabled or restricted by the user agent's + configuration.¶

+

+ The User-Agent header field might contain enough information + to uniquely identify a specific device, usually when combined with other + characteristics, particularly if the user agent sends excessive details + about the user's system or extensions. However, the source of unique + information that is least expected by users is + proactive negotiation (Section 12.1), + including the Accept, Accept-Charset, + Accept-Encoding, and Accept-Language + header fields.¶

+

+ In addition to the fingerprinting concern, detailed use of the + Accept-Language header field can reveal information the + user might consider to be of a private nature. For example, understanding + a given language set might be strongly correlated to membership in a + particular ethnic group. + An approach that limits such loss of privacy would be for a user agent + to omit the sending of Accept-Language except for sites that have been + explicitly permitted, perhaps via interaction after detecting a Vary + header field that indicates language negotiation might be useful.¶

+

+ In environments where proxies are used to enhance privacy, user agents + ought to be conservative in sending proactive negotiation header fields. + General-purpose user agents that provide a high degree of header field + configurability ought to inform users about the loss of privacy that might + result if too much detail is provided. As an extreme privacy measure, + proxies could filter the proactive negotiation header fields in relayed + requests.¶

+
+
+
+
+

+17.14. Validator Retention +

+

+ The validators defined by this specification are not intended to ensure + the validity of a representation, guard against malicious changes, or + detect on-path attacks. At best, they enable more efficient cache + updates and optimistic concurrent writes when all participants are behaving + nicely. At worst, the conditions will fail and the client will receive a + response that is no more harmful than an HTTP exchange without conditional + requests.¶

+

+ An entity tag can be abused in ways that create privacy risks. For example, + a site might deliberately construct a semantically invalid entity tag that + is unique to the user or user agent, send it in a cacheable response with a + long freshness time, and then read that entity tag in later conditional + requests as a means of re-identifying that user or user agent. Such an + identifying tag would become a persistent identifier for as long as the + user agent retained the original cache entry. User agents that cache + representations ought to ensure that the cache is cleared or replaced + whenever the user performs privacy-maintaining actions, such as clearing + stored cookies or changing to a private browsing mode.¶

+
+
+
+
+

+17.15. Denial-of-Service Attacks Using Range +

+

+ Unconstrained multiple range requests are susceptible to denial-of-service + attacks because the effort required to request many overlapping ranges of + the same data is tiny compared to the time, memory, and bandwidth consumed + by attempting to serve the requested data in many parts. + Servers ought to ignore, coalesce, or reject egregious range requests, such + as requests for more than two overlapping ranges or for many small ranges + in a single set, particularly when the ranges are requested out of order + for no apparent reason. Multipart range requests are not designed to + support random access.¶

+
+
+
+
+

+17.16. Authentication Considerations +

+

+ Everything about the topic of HTTP authentication is a security + consideration, so the list of considerations below is not exhaustive. + Furthermore, it is limited to security considerations regarding the + authentication framework, in general, rather than discussing all of the + potential considerations for specific authentication schemes (which ought + to be documented in the specifications that define those schemes). + Various organizations maintain topical information and links to current + research on Web application security (e.g., [OWASP]), + including common pitfalls for implementing and using the authentication + schemes found in practice.¶

+
+
+

+17.16.1. Confidentiality of Credentials +

+

+ The HTTP authentication framework does not define a single mechanism for + maintaining the confidentiality of credentials; instead, each + authentication scheme defines how the credentials are encoded prior to + transmission. While this provides flexibility for the development of future + authentication schemes, it is inadequate for the protection of existing + schemes that provide no confidentiality on their own, or that do not + sufficiently protect against replay attacks. Furthermore, if the server + expects credentials that are specific to each individual user, the exchange + of those credentials will have the effect of identifying that user even if + the content within credentials remains confidential.¶

+

+ HTTP depends on the security properties of the underlying transport- or + session-level connection to provide confidential transmission of + fields. Services that depend on individual user authentication require a + secured connection prior to exchanging credentials + (Section 4.2.2).¶

+
+
+
+
+

+17.16.2. Credentials and Idle Clients +

+

+ Existing HTTP clients and user agents typically retain authentication + information indefinitely. HTTP does not provide a mechanism for the + origin server to direct clients to discard these cached credentials, since + the protocol has no awareness of how credentials are obtained or managed + by the user agent. The mechanisms for expiring or revoking credentials can + be specified as part of an authentication scheme definition.¶

+

+ Circumstances under which credential caching can interfere with the + application's security model include but are not limited to:¶

+
    +
  • Clients that have been idle for an extended period, following + which the server might wish to cause the client to re-prompt the + user for credentials.¶ +
    • +
  • Applications that include a session termination indication + (such as a "logout" or "commit" button on a page) after which + the server side of the application "knows" that there is no + further reason for the client to retain the credentials.¶ +
    • +
+

+ User agents that cache credentials are encouraged to provide a readily + accessible mechanism for discarding cached credentials under user control.¶

+
+
+
+
+

+17.16.3. Protection Spaces +

+

+ Authentication schemes that solely rely on the "realm" mechanism for + establishing a protection space will expose credentials to all resources on + an origin server. Clients that have successfully made authenticated requests + with a resource can use the same authentication credentials for other + resources on the same origin server. This makes it possible for a different + resource to harvest authentication credentials for other resources.¶

+

+ This is of particular concern when an origin server hosts resources for multiple + parties under the same origin (Section 11.5). + Possible mitigation strategies include restricting direct access to + authentication credentials (i.e., not making the content of the + Authorization request header field available), and separating protection + spaces by using a different host name (or port number) for each party.¶

+
+
+
+
+

+17.16.4. Additional Response Fields +

+

+ Adding information to responses that are sent over an unencrypted + channel can affect security and privacy. The presence of the + Authentication-Info and Proxy-Authentication-Info + header fields alone indicates that HTTP authentication is in use. Additional + information could be exposed by the contents of the authentication-scheme + specific parameters; this will have to be considered in the definitions of these + schemes.¶

+
+
+
+
+
+
+
+
+

+18. IANA Considerations +

+

+ The change controller for the following registrations is: + "IETF (iesg@ietf.org) - Internet Engineering Task Force".¶

+
+
+

+18.1. URI Scheme Registration +

+

+ IANA has updated the "Uniform Resource Identifier (URI) Schemes" registry [BCP35] at + <https://www.iana.org/assignments/uri-schemes/> with the + permanent schemes listed in Table 2 in Section 4.2.¶

+
+
+
+
+

+18.2. Method Registration +

+

+ IANA has updated the "Hypertext Transfer Protocol (HTTP) Method Registry" at + <https://www.iana.org/assignments/http-methods> with the + registration procedure of Section 16.1.1 and the method + names summarized in the following table.¶

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 7
MethodSafeIdempotentSection
CONNECTnono + 9.3.6 +
DELETEnoyes + 9.3.5 +
GETyesyes + 9.3.1 +
HEADyesyes + 9.3.2 +
OPTIONSyesyes + 9.3.7 +
POSTnono + 9.3.3 +
PUTnoyes + 9.3.4 +
TRACEyesyes + 9.3.8 +
*nono + 18.2 +
+
+

+ + The method name "*" is reserved because using "*" as a method name would + conflict with its usage as a wildcard in some fields (e.g., + "Access-Control-Request-Method").¶

+
+
+
+
+

+18.3. Status Code Registration +

+

+ IANA has updated the "Hypertext Transfer Protocol (HTTP) Status Code Registry" + at <https://www.iana.org/assignments/http-status-codes> with + the registration procedure of Section 16.2.1 and the + status code values summarized in the following table.¶

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 8
ValueDescriptionSection
100Continue + 15.2.1 +
101Switching Protocols + 15.2.2 +
200OK + 15.3.1 +
201Created + 15.3.2 +
202Accepted + 15.3.3 +
203Non-Authoritative Information + 15.3.4 +
204No Content + 15.3.5 +
205Reset Content + 15.3.6 +
206Partial Content + 15.3.7 +
300Multiple Choices + 15.4.1 +
301Moved Permanently + 15.4.2 +
302Found + 15.4.3 +
303See Other + 15.4.4 +
304Not Modified + 15.4.5 +
305Use Proxy + 15.4.6 +
306(Unused) + 15.4.7 +
307Temporary Redirect + 15.4.8 +
308Permanent Redirect + 15.4.9 +
400Bad Request + 15.5.1 +
401Unauthorized + 15.5.2 +
402Payment Required + 15.5.3 +
403Forbidden + 15.5.4 +
404Not Found + 15.5.5 +
405Method Not Allowed + 15.5.6 +
406Not Acceptable + 15.5.7 +
407Proxy Authentication Required + 15.5.8 +
408Request Timeout + 15.5.9 +
409Conflict + 15.5.10 +
410Gone + 15.5.11 +
411Length Required + 15.5.12 +
412Precondition Failed + 15.5.13 +
413Content Too Large + 15.5.14 +
414URI Too Long + 15.5.15 +
415Unsupported Media Type + 15.5.16 +
416Range Not Satisfiable + 15.5.17 +
417Expectation Failed + 15.5.18 +
418(Unused) + 15.5.19 +
421Misdirected Request + 15.5.20 +
422Unprocessable Content + 15.5.21 +
426Upgrade Required + 15.5.22 +
500Internal Server Error + 15.6.1 +
501Not Implemented + 15.6.2 +
502Bad Gateway + 15.6.3 +
503Service Unavailable + 15.6.4 +
504Gateway Timeout + 15.6.5 +
505HTTP Version Not Supported + 15.6.6 +
+
+
+
+
+
+

+18.4. Field Name Registration +

+

+ This specification updates the HTTP-related aspects of the existing + registration procedures for message header fields defined in [RFC3864]. + It replaces the old procedures as they relate to HTTP by defining a new + registration procedure and moving HTTP field definitions into a separate + registry.¶

+

+ IANA has created a new registry titled "Hypertext Transfer Protocol (HTTP) + Field Name Registry" as outlined in Section 16.3.1.¶

+

+ IANA has moved all entries in the "Permanent Message Header Field + Names" and "Provisional Message Header Field Names" registries (see + <https://www.iana.org/assignments/message-headers/>) with the + protocol 'http' to this registry and has applied the following changes:¶

+
    +
  1. The 'Applicable Protocol' field has been omitted.¶ +
    2. +
  2. Entries that had a status of 'standard', 'experimental', 'reserved', or + 'informational' have been made to have a status of 'permanent'.¶ +
    3. +
  3. Provisional entries without a status have been made to have a status of + 'provisional'.¶ +
    4. +
  4. Permanent entries without a status (after confirmation that the + registration document did not define one) have been made to have a status of + 'provisional'. The expert(s) can choose to update the entries' status if there is + evidence that another is more appropriate.¶ +
    5. +
+

+ IANA has annotated the "Permanent Message Header Field + Names" and "Provisional Message Header Field Names" registries with the + following note to indicate that HTTP field name registrations have moved:¶

+ +

+ IANA has updated the "Hypertext Transfer Protocol (HTTP) Field Name Registry" + with the field names listed in the following table.¶

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 9
Field NameStatusSectionComments
Acceptpermanent + 12.5.1 +
Accept-Charsetdeprecated + 12.5.2 +
Accept-Encodingpermanent + 12.5.3 +
Accept-Languagepermanent + 12.5.4 +
Accept-Rangespermanent + 14.3 +
Allowpermanent + 10.2.1 +
Authentication-Infopermanent + 11.6.3 +
Authorizationpermanent + 11.6.2 +
Connectionpermanent + 7.6.1 +
Content-Encodingpermanent + 8.4 +
Content-Languagepermanent + 8.5 +
Content-Lengthpermanent + 8.6 +
Content-Locationpermanent + 8.7 +
Content-Rangepermanent + 14.4 +
Content-Typepermanent + 8.3 +
Datepermanent + 6.6.1 +
ETagpermanent + 8.8.3 +
Expectpermanent + 10.1.1 +
Frompermanent + 10.1.2 +
Hostpermanent + 7.2 +
If-Matchpermanent + 13.1.1 +
If-Modified-Sincepermanent + 13.1.3 +
If-None-Matchpermanent + 13.1.2 +
If-Rangepermanent + 13.1.5 +
If-Unmodified-Sincepermanent + 13.1.4 +
Last-Modifiedpermanent + 8.8.2 +
Locationpermanent + 10.2.2 +
Max-Forwardspermanent + 7.6.2 +
Proxy-Authenticatepermanent + 11.7.1 +
Proxy-Authentication-Infopermanent + 11.7.3 +
Proxy-Authorizationpermanent + 11.7.2 +
Rangepermanent + 14.2 +
Refererpermanent + 10.1.3 +
Retry-Afterpermanent + 10.2.3 +
Serverpermanent + 10.2.4 +
TEpermanent + 10.1.4 +
Trailerpermanent + 6.6.2 +
Upgradepermanent + 7.8 +
User-Agentpermanent + 10.1.5 +
Varypermanent + 12.5.5 +
Viapermanent + 7.6.3 +
WWW-Authenticatepermanent + 11.6.1 +
*permanent + 12.5.5 + (reserved)
+
+
+

+ + + The field name "*" is reserved because using that name as + an HTTP header field might conflict with its special semantics in the + Vary header field (Section 12.5.5).¶

+
+

+ + + + + IANA has updated the "Content-MD5" entry in the new registry to have + a status of 'obsoleted' with references to + Section 14.15 of [RFC2616] (for the definition + of the header field) and + Appendix B of [RFC7231] (which removed the field + definition from the updated specification).¶

+
+
+
+
+

+18.5. Authentication Scheme Registration +

+

+ IANA has updated the + "Hypertext Transfer Protocol (HTTP) Authentication Scheme Registry" + at <https://www.iana.org/assignments/http-authschemes> with + the registration procedure of Section 16.4.1. + No authentication schemes are defined in this document.¶

+
+
+
+
+

+18.6. Content Coding Registration +

+

+ IANA has updated the "HTTP Content Coding Registry" at + <https://www.iana.org/assignments/http-parameters/> + with the registration procedure of Section 16.6.1 + and the content coding names summarized in the table below.¶

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Table 10
NameDescriptionSection
compressUNIX "compress" data format [Welch] + + 8.4.1.1 +
deflate"deflate" compressed data ([RFC1951]) inside + the "zlib" data format ([RFC1950]) + 8.4.1.2 +
gzipGZIP file format [RFC1952] + + 8.4.1.3 +
identityReserved + 12.5.3 +
x-compressDeprecated (alias for compress) + 8.4.1.1 +
x-gzipDeprecated (alias for gzip) + 8.4.1.3 +
+
+
+
+
+
+

+18.7. Range Unit Registration +

+

+ IANA has updated the "HTTP Range Unit Registry" at + <https://www.iana.org/assignments/http-parameters/> + with the registration procedure of Section 16.5.1 + and the range unit names summarized in the table below.¶

+
+ + + + + + + + + + + + + + + + + + + + + +
Table 11
Range Unit NameDescriptionSection
bytesa range of octets + 14.1.2 +
nonereserved as keyword to indicate range requests are not supported + 14.3 +
+
+
+
+
+
+

+18.8. Media Type Registration +

+

+ IANA has updated the "Media Types" registry at + <https://www.iana.org/assignments/media-types> + with the registration information in + Section 14.6 + for the media type "multipart/byteranges".¶

+

+ IANA has updated the registry note about "q" parameters with + a link to Section 12.5.1 of this document.¶

+
+
+
+
+

+18.9. Port Registration +

+

+ IANA has updated the "Service Name and Transport Protocol Port Number + Registry" at <https://www.iana.org/assignments/service-names-port-numbers/> + for the services on ports 80 and 443 that use UDP or TCP to:¶

+
    +
  1. use this document as "Reference", and¶ +
    2. +
  2. when currently unspecified, set "Assignee" to "IESG" and "Contact" to + "IETF_Chair".¶ +
    3. +
+
+
+
+
+

+18.10. Upgrade Token Registration +

+

+ IANA has updated the + "Hypertext Transfer Protocol (HTTP) Upgrade Token Registry" at + <https://www.iana.org/assignments/http-upgrade-tokens> + with the registration procedure described in Section 16.7 + and the upgrade token names summarized in the following table.¶

+ + + + + + + + + + + + + + + + + + +
Table 12
NameDescriptionExpected Version TokensSection
HTTPHypertext Transfer Protocolany DIGIT.DIGIT (e.g., "2.0") + 2.5 +
+
+
+
+
+
+

+19. References +

+
+

+19.1. Normative References +

+
+
[CACHING]
+
+Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP Caching", STD 98, RFC 9111, DOI 10.17487/RFC9111, , <https://www.rfc-editor.org/info/rfc9111>.
+
+
[RFC1950]
+
+Deutsch, P. and J-L. Gailly, "ZLIB Compressed Data Format Specification version 3.3", RFC 1950, DOI 10.17487/RFC1950, , <https://www.rfc-editor.org/info/rfc1950>.
+
+
[RFC1951]
+
+Deutsch, P., "DEFLATE Compressed Data Format Specification version 1.3", RFC 1951, DOI 10.17487/RFC1951, , <https://www.rfc-editor.org/info/rfc1951>.
+
+
[RFC1952]
+
+Deutsch, P., "GZIP file format specification version 4.3", RFC 1952, DOI 10.17487/RFC1952, , <https://www.rfc-editor.org/info/rfc1952>.
+
+
[RFC2046]
+
+Freed, N. and N. Borenstein, "Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types", RFC 2046, DOI 10.17487/RFC2046, , <https://www.rfc-editor.org/info/rfc2046>.
+
+
[RFC2119]
+
+Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, , <https://www.rfc-editor.org/info/rfc2119>.
+
+
[RFC4647]
+
+Phillips, A., Ed. and M. Davis, Ed., "Matching of Language Tags", BCP 47, RFC 4647, DOI 10.17487/RFC4647, , <https://www.rfc-editor.org/info/rfc4647>.
+
+
[RFC4648]
+
+Josefsson, S., "The Base16, Base32, and Base64 Data Encodings", RFC 4648, DOI 10.17487/RFC4648, , <https://www.rfc-editor.org/info/rfc4648>.
+
+
[RFC5234]
+
+Crocker, D., Ed. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, DOI 10.17487/RFC5234, , <https://www.rfc-editor.org/info/rfc5234>.
+
+
[RFC5280]
+
+Cooper, D., Santesson, S., Farrell, S., Boeyen, S., Housley, R., and W. Polk, "Internet X.509 Public Key Infrastructure Certificate and Certificate Revocation List (CRL) Profile", RFC 5280, DOI 10.17487/RFC5280, , <https://www.rfc-editor.org/info/rfc5280>.
+
+
[RFC5322]
+
+Resnick, P., Ed., "Internet Message Format", RFC 5322, DOI 10.17487/RFC5322, , <https://www.rfc-editor.org/info/rfc5322>.
+
+
[RFC5646]
+
+Phillips, A., Ed. and M. Davis, Ed., "Tags for Identifying Languages", BCP 47, RFC 5646, DOI 10.17487/RFC5646, , <https://www.rfc-editor.org/info/rfc5646>.
+
+
[RFC6125]
+
+Saint-Andre, P. and J. Hodges, "Representation and Verification of Domain-Based Application Service Identity within Internet Public Key Infrastructure Using X.509 (PKIX) Certificates in the Context of Transport Layer Security (TLS)", RFC 6125, DOI 10.17487/RFC6125, , <https://www.rfc-editor.org/info/rfc6125>.
+
+
[RFC6365]
+
+Hoffman, P. and J. Klensin, "Terminology Used in Internationalization in the IETF", BCP 166, RFC 6365, DOI 10.17487/RFC6365, , <https://www.rfc-editor.org/info/rfc6365>.
+
+
[RFC7405]
+
+Kyzivat, P., "Case-Sensitive String Support in ABNF", RFC 7405, DOI 10.17487/RFC7405, , <https://www.rfc-editor.org/info/rfc7405>.
+
+
[RFC8174]
+
+Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, , <https://www.rfc-editor.org/info/rfc8174>.
+
+
[TCP]
+
+Postel, J., "Transmission Control Protocol", STD 7, RFC 793, DOI 10.17487/RFC0793, , <https://www.rfc-editor.org/info/rfc793>.
+
+
[TLS13]
+
+Rescorla, E., "The Transport Layer Security (TLS) Protocol Version 1.3", RFC 8446, DOI 10.17487/RFC8446, , <https://www.rfc-editor.org/info/rfc8446>.
+
+
[URI]
+
+Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, DOI 10.17487/RFC3986, , <https://www.rfc-editor.org/info/rfc3986>.
+
+
[USASCII]
+
+American National Standards Institute, "Coded Character Set -- 7-bit American Standard Code for Information Interchange", ANSI X3.4, .
+
+
[Welch]
+
+Welch, T., "A Technique for High-Performance Data Compression", IEEE Computer 17(6), DOI 10.1109/MC.1984.1659158, , <https://ieeexplore.ieee.org/document/1659158/>.
+
+
+
+
+

+19.2. Informative References +

+
+
[ALTSVC]
+
+Nottingham, M., McManus, P., and J. Reschke, "HTTP Alternative Services", RFC 7838, DOI 10.17487/RFC7838, , <https://www.rfc-editor.org/info/rfc7838>.
+
+
[BCP13]
+
+
+ Freed, N. and J. Klensin, "Multipurpose Internet Mail Extensions (MIME) Part Four: Registration Procedures", BCP 13, RFC 4289, .
+
+ Freed, N., Klensin, J., and T. Hansen, "Media Type Specifications and Registration Procedures", BCP 13, RFC 6838, .
+<https://www.rfc-editor.org/info/bcp13> +
+
+
[BCP178]
+
+
+ Saint-Andre, P., Crocker, D., and M. Nottingham, "Deprecating the "X-" Prefix and Similar Constructs in Application Protocols", BCP 178, RFC 6648, .
+<https://www.rfc-editor.org/info/bcp178> +
+
+
[BCP35]
+
+
+ Thaler, D., Ed., Hansen, T., and T. Hardie, "Guidelines and Registration Procedures for URI Schemes", BCP 35, RFC 7595, .
+<https://www.rfc-editor.org/info/bcp35> +
+
+
[BREACH]
+
+Gluck, Y., Harris, N., and A. Prado, "BREACH: Reviving the CRIME Attack", , <http://breachattack.com/resources/BREACH%20-%20SSL,%20gone%20in%2030%20seconds.pdf>.
+
+
[Bujlow]
+
+Bujlow, T., Carela-Español, V., Solé-Pareta, J., and P. Barlet-Ros, "A Survey on Web Tracking: Mechanisms, Implications, and Defenses", In Proceedings of the IEEE 105(8), DOI 10.1109/JPROC.2016.2637878, , <https://doi.org/10.1109/JPROC.2016.2637878>.
+
+ +
+Barth, A., "HTTP State Management Mechanism", RFC 6265, DOI 10.17487/RFC6265, , <https://www.rfc-editor.org/info/rfc6265>.
+
+
[Err1912]
+
+RFC Errata, Erratum ID 1912, RFC 2978, <https://www.rfc-editor.org/errata/eid1912>.
+
+
[Err5433]
+
+RFC Errata, Erratum ID 5433, RFC 2978, <https://www.rfc-editor.org/errata/eid5433>.
+
+
[Georgiev]
+
+Georgiev, M., Iyengar, S., Jana, S., Anubhai, R., Boneh, D., and V. Shmatikov, "The Most Dangerous Code in the World: Validating SSL Certificates in Non-Browser Software", In Proceedings of the 2012 ACM Conference on Computer and Communications Security (CCS '12), pp. 38-49, DOI 10.1145/2382196.2382204, , <https://doi.org/10.1145/2382196.2382204>.
+
+
[HPACK]
+
+Peon, R. and H. Ruellan, "HPACK: Header Compression for HTTP/2", RFC 7541, DOI 10.17487/RFC7541, , <https://www.rfc-editor.org/info/rfc7541>.
+
+
[HTTP/1.0]
+
+Berners-Lee, T., Fielding, R., and H. Frystyk, "Hypertext Transfer Protocol -- HTTP/1.0", RFC 1945, DOI 10.17487/RFC1945, , <https://www.rfc-editor.org/info/rfc1945>.
+
+
[HTTP/1.1]
+
+Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "HTTP/1.1", STD 99, RFC 9112, DOI 10.17487/RFC9112, , <https://www.rfc-editor.org/info/rfc9112>.
+
+
[HTTP/2]
+
+Thomson, M., Ed. and C. Benfield, Ed., "HTTP/2", RFC 9113, DOI 10.17487/RFC9113, , <https://www.rfc-editor.org/info/rfc9113>.
+
+
[HTTP/3]
+
+Bishop, M., Ed., "HTTP/3", RFC 9114, DOI 10.17487/RFC9114, , <https://www.rfc-editor.org/info/rfc9114>.
+
+
[ISO-8859-1]
+
+International Organization for Standardization, "Information technology -- 8-bit single-byte coded graphic character sets -- Part 1: Latin alphabet No. 1", ISO/IEC 8859-1:1998, .
+
+
[Kri2001]
+
+Kristol, D., "HTTP Cookies: Standards, Privacy, and Politics", ACM Transactions on Internet Technology 1(2), , <http://arxiv.org/abs/cs.SE/0105018>.
+
+
[OWASP]
+
+The Open Web Application Security Project, <https://www.owasp.org/>.
+
+
[REST]
+
+Fielding, R.T., "Architectural Styles and the Design of Network-based Software Architectures", Doctoral Dissertation, University of California, Irvine, , <https://roy.gbiv.com/pubs/dissertation/top.htm>.
+
+
[RFC1919]
+
+Chatel, M., "Classical versus Transparent IP Proxies", RFC 1919, DOI 10.17487/RFC1919, , <https://www.rfc-editor.org/info/rfc1919>.
+
+
[RFC2047]
+
+Moore, K., "MIME (Multipurpose Internet Mail Extensions) Part Three: Message Header Extensions for Non-ASCII Text", RFC 2047, DOI 10.17487/RFC2047, , <https://www.rfc-editor.org/info/rfc2047>.
+
+
[RFC2068]
+
+Fielding, R., Gettys, J., Mogul, J., Frystyk, H., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2068, DOI 10.17487/RFC2068, , <https://www.rfc-editor.org/info/rfc2068>.
+
+
[RFC2145]
+
+Mogul, J. C., Fielding, R., Gettys, J., and H. Frystyk, "Use and Interpretation of HTTP Version Numbers", RFC 2145, DOI 10.17487/RFC2145, , <https://www.rfc-editor.org/info/rfc2145>.
+
+
[RFC2295]
+
+Holtman, K. and A. Mutz, "Transparent Content Negotiation in HTTP", RFC 2295, DOI 10.17487/RFC2295, , <https://www.rfc-editor.org/info/rfc2295>.
+
+
[RFC2324]
+
+Masinter, L., "Hyper Text Coffee Pot Control Protocol (HTCPCP/1.0)", RFC 2324, DOI 10.17487/RFC2324, , <https://www.rfc-editor.org/info/rfc2324>.
+
+
[RFC2557]
+
+Palme, J., Hopmann, A., and N. Shelness, "MIME Encapsulation of Aggregate Documents, such as HTML (MHTML)", RFC 2557, DOI 10.17487/RFC2557, , <https://www.rfc-editor.org/info/rfc2557>.
+
+
[RFC2616]
+
+Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, DOI 10.17487/RFC2616, , <https://www.rfc-editor.org/info/rfc2616>.
+
+
[RFC2617]
+
+Franks, J., Hallam-Baker, P., Hostetler, J., Lawrence, S., Leach, P., Luotonen, A., and L. Stewart, "HTTP Authentication: Basic and Digest Access Authentication", RFC 2617, DOI 10.17487/RFC2617, , <https://www.rfc-editor.org/info/rfc2617>.
+
+
[RFC2774]
+
+Nielsen, H., Leach, P., and S. Lawrence, "An HTTP Extension Framework", RFC 2774, DOI 10.17487/RFC2774, , <https://www.rfc-editor.org/info/rfc2774>.
+
+
[RFC2818]
+
+Rescorla, E., "HTTP Over TLS", RFC 2818, DOI 10.17487/RFC2818, , <https://www.rfc-editor.org/info/rfc2818>.
+
+
[RFC2978]
+
+Freed, N. and J. Postel, "IANA Charset Registration Procedures", BCP 19, RFC 2978, DOI 10.17487/RFC2978, , <https://www.rfc-editor.org/info/rfc2978>.
+
+
[RFC3040]
+
+Cooper, I., Melve, I., and G. Tomlinson, "Internet Web Replication and Caching Taxonomy", RFC 3040, DOI 10.17487/RFC3040, , <https://www.rfc-editor.org/info/rfc3040>.
+
+
[RFC3864]
+
+Klyne, G., Nottingham, M., and J. Mogul, "Registration Procedures for Message Header Fields", BCP 90, RFC 3864, DOI 10.17487/RFC3864, , <https://www.rfc-editor.org/info/rfc3864>.
+
+
[RFC3875]
+
+Robinson, D. and K. Coar, "The Common Gateway Interface (CGI) Version 1.1", RFC 3875, DOI 10.17487/RFC3875, , <https://www.rfc-editor.org/info/rfc3875>.
+
+
[RFC4033]
+
+Arends, R., Austein, R., Larson, M., Massey, D., and S. Rose, "DNS Security Introduction and Requirements", RFC 4033, DOI 10.17487/RFC4033, , <https://www.rfc-editor.org/info/rfc4033>.
+
+
[RFC4559]
+
+Jaganathan, K., Zhu, L., and J. Brezak, "SPNEGO-based Kerberos and NTLM HTTP Authentication in Microsoft Windows", RFC 4559, DOI 10.17487/RFC4559, , <https://www.rfc-editor.org/info/rfc4559>.
+
+
[RFC5789]
+
+Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, DOI 10.17487/RFC5789, , <https://www.rfc-editor.org/info/rfc5789>.
+
+
[RFC5905]
+
+Mills, D., Martin, J., Ed., Burbank, J., and W. Kasch, "Network Time Protocol Version 4: Protocol and Algorithms Specification", RFC 5905, DOI 10.17487/RFC5905, , <https://www.rfc-editor.org/info/rfc5905>.
+
+
[RFC6454]
+
+Barth, A., "The Web Origin Concept", RFC 6454, DOI 10.17487/RFC6454, , <https://www.rfc-editor.org/info/rfc6454>.
+
+
[RFC6585]
+
+Nottingham, M. and R. Fielding, "Additional HTTP Status Codes", RFC 6585, DOI 10.17487/RFC6585, , <https://www.rfc-editor.org/info/rfc6585>.
+
+
[RFC7230]
+
+Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Message Syntax and Routing", RFC 7230, DOI 10.17487/RFC7230, , <https://www.rfc-editor.org/info/rfc7230>.
+
+
[RFC7231]
+
+Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Semantics and Content", RFC 7231, DOI 10.17487/RFC7231, , <https://www.rfc-editor.org/info/rfc7231>.
+
+
[RFC7232]
+
+Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Conditional Requests", RFC 7232, DOI 10.17487/RFC7232, , <https://www.rfc-editor.org/info/rfc7232>.
+
+
[RFC7233]
+
+Fielding, R., Ed., Lafon, Y., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, DOI 10.17487/RFC7233, , <https://www.rfc-editor.org/info/rfc7233>.
+
+
[RFC7234]
+
+Fielding, R., Ed., Nottingham, M., Ed., and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Caching", RFC 7234, DOI 10.17487/RFC7234, , <https://www.rfc-editor.org/info/rfc7234>.
+
+
[RFC7235]
+
+Fielding, R., Ed. and J. Reschke, Ed., "Hypertext Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, DOI 10.17487/RFC7235, , <https://www.rfc-editor.org/info/rfc7235>.
+
+
[RFC7538]
+
+Reschke, J., "The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)", RFC 7538, DOI 10.17487/RFC7538, , <https://www.rfc-editor.org/info/rfc7538>.
+
+
[RFC7540]
+
+Belshe, M., Peon, R., and M. Thomson, Ed., "Hypertext Transfer Protocol Version 2 (HTTP/2)", RFC 7540, DOI 10.17487/RFC7540, , <https://www.rfc-editor.org/info/rfc7540>.
+
+
[RFC7578]
+
+Masinter, L., "Returning Values from Forms: multipart/form-data", RFC 7578, DOI 10.17487/RFC7578, , <https://www.rfc-editor.org/info/rfc7578>.
+
+
[RFC7615]
+
+Reschke, J., "HTTP Authentication-Info and Proxy-Authentication-Info Response Header Fields", RFC 7615, DOI 10.17487/RFC7615, , <https://www.rfc-editor.org/info/rfc7615>.
+
+
[RFC7616]
+
+Shekh-Yusef, R., Ed., Ahrens, D., and S. Bremer, "HTTP Digest Access Authentication", RFC 7616, DOI 10.17487/RFC7616, , <https://www.rfc-editor.org/info/rfc7616>.
+
+
[RFC7617]
+
+Reschke, J., "The 'Basic' HTTP Authentication Scheme", RFC 7617, DOI 10.17487/RFC7617, , <https://www.rfc-editor.org/info/rfc7617>.
+
+
[RFC7694]
+
+Reschke, J., "Hypertext Transfer Protocol (HTTP) Client-Initiated Content-Encoding", RFC 7694, DOI 10.17487/RFC7694, , <https://www.rfc-editor.org/info/rfc7694>.
+
+
[RFC8126]
+
+Cotton, M., Leiba, B., and T. Narten, "Guidelines for Writing an IANA Considerations Section in RFCs", BCP 26, RFC 8126, DOI 10.17487/RFC8126, , <https://www.rfc-editor.org/info/rfc8126>.
+
+
[RFC8187]
+
+Reschke, J., "Indicating Character Encoding and Language for HTTP Header Field Parameters", RFC 8187, DOI 10.17487/RFC8187, , <https://www.rfc-editor.org/info/rfc8187>.
+
+
[RFC8246]
+
+McManus, P., "HTTP Immutable Responses", RFC 8246, DOI 10.17487/RFC8246, , <https://www.rfc-editor.org/info/rfc8246>.
+
+
[RFC8288]
+
+Nottingham, M., "Web Linking", RFC 8288, DOI 10.17487/RFC8288, , <https://www.rfc-editor.org/info/rfc8288>.
+
+
[RFC8336]
+
+Nottingham, M. and E. Nygren, "The ORIGIN HTTP/2 Frame", RFC 8336, DOI 10.17487/RFC8336, , <https://www.rfc-editor.org/info/rfc8336>.
+
+
[RFC8615]
+
+Nottingham, M., "Well-Known Uniform Resource Identifiers (URIs)", RFC 8615, DOI 10.17487/RFC8615, , <https://www.rfc-editor.org/info/rfc8615>.
+
+
[RFC8941]
+
+Nottingham, M. and P-H. Kamp, "Structured Field Values for HTTP", RFC 8941, DOI 10.17487/RFC8941, , <https://www.rfc-editor.org/info/rfc8941>.
+
+
[Sniffing]
+
+WHATWG, "MIME Sniffing", <https://mimesniff.spec.whatwg.org>.
+
+
[WEBDAV]
+
+Dusseault, L., Ed., "HTTP Extensions for Web Distributed Authoring and Versioning (WebDAV)", RFC 4918, DOI 10.17487/RFC4918, , <https://www.rfc-editor.org/info/rfc4918>.
+
+
+
+
+
+
+

+Appendix A. Collected ABNF +

+

In the collected ABNF below, list rules are expanded per Section 5.6.1.¶

+
+
Accept = [ ( media-range [ weight ] ) *( OWS "," OWS ( media-range [
+ weight ] ) ) ]
+Accept-Charset = [ ( ( token / "*" ) [ weight ] ) *( OWS "," OWS ( (
+ token / "*" ) [ weight ] ) ) ]
+Accept-Encoding = [ ( codings [ weight ] ) *( OWS "," OWS ( codings [
+ weight ] ) ) ]
+Accept-Language = [ ( language-range [ weight ] ) *( OWS "," OWS (
+ language-range [ weight ] ) ) ]
+Accept-Ranges = acceptable-ranges
+Allow = [ method *( OWS "," OWS method ) ]
+Authentication-Info = [ auth-param *( OWS "," OWS auth-param ) ]
+Authorization = credentials
+
+BWS = OWS
+
+Connection = [ connection-option *( OWS "," OWS connection-option )
+ ]
+Content-Encoding = [ content-coding *( OWS "," OWS content-coding )
+ ]
+Content-Language = [ language-tag *( OWS "," OWS language-tag ) ]
+Content-Length = 1*DIGIT
+Content-Location = absolute-URI / partial-URI
+Content-Range = range-unit SP ( range-resp / unsatisfied-range )
+Content-Type = media-type
+
+Date = HTTP-date
+
+ETag = entity-tag
+Expect = [ expectation *( OWS "," OWS expectation ) ]
+
+From = mailbox
+
+GMT = %x47.4D.54 ; GMT
+
+HTTP-date = IMF-fixdate / obs-date
+Host = uri-host [ ":" port ]
+
+IMF-fixdate = day-name "," SP date1 SP time-of-day SP GMT
+If-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ]
+If-Modified-Since = HTTP-date
+If-None-Match = "*" / [ entity-tag *( OWS "," OWS entity-tag ) ]
+If-Range = entity-tag / HTTP-date
+If-Unmodified-Since = HTTP-date
+
+Last-Modified = HTTP-date
+Location = URI-reference
+
+Max-Forwards = 1*DIGIT
+
+OWS = *( SP / HTAB )
+
+Proxy-Authenticate = [ challenge *( OWS "," OWS challenge ) ]
+Proxy-Authentication-Info = [ auth-param *( OWS "," OWS auth-param )
+ ]
+Proxy-Authorization = credentials
+
+RWS = 1*( SP / HTAB )
+Range = ranges-specifier
+Referer = absolute-URI / partial-URI
+Retry-After = HTTP-date / delay-seconds
+
+Server = product *( RWS ( product / comment ) )
+
+TE = [ t-codings *( OWS "," OWS t-codings ) ]
+Trailer = [ field-name *( OWS "," OWS field-name ) ]
+
+URI-reference = <URI-reference, see [URI], Section 4.1>
+Upgrade = [ protocol *( OWS "," OWS protocol ) ]
+User-Agent = product *( RWS ( product / comment ) )
+
+Vary = [ ( "*" / field-name ) *( OWS "," OWS ( "*" / field-name ) )
+ ]
+Via = [ ( received-protocol RWS received-by [ RWS comment ] ) *( OWS
+ "," OWS ( received-protocol RWS received-by [ RWS comment ] ) ) ]
+
+WWW-Authenticate = [ challenge *( OWS "," OWS challenge ) ]
+
+absolute-URI = <absolute-URI, see [URI], Section 4.3>
+absolute-path = 1*( "/" segment )
+acceptable-ranges = range-unit *( OWS "," OWS range-unit )
+asctime-date = day-name SP date3 SP time-of-day SP year
+auth-param = token BWS "=" BWS ( token / quoted-string )
+auth-scheme = token
+authority = <authority, see [URI], Section 3.2>
+
+challenge = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS ","
+ OWS auth-param ) ] ) ]
+codings = content-coding / "identity" / "*"
+comment = "(" *( ctext / quoted-pair / comment ) ")"
+complete-length = 1*DIGIT
+connection-option = token
+content-coding = token
+credentials = auth-scheme [ 1*SP ( token68 / [ auth-param *( OWS ","
+ OWS auth-param ) ] ) ]
+ctext = HTAB / SP / %x21-27 ; '!'-'''
+ / %x2A-5B ; '*'-'['
+ / %x5D-7E ; ']'-'~'
+ / obs-text
+
+date1 = day SP month SP year
+date2 = day "-" month "-" 2DIGIT
+date3 = month SP ( 2DIGIT / ( SP DIGIT ) )
+day = 2DIGIT
+day-name = %x4D.6F.6E ; Mon
+ / %x54.75.65 ; Tue
+ / %x57.65.64 ; Wed
+ / %x54.68.75 ; Thu
+ / %x46.72.69 ; Fri
+ / %x53.61.74 ; Sat
+ / %x53.75.6E ; Sun
+day-name-l = %x4D.6F.6E.64.61.79 ; Monday
+ / %x54.75.65.73.64.61.79 ; Tuesday
+ / %x57.65.64.6E.65.73.64.61.79 ; Wednesday
+ / %x54.68.75.72.73.64.61.79 ; Thursday
+ / %x46.72.69.64.61.79 ; Friday
+ / %x53.61.74.75.72.64.61.79 ; Saturday
+ / %x53.75.6E.64.61.79 ; Sunday
+delay-seconds = 1*DIGIT
+
+entity-tag = [ weak ] opaque-tag
+etagc = "!" / %x23-7E ; '#'-'~'
+ / obs-text
+expectation = token [ "=" ( token / quoted-string ) parameters ]
+
+field-content = field-vchar [ 1*( SP / HTAB / field-vchar )
+ field-vchar ]
+field-name = token
+field-value = *field-content
+field-vchar = VCHAR / obs-text
+first-pos = 1*DIGIT
+
+hour = 2DIGIT
+http-URI = "http://" authority path-abempty [ "?" query ]
+https-URI = "https://" authority path-abempty [ "?" query ]
+
+incl-range = first-pos "-" last-pos
+int-range = first-pos "-" [ last-pos ]
+
+language-range = <language-range, see [RFC4647], Section 2.1>
+language-tag = <Language-Tag, see [RFC5646], Section 2.1>
+last-pos = 1*DIGIT
+
+mailbox = <mailbox, see [RFC5322], Section 3.4>
+media-range = ( "*/*" / ( type "/*" ) / ( type "/" subtype ) )
+ parameters
+media-type = type "/" subtype parameters
+method = token
+minute = 2DIGIT
+month = %x4A.61.6E ; Jan
+ / %x46.65.62 ; Feb
+ / %x4D.61.72 ; Mar
+ / %x41.70.72 ; Apr
+ / %x4D.61.79 ; May
+ / %x4A.75.6E ; Jun
+ / %x4A.75.6C ; Jul
+ / %x41.75.67 ; Aug
+ / %x53.65.70 ; Sep
+ / %x4F.63.74 ; Oct
+ / %x4E.6F.76 ; Nov
+ / %x44.65.63 ; Dec
+
+obs-date = rfc850-date / asctime-date
+obs-text = %x80-FF
+opaque-tag = DQUOTE *etagc DQUOTE
+other-range = 1*( %x21-2B ; '!'-'+'
+ / %x2D-7E ; '-'-'~'
+ )
+
+parameter = parameter-name "=" parameter-value
+parameter-name = token
+parameter-value = ( token / quoted-string )
+parameters = *( OWS ";" OWS [ parameter ] )
+partial-URI = relative-part [ "?" query ]
+path-abempty = <path-abempty, see [URI], Section 3.3>
+port = <port, see [URI], Section 3.2.3>
+product = token [ "/" product-version ]
+product-version = token
+protocol = protocol-name [ "/" protocol-version ]
+protocol-name = token
+protocol-version = token
+pseudonym = token
+
+qdtext = HTAB / SP / "!" / %x23-5B ; '#'-'['
+ / %x5D-7E ; ']'-'~'
+ / obs-text
+query = <query, see [URI], Section 3.4>
+quoted-pair = "\" ( HTAB / SP / VCHAR / obs-text )
+quoted-string = DQUOTE *( qdtext / quoted-pair ) DQUOTE
+qvalue = ( "0" [ "." *3DIGIT ] ) / ( "1" [ "." *3"0" ] )
+
+range-resp = incl-range "/" ( complete-length / "*" )
+range-set = range-spec *( OWS "," OWS range-spec )
+range-spec = int-range / suffix-range / other-range
+range-unit = token
+ranges-specifier = range-unit "=" range-set
+received-by = pseudonym [ ":" port ]
+received-protocol = [ protocol-name "/" ] protocol-version
+relative-part = <relative-part, see [URI], Section 4.2>
+rfc850-date = day-name-l "," SP date2 SP time-of-day SP GMT
+
+second = 2DIGIT
+segment = <segment, see [URI], Section 3.3>
+subtype = token
+suffix-length = 1*DIGIT
+suffix-range = "-" suffix-length
+
+t-codings = "trailers" / ( transfer-coding [ weight ] )
+tchar = "!" / "#" / "$" / "%" / "&" / "'" / "*" / "+" / "-" / "." /
+ "^" / "_" / "`" / "|" / "~" / DIGIT / ALPHA
+time-of-day = hour ":" minute ":" second
+token = 1*tchar
+token68 = 1*( ALPHA / DIGIT / "-" / "." / "_" / "~" / "+" / "/" )
+ *"="
+transfer-coding = token *( OWS ";" OWS transfer-parameter )
+transfer-parameter = token BWS "=" BWS ( token / quoted-string )
+type = token
+
+unsatisfied-range = "*/" complete-length
+uri-host = <host, see [URI], Section 3.2.2>
+
+weak = %x57.2F ; W/
+weight = OWS ";" OWS "q=" qvalue
+
+year = 4DIGIT
+
¶ +
+
+
+
+
+

+Appendix B. Changes from Previous RFCs +

+
+
+

+B.1. Changes from RFC 2818 +

+

+ None.¶

+
+
+
+
+

+B.2. Changes from RFC 7230 +

+

+ The sections introducing HTTP's design goals, history, architecture, + conformance criteria, protocol versioning, URIs, message routing, and + header fields have been moved here.¶

+

+ The requirement on semantic conformance has been replaced with permission to + ignore or work around implementation-specific failures. + (Section 2.2)¶

+

+ The description of an origin and authoritative access to origin servers has + been extended for both "http" and "https" URIs to account for alternative + services and secured connections that are not necessarily based on TCP. + (Sections 4.2.1, 4.2.2, + 4.3.1, and 7.3.3)¶

+

+ Explicit requirements have been added to check the target URI scheme's semantics + and reject requests that don't meet any associated requirements. + (Section 7.4)¶

+

+ Parameters in media type, media range, and expectation can be empty via + one or more trailing semicolons. + (Section 5.6.6)¶

+

+ "Field value" now refers to the value after multiple field lines are combined + with commas -- by far the most common use. To refer to a single header + line's value, use "field line value". + (Section 6.3)¶

+

+ Trailer field semantics now transcend the specifics of chunked transfer coding. + The use of trailer fields has been further limited to allow generation + as a trailer field only when the sender knows the field defines that usage and + to allow merging into the header section only if the recipient knows the + corresponding field definition permits and defines how to merge. In all + other cases, implementations are encouraged either to store the trailer + fields separately or to discard them instead of merging. + (Section 6.5.1)¶

+

+ The priority of the absolute form of the request URI over the Host + header field by origin servers has been made explicit to align with proxy handling. + (Section 7.2)¶

+

+ The grammar definition for the Via field's "received-by" was + expanded in RFC 7230 due to changes in the URI grammar for host + [URI] that are not desirable for Via. For simplicity, + we have removed uri-host from the received-by production because it can + be encompassed by the existing grammar for pseudonym. In particular, this + change removed comma from the allowed set of characters for a host name in + received-by. + (Section 7.6.3)¶

+
+
+
+
+

+B.3. Changes from RFC 7231 +

+

+ Minimum URI lengths to be supported by implementations are now recommended. + (Section 4.1)¶

+

+ The following have been clarified: CR and NUL in field values are to be rejected or + mapped to SP, and leading and trailing whitespace needs to be + stripped from field values before they are consumed. + (Section 5.5)¶

+

+ Parameters in media type, media range, and expectation can be empty via + one or more trailing semicolons. + (Section 5.6.6)¶

+

+ An abstract data type for HTTP messages has been introduced to define the + components of a message and their semantics as an abstraction across + multiple HTTP versions, rather than in terms of the specific syntax form of + HTTP/1.1 in [HTTP/1.1], and reflect the contents after the + message is parsed. This makes it easier to distinguish between requirements + on the content (what is conveyed) versus requirements on the messaging + syntax (how it is conveyed) and avoids baking limitations of early protocol + versions into the future of HTTP. (Section 6)¶

+

+ The terms "payload" and "payload body" have been replaced with "content", to better + align with its usage elsewhere (e.g., in field names) and to avoid confusion + with frame payloads in HTTP/2 and HTTP/3. + (Section 6.4)¶

+

+ The term "effective request URI" has been replaced with "target URI". + (Section 7.1)¶

+

+ Restrictions on client retries have been loosened to reflect implementation + behavior. + (Section 9.2.2)¶

+

+ The fact that request bodies on GET, HEAD, and DELETE are not interoperable has been clarified. + (Sections 9.3.1, 9.3.2, and 9.3.5)¶

+

+ The use of the Content-Range header field + (Section 14.4) as a request modifier on PUT is allowed. + (Section 9.3.4)¶

+

+ A superfluous requirement about setting Content-Length + has been removed from the description of the OPTIONS method. + (Section 9.3.7)¶

+

+ The normative requirement to use the "message/http" media type in + TRACE responses has been removed. + (Section 9.3.8)¶

+

+ List-based grammar for Expect has been restored for compatibility with + RFC 2616. + (Section 10.1.1)¶

+

+ Accept and Accept-Encoding are allowed in response + messages; the latter was introduced by [RFC7694]. + (Section 12.3)¶

+

+ "Accept Parameters" (accept-params and accept-ext ABNF production) have + been removed from the definition of the Accept field. + (Section 12.5.1)¶

+

+ The Accept-Charset field is now deprecated. + (Section 12.5.2)¶

+

+ The semantics of "*" in the Vary header field when other + values are present was clarified. + (Section 12.5.5)¶

+

+ Range units are compared in a case-insensitive fashion. + (Section 14.1)¶

+

+ The use of the Accept-Ranges field is not restricted to origin servers. + (Section 14.3)¶

+

+ The process of creating a redirected request has been clarified. + (Section 15.4)¶

+

+ Status code 308 (previously defined in [RFC7538]) + has been added so that it's defined closer to status codes 301, 302, and 307. + (Section 15.4.9)¶

+

+ Status code 421 (previously defined in + Section 9.1.2 of [RFC7540]) has been added because of its general + applicability. 421 is no longer defined as heuristically cacheable since + the response is specific to the connection (not the target resource). + (Section 15.5.20)¶

+

+ Status code 422 (previously defined in + Section 11.2 of [WEBDAV]) has been added because of its general + applicability. + (Section 15.5.21)¶

+
+
+
+
+

+B.4. Changes from RFC 7232 +

+

+ Previous revisions of HTTP imposed an arbitrary 60-second limit on the + determination of whether Last-Modified was a strong validator to guard + against the possibility that the Date and Last-Modified values are + generated from different clocks or at somewhat different times during the + preparation of the response. This specification has relaxed that to allow + reasonable discretion. + (Section 8.8.2.2)¶

+

+ An edge-case requirement on If-Match and If-Unmodified-Since + has been removed that required a validator not to be sent in a 2xx + response if validation fails because the change request has already + been applied. + (Sections 13.1.1 and + 13.1.4)¶

+

+ The fact that If-Unmodified-Since does not apply to a resource without a + concept of modification time has been clarified. + (Section 13.1.4)¶

+

+ Preconditions can now be evaluated before the request content is processed + rather than waiting until the response would otherwise be successful. + (Section 13.2)¶

+
+
+
+
+

+B.5. Changes from RFC 7233 +

+

+ Refactored the range-unit and ranges-specifier grammars to simplify + and reduce artificial distinctions between bytes and other + (extension) range units, removing the overlapping grammar of + other-range-unit by defining range units generically as a token and + placing extensions within the scope of a range-spec (other-range). + This disambiguates the role of list syntax (commas) in all range sets, + including extension range units, for indicating a range-set of more than + one range. Moving the extension grammar into range specifiers also allows + protocol specific to byte ranges to be specified separately.¶

+

+ It is now possible to define Range handling on extension methods. + (Section 14.2)¶

+

+ Described use of the Content-Range header field + (Section 14.4) as a request modifier to perform a + partial PUT. + (Section 14.5)¶

+
+
+
+
+

+B.6. Changes from RFC 7235 +

+

+ None.¶

+
+
+
+
+

+B.7. Changes from RFC 7538 +

+

+ None.¶

+
+
+
+
+

+B.8. Changes from RFC 7615 +

+

+ None.¶

+
+
+
+
+

+B.9. Changes from RFC 7694 +

+

+ This specification includes the extension defined in [RFC7694] + but leaves out examples and deployment considerations.¶

+
+
+
+
+
+
+

+Acknowledgements +

+

+ Aside from the current editors, the following individuals deserve special + recognition for their contributions to early aspects of HTTP and its + core specifications: + Marc Andreessen, Tim Berners-Lee, Robert Cailliau, Daniel W. Connolly, + Bob Denny, John Franks, Jim Gettys, + Jean-François Groff, + Phillip M. Hallam-Baker, + Koen Holtman, Jeffery L. Hostetler, Shel Kaphan, + Dave Kristol, Yves Lafon, Scott D. Lawrence, + Paul J. Leach, Håkon W. Lie, + Ari Luotonen, Larry Masinter, Rob McCool, + Jeffrey C. Mogul, Lou Montulli, + David Morris, Henrik Frystyk Nielsen, Dave Raggett, Eric Rescorla, + Tony Sanders, Lawrence C. Stewart, + Marc VanHeyningen, and Steve Zilles.¶

+

+ This document builds on the many contributions + that went into past specifications of HTTP, including + [HTTP/1.0], + [RFC2068], + [RFC2145], + [RFC2616], + [RFC2617], + [RFC2818], + [RFC7230], + [RFC7231], + [RFC7232], + [RFC7233], + [RFC7234], and + [RFC7235]. + The acknowledgements within those documents still apply.¶

+

+ Since 2014, the following contributors have helped improve this + specification by reporting bugs, asking smart questions, drafting or + reviewing text, and evaluating issues:¶

+

+ Alan Egerton, + Alex Rousskov, + Amichai Rothman, + Amos Jeffries, + Anders Kaseorg, + Andreas Gebhardt, + Anne van Kesteren, + Armin Abfalterer, + Aron Duby, + Asanka Herath, + Asbjørn Ulsberg, + Asta Olofsson, + Attila Gulyas, + Austin Wright, + Barry Pollard, + Ben Burkert, + Benjamin Kaduk, + Björn Höhrmann, + Brad Fitzpatrick, + Chris Pacejo, + Colin Bendell, + Cory Benfield, + Cory Nelson, + Daisuke Miyakawa, + Dale Worley, + Daniel Stenberg, + Danil Suits, + David Benjamin, + David Matson, + David Schinazi, + Дилян Палаузов (Dilyan Palauzov), + Eric Anderson, + Eric Rescorla, + Éric Vyncke, + Erik Kline, + Erwin Pe, + Etan Kissling, + Evert Pot, + Evgeny Vrublevsky, + Florian Best, + Francesca Palombini, + Igor Lubashev, + James Callahan, + James Peach, + Jeffrey Yasskin, + Kalin Gyokov, + Kannan Goundan, + 奥 一穂 (Kazuho Oku), + Ken Murchison, + Krzysztof Maczyński, + Lars Eggert, + Lucas Pardue, + Martin Duke, + Martin Dürst, + Martin Thomson, + Martynas Jusevičius, + Matt Menke, + Matthias Pigulla, + Mattias Grenfeldt, + Michael Osipov, + Mike Bishop, + Mike Pennisi, + Mike Taylor, + Mike West, + Mohit Sethi, + Murray Kucherawy, + Nathaniel J. Smith, + Nicholas Hurley, + Nikita Prokhorov, + Patrick McManus, + Piotr Sikora, + Poul-Henning Kamp, + Rick van Rein, + Robert Wilton, + Roberto Polli, + Roman Danyliw, + Samuel Williams, + Semyon Kholodnov, + Simon Pieters, + Simon Schüppel, + Stefan Eissing, + Taylor Hunt, + Todd Greer, + Tommy Pauly, + Vasiliy Faronov, + Vladimir Lashchev, + Wenbo Zhu, + William A. Rowe Jr., + Willy Tarreau, + Xingwei Liu, + Yishuai Li, and + Zaheduzzaman Sarker.¶

+
+
+
+

+Index +

+
+

+ 1 + 2 + 3 + 4 + 5 + A + B + C + D + E + F + G + H + I + L + M + N + O + P + R + S + T + U + V + W + X¶

+
+ +
+
+
+

+Authors' Addresses +

+
+
Roy T. Fielding (editor)
+
Adobe
+
345 Park Ave
San Jose, CA 95110
+
United States of America
+ +
+URI: +https://roy.gbiv.com/ +
+
+
+
Mark Nottingham (editor)
+
Fastly
+
Prahran
+
Australia
+ +
+URI: +https://www.mnot.net/ +
+
+
+
Julian Reschke (editor)
+
greenbytes GmbH
+
Hafenweg 16
48155 Münster
+
Germany
+ +
+URI: +https://greenbytes.de/tech/webdav/ +
+
+
+
+ + + + diff --git a/skills/structured-extraction/fixtures/rfc9110-http-semantics.yaml b/skills/structured-extraction/fixtures/rfc9110-http-semantics.yaml new file mode 100644 index 000000000..040ab424b --- /dev/null +++ b/skills/structured-extraction/fixtures/rfc9110-http-semantics.yaml @@ -0,0 +1,21 @@ +name: rfc9110-http-semantics +lane: deterministic +target: + kind: skill + ref: . +runner: extract +inputs: + input_path: "fixtures/rfc9110-http-semantics.html" + schema_path: "schemas/extraction.schema.json" + source_url: "https://www.rfc-editor.org/rfc/rfc9110.html" + content_type: "text/html" + max_items: 18 +expect: + status: success + outputs: + structured_extraction_result: + matches_packet: runx.structured_extraction.result.v1 +metadata: + public_skill: structured-extraction + source_case: rfc9110-http-semantics + source: p-40c7eb6c41 diff --git a/skills/structured-extraction/package.json b/skills/structured-extraction/package.json new file mode 100644 index 000000000..e2ac61f46 --- /dev/null +++ b/skills/structured-extraction/package.json @@ -0,0 +1,7 @@ +{ + "name": "@runxhq/structured-extraction", + "version": "0.1.0", + "private": true, + "type": "module", + "description": "runx governed skill for deterministic structured extraction from messy HTML or text." +} diff --git a/skills/structured-extraction/schemas/extraction.schema.json b/skills/structured-extraction/schemas/extraction.schema.json new file mode 100644 index 000000000..d1501afe7 --- /dev/null +++ b/skills/structured-extraction/schemas/extraction.schema.json @@ -0,0 +1,277 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "runx.structured_extraction.result.v1", + "type": "object", + "additionalProperties": false, + "required": [ + "schema", + "source", + "extraction", + "validation", + "provenance" + ], + "properties": { + "schema": { + "const": "runx.structured_extraction.result.v1" + }, + "source": { + "type": "object", + "additionalProperties": false, + "required": [ + "url", + "content_type", + "input_path", + "input_sha256", + "input_bytes" + ], + "properties": { + "url": { + "type": "string", + "minLength": 1 + }, + "content_type": { + "enum": [ + "text/html", + "text/plain" + ] + }, + "input_path": { + "type": "string", + "minLength": 1 + }, + "input_sha256": { + "type": "string", + "pattern": "^sha256:[0-9a-f]{64}$" + }, + "input_bytes": { + "type": "integer", + "minimum": 1 + } + } + }, + "extraction": { + "type": "object", + "additionalProperties": false, + "required": [ + "title", + "summary", + "items" + ], + "properties": { + "title": { + "type": "string", + "minLength": 1 + }, + "summary": { + "type": "object", + "additionalProperties": false, + "required": [ + "item_count", + "heading_count", + "term_count", + "paragraph_count", + "text_chars" + ], + "properties": { + "item_count": { + "type": "integer", + "minimum": 1 + }, + "heading_count": { + "type": "integer", + "minimum": 0 + }, + "term_count": { + "type": "integer", + "minimum": 0 + }, + "paragraph_count": { + "type": "integer", + "minimum": 0 + }, + "text_chars": { + "type": "integer", + "minimum": 1 + } + } + }, + "items": { + "type": "array", + "minItems": 8, + "items": { + "oneOf": [ + { + "$ref": "#/$defs/heading_item" + }, + { + "$ref": "#/$defs/paragraph_item" + }, + { + "$ref": "#/$defs/term_item" + } + ] + } + } + } + }, + "validation": { + "type": "object", + "additionalProperties": false, + "required": [ + "schema_id", + "schema_sha256", + "valid", + "engine", + "checks" + ], + "properties": { + "schema_id": { + "const": "runx.structured_extraction.result.v1" + }, + "schema_sha256": { + "type": "string", + "pattern": "^sha256:[0-9a-f]{64}$" + }, + "valid": { + "type": "boolean" + }, + "engine": { + "const": "native-json-schema-subset-v1" + }, + "checks": { + "type": "array", + "minItems": 4, + "items": { + "type": "object", + "additionalProperties": false, + "required": [ + "name", + "passed", + "detail" + ], + "properties": { + "name": { + "type": "string", + "minLength": 1 + }, + "passed": { + "type": "boolean" + }, + "detail": { + "type": "string" + } + } + } + } + } + }, + "provenance": { + "type": "object", + "additionalProperties": false, + "required": [ + "mode", + "tool_version", + "source_kind", + "output_payload_sha256" + ], + "properties": { + "mode": { + "const": "fixture" + }, + "tool_version": { + "type": "string", + "minLength": 1 + }, + "source_kind": { + "const": "real_public_document" + }, + "output_payload_sha256": { + "type": "string", + "pattern": "^sha256:[0-9a-f]{64}$" + } + } + }, + "artifacts": { + "type": "array", + "minItems": 3 + }, + "signal": { + "type": "object" + } + }, + "$defs": { + "heading_item": { + "type": "object", + "additionalProperties": false, + "required": [ + "kind", + "level", + "text", + "anchor" + ], + "properties": { + "kind": { + "const": "heading" + }, + "level": { + "type": "integer", + "minimum": 1, + "maximum": 4 + }, + "text": { + "type": "string", + "minLength": 3 + }, + "anchor": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ] + } + } + }, + "paragraph_item": { + "type": "object", + "additionalProperties": false, + "required": [ + "kind", + "text" + ], + "properties": { + "kind": { + "const": "paragraph" + }, + "text": { + "type": "string", + "minLength": 80 + } + } + }, + "term_item": { + "type": "object", + "additionalProperties": false, + "required": [ + "kind", + "text", + "context" + ], + "properties": { + "kind": { + "const": "term" + }, + "text": { + "type": "string", + "minLength": 2 + }, + "context": { + "type": "string", + "minLength": 10 + } + } + } + } +} diff --git a/skills/structured-extraction/tools/structured/extract/fixtures/rfc9110.yaml b/skills/structured-extraction/tools/structured/extract/fixtures/rfc9110.yaml new file mode 100644 index 000000000..3ea6a73ea --- /dev/null +++ b/skills/structured-extraction/tools/structured/extract/fixtures/rfc9110.yaml @@ -0,0 +1,27 @@ +name: structured-extract-rfc9110 +lane: deterministic +target: + kind: tool + ref: structured.extract +inputs: + input_path: fixtures/rfc9110-http-semantics.html + schema_path: schemas/extraction.schema.json + source_url: https://www.rfc-editor.org/rfc/rfc9110.html + content_type: text/html + max_items: 18 +expect: + status: success + output: + matches_packet: runx.structured_extraction.result.v1 + subset: + schema: runx.structured_extraction.result.v1 + source: + input_path: fixtures/rfc9110-http-semantics.html + url: https://www.rfc-editor.org/rfc/rfc9110.html + content_type: text/html + validation: + schema_id: runx.structured_extraction.result.v1 + valid: true + provenance: + mode: fixture + source_kind: real_public_document diff --git a/skills/structured-extraction/tools/structured/extract/manifest.json b/skills/structured-extraction/tools/structured/extract/manifest.json new file mode 100644 index 000000000..0b3cc120e --- /dev/null +++ b/skills/structured-extraction/tools/structured/extract/manifest.json @@ -0,0 +1,65 @@ +{ + "schema": "runx.tool.manifest.v1", + "name": "structured.extract", + "version": "0.1.0", + "description": "Extract schema-validated JSON from a messy HTML or text fixture and emit digest-bound artifact references.", + "source": { + "type": "cli-tool", + "command": "node", + "args": [ + "./run.mjs" + ] + }, + "inputs": { + "input_path": { + "type": "string", + "required": true, + "description": "Package-relative messy HTML or text fixture." + }, + "schema_path": { + "type": "string", + "required": true, + "description": "Package-relative JSON Schema path." + }, + "source_url": { + "type": "string", + "required": true, + "description": "Canonical source URL for the fixture bytes." + }, + "content_type": { + "type": "string", + "required": false, + "default": "text/html", + "description": "Input content type." + }, + "max_items": { + "type": "number", + "required": false, + "default": 20, + "description": "Maximum extracted items to include." + } + }, + "scopes": [ + "runx:fixture:read", + "runx:schema:read" + ], + "runx": { + "artifacts": { + "named_emits": { + "structured_extraction_result": "runx.structured_extraction.result.v1" + }, + "wrap_as": "structured_extraction_result" + } + }, + "runtime": { + "command": "node", + "args": [ + "./run.mjs" + ] + }, + "output": { + "packet": "runx.structured_extraction.result.v1", + "wrap_as": "structured_extraction_result" + }, + "toolkit_version": "0.1.4" +} diff --git a/skills/structured-extraction/tools/structured/extract/run.mjs b/skills/structured-extraction/tools/structured/extract/run.mjs new file mode 100644 index 000000000..1ab8cef2f --- /dev/null +++ b/skills/structured-extraction/tools/structured/extract/run.mjs @@ -0,0 +1,415 @@ +import fs from "node:fs"; +import path from "node:path"; +import crypto from "node:crypto"; +import { fileURLToPath } from "node:url"; + +const __dirname = path.dirname(fileURLToPath(import.meta.url)); +const TOOL_VERSION = "0.1.0"; + +function readInputs() { + const raw = process.env.RUNX_INPUTS_PATH + ? fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8") + : (process.env.RUNX_INPUTS_JSON || "{}"); + return JSON.parse(raw); +} + +function packageRoot() { + return path.resolve(__dirname, "../../.."); +} + +function resolveInsidePackage(relativePath, label) { + const root = packageRoot(); + const resolved = path.resolve(root, String(relativePath || "")); + if (!resolved.startsWith(root + path.sep) && resolved !== root) { + throw new Error(`${label} escapes the skill package`); + } + return resolved; +} + +function sha256Bytes(bytes) { + return `sha256:${crypto.createHash("sha256").update(bytes).digest("hex")}`; +} + +function sha256Text(text) { + return sha256Bytes(Buffer.from(text, "utf8")); +} + +function canonicalJson(value) { + if (value === null || typeof value !== "object") { + return JSON.stringify(value); + } + if (Array.isArray(value)) { + return `[${value.map(canonicalJson).join(",")}]`; + } + return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`; +} + +function schemaTypeOf(value) { + if (value === null) { + return "null"; + } + if (Array.isArray(value)) { + return "array"; + } + if (Number.isInteger(value)) { + return "integer"; + } + return typeof value; +} + +function resolveSchemaRef(ref, rootSchema) { + if (!ref.startsWith("#/")) { + throw new Error(`unsupported schema ref: ${ref}`); + } + return ref + .slice(2) + .split("/") + .reduce((node, part) => { + const key = part.replace(/~1/g, "/").replace(/~0/g, "~"); + if (!node || typeof node !== "object" || !(key in node)) { + throw new Error(`unresolved schema ref: ${ref}`); + } + return node[key]; + }, rootSchema); +} + +function validateSchemaValue(value, schemaNode, rootSchema, pointer = "$") { + if (!schemaNode || typeof schemaNode !== "object") { + return []; + } + if (schemaNode.$ref) { + return validateSchemaValue(value, resolveSchemaRef(schemaNode.$ref, rootSchema), rootSchema, pointer); + } + if (Array.isArray(schemaNode.anyOf)) { + const variants = schemaNode.anyOf.map((variant) => validateSchemaValue(value, variant, rootSchema, pointer)); + if (variants.some((errors) => errors.length === 0)) { + return []; + } + return [`${pointer} did not match anyOf: ${variants.map((errors) => errors[0]).filter(Boolean).join("; ")}`]; + } + if (Array.isArray(schemaNode.oneOf)) { + const matches = schemaNode.oneOf + .map((variant) => validateSchemaValue(value, variant, rootSchema, pointer)) + .filter((errors) => errors.length === 0); + return matches.length === 1 ? [] : [`${pointer} matched ${matches.length} oneOf variants`]; + } + + const errors = []; + const actualType = schemaTypeOf(value); + if (schemaNode.type) { + const allowedTypes = Array.isArray(schemaNode.type) ? schemaNode.type : [schemaNode.type]; + if (!allowedTypes.includes(actualType)) { + errors.push(`${pointer} expected ${allowedTypes.join("|")}, got ${actualType}`); + return errors; + } + } + if ("const" in schemaNode && value !== schemaNode.const) { + errors.push(`${pointer} expected const ${JSON.stringify(schemaNode.const)}`); + } + if (Array.isArray(schemaNode.enum) && !schemaNode.enum.includes(value)) { + errors.push(`${pointer} expected one of ${schemaNode.enum.map((entry) => JSON.stringify(entry)).join(", ")}`); + } + if (typeof value === "string") { + if (schemaNode.minLength !== undefined && value.length < schemaNode.minLength) { + errors.push(`${pointer} length ${value.length} < ${schemaNode.minLength}`); + } + if (schemaNode.pattern && !(new RegExp(schemaNode.pattern).test(value))) { + errors.push(`${pointer} does not match ${schemaNode.pattern}`); + } + } + if (typeof value === "number") { + if (schemaNode.minimum !== undefined && value < schemaNode.minimum) { + errors.push(`${pointer} ${value} < ${schemaNode.minimum}`); + } + if (schemaNode.maximum !== undefined && value > schemaNode.maximum) { + errors.push(`${pointer} ${value} > ${schemaNode.maximum}`); + } + } + if (Array.isArray(value)) { + if (schemaNode.minItems !== undefined && value.length < schemaNode.minItems) { + errors.push(`${pointer} has ${value.length} item(s), expected at least ${schemaNode.minItems}`); + } + if (schemaNode.maxItems !== undefined && value.length > schemaNode.maxItems) { + errors.push(`${pointer} has ${value.length} item(s), expected at most ${schemaNode.maxItems}`); + } + if (schemaNode.items) { + value.forEach((item, index) => { + errors.push(...validateSchemaValue(item, schemaNode.items, rootSchema, `${pointer}[${index}]`)); + }); + } + } + if (value && typeof value === "object" && !Array.isArray(value)) { + const properties = schemaNode.properties || {}; + const required = Array.isArray(schemaNode.required) ? schemaNode.required : []; + for (const field of required) { + if (!(field in value)) { + errors.push(`${pointer}.${field} is required`); + } + } + for (const [field, fieldValue] of Object.entries(value)) { + if (field in properties) { + errors.push(...validateSchemaValue(fieldValue, properties[field], rootSchema, `${pointer}.${field}`)); + } else if (schemaNode.additionalProperties === false) { + errors.push(`${pointer}.${field} is not allowed`); + } + } + } + return errors; +} + +function decodeEntities(text) { + return text + .replace(/ /g, " ") + .replace(/&/g, "&") + .replace(/</g, "<") + .replace(/>/g, ">") + .replace(/"/g, "\"") + .replace(/'/g, "'") + .replace(/&#x([0-9a-f]+);/gi, (_, hex) => String.fromCodePoint(Number.parseInt(hex, 16))) + .replace(/&#([0-9]+);/g, (_, dec) => String.fromCodePoint(Number.parseInt(dec, 10))); +} + +function stripTags(html) { + return decodeEntities(html) + .replace(//gi, " ") + .replace(//gi, " ") + .replace(/<[^>]+>/g, " ") + .replace(/\s+/g, " ") + .trim(); +} + +function extractTitle(raw, contentType) { + if (contentType === "text/html") { + const title = raw.match(/]*>([\s\S]*?)<\/title>/i); + if (title) { + return stripTags(title[1]); + } + const h1 = raw.match(/]*>([\s\S]*?)<\/h1>/i); + if (h1) { + return stripTags(h1[1]); + } + } + return raw.split(/\r?\n/).map((line) => line.trim()).find(Boolean) || "Untitled input"; +} + +function extractHeadings(raw, maxItems) { + const items = []; + const headingPattern = /]*)>([\s\S]*?)<\/h\1>/gi; + let match; + while ((match = headingPattern.exec(raw)) && items.length < maxItems) { + const attrs = match[2] || ""; + const id = attrs.match(/\sid=["']([^"']+)["']/i)?.[1] || null; + const text = stripTags(match[3]); + if (text.length >= 3) { + items.push({ + kind: "heading", + level: Number(match[1]), + text, + anchor: id, + }); + } + } + return items; +} + +function extractHttpTokens(text, maxItems) { + const tokenPattern = /\b(GET|HEAD|POST|PUT|DELETE|CONNECT|OPTIONS|TRACE|PATCH|HTTP\/[0-9.]+|Content-Type|Content-Length|Cache-Control|Authorization|Location|ETag|Accept)\b/g; + const seen = new Set(); + const items = []; + let match; + while ((match = tokenPattern.exec(text)) && items.length < maxItems) { + const token = match[1]; + if (seen.has(token)) { + continue; + } + seen.add(token); + const start = Math.max(0, match.index - 90); + const end = Math.min(text.length, match.index + token.length + 90); + items.push({ + kind: "term", + text: token, + context: text.slice(start, end).replace(/\s+/g, " ").trim(), + }); + } + return items; +} + +function extractParagraphs(raw, maxItems) { + const paragraphs = []; + const pattern = /]*>([\s\S]*?)<\/p>/gi; + let match; + while ((match = pattern.exec(raw)) && paragraphs.length < maxItems) { + const text = stripTags(match[1]); + if (text.length > 80) { + paragraphs.push({ + kind: "paragraph", + text: text.slice(0, 360), + }); + } + } + return paragraphs; +} + +function validatePacket(packet, schema) { + const counts = { + heading: packet.extraction.items.filter((item) => item.kind === "heading").length, + term: packet.extraction.items.filter((item) => item.kind === "term").length, + paragraph: packet.extraction.items.filter((item) => item.kind === "paragraph").length, + }; + const checks = [ + { name: "has_source_digest", passed: /^sha256:[0-9a-f]{64}$/.test(packet.source.input_sha256), detail: packet.source.input_sha256 }, + { name: "has_schema_digest", passed: /^sha256:[0-9a-f]{64}$/.test(packet.validation.schema_sha256), detail: packet.validation.schema_sha256 }, + { name: "has_minimum_items", passed: Array.isArray(packet.extraction.items) && packet.extraction.items.length >= 8, detail: String(packet.extraction.items.length) }, + { + name: "summary_counts_match_items", + passed: + packet.extraction.summary.item_count === packet.extraction.items.length && + packet.extraction.summary.heading_count === counts.heading && + packet.extraction.summary.term_count === counts.term && + packet.extraction.summary.paragraph_count === counts.paragraph, + detail: JSON.stringify(counts), + }, + ]; + packet.validation.checks = checks; + packet.validation.valid = checks.every((check) => check.passed); + const schemaErrors = validateSchemaValue(packet, schema, schema); + checks.push({ + name: "json_schema_validation", + passed: schemaErrors.length === 0, + detail: schemaErrors.length === 0 ? "output validates against schemas/extraction.schema.json" : schemaErrors.slice(0, 6).join("; "), + }); + packet.validation.valid = checks.every((check) => check.passed); + return { + valid: packet.validation.valid, + checks, + schemaErrors, + }; +} + +function main() { + const inputs = readInputs(); + const inputPath = resolveInsidePackage(inputs.input_path, "input_path"); + const schemaPath = resolveInsidePackage(inputs.schema_path, "schema_path"); + const contentType = String(inputs.content_type || "text/html"); + const maxItems = Math.max(8, Math.min(Number(inputs.max_items || 20), 60)); + const sourceUrl = String(inputs.source_url || "").trim(); + if (!sourceUrl) { + throw new Error("source_url is required"); + } + + const inputBytes = fs.readFileSync(inputPath); + const raw = inputBytes.toString("utf8"); + const schemaBytes = fs.readFileSync(schemaPath); + const schema = JSON.parse(schemaBytes.toString("utf8")); + const plainText = contentType === "text/html" ? stripTags(raw) : raw.replace(/\s+/g, " ").trim(); + + const headings = contentType === "text/html" ? extractHeadings(raw, Math.ceil(maxItems / 2)) : []; + const paragraphs = contentType === "text/html" ? extractParagraphs(raw, 3) : []; + const terms = extractHttpTokens(plainText, maxItems); + const items = [...headings, ...paragraphs, ...terms].slice(0, maxItems); + + const extraction = { + title: extractTitle(raw, contentType), + summary: { + item_count: items.length, + heading_count: items.filter((item) => item.kind === "heading").length, + term_count: items.filter((item) => item.kind === "term").length, + paragraph_count: items.filter((item) => item.kind === "paragraph").length, + text_chars: plainText.length, + }, + items, + }; + + const packet = { + schema: "runx.structured_extraction.result.v1", + source: { + url: sourceUrl, + content_type: contentType, + input_path: String(inputs.input_path), + input_sha256: sha256Bytes(inputBytes), + input_bytes: inputBytes.length, + }, + extraction, + validation: { + schema_id: schema.$id || "runx.structured_extraction.result.v1", + schema_sha256: sha256Bytes(schemaBytes), + valid: false, + engine: "native-json-schema-subset-v1", + checks: [], + }, + provenance: { + mode: "fixture", + tool_version: TOOL_VERSION, + source_kind: "real_public_document", + output_payload_sha256: null, + }, + }; + + const outputPayload = { + source: packet.source, + extraction: packet.extraction, + validation_schema_id: packet.validation.schema_id, + }; + packet.provenance.output_payload_sha256 = sha256Text(canonicalJson(outputPayload)); + const validation = validatePacket(packet, schema); + packet.validation.valid = validation.valid; + packet.validation.checks = validation.checks; + const finalSchemaErrors = validateSchemaValue(packet, schema, schema); + if (finalSchemaErrors.length > 0) { + packet.validation.valid = false; + packet.validation.checks.push({ + name: "final_json_schema_validation", + passed: false, + detail: finalSchemaErrors.slice(0, 6).join("; "), + }); + } + if (!packet.validation.valid) { + throw new Error(`schema validation failed: ${JSON.stringify(packet.validation.checks)}`); + } + + packet.artifacts = [ + { + id: packet.source.input_sha256, + artifact_id: packet.source.input_sha256, + type: "input_fixture", + artifact_type: "input_fixture", + label: "RFC 9110 HTML fixture", + source_url: sourceUrl, + byte_count: inputBytes.length, + }, + { + id: packet.validation.schema_sha256, + artifact_id: packet.validation.schema_sha256, + type: "json_schema", + artifact_type: "json_schema", + label: packet.validation.schema_id, + }, + { + id: packet.provenance.output_payload_sha256, + artifact_id: packet.provenance.output_payload_sha256, + type: "validated_output", + artifact_type: "validated_output", + label: "Structured extraction JSON payload", + }, + ]; + packet.signal = { + signal_id: `structured-extraction:${packet.source.input_sha256}:${packet.provenance.output_payload_sha256}`, + source_events: [ + { + provider: "rfc-editor", + source_locator: sourceUrl, + title: "RFC 9110 HTTP Semantics HTML", + }, + ], + artifacts: packet.artifacts, + }; + + process.stdout.write(JSON.stringify(packet)); +} + +try { + main(); +} catch (error) { + process.stderr.write(`${JSON.stringify({ error: { message: error.message } })}\n`); + process.exitCode = 1; +} From 04bb94bacbebd5fb088c956c6dbe5567e4ccd1ed Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 19:59:46 +1000 Subject: [PATCH 20/64] fix(runtime): require declared agent outputs --- .../src/adapters/agent_resolver.rs | 135 +++++++++++++++++- .../src/execution/runner/steps/output.rs | 9 +- 2 files changed, 134 insertions(+), 10 deletions(-) diff --git a/crates/runx-runtime/src/adapters/agent_resolver.rs b/crates/runx-runtime/src/adapters/agent_resolver.rs index 717ebbe04..4044a550a 100644 --- a/crates/runx-runtime/src/adapters/agent_resolver.rs +++ b/crates/runx-runtime/src/adapters/agent_resolver.rs @@ -9,7 +9,9 @@ use std::collections::BTreeMap; use std::path::PathBuf; -use runx_contracts::{ContextEntry, JsonObject, JsonValue, ResolutionRequest}; +use runx_contracts::{ + ContextEntry, JsonObject, JsonValue, OutputField, OutputType, ResolutionRequest, +}; use super::agent::{AgentResolution, AgentResolver, AgentResolverError}; use super::agent_anthropic::{AgentToolDefinition, AnthropicModelCaller}; @@ -62,10 +64,92 @@ fn object_schema() -> JsonValue { JsonValue::Object(schema) } +fn final_result_schema(output: Option<&BTreeMap>) -> JsonValue { + let Some(output) = output else { + return object_schema(); + }; + if output.is_empty() { + return object_schema(); + } + + let mut properties = JsonObject::new(); + let mut required = Vec::new(); + for (name, field) in output { + properties.insert(name.clone(), output_field_schema(field)); + if output_field_required(field) { + required.push(JsonValue::String(name.clone())); + } + } + + let mut schema = JsonObject::new(); + schema.insert("type".to_owned(), JsonValue::String("object".to_owned())); + schema.insert("properties".to_owned(), JsonValue::Object(properties)); + schema.insert("additionalProperties".to_owned(), JsonValue::Bool(false)); + if !required.is_empty() { + schema.insert("required".to_owned(), JsonValue::Array(required)); + } + JsonValue::Object(schema) +} + +fn output_field_required(field: &OutputField) -> bool { + match field { + OutputField::Type(_) => true, + OutputField::Spec(spec) => spec.required.unwrap_or(true), + } +} + +fn output_field_schema(field: &OutputField) -> JsonValue { + let mut schema = JsonObject::new(); + match field { + OutputField::Type(field_type) => { + schema.insert( + "type".to_owned(), + JsonValue::String(output_type_name(field_type).to_owned()), + ); + } + OutputField::Spec(spec) => { + if let Some(field_type) = spec.field_type.as_ref() { + schema.insert( + "type".to_owned(), + JsonValue::String(output_type_name(field_type).to_owned()), + ); + } + if let Some(values) = spec.enum_values.as_ref() { + schema.insert( + "enum".to_owned(), + JsonValue::Array(values.iter().cloned().map(JsonValue::String).collect()), + ); + } + if let Some(description) = spec.description.as_ref() { + schema.insert( + "description".to_owned(), + JsonValue::String(description.clone()), + ); + } + } + } + JsonValue::Object(schema) +} + +const fn output_type_name(field_type: &OutputType) -> &'static str { + match field_type { + OutputType::String => "string", + OutputType::Number => "number", + OutputType::Integer => "integer", + OutputType::Boolean => "boolean", + OutputType::Array => "array", + OutputType::Object => "object", + OutputType::Null => "null", + } +} + /// The skill's allowed tools plus the final-result tool the model calls to finish. /// Input schemas are permissive for now; resolving each tool's manifest schema is /// a refinement, not required for the loop to run governed. -fn tool_definitions<'a>(tool_names: impl Iterator) -> Vec { +fn tool_definitions<'a>( + tool_names: impl Iterator, + output: Option<&BTreeMap>, +) -> Vec { let mut tools: Vec = tool_names .map(|name| AgentToolDefinition { name: name.to_owned(), @@ -76,7 +160,7 @@ fn tool_definitions<'a>(tool_names: impl Iterator) -> Vec AgentResolver for AnthropicAgentResolver = tools.iter().map(|tool| tool.name.as_str()).collect(); assert!( names == ["pay", "read", FINAL_RESULT_TOOL], @@ -181,6 +268,44 @@ mod tests { ); } + #[test] + fn final_result_schema_uses_declared_outputs() { + let outputs = BTreeMap::from([ + ("decision".to_owned(), OutputField::Type(OutputType::String)), + ("quality".to_owned(), OutputField::Type(OutputType::Object)), + ]); + let tools = tool_definitions([].into_iter(), Some(&outputs)); + let final_tool = tools + .iter() + .find(|tool| tool.name == FINAL_RESULT_TOOL) + .expect("missing final-result tool"); + + let JsonValue::Object(schema) = &final_tool.input_schema else { + panic!("final result schema should be an object"); + }; + assert_eq!( + schema.get("type"), + Some(&JsonValue::String("object".to_owned())) + ); + let JsonValue::Object(properties) = schema.get("properties").expect("missing properties") + else { + panic!("properties should be an object"); + }; + assert!(properties.contains_key("decision")); + assert!(properties.contains_key("quality")); + assert_eq!( + schema.get("required"), + Some(&JsonValue::Array(vec![ + JsonValue::String("decision".to_owned()), + JsonValue::String("quality".to_owned()), + ])) + ); + assert_eq!( + schema.get("additionalProperties"), + Some(&JsonValue::Bool(false)) + ); + } + #[test] fn prompt_carries_instructions_directive_and_inputs() { let mut inputs = JsonObject::new(); diff --git a/crates/runx-runtime/src/execution/runner/steps/output.rs b/crates/runx-runtime/src/execution/runner/steps/output.rs index 85d40e23c..2d22187cc 100644 --- a/crates/runx-runtime/src/execution/runner/steps/output.rs +++ b/crates/runx-runtime/src/execution/runner/steps/output.rs @@ -46,14 +46,13 @@ fn expose_declared_run_outputs( let Some(JsonValue::Object(declared_outputs)) = run.get("outputs") else { return Ok(()); }; - if claim.is_empty() { - return Ok(()); - } - for name in declared_outputs.keys() { reject_reserved_step_output_name(step, name, "declared run output")?; let Some(value) = declared_claim_value(claim, name) else { - continue; + return Err(RuntimeError::InvalidRunStep { + step_id: step.id.clone(), + reason: format!("declared run output {name:?} was not returned by the step"), + }); }; outputs.insert(name.clone(), value); } From d6063d12820722028e8981aa7e1d97547d65b36e Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 20:08:27 +1000 Subject: [PATCH 21/64] fix(cli): diagnose partial agent config --- crates/runx-cli/src/doctor.rs | 164 +++++++++++++++++++++++++++++++++- 1 file changed, 162 insertions(+), 2 deletions(-) diff --git a/crates/runx-cli/src/doctor.rs b/crates/runx-cli/src/doctor.rs index 53b66af42..86623b777 100644 --- a/crates/runx-cli/src/doctor.rs +++ b/crates/runx-cli/src/doctor.rs @@ -16,7 +16,8 @@ use runx_pay::state::{ use runx_runtime::{ PROVIDER_PERMISSION_GRANT_ID_ENV, PROVIDER_PERMISSION_GRANTED_SCOPES_ENV, RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64_ENV, RUNX_RECEIPT_SIGN_ISSUER_TYPE_ENV, - RUNX_RECEIPT_SIGN_KID_ENV, RuntimeError, default_doctor_options, run_doctor, + RUNX_RECEIPT_SIGN_KID_ENV, RuntimeError, default_doctor_options, load_runx_config_file, + resolve_runx_home_dir, run_doctor, }; use crate::history::{ @@ -76,7 +77,18 @@ fn run_doctor_command( } let root = resolve_doctor_root(plan, env, cwd); - let report = run_doctor(&root, &default_doctor_options())?; + let mut report = run_doctor(&root, &default_doctor_options())?; + report + .diagnostics + .push(managed_agent_config_diagnostic(env, cwd)); + report.summary = summary(&report.diagnostics); + if report + .diagnostics + .iter() + .any(|diagnostic| diagnostic.severity == DoctorDiagnosticSeverity::Error) + { + report.status = DoctorStatus::Failure; + } let exit_code = match report.status { DoctorStatus::Success => 0, DoctorStatus::Failure => 1, @@ -89,6 +101,154 @@ fn run_doctor_command( Ok(DoctorCliOutput { stdout, exit_code }) } +fn managed_agent_config_diagnostic(env: &BTreeMap, cwd: &Path) -> DoctorDiagnostic { + let config_dir = resolve_runx_home_dir(env, cwd); + let config_path = config_dir.join("config.json"); + let config = load_runx_config_file(&config_path); + let mut evidence = JsonObject::new(); + evidence.insert( + "config_path".to_owned(), + JsonValue::String(config_path.display().to_string()), + ); + + let (config_provider, config_model, config_key_ref, config_error) = match config { + Ok(config) => ( + config + .agent + .as_ref() + .and_then(|agent| agent.provider.as_deref()) + .map(str::to_owned), + config + .agent + .as_ref() + .and_then(|agent| agent.model.as_deref()) + .map(str::to_owned), + config + .agent + .as_ref() + .and_then(|agent| agent.api_key_ref.as_deref()) + .map(str::to_owned), + None, + ), + Err(error) => (None, None, None, Some(error.to_string())), + }; + + let provider = first_non_empty([ + env.get("RUNX_AGENT_PROVIDER").map(String::as_str), + config_provider.as_deref(), + ]); + let model = first_non_empty([ + env.get("RUNX_AGENT_MODEL").map(String::as_str), + config_model.as_deref(), + ]); + let provider_key_env = provider.and_then(provider_api_key_env); + let api_key_configured = env_contains_non_empty(env, "RUNX_AGENT_API_KEY") + || provider_key_env.is_some_and(|name| env_contains_non_empty(env, name)) + || config_key_ref + .as_deref() + .is_some_and(|value| !value.trim().is_empty()); + + evidence.insert( + "provider_set".to_owned(), + JsonValue::Bool(provider.is_some()), + ); + evidence.insert("model_set".to_owned(), JsonValue::Bool(model.is_some())); + evidence.insert( + "api_key_set".to_owned(), + JsonValue::Bool(api_key_configured), + ); + if let Some(provider) = provider { + evidence.insert( + "provider".to_owned(), + JsonValue::String(provider.to_owned()), + ); + } + if let Some(model) = model { + evidence.insert("model".to_owned(), JsonValue::String(model.to_owned())); + } + if let Some(name) = provider_key_env { + evidence.insert( + "provider_api_key_env".to_owned(), + JsonValue::String(name.to_owned()), + ); + } + if let Some(error) = config_error.as_ref() { + evidence.insert("config_error".to_owned(), JsonValue::String(error.clone())); + } + + let complete = provider.is_some() && model.is_some() && api_key_configured; + let partial = !complete + && (provider.is_some() || model.is_some() || api_key_configured || config_error.is_some()); + let severity = if partial { + DoctorDiagnosticSeverity::Warning + } else { + DoctorDiagnosticSeverity::Info + }; + let message = if let Some(error) = config_error { + format!("Managed-agent config could not be read: {error}.") + } else if complete { + "Managed-agent config is complete; agent-task runners can execute in-process.".to_owned() + } else if partial { + "Managed-agent config is partial; set provider, model, and API key or unset the partial values. Otherwise agent-task runners may yield to the host or fail later.".to_owned() + } else { + "Managed-agent config is not set; agent-task runners will use host-driven resolution unless a provider is configured.".to_owned() + }; + + DoctorDiagnostic { + id: "runx.agent.config".to_owned(), + instance_id: "runx:doctor:runx.agent.config".to_owned(), + severity, + title: "Managed-agent config".to_owned(), + message, + target: object([ + ("kind", string_value("config")), + ("ref", string_value("runx.agent.config")), + ]), + location: DoctorLocation { + path: "runx config".to_owned(), + json_pointer: Some("/agent".to_owned()), + }, + evidence: Some(evidence), + repairs: if partial { + vec![DoctorRepair { + id: "runx.agent.config.configure".to_owned(), + kind: DoctorRepairKind::Manual, + confidence: DoctorRepairConfidence::High, + risk: DoctorRepairRisk::Low, + path: Some("runx config".to_owned()), + json_pointer: Some("/agent".to_owned()), + contents: Some( + "Set agent.provider, agent.model, and agent.api_key, or unset partial managed-agent config." + .to_owned(), + ), + patch: None, + command: Some( + "runx config set agent.provider anthropic && runx config set agent.model && runx config set agent.api_key ".to_owned(), + ), + requires_human_review: false, + }] + } else { + Vec::new() + }, + } +} + +fn first_non_empty<'a>(values: impl IntoIterator>) -> Option<&'a str> { + values + .into_iter() + .flatten() + .map(str::trim) + .find(|value| !value.is_empty()) +} + +fn provider_api_key_env(provider: &str) -> Option<&'static str> { + match provider.trim().to_ascii_lowercase().as_str() { + "anthropic" => Some("ANTHROPIC_API_KEY"), + "openai" => Some("OPENAI_API_KEY"), + _ => None, + } +} + fn run_registry_doctor(env: &BTreeMap, cwd: &Path) -> DoctorReport { let target = registry::resolve_registry_target(®istry_probe_plan(), env, cwd); let diagnostics = vec![ From d765cafe46776c711a19cb4b3b6d0ed860b50311 Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 20:10:34 +1000 Subject: [PATCH 22/64] chore(cli): link dev native binary --- package.json | 3 ++ scripts/link-dev-native-cli.mjs | 74 +++++++++++++++++++++++++++++++++ 2 files changed, 77 insertions(+) create mode 100644 scripts/link-dev-native-cli.mjs diff --git a/package.json b/package.json index 21d79ec90..c3eb94b32 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,9 @@ "cli:link-global": "pnpm build && node scripts/link-global-cli.mjs", "cli:unlink-global": "node scripts/link-global-cli.mjs --unlink", "cli:check-global": "node scripts/link-global-cli.mjs --check", + "cli:link-dev-native": "cargo build --manifest-path crates/Cargo.toml -p runx-cli && node scripts/link-dev-native-cli.mjs", + "cli:check-dev-native": "node scripts/link-dev-native-cli.mjs --check", + "cli:unlink-dev-native": "node scripts/link-dev-native-cli.mjs --unlink", "dogfood:native-core": "sh scripts/dogfood-native-core.sh", "dogfood:core-skills": "node scripts/dogfood-core-skills.mjs", "dogfood:github-issue-to-pr": "node scripts/dogfood-github-issue-to-pr.mjs", diff --git a/scripts/link-dev-native-cli.mjs b/scripts/link-dev-native-cli.mjs new file mode 100644 index 000000000..2a8d77635 --- /dev/null +++ b/scripts/link-dev-native-cli.mjs @@ -0,0 +1,74 @@ +import { execFileSync } from "node:child_process"; +import { access, lstat, mkdir, readlink, realpath, rm, symlink } from "node:fs/promises"; +import { constants } from "node:fs"; +import path from "node:path"; +import { fileURLToPath } from "node:url"; + +const workspaceRoot = path.resolve(fileURLToPath(new URL("..", import.meta.url))); +const nativeBinary = path.join(workspaceRoot, "crates", "target", "debug", process.platform === "win32" ? "runx.exe" : "runx"); +const globalPrefix = execFileSync("npm", ["prefix", "-g"], { + cwd: workspaceRoot, + encoding: "utf8", + env: Object.fromEntries( + Object.entries(process.env).filter(([key]) => !key.startsWith("npm_config_") && !key.startsWith("npm_package_")), + ), +}).trim(); + +if (!path.isAbsolute(globalPrefix)) { + throw new Error(`npm prefix -g returned a non-absolute path: ${globalPrefix}`); +} + +if (globalPrefix === workspaceRoot || globalPrefix.startsWith(`${workspaceRoot}${path.sep}`)) { + throw new Error(`refusing to link into workspace-local prefix ${globalPrefix}; check your global npm prefix configuration`); +} + +const globalBinDir = path.join(globalPrefix, "bin"); +const globalBinLink = path.join(globalBinDir, process.platform === "win32" ? "runx.exe" : "runx"); + +const mode = process.argv.includes("--unlink") ? "unlink" : process.argv.includes("--check") ? "check" : "link"; + +if (mode === "unlink") { + await rm(globalBinLink, { force: true }); + process.stdout.write(["runx dev-native link removed", `binary ${globalBinLink}`].join("\n") + "\n"); + process.exit(0); +} + +if (mode === "check") { + process.stdout.write( + ["runx dev-native link status", `prefix ${globalPrefix}`, `binary ${await describeLink(globalBinLink)}`].join( + "\n", + ) + "\n", + ); + process.exit(0); +} + +await access(nativeBinary, constants.X_OK).catch(() => { + throw new Error(`native debug binary is not executable: ${nativeBinary}\nRun: cargo build --manifest-path crates/Cargo.toml -p runx-cli`); +}); +await mkdir(globalBinDir, { recursive: true }); +await rm(globalBinLink, { recursive: true, force: true }); +await symlink(nativeBinary, globalBinLink, "file"); + +process.stdout.write( + [ + "runx dev-native link updated", + `prefix ${globalPrefix}`, + `binary ${globalBinLink} -> ${await realpath(globalBinLink)}`, + "", + "This links `runx` directly to crates/target/debug/runx for workspace dogfood. Re-run after clean builds if the target directory changes.", + ].join("\n") + "\n", +); + +async function describeLink(filePath) { + try { + const stats = await lstat(filePath); + if (stats.isSymbolicLink()) { + const target = await readlink(filePath); + const resolved = await realpath(filePath); + return `${filePath} -> ${target} (${resolved})`; + } + return `${filePath} exists but is not a symlink`; + } catch { + return `${filePath} missing`; + } +} From 53c375cb1eb5f747ad13c68ecb7e84e445c1c78c Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 20:23:25 +1000 Subject: [PATCH 23/64] fix(cli): add credential profiles --- crates/runx-cli/src/skill/parser.rs | 311 ++++++++++++++++++++--- crates/runx-parser/src/graph/step.rs | 65 ++++- crates/runx-parser/src/graph/validate.rs | 51 ++++ docs/skill-to-graph.md | 37 +++ 4 files changed, 421 insertions(+), 43 deletions(-) diff --git a/crates/runx-cli/src/skill/parser.rs b/crates/runx-cli/src/skill/parser.rs index 59d98302c..c3a01a845 100644 --- a/crates/runx-cli/src/skill/parser.rs +++ b/crates/runx-cli/src/skill/parser.rs @@ -1,10 +1,13 @@ use std::collections::BTreeMap; use std::env; use std::ffi::OsString; +use std::fs; use std::path::{Path, PathBuf}; use runx_contracts::JsonValue; use runx_runtime::orchestrator::LocalCredentialDescriptor; +use runx_runtime::{resolve_path_from_user_input, resolve_runx_home_dir}; +use serde::Deserialize; use super::SkillPlan; use super::inputs::{parse_direct_input_arg, parse_input_arg}; @@ -18,7 +21,9 @@ pub fn parse_skill_plan(args: &[OsString]) -> Result { index += 1; } - let local_credential = finalize_local_credential(&state)?; + let env = env::vars().collect(); + let cwd = env::current_dir().unwrap_or_else(|_| PathBuf::from(".")); + let local_credential = finalize_local_credential(&state, &env, &cwd)?; let Some(skill_path) = state.skill_path.as_ref() else { return Err("runx skill requires a skill package path".to_owned()); @@ -58,6 +63,7 @@ struct SkillParseState { json: bool, inputs: BTreeMap, credential: Option, + credential_profile: Option, secret_env: Option<(String, String)>, } @@ -68,45 +74,71 @@ struct CredentialBinding { scopes: Vec, } +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct CredentialProfilesFile { + profiles: BTreeMap, +} + +#[derive(Deserialize)] +#[serde(deny_unknown_fields)] +struct CredentialProfile { + credential: String, + secret_env: String, +} + fn parse_credential_binding(value: &str) -> Result { - let mut parts = value.splitn(4, ':'); - let provider = parts - .next() - .filter(|part| !part.is_empty()) - .ok_or_else(|| { - "runx skill --credential requires ::".to_owned() - })?; - let auth_mode = parts - .next() - .filter(|part| !part.is_empty()) - .ok_or_else(|| { - "runx skill --credential requires ::".to_owned() - })?; - let material_ref = parts - .next() - .filter(|part| !part.is_empty()) - .ok_or_else(|| { - "runx skill --credential requires ::".to_owned() - })?; - let scopes = parts - .next() - .map(|raw| { - raw.split(',') - .map(str::trim) - .filter(|scope| !scope.is_empty()) - .map(ToOwned::to_owned) - .collect() - }) - .unwrap_or_default(); + let (provider, rest) = value.split_once(':').ok_or_else(credential_usage_error)?; + let provider = non_empty_credential_part(provider)?; + let (auth_mode, rest) = rest.split_once(':').ok_or_else(credential_usage_error)?; + let auth_mode = non_empty_credential_part(auth_mode)?; + let (material_ref, scopes) = split_material_ref_and_scopes(rest)?; Ok(CredentialBinding { provider: provider.to_owned(), auth_mode: auth_mode.to_owned(), - material_ref: material_ref.to_owned(), + material_ref, scopes, }) } +fn split_material_ref_and_scopes(value: &str) -> Result<(String, Vec), String> { + let value = non_empty_credential_part(value)?; + let Some(index) = value.rfind(':') else { + return Ok((value.to_owned(), Vec::new())); + }; + if value[index..].starts_with("://") { + return Ok((value.to_owned(), Vec::new())); + } + let material_ref = non_empty_credential_part(&value[..index])?.to_owned(); + let scopes = value[index + 1..] + .split(',') + .map(str::trim) + .filter(|scope| !scope.is_empty()) + .map(ToOwned::to_owned) + .collect(); + Ok((material_ref, scopes)) +} + +fn non_empty_credential_part(value: &str) -> Result<&str, String> { + let value = value.trim(); + if value.is_empty() { + return Err(credential_usage_error()); + } + Ok(value) +} + +fn credential_usage_error() -> String { + "runx skill --credential requires ::".to_owned() +} + fn parse_secret_env(value: &str) -> Result<(String, String), String> { + parse_secret_env_from(value, |name| env::var(name).ok()) +} + +fn parse_secret_env_from( + value: &str, + lookup: impl Fn(&str) -> Option, +) -> Result<(String, String), String> { if value.contains('=') { return Err( "runx skill --secret-env accepts an environment variable name, not an inline value" @@ -117,8 +149,8 @@ fn parse_secret_env(value: &str) -> Result<(String, String), String> { if name.is_empty() { return Err("runx skill --secret-env requires a non-empty env var name".to_owned()); } - let secret = env::var(name) - .map_err(|_| format!("runx skill --secret-env env var '{name}' is not set"))?; + let secret = lookup(name) + .ok_or_else(|| format!("runx skill --secret-env env var '{name}' is not set"))?; if secret.trim().is_empty() { return Err("runx skill --secret-env requires a non-empty secret value".to_owned()); } @@ -127,7 +159,21 @@ fn parse_secret_env(value: &str) -> Result<(String, String), String> { fn finalize_local_credential( state: &SkillParseState, + env: &BTreeMap, + cwd: &Path, ) -> Result, String> { + if let Some(profile) = state.credential_profile.as_ref() { + if state.credential.is_some() || state.secret_env.is_some() { + return Err( + "runx skill --credential-profile cannot be combined with --credential or --secret-env" + .to_owned(), + ); + } + let profile = load_credential_profile(profile, env, cwd)?; + let credential = parse_credential_binding(&profile.credential)?; + let secret_env = parse_secret_env_from(&profile.secret_env, |name| env.get(name).cloned())?; + return Ok(Some(local_credential_descriptor(&credential, &secret_env))); + } match (&state.credential, &state.secret_env) { (None, None) => Ok(None), (Some(_), None) => { @@ -138,16 +184,100 @@ fn finalize_local_credential( "runx skill --secret-env requires --credential ::" .to_owned() })?; - Ok(Some(LocalCredentialDescriptor { - provider: binding.provider.clone(), - auth_mode: binding.auth_mode.clone(), - env_var: env_var.clone(), - material_ref: binding.material_ref.clone(), - scopes: binding.scopes.clone(), - secret: secret.clone(), - })) + Ok(Some(local_credential_descriptor( + binding, + &(env_var.clone(), secret.clone()), + ))) + } + } +} + +fn local_credential_descriptor( + binding: &CredentialBinding, + secret_env: &(String, String), +) -> LocalCredentialDescriptor { + LocalCredentialDescriptor { + provider: binding.provider.clone(), + auth_mode: binding.auth_mode.clone(), + env_var: secret_env.0.clone(), + material_ref: binding.material_ref.clone(), + scopes: binding.scopes.clone(), + secret: secret_env.1.clone(), + } +} + +fn load_credential_profile( + profile_name: &str, + env: &BTreeMap, + cwd: &Path, +) -> Result { + let profile_name = profile_name.trim(); + if profile_name.is_empty() { + return Err("runx skill --credential-profile requires a non-empty name".to_owned()); + } + let paths = credential_profile_paths(env, cwd); + for path in &paths { + let contents = match fs::read_to_string(path) { + Ok(contents) => contents, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue, + Err(error) => { + return Err(format!( + "runx skill could not read credential profile file {}: {error}", + path.display() + )); + } + }; + let parsed: CredentialProfilesFile = serde_json::from_str(&contents).map_err(|error| { + format!( + "runx skill credential profile file {} is invalid JSON: {error}", + path.display() + ) + })?; + if let Some(profile) = parsed.profiles.into_iter().find_map(|(name, profile)| { + if name == profile_name { + Some(profile) + } else { + None + } + }) { + return Ok(profile); } } + let searched = paths + .iter() + .map(|path| path.display().to_string()) + .collect::>() + .join(", "); + Err(format!( + "runx skill credential profile '{profile_name}' was not found; searched {searched}" + )) +} + +fn credential_profile_paths(env: &BTreeMap, cwd: &Path) -> Vec { + if let Some(path) = env + .get("RUNX_CREDENTIAL_PROFILES") + .filter(|value| !value.trim().is_empty()) + { + return vec![resolve_path_from_user_input(path, env, cwd, true)]; + } + let mut paths = Vec::new(); + if let Some(project_dir) = env + .get("RUNX_PROJECT_DIR") + .filter(|value| !value.trim().is_empty()) + .map(|value| resolve_path_from_user_input(value, env, cwd, true)) + .or_else(|| nearest_project_runx_dir(cwd)) + { + paths.push(project_dir.join("credentials.json")); + } + paths.push(resolve_runx_home_dir(env, cwd).join("credentials.json")); + paths.dedup(); + paths +} + +fn nearest_project_runx_dir(cwd: &Path) -> Option { + cwd.ancestors() + .map(|ancestor| ancestor.join(".runx")) + .find(|candidate| candidate.is_dir()) } fn reject_resolver_flags_for_skill_management_action( @@ -261,6 +391,19 @@ fn parse_skill_arg( index += 1; state.credential = Some(parse_credential_binding(&string_arg(args, index)?)?); } + value if value.starts_with("--credential-profile=") => { + state.credential_profile = Some(non_empty_flag_value( + "--credential-profile", + value.trim_start_matches("--credential-profile="), + )?); + } + "--credential-profile" => { + index += 1; + state.credential_profile = Some(non_empty_flag_value( + "--credential-profile", + &string_arg(args, index)?, + )?); + } value if value.starts_with("--secret-env=") => { state.secret_env = Some(parse_secret_env(value.trim_start_matches("--secret-env="))?); } @@ -312,3 +455,89 @@ fn string_arg(args: &[OsString], index: usize) -> Result { .map(ToOwned::to_owned) .ok_or_else(|| "runx skill arguments must be UTF-8".to_owned()) } + +#[cfg(test)] +mod tests { + use std::fs; + use std::time::{SystemTime, UNIX_EPOCH}; + + use super::{SkillParseState, finalize_local_credential}; + + #[test] + fn credential_profile_resolves_project_descriptor_and_env_secret() -> Result<(), String> { + let root = unique_temp_dir("runx-credential-profile")?; + let runx_dir = root.join(".runx"); + fs::create_dir_all(&runx_dir).map_err(|error| error.to_string())?; + fs::write( + runx_dir.join("credentials.json"), + r#"{ + "profiles": { + "frantic": { + "credential": "frantic:bearer:local://frantic/internal:frantic.review", + "secret_env": "INTERNAL_SYNC_SECRET" + } + } +} +"#, + ) + .map_err(|error| error.to_string())?; + + let mut state = SkillParseState::default(); + state.credential_profile = Some("frantic".to_owned()); + let env = [ + ( + "RUNX_PROJECT_DIR".to_owned(), + runx_dir.to_string_lossy().into_owned(), + ), + ("INTERNAL_SYNC_SECRET".to_owned(), "secret-value".to_owned()), + ] + .into_iter() + .collect(); + let credential = finalize_local_credential(&state, &env, &root)? + .ok_or_else(|| "credential profile did not resolve".to_owned())?; + + assert_eq!(credential.provider, "frantic"); + assert_eq!(credential.auth_mode, "bearer"); + assert_eq!(credential.material_ref, "local://frantic/internal"); + assert_eq!(credential.env_var, "INTERNAL_SYNC_SECRET"); + assert_eq!(credential.secret, "secret-value"); + assert_eq!(credential.scopes, vec!["frantic.review"]); + + fs::remove_dir_all(root).map_err(|error| error.to_string())?; + Ok(()) + } + + #[test] + fn credential_profile_rejects_manual_credential_flags() -> Result<(), String> { + let mut state = SkillParseState::default(); + state.credential_profile = Some("frantic".to_owned()); + state.secret_env = Some(("TOKEN".to_owned(), "secret".to_owned())); + let error = finalize_local_credential(&state, &Default::default(), &std::env::temp_dir()) + .err() + .ok_or_else(|| "profile unexpectedly combined with manual flags".to_owned())?; + assert!(error.contains("cannot be combined")); + Ok(()) + } + + #[test] + fn credential_parser_keeps_uri_material_ref_intact() -> Result<(), String> { + let binding = super::parse_credential_binding( + "frantic:bearer:local://frantic/internal:frantic.review,frantic.write", + )?; + assert_eq!(binding.provider, "frantic"); + assert_eq!(binding.auth_mode, "bearer"); + assert_eq!(binding.material_ref, "local://frantic/internal"); + assert_eq!(binding.scopes, vec!["frantic.review", "frantic.write"]); + Ok(()) + } + + fn unique_temp_dir(name: &str) -> Result { + let nanos = SystemTime::now() + .duration_since(UNIX_EPOCH) + .map_err(|error| error.to_string())? + .as_nanos(); + let path = std::env::temp_dir().join(format!("{name}-{}-{nanos}", std::process::id())); + fs::create_dir_all(&path).map_err(|error| error.to_string())?; + Ok(path) + } +} diff --git a/crates/runx-parser/src/graph/step.rs b/crates/runx-parser/src/graph/step.rs index adf7dd7fc..e58b31619 100644 --- a/crates/runx-parser/src/graph/step.rs +++ b/crates/runx-parser/src/graph/step.rs @@ -37,6 +37,10 @@ pub fn validate_step( .unwrap_or_default(); validate_context_skills(&context_skills, field, &target)?; + let inputs = + optional_object(raw_step.get("inputs"), &format!("{field}.inputs"))?.unwrap_or_default(); + reject_step_output_refs_in_inputs(&inputs, previous_step_ids, &format!("{field}.inputs"))?; + Ok(GraphStep { id, label: optional_non_empty_string(raw_step.get("label"), &format!("{field}.label"))?, @@ -49,8 +53,7 @@ pub fn validate_step( )?, artifacts: optional_object(raw_step.get("artifacts"), &format!("{field}.artifacts"))?, runner, - inputs: optional_object(raw_step.get("inputs"), &format!("{field}.inputs"))? - .unwrap_or_default(), + inputs, context_edges: context_edges(&context, previous_step_ids, field)?, context, context_skills, @@ -73,6 +76,64 @@ pub fn validate_step( }) } +fn reject_step_output_refs_in_inputs( + inputs: &JsonObject, + previous_step_ids: &BTreeSet, + field: &str, +) -> Result<(), ValidationError> { + for (key, value) in inputs { + reject_step_output_refs_in_input_value( + value, + previous_step_ids, + &format!("{field}.{key}"), + )?; + } + Ok(()) +} + +fn reject_step_output_refs_in_input_value( + value: &JsonValue, + previous_step_ids: &BTreeSet, + field: &str, +) -> Result<(), ValidationError> { + match value { + JsonValue::String(value) => { + if looks_like_previous_step_output_ref(value, previous_step_ids) { + return Err(validation_error(format!( + "{field} looks like step output reference {value:?}; move it to context if you meant to read a previous step output." + ))); + } + } + JsonValue::Object(object) => { + for (key, value) in object { + reject_step_output_refs_in_input_value( + value, + previous_step_ids, + &format!("{field}.{key}"), + )?; + } + } + JsonValue::Array(values) => { + for (index, value) in values.iter().enumerate() { + reject_step_output_refs_in_input_value( + value, + previous_step_ids, + &format!("{field}.{index}"), + )?; + } + } + _ => {} + } + Ok(()) +} + +fn looks_like_previous_step_output_ref(value: &str, previous_step_ids: &BTreeSet) -> bool { + let Some((from_step, output)) = value.split_once('.') else { + return false; + }; + !output.is_empty() && previous_step_ids.contains(from_step) +} + fn validate_when( value: Option<&JsonValue>, field: &str, diff --git a/crates/runx-parser/src/graph/validate.rs b/crates/runx-parser/src/graph/validate.rs index e6b252c2e..388386777 100644 --- a/crates/runx-parser/src/graph/validate.rs +++ b/crates/runx-parser/src/graph/validate.rs @@ -69,3 +69,54 @@ fn reject_unsupported_top_level(document: &JsonObject) -> Result<(), ValidationE } Ok(()) } + +#[cfg(test)] +mod tests { + use super::{parse_graph_yaml, validate_graph}; + + #[test] + fn inputs_reject_previous_step_output_references() -> Result<(), String> { + let raw = parse_graph_yaml( + r#" +name: bad-input-ref +steps: + - id: select + run: + type: agent-task + - id: review + run: + type: agent-task + inputs: + bounty: select.result +"#, + ) + .map_err(|error| error.to_string())?; + let error = validate_graph(raw) + .err() + .ok_or_else(|| "graph unexpectedly validated".to_owned())?; + let message = error.to_string(); + assert!(message.contains("steps.1.inputs.bounty")); + assert!(message.contains("move it to context")); + Ok(()) + } + + #[test] + fn inputs_allow_literals_that_are_not_previous_step_refs() -> Result<(), String> { + let raw = parse_graph_yaml( + r#" +name: literal-input +steps: + - id: review + run: + type: agent-task + inputs: + literal: select.result + variable: $input.claim + url: https://example.com/a.b +"#, + ) + .map_err(|error| error.to_string())?; + validate_graph(raw).map_err(|error| error.to_string())?; + Ok(()) + } +} diff --git a/docs/skill-to-graph.md b/docs/skill-to-graph.md index c0eb8fc84..0e6d9b9ea 100644 --- a/docs/skill-to-graph.md +++ b/docs/skill-to-graph.md @@ -214,3 +214,40 @@ runx skill \ `--secret-env NAME` names an environment variable to deliver as the secret; `--credential`'s final segment is the scope, which must match the tool's declared `scopes`. See `examples/byo-http-tool` and `examples/http-tool-catalog`. + +For repeated local operator runs, keep the secret in project env and put only the +non-secret descriptor in `.runx/credentials.json`: + +```json +{ + "profiles": { + "operator": { + "credential": "frantic:bearer:local://frantic/internal:frantic.review", + "secret_env": "INTERNAL_SYNC_SECRET" + } + } +} +``` + +Then run with `--credential-profile operator`. If `RUNX_CREDENTIAL_PROFILES` is +set, runx reads that JSON file instead; otherwise it checks the project +`.runx/credentials.json` and then the global runx home. The profile file never +contains the secret value. + +Use `inputs` for literals, `$input.*` values, and static configuration. Use +`context` when a step needs an earlier step's output: + +```yaml +steps: + - id: select + run: + type: agent-task + - id: review + run: + type: agent-task + context: + bounty: select.result +``` + +`inputs: { bounty: select.result }` is rejected because it looks like a step +output reference placed in the wrong field. From 6b6d4204ddf472492551bb73db964e0370d3de39 Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 20:44:26 +1000 Subject: [PATCH 24/64] feat(cli): add common short aliases --- crates/runx-cli/src/config.rs | 22 ++++++--- crates/runx-cli/src/launcher.rs | 68 ++++++++++++++++---------- crates/runx-cli/src/login.rs | 8 ++-- crates/runx-cli/src/login_tests.rs | 6 +-- crates/runx-cli/src/publish.rs | 8 ++-- crates/runx-cli/src/publish_tests.rs | 7 +-- crates/runx-cli/src/skill/parser.rs | 72 +++++++++++++++++++++++++++- crates/runx-cli/src/verify.rs | 2 +- crates/runx-cli/tests/launcher.rs | 28 +++++++---- docs/skill-to-graph.md | 8 ++-- 10 files changed, 169 insertions(+), 60 deletions(-) diff --git a/crates/runx-cli/src/config.rs b/crates/runx-cli/src/config.rs index 7d0325ff2..3eb754522 100644 --- a/crates/runx-cli/src/config.rs +++ b/crates/runx-cli/src/config.rs @@ -102,7 +102,7 @@ pub fn parse_config_plan(args: &[OsString]) -> Result { let mut index = 2; while index < args.len() { let token = os_arg(args, index, "config")?; - if !token.starts_with("--") { + if !token.starts_with('-') { positionals.push(token.to_owned()); index += 1; continue; @@ -110,7 +110,7 @@ pub fn parse_config_plan(args: &[OsString]) -> Result { let (flag, inline_value) = split_flag(token); match flag { - "--json" => { + "--json" | "-j" => { if inline_value.is_some() { return Err("--json does not take a value".to_owned()); } @@ -139,7 +139,7 @@ pub fn parse_config_plan(args: &[OsString]) -> Result { }; Ok(ConfigPlan { action, - key: Some(key.clone()), + key: Some(normalize_config_key(key).to_owned()), value: None, json, }) @@ -153,7 +153,7 @@ pub fn parse_config_plan(args: &[OsString]) -> Result { } Ok(ConfigPlan { action, - key: Some(key.clone()), + key: Some(normalize_config_key(key).to_owned()), value: Some(values.join(" ")), json, }) @@ -161,6 +161,16 @@ pub fn parse_config_plan(args: &[OsString]) -> Result { } } +fn normalize_config_key(key: &str) -> &str { + match key { + "provider" => "agent.provider", + "model" => "agent.model", + "api-key" | "agent-key" => "agent.api_key", + "public-token" => "public.api_token", + _ => key, + } +} + pub fn run_config_command( plan: &ConfigPlan, env: &BTreeMap, @@ -305,10 +315,10 @@ mod tests { parse_config_plan(&[ "config".into(), "set".into(), - "agent.model".into(), + "model".into(), "gpt".into(), "test".into(), - "--json".into(), + "-j".into(), ]), Ok(ConfigPlan { action: ConfigAction::Set, diff --git a/crates/runx-cli/src/launcher.rs b/crates/runx-cli/src/launcher.rs index 54dc4b76d..f735e59ad 100644 --- a/crates/runx-cli/src/launcher.rs +++ b/crates/runx-cli/src/launcher.rs @@ -322,13 +322,13 @@ Usage: Commands: runx new [--directory dir] [--json] runx init [-g|--global] [--prefetch official] [--json] - runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [--json] + runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [-j|--json] runx history [query] [--skill s] [--status s] [--source s] [--actor a] [--artifact-type t] [--since iso] [--until iso] [--receipt-dir dir] [--json] - runx list [tools|skills|graphs|packets|overlays] [--ok-only|--invalid-only] [--json] - runx login [--provider github|google|gitlab] [--for default|publish] [--api-base-url url] [--allow-local-api] [--json] - runx config set|get|list [agent.provider|agent.model|agent.api_key|public.api_token] [value] [--json] + runx list [tools|skills|graphs|packets|overlays] [--ok-only|--invalid-only] [-j|--json] + runx login [--provider github|google|gitlab] [--for default|publish] [--api-url url] [--local-api] [-j|--json] + runx config set|get|list [provider|model|api-key|public-token] [value] [-j|--json] runx policy inspect|lint [--json] - runx publish [--api-base-url url] [--token token] [--allow-local-api] [--json] + runx publish [--api-url url] [--token token] [--local-api] [-j|--json] runx kernel eval --input --json runx payment admission issue --input --json runx parser eval --input --json @@ -336,9 +336,9 @@ Commands: runx dev [root] [--lane lane] [--json] runx export [skill-ref...] [--project] [--json] runx mcp serve [--receipt-dir dir] [--http-listen [addr]] [--http-allow-non-loopback] - runx skill [--registry url|path] [--digest sha256] [--input key=value] [--runner name] [--flag value] [--receipt-dir dir] [--run-id id --answers file] [--json] + runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [-R dir] [--run-id id --answers file] runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--installation-id id] [--api-base-url url] [--json] - runx harness [--receipt-dir dir] [--json] + runx harness [-R dir] [-j|--json] runx tool build |--all [--json] runx tool search [--source source] [--json] runx tool inspect [--source source] [--json] @@ -373,13 +373,15 @@ pub fn publish_help_text() -> String { runx publish Usage: - runx publish [--api-base-url url] [--token token] [--allow-local-api] [--json] + runx publish [--api-url url] [--token token] [--local-api] [-j|--json] Options: - --api-base-url url Public API base URL (default: RUNX_PUBLIC_API_BASE_URL or https://api.runx.ai) + --api-url url Public API base URL (default: RUNX_PUBLIC_API_BASE_URL or https://api.runx.ai) + --api-base-url url Alias for --api-url --token token Public API token (default: RUNX_PUBLIC_API_TOKEN or runx login) - --allow-local-api Allow loopback/private public API URLs for local dogfood only - --json Print the raw notary response as JSON + --local-api Allow loopback/private public API URLs for local dogfood only + --allow-local-api Alias for --local-api + -j, --json Print the raw notary response as JSON " .to_owned() } @@ -389,14 +391,14 @@ pub fn verify_help_text() -> String { runx verify Usage: - runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [--json] + runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [-j|--json] Options: --receipt-dir dir --receipt --notary --notary-key trusted.pem - --json + -j, --json " .to_owned() } @@ -406,18 +408,22 @@ pub fn skill_help_text() -> String { runx skill Usage: - runx skill [--registry url|path] [--digest sha256] [--input key=value] [--runner name] [--flag value] [--receipt-dir dir] [--run-id id --answers file] [--json] + runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [-R dir] [--run-id id --answers file] Options: + -p, --profile name Use a local credential profile from .runx/credentials.json + -i, --input key=value Set a structured input; repeat for multiple inputs + -R, --receipts dir Write receipts under dir + --receipt-dir dir Alias for --receipts + -j, --json Print machine-readable output + --runner name Select a named runner from X.yaml --registry url|path --digest sha256 - --runner name - --input key=value --flag value - --receipt-dir dir + --credential descriptor One-shot local credential descriptor + --secret-env NAME Env var holding the one-shot credential secret --run-id id --answers file - --json " .to_owned() } @@ -494,7 +500,7 @@ fn native_harness_plan(args: &[OsString]) -> LauncherAction { return LauncherAction::Error("harness arguments must be UTF-8".to_owned()); }; - if !token.starts_with("--") { + if !token.starts_with('-') { fixture_paths.push(args[index].clone()); index += 1; continue; @@ -502,13 +508,13 @@ fn native_harness_plan(args: &[OsString]) -> LauncherAction { let (flag, inline_value) = split_flag(token); match flag { - "--json" => { + "--json" | "-j" => { if inline_value.is_some() { return LauncherAction::Error("--json does not take a value".to_owned()); } index += 1; } - "--receipt-dir" => match inline_value { + "--receipt-dir" | "--receipts" => match inline_value { Some(value) => { receipt_dir = Some(OsString::from(value)); index += 1; @@ -523,6 +529,18 @@ fn native_harness_plan(args: &[OsString]) -> LauncherAction { index += 2; } }, + "-R" => { + if inline_value.is_some() { + return LauncherAction::Error( + "-R requires a separate directory value".to_owned(), + ); + } + let Some(value) = args.get(index + 1) else { + return LauncherAction::Error("-R requires a directory".to_owned()); + }; + receipt_dir = Some(value.clone()); + index += 2; + } _ => return LauncherAction::Error(format!("unknown harness flag {flag}")), } } @@ -850,7 +868,7 @@ fn parse_doctor_plan(args: &[OsString]) -> Result { while index < args.len() { let token = os_arg(args, index, "doctor")?; - if !token.starts_with("--") { + if !token.starts_with('-') { if matches!(token, "authority" | "registry") && path.is_none() && mode == DoctorMode::Workspace @@ -879,7 +897,7 @@ fn parse_doctor_plan(args: &[OsString]) -> Result { let (flag, inline_value) = split_flag(token); match flag { - "--json" => { + "--json" | "-j" => { if inline_value.is_some() { return Err("--json does not take a value".to_owned()); } @@ -910,7 +928,7 @@ fn parse_list_plan(args: &[OsString]) -> Result { while index < args.len() { let token = os_arg(args, index, "list")?; - if !token.starts_with("--") { + if !token.starts_with('-') { if saw_kind { return Err("runx list accepts at most one kind".to_owned()); } @@ -927,7 +945,7 @@ fn parse_list_plan(args: &[OsString]) -> Result { return Err(format!("{flag} does not take a value")); } let requested = match flag { - "--json" => { + "--json" | "-j" => { json = true; index += 1; continue; diff --git a/crates/runx-cli/src/login.rs b/crates/runx-cli/src/login.rs index b4fb233f7..21e5e0ac5 100644 --- a/crates/runx-cli/src/login.rs +++ b/crates/runx-cli/src/login.rs @@ -179,19 +179,19 @@ pub fn parse_login_plan(args: &[OsString]) -> Result { let mut index = 1; while index < args.len() { let arg = os_arg(args, index, "login")?; - if !arg.starts_with("--") { + if !arg.starts_with('-') { return Err(format!("unexpected login argument {arg}")); } let (flag, inline_value) = split_flag(arg); match flag { - "--json" => { + "--json" | "-j" => { if inline_value.is_some() { return Err("--json does not take a value".to_owned()); } json = true; index += 1; } - "--api-base-url" | "--apiBaseUrl" => { + "--api-base-url" | "--api-url" | "--apiBaseUrl" => { let (value, next_index) = flag_value(args, index, flag, inline_value, "login")?; api_base_url = Some(value); index = next_index; @@ -206,7 +206,7 @@ pub fn parse_login_plan(args: &[OsString]) -> Result { purpose = Some(value); index = next_index; } - "--allow-local-api" | "--allowLocalApi" => { + "--allow-local-api" | "--local-api" | "--allowLocalApi" => { if inline_value.is_some() { return Err("--allow-local-api does not take a value".to_owned()); } diff --git a/crates/runx-cli/src/login_tests.rs b/crates/runx-cli/src/login_tests.rs index 602d59e5f..98e49e687 100644 --- a/crates/runx-cli/src/login_tests.rs +++ b/crates/runx-cli/src/login_tests.rs @@ -33,14 +33,14 @@ impl Transport for StubTransport { fn parses_login_plan() -> Result<(), String> { let args = vec![ OsString::from("login"), - OsString::from("--api-base-url"), + OsString::from("--api-url"), OsString::from("https://runx.test/"), OsString::from("--provider"), OsString::from("github"), OsString::from("--for"), OsString::from("publish"), - OsString::from("--allow-local-api"), - OsString::from("--json"), + OsString::from("--local-api"), + OsString::from("-j"), ]; assert_eq!( parse_login_plan(&args)?, diff --git a/crates/runx-cli/src/publish.rs b/crates/runx-cli/src/publish.rs index 20e874678..348f7f029 100644 --- a/crates/runx-cli/src/publish.rs +++ b/crates/runx-cli/src/publish.rs @@ -165,7 +165,7 @@ pub fn parse_publish_plan(args: &[OsString]) -> Result { let mut index = 1; while index < args.len() { let arg = os_arg(args, index, "publish")?; - if !arg.starts_with("--") { + if !arg.starts_with('-') { if receipt_path.is_some() { return Err(PublishCliError::ExtraReceipt.to_string()); } @@ -175,14 +175,14 @@ pub fn parse_publish_plan(args: &[OsString]) -> Result { } let (flag, inline_value) = split_flag(arg); match flag { - "--json" => { + "--json" | "-j" => { if inline_value.is_some() { return Err("--json does not take a value".to_owned()); } json = true; index += 1; } - "--api-base-url" | "--apiBaseUrl" => { + "--api-base-url" | "--api-url" | "--apiBaseUrl" => { let (value, next_index) = flag_value(args, index, flag, inline_value, "publish")?; api_base_url = Some(value); index = next_index; @@ -192,7 +192,7 @@ pub fn parse_publish_plan(args: &[OsString]) -> Result { token = Some(value); index = next_index; } - "--allow-local-api" | "--allowLocalApi" => { + "--allow-local-api" | "--local-api" | "--allowLocalApi" => { if inline_value.is_some() { return Err("--allow-local-api does not take a value".to_owned()); } diff --git a/crates/runx-cli/src/publish_tests.rs b/crates/runx-cli/src/publish_tests.rs index d8a8cb493..9fc288bc9 100644 --- a/crates/runx-cli/src/publish_tests.rs +++ b/crates/runx-cli/src/publish_tests.rs @@ -33,11 +33,12 @@ fn parses_publish_plan() -> Result<(), String> { let args = vec![ OsString::from("publish"), OsString::from("receipt.json"), - OsString::from("--api-base-url"), + OsString::from("--api-url"), OsString::from("https://runx.test/"), OsString::from("--token"), OsString::from("rxk_test"), - OsString::from("--json"), + OsString::from("--local-api"), + OsString::from("-j"), ]; let plan = parse_publish_plan(&args)?; assert_eq!( @@ -46,7 +47,7 @@ fn parses_publish_plan() -> Result<(), String> { receipt_path: PathBuf::from("receipt.json"), api_base_url: Some("https://runx.test/".to_owned()), token: Some("rxk_test".to_owned()), - allow_local_api: false, + allow_local_api: true, json: true, } ); diff --git a/crates/runx-cli/src/skill/parser.rs b/crates/runx-cli/src/skill/parser.rs index c3a01a845..290eb46a7 100644 --- a/crates/runx-cli/src/skill/parser.rs +++ b/crates/runx-cli/src/skill/parser.rs @@ -321,10 +321,24 @@ fn parse_skill_arg( value if value.starts_with("--receipt-dir=") => { state.receipt_dir = Some(PathBuf::from(value.trim_start_matches("--receipt-dir="))); } + value if value.starts_with("-R=") => { + state.receipt_dir = Some(PathBuf::from(value.trim_start_matches("-R="))); + } + value if value.starts_with("--receipts=") => { + state.receipt_dir = Some(PathBuf::from(value.trim_start_matches("--receipts="))); + } "--receipt-dir" => { index += 1; state.receipt_dir = Some(PathBuf::from(string_arg(args, index)?)); } + "--receipts" => { + index += 1; + state.receipt_dir = Some(PathBuf::from(string_arg(args, index)?)); + } + "-R" => { + index += 1; + state.receipt_dir = Some(PathBuf::from(string_arg(args, index)?)); + } value if value.starts_with("--run-id=") => { state.run_id = Some(value.trim_start_matches("--run-id=").to_owned()); } @@ -381,7 +395,16 @@ fn parse_skill_arg( &mut state.inputs, )?; } + value if value.starts_with("-i=") => { + index = parse_input_arg( + args, + index, + Some(value.trim_start_matches("-i=")), + &mut state.inputs, + )?; + } "--input" => index = parse_input_arg(args, index, None, &mut state.inputs)?, + "-i" => index = parse_input_arg(args, index, None, &mut state.inputs)?, value if value.starts_with("--credential=") => { state.credential = Some(parse_credential_binding( value.trim_start_matches("--credential="), @@ -397,6 +420,12 @@ fn parse_skill_arg( value.trim_start_matches("--credential-profile="), )?); } + value if value.starts_with("--profile=") => { + state.credential_profile = Some(non_empty_flag_value( + "--profile", + value.trim_start_matches("--profile="), + )?); + } "--credential-profile" => { index += 1; state.credential_profile = Some(non_empty_flag_value( @@ -404,6 +433,13 @@ fn parse_skill_arg( &string_arg(args, index)?, )?); } + "--profile" | "-p" => { + index += 1; + state.credential_profile = Some(non_empty_flag_value( + "--profile", + &string_arg(args, index)?, + )?); + } value if value.starts_with("--secret-env=") => { state.secret_env = Some(parse_secret_env(value.trim_start_matches("--secret-env="))?); } @@ -411,7 +447,7 @@ fn parse_skill_arg( index += 1; state.secret_env = Some(parse_secret_env(&string_arg(args, index)?)?); } - "--json" => state.json = true, + "--json" | "-j" => state.json = true, "--non-interactive" => {} value if value.starts_with("--") => { index = parse_direct_input_arg(args, index, value, &mut state.inputs)?; @@ -519,6 +555,40 @@ mod tests { Ok(()) } + #[test] + fn short_human_flags_parse_for_skill_runs() -> Result<(), String> { + let args = [ + "skill", + "-p", + "operator", + "-i", + "claim=abc", + "-R", + "receipts", + "-j", + ] + .into_iter() + .map(std::ffi::OsString::from) + .collect::>(); + let mut state = SkillParseState::default(); + let mut index = 1; + while index < args.len() { + index = super::parse_skill_arg(&args, index, &mut state)?; + index += 1; + } + assert_eq!(state.credential_profile.as_deref(), Some("operator")); + assert_eq!( + state.inputs.get("claim"), + Some(&runx_contracts::JsonValue::String("abc".to_owned())) + ); + assert_eq!( + state.receipt_dir.as_deref(), + Some(std::path::Path::new("receipts")) + ); + assert!(state.json); + Ok(()) + } + #[test] fn credential_parser_keeps_uri_material_ref_intact() -> Result<(), String> { let binding = super::parse_credential_binding( diff --git a/crates/runx-cli/src/verify.rs b/crates/runx-cli/src/verify.rs index 76d8b04bc..f977b693b 100644 --- a/crates/runx-cli/src/verify.rs +++ b/crates/runx-cli/src/verify.rs @@ -253,7 +253,7 @@ fn parse_verify_args(args: &[OsString]) -> Result parsed.json = true, + "--json" | "-j" => parsed.json = true, "--allow-local-development-signatures" => { parsed.allow_local_development_signatures = true; } diff --git a/crates/runx-cli/tests/launcher.rs b/crates/runx-cli/tests/launcher.rs index 3516f5488..1851af08b 100644 --- a/crates/runx-cli/tests/launcher.rs +++ b/crates/runx-cli/tests/launcher.rs @@ -29,11 +29,11 @@ fn top_level_help_and_version_are_native() { let help = help_text(); assert_help_line( &help, - "runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [--json]", + "runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [-j|--json]", ); assert_help_line( &help, - "runx skill [--registry url|path] [--digest sha256] [--input key=value] [--runner name] [--flag value] [--receipt-dir dir] [--run-id id --answers file] [--json]", + "runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [-R dir] [--run-id id --answers file]", ); assert_help_line( &help, @@ -42,7 +42,7 @@ fn top_level_help_and_version_are_native() { assert_help_line(&help, "runx parser eval --input --json"); assert_help_line( &help, - "runx harness [--receipt-dir dir] [--json]", + "runx harness [-R dir] [-j|--json]", ); assert_help_line(&help, "runx doctor [path|authority|registry] [--json]"); assert_help_line( @@ -51,7 +51,7 @@ fn top_level_help_and_version_are_native() { ); assert_help_line( &help, - "runx login [--provider github|google|gitlab] [--for default|publish] [--api-base-url url] [--allow-local-api] [--json]", + "runx login [--provider github|google|gitlab] [--for default|publish] [--api-url url] [--local-api] [-j|--json]", ); assert!( !help.contains("runx connect"), @@ -98,7 +98,11 @@ fn nested_skill_history_verify_and_publish_help_are_native() { assert_help_line( &skill_help_text(), - "runx skill [--registry url|path] [--digest sha256] [--input key=value] [--runner name] [--flag value] [--receipt-dir dir] [--run-id id --answers file] [--json]", + "runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [-R dir] [--run-id id --answers file]", + ); + assert_help_line( + &skill_help_text(), + "-p, --profile name Use a local credential profile from .runx/credentials.json", ); assert_help_line( &history_help_text(), @@ -106,11 +110,11 @@ fn nested_skill_history_verify_and_publish_help_are_native() { ); assert_help_line( &verify_help_text(), - "runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [--json]", + "runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [-j|--json]", ); assert_help_line( &publish_help_text(), - "runx publish [--api-base-url url] [--token token] [--allow-local-api] [--json]", + "runx publish [--api-url url] [--token token] [--local-api] [-j|--json]", ); } @@ -235,10 +239,16 @@ fn mcp_rejects_unknown_shapes_without_delegating() { #[test] fn routes_harness_to_native_runner() { assert_eq!( - plan(&["harness", "fixtures/harness/echo-skill.yaml", "--json"]), + plan(&[ + "harness", + "fixtures/harness/echo-skill.yaml", + "-R", + ".runx/receipts", + "-j" + ]), LauncherAction::RunHarness(HarnessPlan { fixture_paths: vec!["fixtures/harness/echo-skill.yaml".into()], - receipt_dir: None, + receipt_dir: Some(".runx/receipts".into()), }) ); } diff --git a/docs/skill-to-graph.md b/docs/skill-to-graph.md index 0e6d9b9ea..0d091480a 100644 --- a/docs/skill-to-graph.md +++ b/docs/skill-to-graph.md @@ -229,10 +229,10 @@ non-secret descriptor in `.runx/credentials.json`: } ``` -Then run with `--credential-profile operator`. If `RUNX_CREDENTIAL_PROFILES` is -set, runx reads that JSON file instead; otherwise it checks the project -`.runx/credentials.json` and then the global runx home. The profile file never -contains the secret value. +Then run with `-p operator` (or `--profile operator`). If +`RUNX_CREDENTIAL_PROFILES` is set, runx reads that JSON file instead; otherwise +it checks the project `.runx/credentials.json` and then the global runx home. +The profile file never contains the secret value. Use `inputs` for literals, `$input.*` values, and static configuration. Use `context` when a step needs an earlier step's output: From 819396c445aa40bf1550585e8f8e23a31e681dc9 Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 20:56:34 +1000 Subject: [PATCH 25/64] feat(skills): support portable category metadata --- README.md | 16 ++++++-- crates/runx-cli/src/official_skills.rs | 24 +++++------ crates/runx-cli/src/registry/output.rs | 28 ++++++++++++- crates/runx-parser/src/skill.rs | 26 ++++++++++++ crates/runx-parser/src/skill/types.rs | 4 ++ crates/runx-parser/tests/parser_fixtures.rs | 24 +++++++++++ crates/runx-runtime/src/registry/local.rs | 2 + .../runx-runtime/src/registry/local/build.rs | 35 +++++++++++++++- .../runx-runtime/src/registry/local/trust.rs | 10 +++++ crates/runx-runtime/src/registry/payload.rs | 4 ++ crates/runx-runtime/src/registry/types.rs | 16 ++++++++ crates/runx-runtime/src/scaffold/templates.rs | 1 + crates/runx-runtime/tests/registry.rs | 14 +++++++ docs/publishing.md | 17 +++++++- packages/cli/src/cli-parser/index.ts | 19 +++++++++ packages/cli/src/cli-registry.ts | 2 + packages/cli/src/cli-runtime-contracts.ts | 2 + packages/cli/src/native-registry.ts | 2 + packages/cli/src/official-skills.lock.json | 24 +++++------ packages/cli/src/presentation/search.ts | 6 +++ packages/cli/src/scaffold.ts | 1 + packages/cli/src/skill-refs.ts | 41 ++++++++++++++++--- skills/issue-to-pr/push-outbox/SKILL.md | 2 + skills/pr-review-note/SKILL.md | 2 + skills/review-skill/SKILL.md | 25 +++++++++++ skills/runx-operator/SKILL.md | 9 ++++ skills/skill-testing/SKILL.md | 21 ++++++++++ skills/sourcey/SKILL.md | 14 +++++++ skills/write-harness/SKILL.md | 9 ++++ 29 files changed, 362 insertions(+), 38 deletions(-) diff --git a/README.md b/README.md index 8d234eff7..bdf5a29a2 100644 --- a/README.md +++ b/README.md @@ -49,7 +49,10 @@ Full walkthrough, including production signing keys, is in [docs/getting-started ## a skill is a URL -A skill is one file: prose for the model, a typed execution profile for the runtime. +A skill starts with one portable file, `SKILL.md`: prose for the model and the +human-readable contract. When the skill needs deterministic runners, graphs, +harness cases, or governed side effects, the package also carries an execution +profile named `X.yaml`. ```yaml --- @@ -64,18 +67,25 @@ source: cwd_policy: skill-directory inputs: message: { type: string, required: true } +runx: + category: ops --- Print one message so a new contributor can verify the local runx execution path. ``` -The prose tells the agent what to do. The frontmatter tells runx what it is allowed to do. Publish it and the URL is the skill. Browse the open catalog at [runx.ai/x](https://runx.ai/x). +The prose tells the agent what to do. The execution profile tells runx how the +skill is allowed to run. `X.yaml` owns runner wiring, typed inputs/outputs, +receipt mapping, harness cases, and side-effect posture; it should not become a +strategy document, copy deck, target registry, or private state file. Publish it +and the URL is the skill. Browse the open catalog at +[runx.ai/x](https://runx.ai/x). ## the model Nine objects, one runtime. A run is a graph; every hop runs the same four steps, and authority only narrows as it descends. -- **skill**: expertise plus a typed execution profile. +- **skill**: expertise plus an optional checked-in execution profile. - **graph**: skills calling skills. runx renders the topology from the skills themselves and scopes authority at every branch, with no orchestration layer to maintain. - **bounds**: least privilege by default. Grants are explicit, and an over-scope request is refused before anything runs. - **receipt**: every act is signed and linked into one reproducible record. The artifact a CISO accepts and a developer can replay. diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index 648c99df4..e283a8e40 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -197,8 +197,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/pr-review-note", - version: "sha-dd1608925a76", - digest: "1b9f34f9e7f5355a10babbd154333db4b1b94fa16668583438166b91eec95e0a", + version: "sha-537dd9fc3c6b", + digest: "b073ec884f56c9e412d0c1039d5f28f163df0f5530eb0bee922ed4c557955c52", }, OfficialSkillLockEntry { skill_id: "runx/prior-art", @@ -242,8 +242,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/review-skill", - version: "sha-a27dde2ab9bb", - digest: "09b4a6ec017f9d75536c6db21c60667bd855a20b0b20f53054f63143cbb9d13d", + version: "sha-622805df5ff3", + digest: "6fc1b341d55e3c6be8a5f7693dfe3312654b89a14f88fe42e4ffc84a65a9cd09", }, OfficialSkillLockEntry { skill_id: "runx/run-history-analyst", @@ -252,8 +252,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/runx-operator", - version: "sha-da018df211a3", - digest: "1c8d199a5dd0812a09eb4e785bcd9bfd7af67ec0ef3227149bed1de150a47fff", + version: "sha-0fed07a0dc00", + digest: "9de1d9dffb46b6bb14872b66738d5e9b26f271c6f11595c6a685d4c30e539176", }, OfficialSkillLockEntry { skill_id: "runx/sandbox-harden", @@ -282,8 +282,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/skill-testing", - version: "sha-c31b54a981c8", - digest: "7fc86c62bd493cb374850d7e9fc4faad94adb318fc3b20947aa2d411a741cc75", + version: "sha-9113dacaa62a", + digest: "93f7a0c009e289862fcc9236effdf0ac75197e9eb042a83200720d23d01cb443", }, OfficialSkillLockEntry { skill_id: "runx/slack-notify", @@ -292,8 +292,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/sourcey", - version: "sha-d025d3a4701e", - digest: "2bdffb5206cbfc2dc619ffead5d26ad192afe0f2836093d782c7901841713006", + version: "sha-2b08f620e0fa", + digest: "4b6316c7fbb323b7d27d304deb8f11cb8f939dc31e0b74349d56f27abf618504", }, OfficialSkillLockEntry { skill_id: "runx/spend", @@ -357,8 +357,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/write-harness", - version: "sha-c989640c5604", - digest: "f4fbf60192335baff43a5d50f3702a17f96a42a25d69508f457cf0e396320528", + version: "sha-f69b01f883e0", + digest: "8fbac78e4c760a124c704ce62aa11ecb8b65b165c72a81fd2c1de163c5bb259b", }, OfficialSkillLockEntry { skill_id: "runx/x402-pay", diff --git a/crates/runx-cli/src/registry/output.rs b/crates/runx-cli/src/registry/output.rs index 02aec80d0..fbedf8374 100644 --- a/crates/runx-cli/src/registry/output.rs +++ b/crates/runx-cli/src/registry/output.rs @@ -80,10 +80,22 @@ pub(super) fn render_search( results.len() ); for result in results { + let category = result + .category + .as_ref() + .map(|category| format!(" category {category}\n")) + .or_else(|| { + result + .source_category + .as_ref() + .map(|category| format!(" source-category {category}\n")) + }) + .unwrap_or_default(); output.push_str(&format!( - " - {}@{}\n digest {}\n trust {}\n install {}\n run {}\n", + " - {}@{}\n{} digest {}\n trust {}\n install {}\n run {}\n", result.skill_id, result.version.as_deref().unwrap_or("unknown"), + category, result .digest .as_deref() @@ -102,9 +114,21 @@ pub(super) fn render_read( registry_ref: &str, skill: &runx_runtime::registry::RegistrySkillDetail, ) -> String { + let category = skill + .category + .as_ref() + .map(|category| format!(" category {category}\n")) + .or_else(|| { + skill + .source_category + .as_ref() + .map(|category| format!(" source category {category}\n")) + }) + .unwrap_or_default(); format!( - "\n registry read {registry_ref}\n source {source}\n skill {}\n version {}\n digest {}\n trust {}\n signed {}\n next {}\n\n", + "\n registry read {registry_ref}\n source {source}\n skill {}\n{} version {}\n digest {}\n trust {}\n signed {}\n next {}\n\n", skill.skill_id, + category, skill.version, digest_label(&skill.digest), trust_tier_label(&skill.trust_tier), diff --git a/crates/runx-parser/src/skill.rs b/crates/runx-parser/src/skill.rs index 11368ff81..6a1424b3b 100644 --- a/crates/runx-parser/src/skill.rs +++ b/crates/runx-parser/src/skill.rs @@ -72,10 +72,14 @@ pub fn validate_skill_with_options( .unwrap_or_else(default_agent_source); let risk = raw.frontmatter.get("risk").cloned(); let governance = validate_skill_governance(&raw, runx.as_ref(), risk.as_ref())?; + let category = validate_portable_skill_category(&raw)?; + let runx_category = validate_runx_skill_category(runx.as_ref())?; Ok(ValidatedSkill { name: FIELDS.required_string(raw.frontmatter.get("name"), "name")?, description: FIELDS.optional_string(raw.frontmatter.get("description"), "description")?, + category, + runx_category, body: raw.body.clone(), source: validate_source(&source, runx.as_ref())?, inputs: validate_inputs( @@ -98,6 +102,28 @@ pub fn validate_skill_with_options( }) } +fn validate_portable_skill_category(raw: &RawSkillIr) -> Result, ValidationError> { + Ok(normalize_optional_category(FIELDS.optional_string( + raw.frontmatter.get("category"), + "category", + )?)) +} + +fn validate_runx_skill_category( + runx: Option<&JsonObject>, +) -> Result, ValidationError> { + Ok(normalize_optional_category(FIELDS.optional_string( + field_value(runx, "category"), + "runx.category", + )?)) +} + +fn normalize_optional_category(value: Option) -> Option { + value + .map(|value| value.trim().to_owned()) + .filter(|value| !value.is_empty()) +} + fn validate_runx_metadata( value: Option<&JsonValue>, mode: ValidateSkillMode, diff --git a/crates/runx-parser/src/skill/types.rs b/crates/runx-parser/src/skill/types.rs index eabe1bb8b..c6b130ffd 100644 --- a/crates/runx-parser/src/skill/types.rs +++ b/crates/runx-parser/src/skill/types.rs @@ -300,6 +300,10 @@ pub struct ValidatedSkill { pub name: String, #[serde(skip_serializing_if = "Option::is_none")] pub description: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub category: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub runx_category: Option, pub body: String, pub source: SkillSource, pub inputs: BTreeMap, diff --git a/crates/runx-parser/tests/parser_fixtures.rs b/crates/runx-parser/tests/parser_fixtures.rs index 7d50a3dc4..fe8c8f05e 100644 --- a/crates/runx-parser/tests/parser_fixtures.rs +++ b/crates/runx-parser/tests/parser_fixtures.rs @@ -163,6 +163,30 @@ fn skill_fixtures_match_typescript() -> Result<(), String> { Ok(()) } +#[test] +fn skill_category_accepts_portable_top_level_field() -> Result<(), String> { + let skill = validate_skill(parse_skill_markdown( + "---\nname: docs-demo\ndescription: Demo skill.\ncategory: documentation\n---\n# Demo\n", + ).map_err(|error| error.to_string())?) + .map_err(|error| error.to_string())?; + + assert_eq!(skill.category.as_deref(), Some("documentation")); + assert_eq!(skill.runx_category.as_deref(), None); + Ok(()) +} + +#[test] +fn skill_category_accepts_runx_catalog_override() -> Result<(), String> { + let skill = validate_skill(parse_skill_markdown( + "---\nname: docs-demo\ndescription: Demo skill.\ncategory: documentation\nrunx:\n category: content\n---\n# Demo\n", + ).map_err(|error| error.to_string())?) + .map_err(|error| error.to_string())?; + + assert_eq!(skill.category.as_deref(), Some("documentation")); + assert_eq!(skill.runx_category.as_deref(), Some("content")); + Ok(()) +} + #[test] fn runner_manifest_fixtures_match_typescript() -> Result<(), String> { for fixture_json in RUNNER_MANIFEST_FIXTURES { diff --git a/crates/runx-runtime/src/registry/local.rs b/crates/runx-runtime/src/registry/local.rs index b55bfd577..55725fcd3 100644 --- a/crates/runx-runtime/src/registry/local.rs +++ b/crates/runx-runtime/src/registry/local.rs @@ -216,6 +216,8 @@ impl FileRegistryStore { owner: latest.owner.clone(), name: latest.name.clone(), description: latest.description.clone(), + category: latest.category.clone(), + source_category: latest.source_category.clone(), latest_version: latest.version.clone(), latest_digest: latest.digest.clone(), versions, diff --git a/crates/runx-runtime/src/registry/local/build.rs b/crates/runx-runtime/src/registry/local/build.rs index 0d1a344a3..a52f3225e 100644 --- a/crates/runx-runtime/src/registry/local/build.rs +++ b/crates/runx-runtime/src/registry/local/build.rs @@ -48,6 +48,8 @@ pub fn build_registry_skill_version( owner: defaults.owner, name: skill.name.clone(), description: skill.description.clone(), + category: skill.runx_category.clone(), + source_category: skill.category.clone(), version: defaults.version, digest, signed_manifest: None, @@ -180,6 +182,7 @@ pub(super) fn registry_tags( unique( extract_tags(skill) .into_iter() + .chain(skill.runx_category.clone()) .chain(extract_runner_tags(manifest)) .collect(), ) @@ -207,15 +210,22 @@ pub fn normalize_registry_skill_version( message: "declared without package_files".to_owned(), }); } + let markdown = required_string(payload.markdown, "registry_version.markdown")?; + let derived_categories = derive_categories_from_markdown(&markdown); + let category = payload.category.or(derived_categories.runx_category); + let source_category = payload.source_category.or(derived_categories.category); + Ok(RegistrySkillVersion { skill_id: required_string(payload.skill_id, "registry_version.skill_id")?, owner: governance.owner, name: required_string(payload.name, "registry_version.name")?, description: payload.description, + category, + source_category, version: required_string(payload.version, "registry_version.version")?, digest: required_string(payload.digest, "registry_version.digest")?, signed_manifest: payload.signed_manifest, - markdown: required_string(payload.markdown, "registry_version.markdown")?, + markdown, profile_document: payload.profile_document, profile_digest: payload.profile_digest, package_files, @@ -242,6 +252,27 @@ pub fn normalize_registry_skill_version( }) } +struct DerivedCategories { + category: Option, + runx_category: Option, +} + +fn derive_categories_from_markdown(markdown: &str) -> DerivedCategories { + let Some(skill) = parse_skill_markdown(markdown) + .ok() + .and_then(|raw| validate_skill(raw).ok()) + else { + return DerivedCategories { + category: None, + runx_category: None, + }; + }; + DerivedCategories { + category: skill.category, + runx_category: skill.runx_category, + } +} + struct NormalizedRegistryVersionGovernance { owner: String, created_at: String, @@ -336,6 +367,8 @@ pub struct RegistrySkillVersionPayload { owner: Option, name: Option, description: Option, + category: Option, + source_category: Option, version: Option, digest: Option, signed_manifest: Option, diff --git a/crates/runx-runtime/src/registry/local/trust.rs b/crates/runx-runtime/src/registry/local/trust.rs index aa078e280..063588f1c 100644 --- a/crates/runx-runtime/src/registry/local/trust.rs +++ b/crates/runx-runtime/src/registry/local/trust.rs @@ -303,6 +303,8 @@ pub(super) fn search_result_for_version( skill_id: version.skill_id.clone(), name: version.name.clone(), summary: version.description.clone(), + category: version.category.clone(), + source_category: version.source_category.clone(), owner: version.owner.clone(), version: Some(version.version.clone()), digest: Some(version.digest.clone()), @@ -339,6 +341,8 @@ pub(super) fn detail_for_version( owner: version.owner.clone(), name: version.name.clone(), description: version.description.clone(), + category: version.category.clone(), + source_category: version.source_category.clone(), version: version.version.clone(), digest: version.digest.clone(), signed_manifest: version.signed_manifest.clone(), @@ -389,6 +393,12 @@ pub(super) fn searchable_text(version: &RegistrySkillVersion) -> String { if let Some(description) = &version.description { parts.push(description.clone()); } + if let Some(category) = &version.category { + parts.push(category.clone()); + } + if let Some(source_category) = &version.source_category { + parts.push(source_category.clone()); + } parts.extend(version.runner_names.clone()); parts.extend(version.tags.clone()); normalize(&parts.join(" ")) diff --git a/crates/runx-runtime/src/registry/payload.rs b/crates/runx-runtime/src/registry/payload.rs index fd71357c9..f720ca380 100644 --- a/crates/runx-runtime/src/registry/payload.rs +++ b/crates/runx-runtime/src/registry/payload.rs @@ -26,6 +26,8 @@ pub(crate) fn parse_search( skill_id: string_field(skill, "skill_id", route, &path)?, name: string_field(skill, "name", route, &path)?, summary: optional_string_field(skill, "description", route, &path)?, + category: optional_string_field(skill, "category", route, &path)?, + source_category: optional_string_field(skill, "source_category", route, &path)?, owner: string_field(skill, "owner", route, &path)?, version: optional_string_field(skill, "version", route, &path)?, digest: optional_string_field(skill, "digest", route, &path)?, @@ -64,6 +66,8 @@ pub(crate) fn parse_read( owner: string_field(skill, "owner", route, "$.skill")?, name: string_field(skill, "name", route, "$.skill")?, description: optional_string_field(skill, "description", route, "$.skill")?, + category: optional_string_field(skill, "category", route, "$.skill")?, + source_category: optional_string_field(skill, "source_category", route, "$.skill")?, version: string_field(skill, "version", route, "$.skill")?, digest: string_field(skill, "digest", route, "$.skill")?, signed_manifest: signed_manifest_field(skill, "signed_manifest", route, "$.skill")?, diff --git a/crates/runx-runtime/src/registry/types.rs b/crates/runx-runtime/src/registry/types.rs index 8c6c4bed4..46a3a8736 100644 --- a/crates/runx-runtime/src/registry/types.rs +++ b/crates/runx-runtime/src/registry/types.rs @@ -124,6 +124,10 @@ pub struct RegistrySearchResult { pub name: String, #[serde(skip_serializing_if = "Option::is_none")] pub summary: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub category: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub source_category: Option, pub owner: String, #[serde(skip_serializing_if = "Option::is_none")] pub version: Option, @@ -156,6 +160,10 @@ pub struct RegistrySkillVersion { pub name: String, #[serde(skip_serializing_if = "Option::is_none")] pub description: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub category: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub source_category: Option, pub version: String, pub digest: String, #[serde(skip_serializing_if = "Option::is_none")] @@ -206,6 +214,10 @@ pub struct RegistrySkill { pub name: String, #[serde(skip_serializing_if = "Option::is_none")] pub description: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub category: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub source_category: Option, pub latest_version: String, pub latest_digest: String, pub versions: Vec, @@ -311,6 +323,10 @@ pub struct RegistrySkillDetail { pub name: String, #[serde(skip_serializing_if = "Option::is_none")] pub description: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub category: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub source_category: Option, pub version: String, pub digest: String, #[serde(skip_serializing_if = "Option::is_none")] diff --git a/crates/runx-runtime/src/scaffold/templates.rs b/crates/runx-runtime/src/scaffold/templates.rs index 8794edacd..5bc6bd011 100644 --- a/crates/runx-runtime/src/scaffold/templates.rs +++ b/crates/runx-runtime/src/scaffold/templates.rs @@ -45,6 +45,7 @@ inputs: required: true description: Input the skill acts on. Replace with the real inputs. runx: + category: ops input_resolution: required: - message diff --git a/crates/runx-runtime/tests/registry.rs b/crates/runx-runtime/tests/registry.rs index 33297f61c..91d45fa92 100644 --- a/crates/runx-runtime/tests/registry.rs +++ b/crates/runx-runtime/tests/registry.rs @@ -105,6 +105,8 @@ fn file_registry_store_covers_profiled_skill_surface() -> Result<(), Box Result<(), Box Result<(), Box Result<(), Box Result<(), Box --json ``` +`X.yaml` is the canonical v1 filename, but the artifact is an execution profile: +runner wiring, typed inputs and outputs, tool/context refs, authority and receipt +mapping, side-effect posture, and harness cases. Do not use it as a strategy +document, target registry, copy deck, generated state file, or secret container. +Keep profile YAML explicit: anchors, aliases, merge keys, custom tags, +multi-document markers, duplicate mapping keys, and unknown profile fields are +not supported. + ## Publish locally first ```bash diff --git a/packages/cli/src/cli-parser/index.ts b/packages/cli/src/cli-parser/index.ts index e6e1d26f5..d78408206 100644 --- a/packages/cli/src/cli-parser/index.ts +++ b/packages/cli/src/cli-parser/index.ts @@ -83,6 +83,8 @@ export interface SkillSandbox { export interface ValidatedSkill { readonly name: string; readonly description?: string; + readonly category?: string; + readonly runxCategory?: string; readonly body: string; readonly source: SkillSource; readonly inputs: Readonly>; @@ -326,11 +328,15 @@ export function validateSkill(raw: RawSkillIR, options: ValidateSkillOptions = { } const source = validateSource(sourceRecord ?? { type: "agent" }, isRecord(runxValue) ? runxValue : undefined); const runx = isRecord(runxValue) ? runxValue : undefined; + const category = validatePortableSkillCategory(raw.frontmatter.category); + const runxCategory = validateRunxSkillCategory(readField(runx, "category")); const risk = raw.frontmatter.risk; return { name, description, + category, + runxCategory, body: raw.body, source, inputs, @@ -352,6 +358,19 @@ export function validateSkill(raw: RawSkillIR, options: ValidateSkillOptions = { }; } +function validatePortableSkillCategory(value: unknown): string | undefined { + return normalizeOptionalCategory(optionalNullableString(value, "category")); +} + +function validateRunxSkillCategory(value: unknown): string | undefined { + return normalizeOptionalCategory(optionalNullableString(value, "runx.category")); +} + +function normalizeOptionalCategory(value: string | undefined): string | undefined { + const normalized = value?.trim(); + return normalized ? normalized : undefined; +} + export function extractSkillQualityProfile(body: string): SkillQualityProfile | undefined { const content = extractMarkdownSection(body, "Quality Profile", 2); if (!content) { diff --git a/packages/cli/src/cli-registry.ts b/packages/cli/src/cli-registry.ts index 26532edd1..4c636617e 100644 --- a/packages/cli/src/cli-registry.ts +++ b/packages/cli/src/cli-registry.ts @@ -6,6 +6,8 @@ export interface SkillSearchResult { readonly skill_id: string; readonly name: string; readonly summary?: string; + readonly category?: string; + readonly source_category?: string; readonly owner: string; readonly version?: string; readonly digest?: string; diff --git a/packages/cli/src/cli-runtime-contracts.ts b/packages/cli/src/cli-runtime-contracts.ts index b54b13328..1c3153913 100644 --- a/packages/cli/src/cli-runtime-contracts.ts +++ b/packages/cli/src/cli-runtime-contracts.ts @@ -37,6 +37,8 @@ export interface RegistrySkillVersion { readonly runner_names: readonly string[]; readonly skill_id: string; readonly name: string; + readonly category?: string; + readonly source_category?: string; readonly version: string; readonly digest: string; readonly source_type: string; diff --git a/packages/cli/src/native-registry.ts b/packages/cli/src/native-registry.ts index 4e0774049..386e00041 100644 --- a/packages/cli/src/native-registry.ts +++ b/packages/cli/src/native-registry.ts @@ -67,6 +67,8 @@ function normalizeRustRegistrySearchResult(value: unknown): SkillSearchResult { !result || typeof result.skill_id !== "string" || typeof result.name !== "string" || + (result.category !== undefined && typeof result.category !== "string") || + (result.source_category !== undefined && typeof result.source_category !== "string") || typeof result.owner !== "string" || result.source !== "runx-registry" || typeof result.source_label !== "string" || diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index c67d363cb..abcb922e1 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -260,8 +260,8 @@ }, { "skill_id": "runx/pr-review-note", - "version": "sha-dd1608925a76", - "digest": "1b9f34f9e7f5355a10babbd154333db4b1b94fa16668583438166b91eec95e0a", + "version": "sha-537dd9fc3c6b", + "digest": "b073ec884f56c9e412d0c1039d5f28f163df0f5530eb0bee922ed4c557955c52", "catalog_visibility": "public", "catalog_role": "context" }, @@ -323,8 +323,8 @@ }, { "skill_id": "runx/review-skill", - "version": "sha-a27dde2ab9bb", - "digest": "09b4a6ec017f9d75536c6db21c60667bd855a20b0b20f53054f63143cbb9d13d", + "version": "sha-622805df5ff3", + "digest": "6fc1b341d55e3c6be8a5f7693dfe3312654b89a14f88fe42e4ffc84a65a9cd09", "catalog_visibility": "public", "catalog_role": "context" }, @@ -337,8 +337,8 @@ }, { "skill_id": "runx/runx-operator", - "version": "sha-da018df211a3", - "digest": "1c8d199a5dd0812a09eb4e785bcd9bfd7af67ec0ef3227149bed1de150a47fff", + "version": "sha-0fed07a0dc00", + "digest": "9de1d9dffb46b6bb14872b66738d5e9b26f271c6f11595c6a685d4c30e539176", "catalog_visibility": "public", "catalog_role": "canonical" }, @@ -379,8 +379,8 @@ }, { "skill_id": "runx/skill-testing", - "version": "sha-c31b54a981c8", - "digest": "7fc86c62bd493cb374850d7e9fc4faad94adb318fc3b20947aa2d411a741cc75", + "version": "sha-9113dacaa62a", + "digest": "93f7a0c009e289862fcc9236effdf0ac75197e9eb042a83200720d23d01cb443", "catalog_visibility": "public", "catalog_role": "context" }, @@ -393,8 +393,8 @@ }, { "skill_id": "runx/sourcey", - "version": "sha-d025d3a4701e", - "digest": "2bdffb5206cbfc2dc619ffead5d26ad192afe0f2836093d782c7901841713006", + "version": "sha-2b08f620e0fa", + "digest": "4b6316c7fbb323b7d27d304deb8f11cb8f939dc31e0b74349d56f27abf618504", "catalog_visibility": "public", "catalog_role": "context" }, @@ -484,8 +484,8 @@ }, { "skill_id": "runx/write-harness", - "version": "sha-c989640c5604", - "digest": "f4fbf60192335baff43a5d50f3702a17f96a42a25d69508f457cf0e396320528", + "version": "sha-f69b01f883e0", + "digest": "8fbac78e4c760a124c704ce62aa11ecb8b65b165c72a81fd2c1de163c5bb259b", "catalog_visibility": "public", "catalog_role": "context" }, diff --git a/packages/cli/src/presentation/search.ts b/packages/cli/src/presentation/search.ts index aa2974664..22bf3b457 100644 --- a/packages/cli/src/presentation/search.ts +++ b/packages/cli/src/presentation/search.ts @@ -62,6 +62,12 @@ export function renderSearchResults( if (result.summary) { lines.push(` ${t.dim}${result.summary}${t.reset}`); } + if (result.category) { + lines.push(` ${t.dim}category:${t.reset} ${result.category}`); + } + if (!result.category && result.source_category) { + lines.push(` ${t.dim}source category:${t.reset} ${result.source_category}`); + } if (result.profile_mode === "profiled" && result.runner_names.length > 0) { lines.push(` ${t.dim}runners:${t.reset} ${result.runner_names.join(", ")}`); } diff --git a/packages/cli/src/scaffold.ts b/packages/cli/src/scaffold.ts index 68a8cd978..abe81aebe 100644 --- a/packages/cli/src/scaffold.ts +++ b/packages/cli/src/scaffold.ts @@ -69,6 +69,7 @@ inputs: required: true description: Input the skill acts on. Replace with the real inputs. runx: + category: ops input_resolution: required: - message diff --git a/packages/cli/src/skill-refs.ts b/packages/cli/src/skill-refs.ts index 21358976f..d39d03817 100644 --- a/packages/cli/src/skill-refs.ts +++ b/packages/cli/src/skill-refs.ts @@ -2,6 +2,7 @@ import { existsSync, readFileSync } from "node:fs"; import { cp, mkdir, readFile, readdir, rm, writeFile } from "node:fs/promises"; import path from "node:path"; import { fileURLToPath } from "node:url"; +import { parseDocument } from "yaml"; import { resolvePathFromUserInput, @@ -341,9 +342,9 @@ async function searchBundledSkills(query: string, env: NodeJS.ProcessEnv): Promi const skillMdPath = path.join(bundledDir, entry.name, "SKILL.md"); if (!existsSync(skillMdPath)) continue; const raw = await readFile(skillMdPath, "utf8"); - const { name, description } = parseSkillFrontmatter(raw, entry.name); + const { name, description, category, sourceCategory } = parseSkillFrontmatter(raw, entry.name); if (!officialSkillVisibleForCatalog(`runx/${name}`, env)) continue; - const hay = `${name}\n${description}`.toLowerCase(); + const hay = `${name}\n${description}\n${category ?? ""}\n${sourceCategory ?? ""}`.toLowerCase(); if (needle && !hay.includes(needle)) continue; const hasProfile = existsSync(path.join(path.dirname(bundledDir), "bindings", "runx", entry.name, "X.yaml")); out.push({ @@ -356,7 +357,9 @@ async function searchBundledSkills(query: string, env: NodeJS.ProcessEnv): Promi source_type: "bundled", trust_tier: "first_party", required_scopes: [], - tags: [], + tags: category ? [category] : [], + category, + source_category: sourceCategory, profile_mode: hasProfile ? "profiled" : "portable", runner_names: [], add_command: `runx add runx/${name}`, @@ -483,18 +486,44 @@ function assertSkillReferencePath(resolved: string): void { } } -function parseSkillFrontmatter(raw: string, fallbackName: string): { name: string; description: string } { +function parseSkillFrontmatter(raw: string, fallbackName: string): { name: string; description: string; category?: string; sourceCategory?: string } { const match = raw.match(/^---\n([\s\S]*?)\n---/); let name = fallbackName; let description = ""; + let category: string | undefined; + let sourceCategory: string | undefined; if (match) { + const parsed = parseDocument(match[1], { prettyErrors: false }); + if (parsed.errors.length === 0) { + const frontmatter = asRecord(parsed.toJS()); + if (frontmatter) { + const runx = asRecord(frontmatter.runx); + const runxCategory = normalizeCategory(stringValue(runx?.category)); + return { + name: stringValue(frontmatter.name) || fallbackName, + description: stringValue(frontmatter.description) ?? "", + category: runxCategory, + sourceCategory: normalizeCategory(stringValue(frontmatter.category)), + }; + } + } for (const line of match[1].split("\n")) { - const kv = line.match(/^(name|description):\s*(.*)$/); + const kv = line.match(/^(name|description|category):\s*(.*)$/); if (!kv) continue; const value = kv[2].trim().replace(/^["']|["']$/g, ""); if (kv[1] === "name") name = value || fallbackName; else if (kv[1] === "description") description = value; + else if (kv[1] === "category") sourceCategory = normalizeCategory(value); } } - return { name, description }; + return { name, description, category, sourceCategory }; +} + +function stringValue(value: unknown): string | undefined { + return typeof value === "string" ? value : undefined; +} + +function normalizeCategory(value: string | undefined): string | undefined { + const normalized = value?.trim(); + return normalized ? normalized : undefined; } diff --git a/skills/issue-to-pr/push-outbox/SKILL.md b/skills/issue-to-pr/push-outbox/SKILL.md index 89b720aeb..2d0dd16ca 100644 --- a/skills/issue-to-pr/push-outbox/SKILL.md +++ b/skills/issue-to-pr/push-outbox/SKILL.md @@ -1,6 +1,8 @@ --- name: issue-to-pr-push-outbox description: Publish issue-to-PR outbox entries through the governed Rust thread-outbox-provider front. +runx: + category: code source: type: thread-outbox-provider thread_outbox_provider: diff --git a/skills/pr-review-note/SKILL.md b/skills/pr-review-note/SKILL.md index 135c2d0ca..2d3d7db6e 100644 --- a/skills/pr-review-note/SKILL.md +++ b/skills/pr-review-note/SKILL.md @@ -1,6 +1,8 @@ --- name: pr-review-note description: Govern a GitHub PR review-note lane over MCP; comment scope is admitted, merge scope is refused. +runx: + category: code --- # PR Review Note diff --git a/skills/review-skill/SKILL.md b/skills/review-skill/SKILL.md index aa230a7a0..3aef41f7a 100644 --- a/skills/review-skill/SKILL.md +++ b/skills/review-skill/SKILL.md @@ -31,9 +31,34 @@ adopt, publish, sandbox, or reject the skill. - Strategic bar: explain whether the skill strengthens the catalog, fills a real operator need, duplicates existing capability, or carries unacceptable trust risk. +- Public value bar: a skill is not publication-ready merely because it parses or + runs once. It should solve a real operator or user problem, be something the + catalog would stand behind, and produce evidence a stranger can verify. A + wrapper, placeholder, toy, or copied example with no credible adoption path is + a reject or sandbox-only recommendation. - Stop conditions: return `needs_more_evidence` when receipts or harness proof are missing, and `reject` when the skill cannot be bounded or audited. +## Review Gates + +Check these before recommending adoption or publication: + +- The `SKILL.md` states a bounded capability and does not promise more than the + execution profile implements. +- The execution profile declares typed inputs, outputs, side-effect posture, + allowed refs/tools, authority or approval posture, receipt mapping when a + domain act occurs, and harness cases. +- At least one meaningful happy path and one error or stop path are covered by + harness evidence or receipts. Local assertions without captured output are not + enough. +- Any published URL, registry listing, docs site, or repo is durable and public. + Placeholder hosts, private previews, unrelated parent domains, and dead links + lower trust or block publication. +- The evidence pack contains no secrets, private tokens, customer data, private + inbox content, or provider dumps. +- The recommendation states who would use or trust the skill and why. If that + answer is weak, recommend rejection, sandboxing, or a narrower redesign. + ## Output - `capability_profile`: what the skill appears to do and how it executes. diff --git a/skills/runx-operator/SKILL.md b/skills/runx-operator/SKILL.md index 0627dbf9b..cfa3e6197 100644 --- a/skills/runx-operator/SKILL.md +++ b/skills/runx-operator/SKILL.md @@ -105,6 +105,10 @@ product gap. Do not invent a private workaround. - Treat missing evidence as missing. Do not infer success from UI state alone. - Separate health, money, communications, provider mutations, access, deployment, and incident signals. + - For review, catalog, publication, bounty, or marketplace work, classify + whether the artifact is real, useful, complete, and valuable. A reachable + artifact with no credible user, maintainer, operator, public proof, or + marketing value is not ready. 3. Route to governed lanes. - Release questions route to `release` plus the project release profile and @@ -126,6 +130,9 @@ product gap. Do not invent a private workaround. - Live sends, payouts, refunds, customer-visible posts, provider mutations, target changes, credential changes, deploys, destructive actions, and broad audience decisions: explicit approval required. + - A review verdict, recommendation, or green dry-run is not payment approval. + Money movement needs a separate approval prompt naming the amount, recipient, + rail, target class, and verification receipt expected after settlement. - Missing approval means `awaiting_approval`, not "ready". 5. Produce the operator packet. @@ -236,6 +243,8 @@ operator_packet: provider response dumps. - Never claim a state is settled, sent, deployed, paid, or refunded without a receipt/effect/readback reference. +- Never route a public artifact, skill, bounty result, or docs deployment as + ready when it lacks a credible real-world audience or durable public evidence. - Never widen authority because a dashboard widget would be convenient. - Never duplicate an existing CLI command, workflow, hosted endpoint, or domain skill in operator prose. Route to it. diff --git a/skills/skill-testing/SKILL.md b/skills/skill-testing/SKILL.md index 49af0f562..0019a34cf 100644 --- a/skills/skill-testing/SKILL.md +++ b/skills/skill-testing/SKILL.md @@ -26,9 +26,30 @@ packages the approved output for publication or operator handoff. gaps directly. - Strategic bar: make adoption, sandboxing, rejection, or further testing easier. +- Public value bar: test whether the skill has a credible user, operator, + maintainer, or catalog reason to exist. Passing harnesses do not rescue a + placeholder, toy, duplicate, or low-value package. - Stop conditions: stop at review when trust evidence is insufficient or the skill cannot be bounded. +## Trust Audit Checks + +Before packaging a recommendation, confirm: + +- The skill contract is bounded and matches the execution profile. +- The execution profile declares typed inputs and outputs, side-effect posture, + allowed refs/tools, approval or authority posture, receipt mapping where + relevant, and harness cases. +- Harness or receipt evidence covers a meaningful happy path and at least one + stop or error path. +- Published artifacts are durable and public. Private previews, localhost, + placeholder hosts, unrelated parent domains, or dead links block a publication + recommendation. +- The audit names the concrete user-visible value: who would use, link, install, + trust, or maintain the skill. +- The evidence pack contains no secrets, raw credentials, private customer data, + private email bodies, wallet private keys, or provider response dumps. + ## Inputs - `skill_ref` (required): skill package or registry reference to assess. diff --git a/skills/sourcey/SKILL.md b/skills/sourcey/SKILL.md index a5368c89a..22f6c3241 100644 --- a/skills/sourcey/SKILL.md +++ b/skills/sourcey/SKILL.md @@ -69,6 +69,10 @@ would stand behind: demo framing unless the project itself uses that framing - never describe pages as machine output, agent output, or AI-generated docs; the site should read like the project maintainer wrote and stands behind it +- when publishing public docs, use a credible durable project, maintainer, + organization, product, or documentation home. Random personal domains, + placeholder parent sites, sandbox hosts, preview deploys, throwaway + subdomains, and unrelated novelty domains are not publication-quality homes - if the repo evidence is too thin for a strong docs page, surface that as an evidence gap instead of manufacturing confident filler @@ -88,6 +92,9 @@ would stand behind: - Strategic bar: the docs should make a real user action easier: install, evaluate, integrate, operate, or contribute. A pretty site with thin content is a failed run. +- Public value bar: a public Sourcey site should be something a real maintainer, + user, or ecosystem account would link. If the target project, host, or content + has no credible audience, return `needs_review` instead of shipping. - Stop conditions: return `needs_more_evidence`, `needs_review`, or an empty author/revise bundle when the repo already has the right docs or the evidence does not support new pages. @@ -223,6 +230,10 @@ with `needs_more_evidence` or `needs_review` instead of producing filler. - CI or deploy may run deterministic `sourcey build` from committed source. - Deploy must not be the step where docs scope, prose, or IA is invented. Do discovery, authoring, and review before deploy. +- For public publication, include enough proof for an external reviewer to + inspect the target project, source commit, Sourcey config or input source, + generated page list, deployment URL, parent domain, and durability of the + hosting choice. ## Config reference @@ -357,5 +368,8 @@ Invalid card icon names are a blocking quality issue. The build report includes missing ignore rule as an operational gap. - Build output may be regenerated in CI or deploy, but deploy must not author or revise docs content. +- Public deployments must be durable and socially credible. Do not treat a + throwaway preview URL, unrelated personal domain, placeholder parent site, or + sandbox subdomain as a completed public docs home. - Do not encode open-ended critique or revision behavior. Critique is one bounded evaluation pass. Revision is at most one explicit bounded pass. diff --git a/skills/write-harness/SKILL.md b/skills/write-harness/SKILL.md index dc2b748d1..97965091e 100644 --- a/skills/write-harness/SKILL.md +++ b/skills/write-harness/SKILL.md @@ -62,6 +62,11 @@ Start from the skill contract (SKILL.md + execution profile). Design fixtures fo invalid tool path. Expect failure with meaningful error. - **Governance gates** (composite skills only): one fixture per approval or policy transition that matters. +- **Publication evidence**: for skills intended for registry or public use, + include checks that prove the registry listing or public artifact is reachable, + durable, and tied to the submitted source. +- **User-value boundary**: include at least one assertion or acceptance check + that protects the real user-visible promise, not only internal step success. Each fixture tests one thing. Do not combine happy-path and error checks. Test the contract, not the internal wiring. @@ -83,6 +88,7 @@ internal builder transcript. That means: - explain catalog fit against adjacent current runx skills or graphs - describe the concrete user-visible artifact, not only the internal execution sequence +- name who would use, trust, link, install, or maintain the artifact and why - convert unresolved ambiguity into explicit maintainer decisions - keep issue comments, amendments, and approval records as provenance instead of copying them into the public proposal @@ -110,6 +116,9 @@ that in `maintainer_decisions` rather than leaking it into the fixture target. bundle. - Strategic bar: every fixture should protect a user-visible promise, trust boundary, or failure mode that matters for the skill's purpose. +- Public value bar: do not write fixtures for a skill whose only value is that it + exists. Return `not_first_party` or `needs_agent` when the proposal lacks a + credible user, operator, maintainer, catalog, or public proof value. - Stop conditions: return `needs_agent` when the contract is too vague to harness, and return `not_first_party` when the proposed skill should be reuse, Sourcey/content work, or a graph amendment instead. From 14fe3be9b91b4f80b54661946f63425dd94ae8ee Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 21:18:38 +1000 Subject: [PATCH 26/64] fix(skills): enforce execution profile yaml subset --- crates/runx-cli/src/launcher.rs | 4 +- crates/runx-cli/tests/launcher.rs | 4 +- crates/runx-parser/src/json_fields.rs | 17 + crates/runx-parser/src/lib.rs | 4 +- crates/runx-parser/src/runner.rs | 20 +- crates/runx-parser/src/skill.rs | 1 + .../src/skill/runner_definition.rs | 64 ++- crates/runx-parser/src/skill/source.rs | 51 ++- crates/runx-parser/src/skill/types.rs | 7 + crates/runx-parser/src/yaml.rs | 258 +++++++++++- crates/runx-runtime/src/adapters/http.rs | 169 ++++++-- .../runx-runtime/src/execution/skill_front.rs | 57 ++- .../runx-runtime/src/tool_catalogs/build.rs | 32 +- docs/reference.md | 5 + docs/skill-quality-standard.md | 27 ++ packages/cli/src/cli-parser/index.test.ts | 101 +++++ packages/cli/src/cli-parser/index.ts | 241 ++++++++++- packages/cli/src/cli-parser/yaml-subset.ts | 393 ++++++++++++++++++ scripts/generate-official-lock.mjs | 168 ++++++++ skills/spend/graph/pay-fulfill-rail/X.yaml | 134 +++++- 20 files changed, 1678 insertions(+), 79 deletions(-) create mode 100644 packages/cli/src/cli-parser/index.test.ts create mode 100644 packages/cli/src/cli-parser/yaml-subset.ts diff --git a/crates/runx-cli/src/launcher.rs b/crates/runx-cli/src/launcher.rs index f735e59ad..a534769c3 100644 --- a/crates/runx-cli/src/launcher.rs +++ b/crates/runx-cli/src/launcher.rs @@ -336,7 +336,7 @@ Commands: runx dev [root] [--lane lane] [--json] runx export [skill-ref...] [--project] [--json] runx mcp serve [--receipt-dir dir] [--http-listen [addr]] [--http-allow-non-loopback] - runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [-R dir] [--run-id id --answers file] + runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] [--run-id id --answers file] runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--installation-id id] [--api-base-url url] [--json] runx harness [-R dir] [-j|--json] runx tool build |--all [--json] @@ -408,7 +408,7 @@ pub fn skill_help_text() -> String { runx skill Usage: - runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [-R dir] [--run-id id --answers file] + runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] [--run-id id --answers file] Options: -p, --profile name Use a local credential profile from .runx/credentials.json diff --git a/crates/runx-cli/tests/launcher.rs b/crates/runx-cli/tests/launcher.rs index 1851af08b..e4b85120d 100644 --- a/crates/runx-cli/tests/launcher.rs +++ b/crates/runx-cli/tests/launcher.rs @@ -33,7 +33,7 @@ fn top_level_help_and_version_are_native() { ); assert_help_line( &help, - "runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [-R dir] [--run-id id --answers file]", + "runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] [--run-id id --answers file]", ); assert_help_line( &help, @@ -98,7 +98,7 @@ fn nested_skill_history_verify_and_publish_help_are_native() { assert_help_line( &skill_help_text(), - "runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [-R dir] [--run-id id --answers file]", + "runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] [--run-id id --answers file]", ); assert_help_line( &skill_help_text(), diff --git a/crates/runx-parser/src/json_fields.rs b/crates/runx-parser/src/json_fields.rs index 54f901f3b..2bdf245e0 100644 --- a/crates/runx-parser/src/json_fields.rs +++ b/crates/runx-parser/src/json_fields.rs @@ -151,6 +151,23 @@ impl JsonFieldReader { Some(_) => Err(self.validation_error(format!("{field} must be a finite number."))), } } + + pub(crate) fn reject_unknown_fields( + &self, + object: &JsonObject, + field: &str, + allowed: &[&str], + ) -> Result<(), ValidationError> { + for key in object.keys() { + if !allowed.contains(&key.as_str()) { + return Err(self.validation_error(format!( + "{field}.{key} is not supported; allowed fields: {}.", + allowed.join(", ") + ))); + } + } + Ok(()) + } } pub(crate) fn first_value<'a>( diff --git a/crates/runx-parser/src/lib.rs b/crates/runx-parser/src/lib.rs index 7630a0651..d40e5af2a 100644 --- a/crates/runx-parser/src/lib.rs +++ b/crates/runx-parser/src/lib.rs @@ -37,6 +37,6 @@ pub use tool::{ validate_tool_manifest, }; pub use yaml::{ - assert_yaml_parity_subset, assert_yaml_scalar_subset, parse_yaml_document, - yaml_scalar_subset_allows, + assert_execution_profile_yaml_subset, assert_yaml_parity_subset, assert_yaml_scalar_subset, + parse_yaml_document, yaml_scalar_subset_allows, }; diff --git a/crates/runx-parser/src/runner.rs b/crates/runx-parser/src/runner.rs index 0408c65b9..88fcc7651 100644 --- a/crates/runx-parser/src/runner.rs +++ b/crates/runx-parser/src/runner.rs @@ -8,11 +8,14 @@ use crate::skill::{ validate_harness_manifest, validate_runner_definition, }; use crate::{ - ParseError, ValidationError, assert_yaml_parity_subset, + ParseError, ValidationError, assert_execution_profile_yaml_subset, json_fields::{self, JsonFieldReader}, }; const FIELDS: JsonFieldReader = JsonFieldReader::new("runner_manifest"); +const MANIFEST_FIELDS: &[&str] = &[ + "skill", "version", "runx", "policy", "emits", "catalog", "runners", "harness", +]; #[derive(Clone, Debug, PartialEq, Serialize, Deserialize)] pub struct RawRunnerManifestIr { @@ -25,6 +28,14 @@ pub struct SkillRunnerManifest { #[serde(skip_serializing_if = "Option::is_none")] pub skill: Option, #[serde(skip_serializing_if = "Option::is_none")] + pub version: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub runx: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub policy: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub emits: Option, + #[serde(skip_serializing_if = "Option::is_none")] pub catalog: Option, pub runners: BTreeMap, #[serde(skip_serializing_if = "Option::is_none")] @@ -33,7 +44,7 @@ pub struct SkillRunnerManifest { } pub fn parse_runner_manifest_yaml(yaml: &str) -> Result { - assert_yaml_parity_subset("runner_manifest", yaml)?; + assert_execution_profile_yaml_subset("runner_manifest", yaml)?; let parsed: JsonValue = serde_norway::from_str(yaml).map_err(|error| ParseError::InvalidYaml { field: "runner_manifest".to_owned(), @@ -54,6 +65,7 @@ pub fn parse_runner_manifest_yaml(yaml: &str) -> Result Result { + FIELDS.reject_unknown_fields(&raw.document, "runner_manifest", MANIFEST_FIELDS)?; let runners_record = FIELDS.required_object(raw.document.get("runners"), "runners")?; let mut runners = BTreeMap::new(); for (name, value) in runners_record { @@ -74,6 +86,10 @@ pub fn validate_runner_manifest( Ok(SkillRunnerManifest { skill: FIELDS.optional_string(raw.document.get("skill"), "skill")?, + version: FIELDS.optional_string(raw.document.get("version"), "version")?, + runx: FIELDS.optional_object(raw.document.get("runx"), "runx")?, + policy: raw.document.get("policy").cloned(), + emits: raw.document.get("emits").cloned(), catalog: validate_catalog_metadata( FIELDS.optional_object(raw.document.get("catalog"), "catalog")?, "catalog", diff --git a/crates/runx-parser/src/skill.rs b/crates/runx-parser/src/skill.rs index 6a1424b3b..62748d369 100644 --- a/crates/runx-parser/src/skill.rs +++ b/crates/runx-parser/src/skill.rs @@ -40,6 +40,7 @@ use governance::{ use sandbox::validate_sandbox; use source::default_agent_source; use source::validate_source; +use source::validate_source_fields; const FIELDS: JsonFieldReader = JsonFieldReader::new("skill"); diff --git a/crates/runx-parser/src/skill/runner_definition.rs b/crates/runx-parser/src/skill/runner_definition.rs index 516975525..3bbbb3e10 100644 --- a/crates/runx-parser/src/skill/runner_definition.rs +++ b/crates/runx-parser/src/skill/runner_definition.rs @@ -6,17 +6,75 @@ use super::{ FIELDS, SkillGovernance, SkillRunnerDefinition, field_value, first_value, nested_value, validate_allowed_tools, validate_artifact_contract, validate_execution_semantics, validate_idempotency, validate_inputs, validate_mutating, validate_retry, validate_source, + validate_source_fields, }; +const RUNNER_FIELDS: &[&str] = &[ + "act", + "agent", + "agent_card_url", + "agent_identity", + "allowed_tools", + "args", + "arguments", + "artifacts", + "auth", + "catalog_ref", + "command", + "context", + "context_skills", + "cwd", + "default", + "execution", + "external_adapter", + "external_adapter_manifest", + "external_adapter_manifest_path", + "graph", + "headers", + "hook", + "http", + "idempotency", + "input_mode", + "inputs", + "instructions", + "invocation_id", + "method", + "mutating", + "outputs", + "policy", + "retry", + "risk", + "run_id", + "runx", + "runtime", + "sandbox", + "server", + "skill_ref", + "scopes", + "source", + "task", + "timeout_seconds", + "tool", + "type", + "url", + "allow_private_network", +]; + pub(crate) fn validate_runner_definition( name: &str, runner: JsonObject, ) -> Result { + FIELDS.reject_unknown_fields(&runner, &format!("runners.{name}"), RUNNER_FIELDS)?; let runx = FIELDS.optional_object(runner.get("runx"), &format!("runners.{name}.runx"))?; crate::runner::resolve_post_run_reflect_policy(runx.as_ref(), &format!("runners.{name}.runx"))?; - let source_record = FIELDS - .optional_object(runner.get("source"), &format!("runners.{name}.source"))? - .unwrap_or_else(|| runner.clone()); + let source_record = + match FIELDS.optional_object(runner.get("source"), &format!("runners.{name}.source"))? { + Some(source) => { + validate_source_fields(&source, &format!("runners.{name}.source"))?; + source + } + None => runner.clone(), + }; let risk = runner.get("risk").cloned(); let governance = validate_runner_governance(name, &runner, runx.as_ref(), risk.as_ref())?; Ok(SkillRunnerDefinition { diff --git a/crates/runx-parser/src/skill/source.rs b/crates/runx-parser/src/skill/source.rs index ca4148784..d03d5d39e 100644 --- a/crates/runx-parser/src/skill/source.rs +++ b/crates/runx-parser/src/skill/source.rs @@ -8,6 +8,39 @@ use super::{ field_value, first_value, validate_sandbox, }; +const SOURCE_FIELDS: &[&str] = &[ + "act", + "agent", + "agent_card_url", + "agent_identity", + "allow_private_network", + "args", + "arguments", + "catalog_ref", + "command", + "cwd", + "external_adapter", + "external_adapter_manifest", + "external_adapter_manifest_path", + "graph", + "headers", + "hook", + "http", + "input_mode", + "invocation_id", + "method", + "outputs", + "run_id", + "sandbox", + "server", + "skill_ref", + "task", + "timeout_seconds", + "tool", + "type", + "url", +]; + pub fn validate_skill_source( source: &JsonObject, runx: Option<&JsonObject>, @@ -15,6 +48,13 @@ pub fn validate_skill_source( validate_source(source, runx) } +pub(super) fn validate_source_fields( + source: &JsonObject, + field: &str, +) -> Result<(), ValidationError> { + FIELDS.reject_unknown_fields(source, field, SOURCE_FIELDS) +} + pub(super) fn validate_source( source: &JsonObject, runx: Option<&JsonObject>, @@ -225,8 +265,11 @@ fn validate_http_source( if source_type != "http" { return Ok(None); } - let url = FIELDS.required_string(source.get("url"), "source.url")?; - let method = match FIELDS.optional_string(source.get("method"), "source.method")? { + let http = FIELDS + .optional_object(source.get("http"), "source.http")? + .unwrap_or_else(|| source.clone()); + let url = FIELDS.required_string(http.get("url"), "source.url")?; + let method = match FIELDS.optional_string(http.get("method"), "source.method")? { Some(method) => { if !matches!( method.to_ascii_uppercase().as_str(), @@ -243,9 +286,9 @@ fn validate_http_source( Ok(Some(SkillHttpSource { url, method, - headers: validate_http_headers(source.get("headers"))?, + headers: validate_http_headers(http.get("headers"))?, allow_private_network: FIELDS.optional_bool( - source.get("allow_private_network"), + http.get("allow_private_network"), "source.allow_private_network", )?, })) diff --git a/crates/runx-parser/src/skill/types.rs b/crates/runx-parser/src/skill/types.rs index c6b130ffd..723153339 100644 --- a/crates/runx-parser/src/skill/types.rs +++ b/crates/runx-parser/src/skill/types.rs @@ -158,6 +158,7 @@ pub struct SkillSource { /// the act's structure from these and the trusted inputs; the model authors only /// the reason prose. Absent an `act:` block, a run seals a generic observation. #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] +#[serde(deny_unknown_fields)] pub struct ActDeclaration { #[serde(skip_serializing_if = "Option::is_none")] pub form: Option, @@ -180,10 +181,16 @@ pub struct ActDeclaration { #[serde(skip_serializing_if = "Option::is_none")] pub effect_from: Option, #[serde(skip_serializing_if = "Option::is_none")] + pub effect_field_from: Option, + #[serde(skip_serializing_if = "Option::is_none")] + pub effect_from_input: Option, + #[serde(skip_serializing_if = "Option::is_none")] pub effect_type: Option, #[serde(skip_serializing_if = "Option::is_none")] pub effect_prefix: Option, #[serde(skip_serializing_if = "Option::is_none")] + pub effect_prefix_from: Option, + #[serde(skip_serializing_if = "Option::is_none")] pub actor_from: Option, #[serde(skip_serializing_if = "Option::is_none")] pub authority_from: Option, diff --git a/crates/runx-parser/src/yaml.rs b/crates/runx-parser/src/yaml.rs index 04f1a3906..d26d32f46 100644 --- a/crates/runx-parser/src/yaml.rs +++ b/crates/runx-parser/src/yaml.rs @@ -1,6 +1,8 @@ // rust-style-allow: large-file the QuoteScanner state machine and its // quote-aware scanners belong next to the parity-subset rules they enforce; // splitting the scanner from the rules trades clarity for two-file traversal. +use std::collections::HashSet; + use serde::de::DeserializeOwned; use crate::ParseError; @@ -20,18 +22,53 @@ where } pub fn assert_yaml_parity_subset(field: &str, source: &str) -> Result<(), ParseError> { + let mut block_scalar_indent = None; for (line_index, line) in source.lines().enumerate() { let line_number = line_index + 1; let Some(content) = strip_yaml_comment(line) else { continue; }; let trimmed = content.trim(); + if let Some(indent) = block_scalar_indent { + if trimmed.is_empty() || leading_spaces(content) > indent { + continue; + } + block_scalar_indent = None; + } if trimmed.is_empty() || trimmed.starts_with("---") || trimmed.starts_with("...") { continue; } reject_explicit_mapping_key(field, line_number, trimmed)?; reject_embedded_colon_key(field, line_number, trimmed)?; reject_colon_space_plain_scalar(field, line_number, content)?; + block_scalar_indent = block_scalar_indent_after(content).or(block_scalar_indent); + } + Ok(()) +} + +pub fn assert_execution_profile_yaml_subset(field: &str, source: &str) -> Result<(), ParseError> { + assert_yaml_parity_subset(field, source)?; + let mut mapping_stack = Vec::new(); + let mut block_scalar_indent = None; + for (line_index, line) in source.lines().enumerate() { + let line_number = line_index + 1; + let Some(content) = strip_yaml_comment(line) else { + continue; + }; + let trimmed = content.trim(); + if let Some(indent) = block_scalar_indent { + if trimmed.is_empty() || leading_spaces(content) > indent { + continue; + } + block_scalar_indent = None; + } + if trimmed.is_empty() { + continue; + } + reject_document_marker(field, line_number, trimmed)?; + reject_yaml_reference_syntax(field, line_number, content)?; + reject_duplicate_mapping_key(field, line_number, content, &mut mapping_stack)?; + block_scalar_indent = block_scalar_indent_after(content).or(block_scalar_indent); } Ok(()) } @@ -222,6 +259,181 @@ fn reject_colon_space_plain_scalar( Ok(()) } +fn reject_document_marker( + field: &str, + line_number: usize, + trimmed: &str, +) -> Result<(), ParseError> { + if trimmed == "---" + || trimmed == "..." + || trimmed.starts_with("--- ") + || trimmed.starts_with("... ") + { + return Err(ParseError::InvalidYaml { + field: field.to_owned(), + message: format!( + "YAML document markers are not supported in X.yaml at line {line_number}; use one plain profile document." + ), + }); + } + Ok(()) +} + +fn reject_yaml_reference_syntax( + field: &str, + line_number: usize, + content: &str, +) -> Result<(), ParseError> { + for token in [": &", ": *", ": !", "- &", "- *", "- !"] { + if contains_plain_token(content, token) { + return Err(ParseError::InvalidYaml { + field: field.to_owned(), + message: format!( + "YAML anchors, aliases, and tags are not supported in X.yaml at line {line_number}; write the profile explicitly." + ), + }); + } + } + let trimmed = content.trim_start(); + if trimmed.starts_with(['&', '*', '!']) { + return Err(ParseError::InvalidYaml { + field: field.to_owned(), + message: format!( + "YAML anchors, aliases, and tags are not supported in X.yaml at line {line_number}; write the profile explicitly." + ), + }); + } + Ok(()) +} + +fn contains_plain_token(content: &str, token: &str) -> bool { + let mut scanner = QuoteScanner::new(); + for (index, char) in content.char_indices() { + if scanner.is_plain_at(char) && content[index..].starts_with(token) { + return true; + } + scanner.consume(char); + } + false +} + +struct MappingFrame { + indent: usize, + keys: HashSet, +} + +fn reject_duplicate_mapping_key( + field: &str, + line_number: usize, + content: &str, + stack: &mut Vec, +) -> Result<(), ParseError> { + let indent = leading_spaces(content); + let trimmed = content.trim_start(); + let (key_indent, key, sequence_item) = match sequence_item_key(trimmed, indent) { + Some(value) => value, + None => { + let Some((key, _)) = top_level_plain_key(trimmed) else { + return Ok(()); + }; + (indent, key, false) + } + }; + if key == "<<" { + return Err(ParseError::InvalidYaml { + field: field.to_owned(), + message: format!( + "YAML merge keys are not supported in X.yaml at line {line_number}; write the profile explicitly." + ), + }); + } + if sequence_item { + while stack.last().is_some_and(|frame| frame.indent >= key_indent) { + stack.pop(); + } + } else { + while stack.last().is_some_and(|frame| frame.indent > key_indent) { + stack.pop(); + } + } + if stack.last().is_none_or(|frame| frame.indent != key_indent) { + stack.push(MappingFrame { + indent: key_indent, + keys: HashSet::new(), + }); + } + let frame = stack + .last_mut() + .expect("mapping frame is created before key insertion"); + if !frame.keys.insert(key.to_owned()) { + return Err(ParseError::InvalidYaml { + field: field.to_owned(), + message: format!( + "duplicate mapping key {key:?} in X.yaml at line {line_number}; keep profile keys unique." + ), + }); + } + Ok(()) +} + +fn sequence_item_key(trimmed: &str, indent: usize) -> Option<(usize, &str, bool)> { + let rest = trimmed.strip_prefix("- ")?; + let item = rest.trim_start(); + let leading = rest.len() - item.len(); + let (key, _) = top_level_plain_key(item)?; + Some((indent + 2 + leading, key, true)) +} + +fn leading_spaces(content: &str) -> usize { + content.bytes().take_while(|byte| *byte == b' ').count() +} + +fn block_scalar_indent_after(content: &str) -> Option { + block_scalar_value_candidates(content) + .iter() + .any(|value| is_block_scalar_header(value)) + .then(|| leading_spaces(content)) +} + +fn block_scalar_value_candidates(content: &str) -> Vec<&str> { + let mut candidates = Vec::new(); + if let Some((_, value)) = split_plain_mapping_value(content) { + candidates.push(value); + } + let trimmed = content.trim_start(); + if let Some(rest) = trimmed.strip_prefix("- ") { + let item = rest.trim_start(); + candidates.push(item); + if let Some((_, value)) = split_plain_mapping_value(item) { + candidates.push(value); + } + } + candidates +} + +fn is_block_scalar_header(value: &str) -> bool { + let trimmed = value.trim(); + let mut chars = trimmed.chars(); + let Some(first) = chars.next() else { + return false; + }; + if !matches!(first, '|' | '>') { + return false; + } + let mut seen_chomp = false; + let mut seen_indent = false; + for char in chars { + if matches!(char, '+' | '-') && !seen_chomp { + seen_chomp = true; + } else if char.is_ascii_digit() && !seen_indent { + seen_indent = true; + } else { + return false; + } + } + true +} + fn split_plain_mapping_value(content: &str) -> Option<(&str, &str)> { let trimmed = content.trim_start(); let (key, delimiter_index) = top_level_plain_key(trimmed)?; @@ -303,7 +515,10 @@ fn is_special_float(value: &str) -> bool { #[cfg(test)] mod tests { - use super::{assert_yaml_parity_subset, assert_yaml_scalar_subset, yaml_scalar_subset_allows}; + use super::{ + assert_execution_profile_yaml_subset, assert_yaml_parity_subset, assert_yaml_scalar_subset, + yaml_scalar_subset_allows, + }; #[test] fn scalar_subset_rejects_divergent_forms() { @@ -359,6 +574,47 @@ mod tests { assert!(result.is_err(), "expected rejection, got {result:?}"); } + #[test] + fn execution_profile_subset_rejects_yaml_references_and_document_markers() { + for literal in [ + "---\nskill: example", + "runners:\n one:\n outputs: &shared\n result: string", + "runners:\n one:\n outputs: *shared", + "runners:\n one:\n runx:\n <<: *shared", + "runners:\n one:\n type: !custom graph", + ] { + let result = assert_execution_profile_yaml_subset("runner_manifest", literal); + assert!(result.is_err(), "expected rejection, got {result:?}"); + } + } + + #[test] + fn execution_profile_subset_rejects_duplicate_keys_but_allows_sequence_reuse() { + let result = + assert_execution_profile_yaml_subset("runner_manifest", "skill: one\nskill: two\n"); + assert!( + result.is_err(), + "expected duplicate key rejection, got {result:?}" + ); + + assert_execution_profile_yaml_subset( + "runner_manifest", + r#" +runners: + demo: + type: graph + graph: + name: demo + steps: + - id: first + tool: one.tool + - id: second + tool: two.tool +"#, + ) + .expect("sequence item maps may reuse keys in separate items"); + } + // Regression cases for the single-quote `''` escape. The earlier toggle // flipped on every `'`, so `'it''s'` mis-segmented into three scalars and // any `:` after byte 4 was treated as still-quoted. diff --git a/crates/runx-runtime/src/adapters/http.rs b/crates/runx-runtime/src/adapters/http.rs index 2256a3690..440d6219f 100644 --- a/crates/runx-runtime/src/adapters/http.rs +++ b/crates/runx-runtime/src/adapters/http.rs @@ -129,8 +129,9 @@ fn resolve_path_template( Ok((out, remaining)) } -fn json_body(inputs: &JsonObject) -> Result { - serde_json::to_string(&serde_json::to_value(inputs).unwrap_or(WireValue::Null)) +fn json_body(inputs: &JsonObject, secrets: &SecretEnv) -> Result { + let value = substitute_json_secrets(&JsonValue::Object(inputs.clone()), secrets)?; + serde_json::to_string(&serde_json::to_value(value).unwrap_or(WireValue::Null)) .map_err(|error| failure(format!("serializing http request body: {error}"))) } @@ -140,6 +141,7 @@ pub fn execute_http_call( transport: &T, call: &HttpCall, inputs: &JsonObject, + secrets: &SecretEnv, ) -> Result { let (resolved_url, query_inputs) = resolve_path_template(&call.url, inputs)?; let mut headers = call.headers.clone(); @@ -151,7 +153,7 @@ pub fn execute_http_call( { headers.push(RuntimeHttpHeader::new("content-type", "application/json")); } - (resolved_url, Some(json_body(&query_inputs)?)) + (resolved_url, Some(json_body(&query_inputs, secrets)?)) } HttpMethod::Get | HttpMethod::Delete => (with_query(&resolved_url, &query_inputs), None), }; @@ -185,22 +187,22 @@ pub fn execute_http_call( const SECRET_PREFIX: &str = "${secret:"; -/// Resolve `${secret:NAME}` references in a header value against the run's secret -/// env, mirroring how the cli-tool front lets a command reference a delivered -/// secret. A reference to a secret that was not delivered fails closed. +/// Resolve `${secret:NAME}` references against the run's secret env, mirroring +/// how the cli-tool front lets a command reference a delivered secret. A +/// reference to a secret that was not delivered fails closed. fn substitute_secrets(value: &str, secrets: &SecretEnv) -> Result { let mut out = String::with_capacity(value.len()); let mut rest = value; while let Some(start) = rest.find(SECRET_PREFIX) { out.push_str(&rest[..start]); let after = &rest[start + SECRET_PREFIX.len()..]; - let end = after.find('}').ok_or_else(|| { - failure("http header secret reference is missing a closing '}'".to_owned()) - })?; + let end = after + .find('}') + .ok_or_else(|| failure("http secret reference is missing a closing '}'".to_owned()))?; let name = &after[..end]; let secret = secrets.get(name).ok_or_else(|| { failure(format!( - "http header references secret {name}, which was not delivered to this run" + "http references secret {name}, which was not delivered to this run" )) })?; out.push_str(secret); @@ -210,6 +212,26 @@ fn substitute_secrets(value: &str, secrets: &SecretEnv) -> Result Result { + match value { + JsonValue::String(value) => substitute_secrets(value, secrets).map(JsonValue::String), + JsonValue::Array(values) => values + .iter() + .map(|value| substitute_json_secrets(value, secrets)) + .collect::, _>>() + .map(JsonValue::Array), + JsonValue::Object(object) => object + .iter() + .map(|(key, value)| Ok((key.clone(), substitute_json_secrets(value, secrets)?))) + .collect::>() + .map(JsonValue::Object), + value => Ok(value.clone()), + } +} + /// Build the request headers from the source's validated `headers` map, resolving /// any `${secret:NAME}` references. Header names and values are otherwise passed /// through verbatim; the transport validates them and redacts sensitive ones. @@ -327,7 +349,12 @@ impl SkillAdapter for HttpSkillAdapter { browser_user_agent(&request.env), ) .map_err(|error| failure(format!("http transport unavailable: {error}")))?; - let mut output = execute_http_call(&transport, &call, &merged_inputs(&request))?; + let mut output = execute_http_call( + &transport, + &call, + &merged_inputs(&request), + request.credential_delivery.secret_env(), + )?; add_credential_delivery_metadata(&mut output, &request.credential_delivery)?; Ok(output) } @@ -396,6 +423,10 @@ mod tests { .collect() } + fn empty_secrets() -> SecretEnv { + SecretEnv::default() + } + fn http_invocation( allow_private_network: Option, env: BTreeMap, @@ -467,7 +498,12 @@ mod tests { url: "https://api.example.test/v1/pets".to_owned(), headers: Vec::new(), }; - let output = execute_http_call(&transport, &call, &inputs(&[("id", "p-7")]))?; + let output = execute_http_call( + &transport, + &call, + &inputs(&[("id", "p-7")]), + &empty_secrets(), + )?; assert_eq!(output.status, InvocationStatus::Success); assert_eq!(output.stdout, r#"{"ok":true}"#); let sent = transport.requests.borrow(); @@ -487,7 +523,12 @@ mod tests { url: "https://api.example.test/v1/pets".to_owned(), headers: Vec::new(), }; - execute_http_call(&transport, &call, &inputs(&[("name", "rex")]))?; + execute_http_call( + &transport, + &call, + &inputs(&[("name", "rex")]), + &empty_secrets(), + )?; let sent = transport.requests.borrow(); assert!( sent[0] @@ -500,6 +541,41 @@ mod tests { Ok(()) } + #[test] + fn post_substitutes_secret_references_in_json_body() -> Result<(), RuntimeError> { + let delivery = crate::credentials::CredentialDelivery::from_local_descriptor( + "github", + "bearer", + "GITHUB_TOKEN", + "credential:test", + vec!["github.issue-create".to_owned()], + "ghp_secret", + ) + .map_err(|error| failure(format!("building test credential: {error}")))?; + let transport = stub(201, ""); + let call = HttpCall { + method: HttpMethod::Post, + url: "https://api.example.test/v1/pets".to_owned(), + headers: Vec::new(), + }; + execute_http_call( + &transport, + &call, + &inputs(&[("token", "${secret:GITHUB_TOKEN}")]), + delivery.secret_env(), + )?; + let sent = transport.requests.borrow(); + assert!( + sent[0] + .body + .as_deref() + .is_some_and(|body| body.contains(r#""token":"ghp_secret""#)), + "POST body should substitute delivered secret refs; got: {:?}", + sent[0].body + ); + Ok(()) + } + #[test] fn path_template_substitutes_inputs_and_drops_them_from_the_query() -> Result<(), RuntimeError> { @@ -513,6 +589,7 @@ mod tests { &transport, &call, &inputs(&[("id", "p-7"), ("fields", "name")]), + &empty_secrets(), )?; let sent = transport.requests.borrow(); assert!( @@ -534,23 +611,47 @@ mod tests { headers: Vec::new(), }; assert!( - execute_http_call(&transport, &call, &JsonObject::new()).is_err(), + execute_http_call(&transport, &call, &JsonObject::new(), &empty_secrets()).is_err(), "a placeholder with no matching input must fail closed" ); assert!( - execute_http_call(&transport, &call, &inputs(&[("id", "a/b")])).is_err(), + execute_http_call( + &transport, + &call, + &inputs(&[("id", "a/b")]), + &empty_secrets() + ) + .is_err(), "a path value with a path separator must fail closed" ); assert!( - execute_http_call(&transport, &call, &inputs(&[("id", "a#b")])).is_err(), + execute_http_call( + &transport, + &call, + &inputs(&[("id", "a#b")]), + &empty_secrets() + ) + .is_err(), "a path value with a fragment delimiter must fail closed" ); assert!( - execute_http_call(&transport, &call, &inputs(&[("id", "a%2Fb")])).is_err(), + execute_http_call( + &transport, + &call, + &inputs(&[("id", "a%2Fb")]), + &empty_secrets() + ) + .is_err(), "a path value with an encoded path delimiter must fail closed" ); assert!( - execute_http_call(&transport, &call, &inputs(&[("id", "a%3Fb")])).is_err(), + execute_http_call( + &transport, + &call, + &inputs(&[("id", "a%3Fb")]), + &empty_secrets() + ) + .is_err(), "a path value with an encoded query delimiter must fail closed" ); } @@ -563,7 +664,12 @@ mod tests { url: "https://api.example.test/v1/pets/p-7".to_owned(), headers: Vec::new(), }; - execute_http_call(&transport, &call, &inputs(&[("name", "rex")]))?; + execute_http_call( + &transport, + &call, + &inputs(&[("name", "rex")]), + &empty_secrets(), + )?; let sent = transport.requests.borrow(); assert!( sent[0].method == HttpMethod::Put @@ -585,7 +691,12 @@ mod tests { url: "https://api.example.test/v1/pets/p-7".to_owned(), headers: Vec::new(), }; - execute_http_call(&transport, &call, &inputs(&[("name", "rex")]))?; + execute_http_call( + &transport, + &call, + &inputs(&[("name", "rex")]), + &empty_secrets(), + )?; let sent = transport.requests.borrow(); assert!( sent[0].method == HttpMethod::Patch @@ -607,7 +718,12 @@ mod tests { url: "https://api.example.test/v1/pets".to_owned(), headers: Vec::new(), }; - execute_http_call(&transport, &call, &inputs(&[("id", "p-7")]))?; + execute_http_call( + &transport, + &call, + &inputs(&[("id", "p-7")]), + &empty_secrets(), + )?; let sent = transport.requests.borrow(); assert!( sent[0].method == HttpMethod::Delete @@ -631,7 +747,12 @@ mod tests { RuntimeHttpHeader::new("content-type", "application/cbor"), ], }; - execute_http_call(&transport, &call, &inputs(&[("name", "rex")]))?; + execute_http_call( + &transport, + &call, + &inputs(&[("name", "rex")]), + &empty_secrets(), + )?; let sent = transport.requests.borrow(); let content_types = sent[0] .headers @@ -717,7 +838,7 @@ mod tests { url: "https://api.example.test/v1/pets/none".to_owned(), headers: Vec::new(), }; - let output = execute_http_call(&transport, &call, &JsonObject::new())?; + let output = execute_http_call(&transport, &call, &JsonObject::new(), &empty_secrets())?; assert_eq!(output.status, InvocationStatus::Failure); assert_eq!(output.stdout, "not found"); Ok(()) @@ -731,7 +852,7 @@ mod tests { url: "https://api.example.test/v1/pets".to_owned(), headers: Vec::new(), }; - let output = execute_http_call(&transport, &call, &JsonObject::new())?; + let output = execute_http_call(&transport, &call, &JsonObject::new(), &empty_secrets())?; assert_eq!( output.status, InvocationStatus::Failure, diff --git a/crates/runx-runtime/src/execution/skill_front.rs b/crates/runx-runtime/src/execution/skill_front.rs index d314b72f3..31eb1a721 100644 --- a/crates/runx-runtime/src/execution/skill_front.rs +++ b/crates/runx-runtime/src/execution/skill_front.rs @@ -356,29 +356,50 @@ fn build_domain_act_frame( .and_then(map_decision_choice) .unwrap_or(DecisionChoice::Close); - // The effect ref: a venue id read from the real governed tool result (never - // the model's restatement), wrapped into a domain uri. e.g. the `/v1` - // response's `id` becomes `frantic:judgment:` for the venue to reconcile. - let artifact_refs = governed_effect + let reference_type = match act.effect_type.as_deref().unwrap_or("artifact") { + "act" => ReferenceType::Act, + "tracking_item" => ReferenceType::TrackingItem, + "receipt" => ReferenceType::Receipt, + "provider" | "provider_event" => ReferenceType::ProviderEvent, + "provider_thread" => ReferenceType::ProviderThread, + "provider_comment" => ReferenceType::ProviderComment, + "github_issue" => ReferenceType::GithubIssue, + "external_url" => ReferenceType::ExternalUrl, + _ => ReferenceType::Artifact, + }; + let prefix = resolve( + act.effect_prefix_from.as_deref(), + act.effect_prefix.as_deref(), + ) + .unwrap_or_default(); + let effect_ref = |id: &str| { + let id = id.trim(); + (!id.is_empty()) + .then(|| Reference::with_uri(reference_type.clone(), format!("{prefix}{id}"))) + }; + let mut artifact_refs = Vec::new(); + if let Some(reference) = act + .effect_from_input + .as_deref() + .and_then(|key| inputs.get(key)) + .and_then(JsonValue::as_str) + .and_then(effect_ref) + { + artifact_refs.push(reference); + } + if let Some(reference) = governed_effect .and_then(|effect| { - let field = resolve(None, act.effect_from.as_deref())?; - let id = effect + let field = resolve(act.effect_field_from.as_deref(), act.effect_from.as_deref())?; + effect .as_object() .and_then(|object| object.get(field.as_str())) .and_then(JsonValue::as_str) - .map(str::trim) - .filter(|value| !value.is_empty())?; - let reference_type = match act.effect_type.as_deref().unwrap_or("artifact") { - "act" => ReferenceType::Act, - "tracking_item" => ReferenceType::TrackingItem, - "receipt" => ReferenceType::Receipt, - _ => ReferenceType::Artifact, - }; - let prefix = resolve(None, act.effect_prefix.as_deref()).unwrap_or_default(); - Some(Reference::with_uri(reference_type, format!("{prefix}{id}"))) + .and_then(effect_ref) }) - .into_iter() - .collect::>(); + .filter(|reference| !artifact_refs.contains(reference)) + { + artifact_refs.push(reference); + } Some(DomainActFrame { form, diff --git a/crates/runx-runtime/src/tool_catalogs/build.rs b/crates/runx-runtime/src/tool_catalogs/build.rs index a224c950a..425d8631f 100644 --- a/crates/runx-runtime/src/tool_catalogs/build.rs +++ b/crates/runx-runtime/src/tool_catalogs/build.rs @@ -86,8 +86,6 @@ fn build_tool_manifest( let manifest_path = tool_dir.join("manifest.json"); let source = fs::read_to_string(&manifest_path) .map_err(|error| ToolCatalogError::io("reading tool manifest", &manifest_path, error))?; - let raw: RawToolManifest = serde_json::from_str(&source) - .map_err(|error| ToolCatalogError::json("parsing tool manifest", &manifest_path, error))?; let raw_payload: JsonPayload = serde_json::from_str(&source) .map_err(|error| ToolCatalogError::json("parsing tool manifest", &manifest_path, error))?; let JsonPayload::Object(raw_object) = raw_payload else { @@ -96,6 +94,13 @@ fn build_tool_manifest( message: "manifest.json must be an object.".to_owned(), }); }; + let normalized_object = normalize_tool_manifest_shape(raw_object.clone()); + let raw: RawToolManifest = serde_json::from_value( + serde_json::to_value(JsonPayload::Object(normalized_object.clone())).map_err(|error| { + ToolCatalogError::json("normalizing tool manifest", &manifest_path, error) + })?, + ) + .map_err(|error| ToolCatalogError::json("parsing tool manifest", &manifest_path, error))?; let output = raw .output .unwrap_or_else(|| normalize_tool_output(raw.runx.as_ref())); @@ -132,6 +137,29 @@ fn build_tool_manifest( }) } +fn normalize_tool_manifest_shape(mut raw: JsonPayloadObject) -> JsonPayloadObject { + let Some(JsonPayload::Object(source)) = raw.get_mut("source") else { + return raw; + }; + if !matches!( + source.get("type"), + Some(JsonPayload::String(value)) if value == "http" + ) || source.contains_key("http") + { + return raw; + } + let mut http = JsonPayloadObject::new(); + for key in ["url", "method", "headers", "allow_private_network"] { + if let Some(value) = source.remove(key) { + http.insert(key.to_owned(), value); + } + } + if !http.is_empty() { + source.insert("http".to_owned(), JsonPayload::Object(http)); + } + raw +} + fn normalize_tool_output(runx: Option<&JsonPayloadObject>) -> ToolOutput { let artifacts = runx .and_then(|runx| runx.get("artifacts")) diff --git a/docs/reference.md b/docs/reference.md index 39109173e..a13f14181 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -254,6 +254,11 @@ skills/sourcey/ Direct execution accepts the package directory or `SKILL.md` inside it. Flat `foo.md` skill files are no longer a supported execution surface. +Execution profiles use a strict YAML subset: no anchors, aliases, merge keys, +custom tags, multi-document markers, duplicate mapping keys, or unknown profile +fields. Keep capability and receipt mappings explicit in the runner that uses +them. + See `../docs/skill-profile-model.md` for resolution rules, publication modes, trust tiers, MCP export, and composite skill behavior. See `../docs/evolution-model.md` for the evolve lane, the skill/tool boundary, diff --git a/docs/skill-quality-standard.md b/docs/skill-quality-standard.md index 319e4c0f9..e71f71974 100644 --- a/docs/skill-quality-standard.md +++ b/docs/skill-quality-standard.md @@ -70,3 +70,30 @@ The public catalog test enforces the required sections for every skill with `catalog.visibility: public`. Runnable internals belong in owner-local graph stages at `skills//graph//X.yaml`; they are not hidden catalog skills and should not carry public-skill documentation requirements. + +## Execution Profile Discipline + +Use the term **execution profile** for `X.yaml`. The filename stays `X.yaml` for +v1, but public docs and reviews should describe what it is instead of treating +the letter as the concept. + +`X.yaml` owns capability and governance: + +- named runners and default runner choice; +- typed runner inputs and outputs; +- model-vs-deterministic step boundaries; +- tool, adapter, context-skill, and graph wiring; +- authority, approval, and receipt-act mappings; +- side-effect posture: read, draft, plan, mutate, send, pay, or manual-gated; +- inline `harness.cases`. + +Author `X.yaml` in the strict profile YAML subset: no anchors, aliases, merge +keys, custom tags, multi-document markers, duplicate mapping keys, or unknown +profile fields. Capability mappings should be explicit at the runner that uses +them. + +`X.yaml` must not become the home for long strategy, target registries, campaign +copy, generated state, or secrets. Put operating guidance in `SKILL.md`, +`context/`, or `references/`; put deterministic implementation in `tools/` or +explicit runner files. Doctor and catalog review should treat a bloated, +strategy-heavy profile as a maintainability defect even when it parses. diff --git a/packages/cli/src/cli-parser/index.test.ts b/packages/cli/src/cli-parser/index.test.ts new file mode 100644 index 000000000..9c2648749 --- /dev/null +++ b/packages/cli/src/cli-parser/index.test.ts @@ -0,0 +1,101 @@ +import { describe, expect, it } from "vitest"; + +import { + parseRunnerManifestYaml, + parseToolManifestYaml, + SkillParseError, + SkillValidationError, + validateRunnerManifest, +} from "./index.js"; + +describe("CLI runner manifest parser", () => { + it("rejects execution profile YAML references and document markers", () => { + for (const yaml of [ + "---\nskill: example", + "runners:\n one:\n outputs: &shared\n result: string\n", + "runners:\n one:\n outputs: *shared\n", + "runners:\n one:\n runx:\n <<: *shared\n", + "runners:\n one:\n type: !custom graph\n", + ]) { + expect(() => parseRunnerManifestYaml(yaml), yaml).toThrow(SkillParseError); + } + }); + + it("rejects duplicate execution profile mapping keys", () => { + expect(() => parseRunnerManifestYaml(` +runners: + one: + type: agent + type: graph +`)).toThrow(/duplicate mapping key/); + }); + + it("rejects unknown top-level and runner fields", () => { + expect(() => validateRunnerManifest(parseRunnerManifestYaml(` +skill: example +unexpected: true +runners: + one: + type: agent +`))).toThrow(SkillValidationError); + + expect(() => validateRunnerManifest(parseRunnerManifestYaml(` +runners: + one: + type: agent + typo_field: true +`))).toThrow(SkillValidationError); + }); + + it("accepts the governed act effect source fields", () => { + const manifest = validateRunnerManifest(parseRunnerManifestYaml(` +version: "1" +runners: + observe: + type: http + url: https://example.test/observe + method: POST + act: + effect_field_from: effect_field + effect_from_input: thread_locator + effect_prefix_from: effect_prefix +`)); + + expect(manifest.version).toBe("1"); + expect(manifest.runners.observe?.source.act).toMatchObject({ + effect_field_from: "effect_field", + effect_from_input: "thread_locator", + effect_prefix_from: "effect_prefix", + }); + }); + + it("normalizes nested http source declarations", () => { + const manifest = validateRunnerManifest(parseRunnerManifestYaml(` +runners: + fetch: + source: + type: http + http: + url: https://example.test/api + method: GET + headers: + accept: application/json + allow_private_network: false +`)); + + expect(manifest.runners.fetch?.source.http).toEqual({ + url: "https://example.test/api", + method: "GET", + headers: { + accept: "application/json", + }, + allowPrivateNetwork: false, + }); + }); +}); + +describe("CLI tool manifest parser", () => { + it("keeps YAML parity checks for tool manifests", () => { + expect(() => parseToolManifestYaml("name: tool\ndescription: one: two\n")).toThrow(SkillParseError); + }); +}); diff --git a/packages/cli/src/cli-parser/index.ts b/packages/cli/src/cli-parser/index.ts index d78408206..6bb802dcd 100644 --- a/packages/cli/src/cli-parser/index.ts +++ b/packages/cli/src/cli-parser/index.ts @@ -1,6 +1,11 @@ import { parseDocument } from "yaml"; import { validateGraphDocument, type ExecutionGraph } from "./graph.js"; +import { + assertExecutionProfileYamlSubset, + assertYamlParitySubset, + YamlSubsetError, +} from "./yaml-subset.js"; import { normalizeSandboxDeclaration } from "../cli-sandbox.js"; import { GOVERNED_DISPOSITIONS, type ExecutionSemantics } from "../cli-execution-semantics.js"; import { errorMessage, isRecord, readField } from "../cli-util.js"; @@ -53,9 +58,41 @@ export interface SkillSource { readonly hook?: string; readonly outputs?: Readonly>; readonly graph?: ExecutionGraph; + readonly http?: SkillHttpSource; + readonly act?: ActDeclaration; readonly raw: Record; } +export interface SkillHttpSource { + readonly url: string; + readonly method?: string; + readonly headers?: Readonly>; + readonly allowPrivateNetwork?: boolean; +} + +export interface ActDeclaration { + readonly form?: string; + readonly form_from?: string; + readonly purpose?: string; + readonly purpose_from?: string; + readonly legitimacy?: string; + readonly legitimacy_from?: string; + readonly reason_from?: string; + readonly target_from?: string; + readonly decision_from?: string; + readonly effect_from?: string; + readonly effect_field_from?: string; + readonly effect_from_input?: string; + readonly effect_type?: string; + readonly effect_prefix?: string; + readonly effect_prefix_from?: string; + readonly actor_from?: string; + readonly authority_from?: string; + readonly previous_from?: string; + readonly reason_step?: string; + readonly effect_step?: string; +} + export interface SkillArtifactContract { readonly emits?: readonly string[]; readonly namedEmits?: Readonly>; @@ -133,7 +170,7 @@ export interface SkillRunnerDefinition { export type PostRunReflectPolicy = "auto" | "always" | "never"; export type CatalogKind = "skill" | "graph"; -export type CatalogAudience = "public" | "builder" | "operator"; +export type CatalogAudience = "public" | "builder" | "operator" | "system"; export type CatalogVisibility = "public" | "internal"; export type CatalogRole = | "canonical" @@ -196,6 +233,10 @@ export interface RunnerHarnessManifest { export interface SkillRunnerManifest { readonly skill?: string; + readonly version?: string; + readonly runx?: Readonly>; + readonly policy?: unknown; + readonly emits?: unknown; readonly catalog?: CatalogMetadata; readonly runners: Readonly>; readonly harness?: RunnerHarnessManifest; @@ -261,6 +302,7 @@ export function parseSkillMarkdown(markdown: string): RawSkillIR { } export function parseRunnerManifestYaml(yaml: string): RawRunnerManifestIR { + assertYamlSubset("runner_manifest", yaml, "execution-profile"); const document = parseDocument(yaml, { prettyErrors: false }); if (document.errors.length > 0) { throw new SkillParseError(document.errors.map((error) => error.message).join("; ")); @@ -278,6 +320,7 @@ export function parseRunnerManifestYaml(yaml: string): RawRunnerManifestIR { } export function parseToolManifestYaml(yaml: string): RawToolManifestIR { + assertYamlSubset("tool_manifest", yaml, "parity"); const document = parseDocument(yaml, { prettyErrors: false }); if (document.errors.length > 0) { throw new SkillParseError(document.errors.map((error) => error.message).join("; ")); @@ -384,13 +427,18 @@ export function extractSkillQualityProfile(body: string): SkillQualityProfile | export function validateRunnerManifest(raw: RawRunnerManifestIR): SkillRunnerManifest { const runnersRecord = requiredNullableRecord(raw.document.runners, "runners"); + rejectUnknownFields(raw.document, "runner_manifest", ["skill", "version", "runx", "policy", "emits", "catalog", "runners", "harness"]); const runners: Record = {}; for (const [name, value] of Object.entries(runnersRecord)) { const runner = requiredNullableRecord(value, `runners.${name}`); + rejectUnknownFields(runner, `runners.${name}`, runnerFields); const runx = optionalNullableRecord(runner.runx, `runners.${name}.runx`); validatePostRunReflectPolicy(runx, `runners.${name}.runx`); const sourceRecord = optionalNullableRecord(runner.source, `runners.${name}.source`) ?? runner; + if (runner.source !== undefined) { + rejectUnknownFields(sourceRecord, `runners.${name}.source`, sourceFields); + } const risk = runner.risk; runners[name] = { name, @@ -426,6 +474,10 @@ export function validateRunnerManifest(raw: RawRunnerManifestIR): SkillRunnerMan return { skill: optionalNullableString(raw.document.skill, "skill"), + version: optionalNullableString(raw.document.version, "version"), + runx: optionalNullableRecord(raw.document.runx, "runx"), + policy: raw.document.policy, + emits: raw.document.emits, catalog: validateCatalogMetadata(optionalNullableRecord(raw.document.catalog, "catalog"), "catalog"), runners, harness, @@ -449,8 +501,8 @@ function validateCatalogMetadata(value: Record | undefined, lab if (kind !== "skill" && kind !== "graph") { throw new SkillValidationError(`${label}.kind must be skill or graph.`); } - if (audience !== "public" && audience !== "builder" && audience !== "operator") { - throw new SkillValidationError(`${label}.audience must be public, builder, or operator.`); + if (audience !== "public" && audience !== "builder" && audience !== "operator" && audience !== "system") { + throw new SkillValidationError(`${label}.audience must be public, builder, operator, or system.`); } if (visibility !== "public" && visibility !== "internal") { throw new SkillValidationError(`${label}.visibility must be public or internal.`); @@ -586,6 +638,7 @@ export function resolvePostRunReflectPolicy( function validateSource(source: Record, runx: Record | undefined): SkillSource { const type = requiredNullableString(source.type, "source.type"); + validateSourceType(type, "source.type"); const args = optionalNullableStringArray(source.args, "source.args") ?? []; const inputMode = optionalInputMode(source.input_mode); const timeoutSeconds = optionalNullableNumber(source.timeout_seconds, "source.timeout_seconds"); @@ -615,6 +668,8 @@ function validateSource(source: Record, runx: Record, runx: Record, type: string): SkillHttpSource | undefined { + if (type !== "http") { + return undefined; + } + const http = optionalNullableRecord(source.http, "source.http") ?? source; + return { + url: requiredNullableString(http.url, "source.url"), + method: validateHttpMethod(optionalNullableString(http.method, "source.method")), + headers: validateHttpHeaders(http.headers), + allowPrivateNetwork: optionalNullableBoolean(http.allow_private_network, "source.allow_private_network"), + }; +} + +function validateHttpMethod(method: string | undefined): string | undefined { + if (method === undefined) { + return undefined; + } + if (["GET", "POST", "PUT", "PATCH", "DELETE"].includes(method.toUpperCase())) { + return method; + } + throw new SkillValidationError(`source.method ${method} is not supported; use GET, POST, PUT, PATCH, or DELETE.`); +} + +function validateHttpHeaders(value: unknown): Readonly> | undefined { + const headers = optionalNullableRecord(value, "source.headers"); + if (!headers) { + return undefined; + } + for (const [key, entry] of Object.entries(headers)) { + if (typeof entry !== "string") { + throw new SkillValidationError(`source.headers.${key} must be a string.`); + } + } + return headers as Readonly>; +} + +const actFields = [ + "form", + "form_from", + "purpose", + "purpose_from", + "legitimacy", + "legitimacy_from", + "reason_from", + "target_from", + "decision_from", + "effect_from", + "effect_field_from", + "effect_from_input", + "effect_type", + "effect_prefix", + "effect_prefix_from", + "actor_from", + "authority_from", + "previous_from", + "reason_step", + "effect_step", +] as const; + +function validateActDeclaration(value: unknown, field: string): ActDeclaration | undefined { + const record = optionalNullableRecord(value, field); + if (!record) { + return undefined; + } + rejectUnknownFields(record, field, actFields); + const validated: Record = {}; + for (const key of actFields) { + const entry = optionalNullableString(record[key], `${field}.${key}`); + if (entry !== undefined) { + validated[key] = entry; + } + } + return validated; +} + function validateSandbox(value: unknown): SkillSandbox | undefined { if (value === undefined || value === null) { return undefined; @@ -1114,5 +1253,101 @@ function optionalCwdPolicy(value: unknown): SkillSandbox["cwdPolicy"] { throw new SkillValidationError("sandbox.cwd_policy must be skill-directory, workspace, or custom."); } +function rejectUnknownFields( + record: Record, + field: string, + allowed: readonly string[], +): void { + for (const key of Object.keys(record)) { + if (!allowed.includes(key)) { + throw new SkillValidationError(`${field}.${key} is not supported; allowed fields: ${allowed.join(", ")}.`); + } + } +} + +function assertYamlSubset(field: string, yaml: string, kind: "execution-profile" | "parity"): void { + try { + if (kind === "execution-profile") { + assertExecutionProfileYamlSubset(field, yaml); + } else { + assertYamlParitySubset(field, yaml); + } + } catch (error) { + if (error instanceof YamlSubsetError) { + throw new SkillParseError(error.message, { cause: error }); + } + throw error; + } +} + +const sourceTypes = [ + "cli-tool", + "mcp", + "catalog", + "a2a", + "agent", + "agent-task", + "harness-hook", + "graph", + "http", + "external-adapter", + "thread-outbox-provider", +] as const; + +const sourceFields = [ + "act", + "agent", + "agent_card_url", + "agent_identity", + "allow_private_network", + "args", + "arguments", + "catalog_ref", + "command", + "cwd", + "external_adapter", + "external_adapter_manifest", + "external_adapter_manifest_path", + "graph", + "headers", + "hook", + "http", + "input_mode", + "invocation_id", + "method", + "outputs", + "run_id", + "sandbox", + "server", + "skill_ref", + "task", + "timeout_seconds", + "tool", + "type", + "url", +] as const; + +const runnerFields = [ + ...sourceFields, + "allowed_tools", + "artifacts", + "auth", + "context", + "context_skills", + "default", + "execution", + "idempotency", + "inputs", + "instructions", + "mutating", + "policy", + "retry", + "risk", + "runx", + "runtime", + "scopes", + "source", +] as const; + export * from "./graph.js"; diff --git a/packages/cli/src/cli-parser/yaml-subset.ts b/packages/cli/src/cli-parser/yaml-subset.ts new file mode 100644 index 000000000..e13b11f46 --- /dev/null +++ b/packages/cli/src/cli-parser/yaml-subset.ts @@ -0,0 +1,393 @@ +const divergentBoolish = ["yes", "no", "on", "off"] as const; + +export class YamlSubsetError extends Error { + constructor(message: string) { + super(message); + this.name = "YamlSubsetError"; + } +} + +export function assertYamlParitySubset(field: string, source: string): void { + let blockScalarIndent: number | undefined; + for (const [lineIndex, line] of source.split(/\r?\n/).entries()) { + const lineNumber = lineIndex + 1; + const content = stripYamlComment(line); + if (content === undefined) { + continue; + } + const trimmed = content.trim(); + if (blockScalarIndent !== undefined) { + if (trimmed === "" || leadingSpaces(content) > blockScalarIndent) { + continue; + } + blockScalarIndent = undefined; + } + if (trimmed === "" || trimmed.startsWith("---") || trimmed.startsWith("...")) { + continue; + } + rejectExplicitMappingKey(field, lineNumber, trimmed); + rejectEmbeddedColonKey(field, lineNumber, trimmed); + rejectColonSpacePlainScalar(field, lineNumber, content); + blockScalarIndent = blockScalarIndentAfter(content) ?? blockScalarIndent; + } +} + +export function assertExecutionProfileYamlSubset(field: string, source: string): void { + assertYamlParitySubset(field, source); + const mappingStack: MappingFrame[] = []; + let blockScalarIndent: number | undefined; + for (const [lineIndex, line] of source.split(/\r?\n/).entries()) { + const lineNumber = lineIndex + 1; + const content = stripYamlComment(line); + if (content === undefined) { + continue; + } + const trimmed = content.trim(); + if (blockScalarIndent !== undefined) { + if (trimmed === "" || leadingSpaces(content) > blockScalarIndent) { + continue; + } + blockScalarIndent = undefined; + } + if (trimmed === "") { + continue; + } + rejectDocumentMarker(field, lineNumber, trimmed); + rejectYamlReferenceSyntax(field, lineNumber, content); + rejectDuplicateMappingKey(field, lineNumber, content, mappingStack); + blockScalarIndent = blockScalarIndentAfter(content) ?? blockScalarIndent; + } +} + +export function yamlScalarSubsetAllows(literal: string): boolean { + const trimmed = literal.trim(); + return !isBoolish(trimmed) + && !isBasePrefixedNumber(trimmed) + && !isSexagesimalLike(trimmed) + && !isDateLike(trimmed) + && !isSpecialFloat(trimmed); +} + +export function assertYamlScalarSubset(field: string, literal: string): void { + if (yamlScalarSubsetAllows(literal)) { + return; + } + throw new YamlSubsetError(`${field} uses unsupported YAML scalar ${JSON.stringify(literal)}.`); +} + +function stripYamlComment(line: string): string | undefined { + const scanner = new QuoteScanner(); + for (let index = 0; index < line.length; index += 1) { + const char = line[index]!; + if (scanner.isPlainAt(char) && char === "#" && isCommentStart(line, index)) { + return line.slice(0, index); + } + scanner.consume(char); + } + return line; +} + +function isCommentStart(line: string, index: number): boolean { + return index === 0 || /\s/.test(line[index - 1]!); +} + +function rejectExplicitMappingKey(field: string, lineNumber: number, trimmed: string): void { + if (trimmed === "?" || trimmed.startsWith("? ")) { + throw ambiguousYaml(field, lineNumber, trimmed); + } +} + +function rejectEmbeddedColonKey(field: string, lineNumber: number, trimmed: string): void { + const key = topLevelPlainKey(trimmed)?.[0]; + if (key?.includes(":")) { + throw ambiguousYaml(field, lineNumber, trimmed); + } +} + +function topLevelPlainKey(trimmed: string): [string, number] | undefined { + const first = trimmed[0]; + if (first === undefined || ["-", "?", "{", "[", "\"", "'"].includes(first)) { + return undefined; + } + const scanner = new QuoteScanner(); + for (let index = 0; index < trimmed.length; index += 1) { + const char = trimmed[index]!; + if (scanner.isPlainAt(char) && char === ":" && isMappingDelimiter(trimmed, index)) { + return [trimmed.slice(0, index).trim(), index]; + } + scanner.consume(char); + } + return undefined; +} + +type QuoteState = + | "plain" + | "in-double" + | "in-single-pending-apostrophe" + | "in-single" + | "in-double-escape"; + +class QuoteScanner { + private state: QuoteState = "plain"; + + isPlainAt(char: string): boolean { + if (this.state === "plain") { + return true; + } + if (this.state === "in-single-pending-apostrophe") { + return char !== "'"; + } + return false; + } + + consume(char: string): void { + if (this.state === "plain") { + this.state = this.plainStateAfter(char); + return; + } + if (this.state === "in-double") { + this.state = char === "\\" ? "in-double-escape" : char === "\"" ? "plain" : "in-double"; + return; + } + if (this.state === "in-double-escape") { + this.state = "in-double"; + return; + } + if (this.state === "in-single") { + this.state = char === "'" ? "in-single-pending-apostrophe" : "in-single"; + return; + } + this.state = char === "'" ? "in-single" : this.plainStateAfter(char); + } + + private plainStateAfter(char: string): QuoteState { + if (char === "'") { + return "in-single"; + } + if (char === "\"") { + return "in-double"; + } + return "plain"; + } +} + +function isMappingDelimiter(value: string, index: number): boolean { + const next = value[index + 1]; + return next === undefined || /\s/.test(next); +} + +function rejectColonSpacePlainScalar(field: string, lineNumber: number, content: string): void { + const split = splitPlainMappingValue(content); + if (!split) { + return; + } + const [, value] = split; + if (plainScalarContainsColonSpace(value)) { + throw ambiguousYaml(field, lineNumber, value.trim()); + } +} + +function rejectDocumentMarker(field: string, lineNumber: number, trimmed: string): void { + if ( + trimmed === "---" + || trimmed === "..." + || trimmed.startsWith("--- ") + || trimmed.startsWith("... ") + ) { + throw new YamlSubsetError( + `${field}: YAML document markers are not supported in X.yaml at line ${lineNumber}; use one plain profile document.`, + ); + } +} + +function rejectYamlReferenceSyntax(field: string, lineNumber: number, content: string): void { + for (const token of [": &", ": *", ": !", "- &", "- *", "- !"] as const) { + if (containsPlainToken(content, token)) { + throw new YamlSubsetError( + `${field}: YAML anchors, aliases, and tags are not supported in X.yaml at line ${lineNumber}; write the profile explicitly.`, + ); + } + } + const trimmed = content.trimStart(); + if (trimmed.startsWith("&") || trimmed.startsWith("*") || trimmed.startsWith("!")) { + throw new YamlSubsetError( + `${field}: YAML anchors, aliases, and tags are not supported in X.yaml at line ${lineNumber}; write the profile explicitly.`, + ); + } +} + +function containsPlainToken(content: string, token: string): boolean { + const scanner = new QuoteScanner(); + for (let index = 0; index < content.length; index += 1) { + const char = content[index]!; + if (scanner.isPlainAt(char) && content.startsWith(token, index)) { + return true; + } + scanner.consume(char); + } + return false; +} + +interface MappingFrame { + readonly indent: number; + readonly keys: Set; +} + +function rejectDuplicateMappingKey( + field: string, + lineNumber: number, + content: string, + stack: MappingFrame[], +): void { + const indent = leadingSpaces(content); + const trimmed = content.trimStart(); + const sequenceKey = sequenceItemKey(trimmed, indent); + const keyMatch = sequenceKey + ? { keyIndent: sequenceKey[0], key: sequenceKey[1], sequenceItem: true } + : topLevelPlainKey(trimmed) + ? { keyIndent: indent, key: topLevelPlainKey(trimmed)![0], sequenceItem: false } + : undefined; + if (!keyMatch) { + return; + } + const { key, keyIndent, sequenceItem } = keyMatch; + if (key === "<<") { + throw new YamlSubsetError( + `${field}: YAML merge keys are not supported in X.yaml at line ${lineNumber}; write the profile explicitly.`, + ); + } + if (sequenceItem) { + while (stack.at(-1) && stack.at(-1)!.indent >= keyIndent) { + stack.pop(); + } + } else { + while (stack.at(-1) && stack.at(-1)!.indent > keyIndent) { + stack.pop(); + } + } + if (!stack.at(-1) || stack.at(-1)!.indent !== keyIndent) { + stack.push({ indent: keyIndent, keys: new Set() }); + } + const frame = stack.at(-1)!; + if (frame.keys.has(key)) { + throw new YamlSubsetError( + `${field}: duplicate mapping key ${JSON.stringify(key)} in X.yaml at line ${lineNumber}; keep profile keys unique.`, + ); + } + frame.keys.add(key); +} + +function blockScalarIndentAfter(content: string): number | undefined { + return blockScalarValueCandidates(content).some(isBlockScalarHeader) ? leadingSpaces(content) : undefined; +} + +function blockScalarValueCandidates(content: string): string[] { + const candidates: string[] = []; + const mapping = splitPlainMappingValue(content); + if (mapping) { + candidates.push(mapping[1]); + } + const trimmed = content.trimStart(); + if (trimmed.startsWith("- ")) { + const item = trimmed.slice(2).trimStart(); + candidates.push(item); + const itemMapping = splitPlainMappingValue(item); + if (itemMapping) { + candidates.push(itemMapping[1]); + } + } + return candidates; +} + +function isBlockScalarHeader(value: string): boolean { + return /^[|>](?:[+-]?\d?|\d?[+-]?)$/.test(value.trim()); +} + +function sequenceItemKey(trimmed: string, indent: number): [number, string] | undefined { + const rest = trimmed.startsWith("- ") ? trimmed.slice(2) : undefined; + if (rest === undefined) { + return undefined; + } + const item = rest.trimStart(); + const leading = rest.length - item.length; + const key = topLevelPlainKey(item)?.[0]; + return key === undefined ? undefined : [indent + 2 + leading, key]; +} + +function leadingSpaces(content: string): number { + return content.length - content.trimStart().length; +} + +function splitPlainMappingValue(content: string): [string, string] | undefined { + const trimmed = content.trimStart(); + const split = topLevelPlainKey(trimmed); + if (!split) { + return undefined; + } + const [key, delimiterIndex] = split; + return [key, trimmed.slice(delimiterIndex + 1)]; +} + +function plainScalarContainsColonSpace(value: string): boolean { + const trimmed = value.trimStart(); + if ( + trimmed === "" + || trimmed.startsWith("\"") + || trimmed.startsWith("'") + || trimmed.startsWith("|") + || trimmed.startsWith(">") + || trimmed.startsWith("{") + || trimmed.startsWith("[") + || trimmed === "null" + || trimmed === "true" + || trimmed === "false" + ) { + return false; + } + return containsUnquotedColonSpace(trimmed); +} + +function containsUnquotedColonSpace(value: string): boolean { + const scanner = new QuoteScanner(); + for (let index = 0; index < value.length; index += 1) { + const char = value[index]!; + if (scanner.isPlainAt(char) && char === ":" && isMappingDelimiter(value, index)) { + return true; + } + scanner.consume(char); + } + return false; +} + +function ambiguousYaml(field: string, lineNumber: number, literal: string): YamlSubsetError { + return new YamlSubsetError( + `${field}: ambiguous YAML construct at line ${lineNumber}; quote the value or key: ${literal}`, + ); +} + +function isBoolish(value: string): boolean { + return divergentBoolish.some((candidate) => candidate.toLowerCase() === value.toLowerCase()); +} + +function isBasePrefixedNumber(value: string): boolean { + const unsigned = value.replace(/^[+-]/, ""); + return unsigned.startsWith("0x") || unsigned.startsWith("0X") || unsigned.startsWith("0o"); +} + +function isSexagesimalLike(value: string): boolean { + const unsigned = value.replace(/^[+-]/, ""); + const parts = unsigned.split(":"); + const [first, ...rest] = parts; + return Boolean(first) + && /^\d+$/.test(first) + && rest.length > 0 + && rest.every((part) => part !== "" && /^\d+$/.test(part)); +} + +function isDateLike(value: string): boolean { + return /^\d{4}-\d{2}-\d{2}/.test(value); +} + +function isSpecialFloat(value: string): boolean { + return [".nan", ".inf", "+.inf", "-.inf"].includes(value.toLowerCase()); +} diff --git a/scripts/generate-official-lock.mjs b/scripts/generate-official-lock.mjs index b96665d76..3ec2c9a64 100644 --- a/scripts/generate-official-lock.mjs +++ b/scripts/generate-official-lock.mjs @@ -76,6 +76,7 @@ function parseSkillFrontmatter(markdown) { } function parseRunnerManifest(profileDocument) { + assertExecutionProfileYamlSubset("runner_manifest", profileDocument); const manifest = YAML.parse(profileDocument); if (!manifest || typeof manifest !== "object") { throw new Error("Official X.yaml must parse to an object."); @@ -170,3 +171,170 @@ function rustOfficialLock(entries) { ); return lines.join("\n"); } + +function assertExecutionProfileYamlSubset(field, source) { + const stack = []; + let blockScalarIndent; + for (const [lineIndex, line] of source.split(/\r?\n/).entries()) { + const lineNumber = lineIndex + 1; + const content = stripYamlComment(line); + if (content === undefined) continue; + const trimmed = content.trim(); + if (blockScalarIndent !== undefined) { + if (trimmed === "" || leadingSpaces(content) > blockScalarIndent) continue; + blockScalarIndent = undefined; + } + if (trimmed === "") continue; + if (trimmed === "---" || trimmed === "..." || trimmed.startsWith("--- ") || trimmed.startsWith("... ")) { + throw new Error(`${field}: YAML document markers are not supported in X.yaml at line ${lineNumber}; use one plain profile document.`); + } + for (const token of [": &", ": *", ": !", "- &", "- *", "- !"]) { + if (containsPlainToken(content, token)) { + throw new Error(`${field}: YAML anchors, aliases, and tags are not supported in X.yaml at line ${lineNumber}; write the profile explicitly.`); + } + } + const trimmedStart = content.trimStart(); + if (trimmedStart.startsWith("&") || trimmedStart.startsWith("*") || trimmedStart.startsWith("!")) { + throw new Error(`${field}: YAML anchors, aliases, and tags are not supported in X.yaml at line ${lineNumber}; write the profile explicitly.`); + } + rejectDuplicateMappingKey(field, lineNumber, content, stack); + blockScalarIndent = blockScalarIndentAfter(content) ?? blockScalarIndent; + } +} + +function stripYamlComment(line) { + const scanner = createQuoteScanner(); + for (let index = 0; index < line.length; index += 1) { + const char = line[index]; + if (scanner.isPlainAt(char) && char === "#" && (index === 0 || /\s/.test(line[index - 1]))) { + return line.slice(0, index); + } + scanner.consume(char); + } + return line; +} + +function containsPlainToken(content, token) { + const scanner = createQuoteScanner(); + for (let index = 0; index < content.length; index += 1) { + const char = content[index]; + if (scanner.isPlainAt(char) && content.startsWith(token, index)) { + return true; + } + scanner.consume(char); + } + return false; +} + +function createQuoteScanner() { + let state = "plain"; + return { + isPlainAt(char) { + if (state === "plain") return true; + if (state === "in-single-pending-apostrophe") return char !== "'"; + return false; + }, + consume(char) { + if (state === "plain") { + state = plainStateAfter(char); + } else if (state === "in-double") { + state = char === "\\" ? "in-double-escape" : char === "\"" ? "plain" : "in-double"; + } else if (state === "in-double-escape") { + state = "in-double"; + } else if (state === "in-single") { + state = char === "'" ? "in-single-pending-apostrophe" : "in-single"; + } else { + state = char === "'" ? "in-single" : plainStateAfter(char); + } + }, + }; + + function plainStateAfter(char) { + if (char === "'") return "in-single"; + if (char === "\"") return "in-double"; + return "plain"; + } +} + +function rejectDuplicateMappingKey(field, lineNumber, content, stack) { + const indent = leadingSpaces(content); + const trimmed = content.trimStart(); + const sequence = sequenceItemKey(trimmed, indent); + const plain = sequence ?? topLevelPlainKey(trimmed)?.map((value, index) => index === 0 ? value : indent); + if (!plain) return; + const keyIndent = sequence ? sequence[0] : indent; + const key = sequence ? sequence[1] : plain[0]; + const sequenceItem = Boolean(sequence); + if (key === "<<") { + throw new Error(`${field}: YAML merge keys are not supported in X.yaml at line ${lineNumber}; write the profile explicitly.`); + } + while (stack.at(-1) && (sequenceItem ? stack.at(-1).indent >= keyIndent : stack.at(-1).indent > keyIndent)) { + stack.pop(); + } + if (!stack.at(-1) || stack.at(-1).indent !== keyIndent) { + stack.push({ indent: keyIndent, keys: new Set() }); + } + const frame = stack.at(-1); + if (frame.keys.has(key)) { + throw new Error(`${field}: duplicate mapping key ${JSON.stringify(key)} in X.yaml at line ${lineNumber}; keep profile keys unique.`); + } + frame.keys.add(key); +} + +function blockScalarIndentAfter(content) { + return blockScalarValueCandidates(content).some(isBlockScalarHeader) ? leadingSpaces(content) : undefined; +} + +function blockScalarValueCandidates(content) { + const candidates = []; + const mapping = splitPlainMappingValue(content); + if (mapping) candidates.push(mapping[1]); + const trimmed = content.trimStart(); + if (trimmed.startsWith("- ")) { + const item = trimmed.slice(2).trimStart(); + candidates.push(item); + const itemMapping = splitPlainMappingValue(item); + if (itemMapping) candidates.push(itemMapping[1]); + } + return candidates; +} + +function isBlockScalarHeader(value) { + return /^[|>](?:[+-]?\d?|\d?[+-]?)$/.test(value.trim()); +} + +function splitPlainMappingValue(content) { + const trimmed = content.trimStart(); + const split = topLevelPlainKey(trimmed); + return split ? [split[0], trimmed.slice(split[1] + 1)] : undefined; +} + +function leadingSpaces(content) { + return content.length - content.trimStart().length; +} + +function sequenceItemKey(trimmed, indent) { + if (!trimmed.startsWith("- ")) return undefined; + const rest = trimmed.slice(2); + const item = rest.trimStart(); + const key = topLevelPlainKey(item)?.[0]; + return key === undefined ? undefined : [indent + 2 + rest.length - item.length, key]; +} + +function topLevelPlainKey(trimmed) { + const first = trimmed[0]; + if (!first || ["-", "?", "{", "[", "\"", "'"].includes(first)) return undefined; + const scanner = createQuoteScanner(); + for (let index = 0; index < trimmed.length; index += 1) { + const char = trimmed[index]; + if (scanner.isPlainAt(char) && char === ":" && isMappingDelimiter(trimmed, index)) { + return [trimmed.slice(0, index).trim(), index]; + } + scanner.consume(char); + } + return undefined; +} + +function isMappingDelimiter(value, index) { + return value[index + 1] === undefined || /\s/.test(value[index + 1]); +} diff --git a/skills/spend/graph/pay-fulfill-rail/X.yaml b/skills/spend/graph/pay-fulfill-rail/X.yaml index 34655707a..2876ad7f2 100644 --- a/skills/spend/graph/pay-fulfill-rail/X.yaml +++ b/skills/spend/graph/pay-fulfill-rail/X.yaml @@ -91,16 +91,16 @@ runners: max_attempts: 1 idempotency: key: pay-fulfill-rail-mock - outputs: &a1 + outputs: rail_result: object rail_proof: object credential_envelope: object redactions: array recovery_hint: object - artifacts: &a2 + artifacts: wrap_as: effect_evidence_packet packet: runx.effect.evidence.v1 - runx: &a3 + runx: payment_authority: phase: fulfill resource_family: effect @@ -110,7 +110,7 @@ runners: authorization_form: single_use_capability receives_funding_material: false receipt_before_success: true - inputs: &a4 + inputs: payment_challenge: type: object required: true @@ -148,10 +148,16 @@ runners: max_attempts: 1 idempotency: key: payment-rail-x402 - outputs: *a1 - artifacts: *a2 + outputs: + rail_result: object + rail_proof: object + credential_envelope: object + redactions: array + recovery_hint: object + artifacts: + wrap_as: effect_evidence_packet + packet: runx.effect.evidence.v1 runx: - <<: *a3 payment_authority: phase: fulfill resource_family: effect @@ -163,7 +169,35 @@ runners: authorization_form: single_use_capability receives_funding_material: false receipt_before_success: true - inputs: *a4 + inputs: + payment_challenge: + type: object + required: true + description: Protocol/provider challenge to fulfill. + reserved_payment_authority: + type: object + required: true + description: Child payment authority term admitted by core. + spend_capability_ref: + type: object + required: true + description: Scoped single-use spend capability reference. + rail_profile_ref: + type: string + required: true + description: Configured rail profile reference. + payment_admission: + type: object + required: false + description: Hosted payment admission token and settlement identity. + idempotency: + type: object + required: true + description: Reservation key and recovery lookup fields. + quote_packet: + type: object + required: false + description: Source quote packet for evidence continuity. mpp: type: agent-task agent: operator @@ -173,10 +207,16 @@ runners: max_attempts: 1 idempotency: key: payment-rail-mpp - outputs: *a1 - artifacts: *a2 + outputs: + rail_result: object + rail_proof: object + credential_envelope: object + redactions: array + recovery_hint: object + artifacts: + wrap_as: effect_evidence_packet + packet: runx.effect.evidence.v1 runx: - <<: *a3 payment_authority: phase: fulfill resource_family: effect @@ -188,7 +228,35 @@ runners: authorization_form: single_use_capability receives_funding_material: false receipt_before_success: true - inputs: *a4 + inputs: + payment_challenge: + type: object + required: true + description: Protocol/provider challenge to fulfill. + reserved_payment_authority: + type: object + required: true + description: Child payment authority term admitted by core. + spend_capability_ref: + type: object + required: true + description: Scoped single-use spend capability reference. + rail_profile_ref: + type: string + required: true + description: Configured rail profile reference. + payment_admission: + type: object + required: false + description: Hosted payment admission token and settlement identity. + idempotency: + type: object + required: true + description: Reservation key and recovery lookup fields. + quote_packet: + type: object + required: false + description: Source quote packet for evidence continuity. stripe-spt: source: type: external-adapter @@ -199,10 +267,16 @@ runners: max_attempts: 1 idempotency: key: payment-rail-stripe-spt - outputs: *a1 - artifacts: *a2 + outputs: + rail_result: object + rail_proof: object + credential_envelope: object + redactions: array + recovery_hint: object + artifacts: + wrap_as: effect_evidence_packet + packet: runx.effect.evidence.v1 runx: - <<: *a3 payment_authority: phase: fulfill resource_family: effect @@ -214,4 +288,32 @@ runners: authorization_form: single_use_capability receives_funding_material: false receipt_before_success: true - inputs: *a4 + inputs: + payment_challenge: + type: object + required: true + description: Protocol/provider challenge to fulfill. + reserved_payment_authority: + type: object + required: true + description: Child payment authority term admitted by core. + spend_capability_ref: + type: object + required: true + description: Scoped single-use spend capability reference. + rail_profile_ref: + type: string + required: true + description: Configured rail profile reference. + payment_admission: + type: object + required: false + description: Hosted payment admission token and settlement identity. + idempotency: + type: object + required: true + description: Reservation key and recovery lookup fields. + quote_packet: + type: object + required: false + description: Source quote packet for evidence continuity. From 897951345483ddb97b3bb1f086707037c51d79ef Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 21:26:44 +1000 Subject: [PATCH 27/64] fix(scafld): enforce minimum runner version --- skills/issue-to-pr/graph/scafld/run.mjs | 71 +++++++++++++++++++++++++ tests/scafld-skill-parser.test.ts | 54 +++++++++++++++++++ 2 files changed, 125 insertions(+) diff --git a/skills/issue-to-pr/graph/scafld/run.mjs b/skills/issue-to-pr/graph/scafld/run.mjs index 39dc0900e..7a7ddb29e 100644 --- a/skills/issue-to-pr/graph/scafld/run.mjs +++ b/skills/issue-to-pr/graph/scafld/run.mjs @@ -12,6 +12,7 @@ const scafldSource = inputs.scafld_bin ? "env:SCAFLD_BIN" : "path:scafld"; const scafld = resolveBinary(scafldCandidate); +const minimumScafldVersion = String(inputs.scafld_min_version || "2.4.0"); const cwd = path.resolve(String( inputs.fixture || inputs.cwd @@ -136,6 +137,20 @@ if (path.isAbsolute(scafld) || scafld.includes(path.sep)) { env.PATH = `${path.dirname(scafld)}${path.delimiter}${env.PATH || "/usr/local/bin:/usr/bin:/bin"}`; } +try { + ensureScafldVersion({ + scafldBinary: scafld, + source: scafldSource, + requestedBinary: scafldCandidate, + workingDirectory: cwd, + processEnv: env, + minimum: minimumScafldVersion, + }); +} catch (error) { + console.error(error.message); + process.exit(1); +} + if (command === "build_to_review") { const outcome = runBuildToReview({ scafld, @@ -456,6 +471,62 @@ function parseMaxBuilds(value) { return 12; } +function ensureScafldVersion({ scafldBinary, source, requestedBinary, workingDirectory, processEnv, minimum }) { + const result = spawnSync(scafldBinary, ["--version"], { + cwd: workingDirectory, + env: processEnv, + encoding: "utf8", + shell: false, + }); + if (result.error) { + throw new Error(formatSpawnError({ + error: result.error, + source, + requestedBinary, + resolvedBinary: scafldBinary, + cwd: workingDirectory, + command: "--version", + args: ["--version"], + })); + } + + const exitCode = result.status ?? 1; + const rawVersion = `${result.stdout ?? ""}${result.stderr ?? ""}`.trim(); + if (exitCode !== 0) { + throw new Error(`scafld --version failed with exit ${exitCode}: ${rawVersion}`); + } + + const required = parseSemver(minimum); + if (!required) { + throw new Error(`invalid required scafld version: ${minimum}`); + } + + const actual = parseSemver(rawVersion); + if (!actual || compareSemver(actual, required) < 0) { + throw new Error( + `scafld ${minimum} or newer is required by this runx runner; ` + + `resolved ${scafldBinary} reported ${rawVersion || "no version"}`, + ); + } +} + +function parseSemver(value) { + const match = String(value).match(/\bv?(\d+)\.(\d+)\.(\d+)(?:[-+][0-9A-Za-z.-]+)?\b/); + if (!match) { + return null; + } + return [Number(match[1]), Number(match[2]), Number(match[3])]; +} + +function compareSemver(left, right) { + for (let index = 0; index < 3; index += 1) { + if (left[index] !== right[index]) { + return left[index] > right[index] ? 1 : -1; + } + } + return 0; +} + function firstNonEmptyString(...values) { for (const value of values) { if (typeof value !== "string") { diff --git a/tests/scafld-skill-parser.test.ts b/tests/scafld-skill-parser.test.ts index d2cbe0dc2..e1c0d3f8f 100644 --- a/tests/scafld-skill-parser.test.ts +++ b/tests/scafld-skill-parser.test.ts @@ -36,6 +36,8 @@ describe("scafld graph stage contract", () => { expect(wrapper).toContain('"build"'); expect(wrapper).toContain('"build_to_review"'); expect(wrapper).toContain('"handoff"'); + expect(wrapper).toContain("scafld_min_version"); + expect(wrapper).toContain("ensureScafldVersion"); expect(wrapper).toContain("function runBuildToReview"); expect(wrapper).not.toContain('"new"'); expect(wrapper).not.toContain('"branch"'); @@ -72,6 +74,10 @@ describe("scafld graph stage contract", () => { `#!/usr/bin/env node const argv = process.argv.slice(2); const command = argv[0] || ""; +if (command === "--version") { + process.stdout.write("2.4.0\\n"); + process.exit(0); +} if (command === "review") { process.stderr.write("scafld review[command] started node reviewer.mjs\\n"); process.stderr.write("scafld review[command] completed exit=0 elapsed=4ms last_output=0s\\n"); @@ -130,4 +136,52 @@ process.exit(1); await rm(tempDir, { recursive: true, force: true }); } }); + + it("fails closed when the resolved scafld is older than 2.4.0", async () => { + const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-scafld-old-version-")); + const fakeScafld = path.join(tempDir, "fake-scafld.mjs"); + const wrapperPath = path.join(scafldStageDir, "run.mjs"); + + try { + await writeFile( + fakeScafld, + `#!/usr/bin/env node +const argv = process.argv.slice(2); +const command = argv[0] || ""; +if (command === "--version") { + process.stdout.write("2.3.12\\n"); + process.exit(0); +} +if (command === "validate") { + process.stdout.write(JSON.stringify({ + ok: true, + command: "validate", + result: { task_id: argv[1], valid: true, errors: null }, + }) + "\\n"); + process.exit(0); +} +process.stderr.write(\`unsupported command: \${command}\\n\`); +process.exit(1); +`, + { mode: 0o755 }, + ); + + await expect(execFile("node", [wrapperPath], { + cwd: tempDir, + env: { + ...process.env, + RUNX_INPUTS_JSON: JSON.stringify({ + command: "validate", + task_id: "fixture-task", + fixture: tempDir, + scafld_bin: fakeScafld, + }), + }, + })).rejects.toMatchObject({ + stderr: expect.stringContaining("scafld 2.4.0 or newer is required"), + }); + } finally { + await rm(tempDir, { recursive: true, force: true }); + } + }); }); From f8af64383da29619626c8514450f1df0d8dd9841 Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 21:27:07 +1000 Subject: [PATCH 28/64] fix(registry): support system catalog audience --- crates/runx-parser/src/skill/catalog.rs | 5 +++- crates/runx-parser/tests/parser_catalog.rs | 24 +++++++++++++++++++ .../runx-runtime/src/registry/local/build.rs | 1 + tests/registry-fixtures.ts | 2 +- 4 files changed, 30 insertions(+), 2 deletions(-) diff --git a/crates/runx-parser/src/skill/catalog.rs b/crates/runx-parser/src/skill/catalog.rs index 5c31d8fe7..06e85090c 100644 --- a/crates/runx-parser/src/skill/catalog.rs +++ b/crates/runx-parser/src/skill/catalog.rs @@ -18,6 +18,7 @@ pub enum CatalogAudience { Public, Builder, Operator, + System, } #[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)] @@ -53,6 +54,7 @@ impl CatalogAudience { CatalogAudience::Public => "public", CatalogAudience::Builder => "builder", CatalogAudience::Operator => "operator", + CatalogAudience::System => "system", } } } @@ -153,8 +155,9 @@ fn parse_catalog_audience( "public" => Ok(CatalogAudience::Public), "builder" => Ok(CatalogAudience::Builder), "operator" => Ok(CatalogAudience::Operator), + "system" => Ok(CatalogAudience::System), _ => Err(FIELDS.validation_error(format!( - "{label}.audience must be public, builder, or operator." + "{label}.audience must be public, builder, operator, or system." ))), } } diff --git a/crates/runx-parser/tests/parser_catalog.rs b/crates/runx-parser/tests/parser_catalog.rs index 7cb17b6d6..c8d990247 100644 --- a/crates/runx-parser/tests/parser_catalog.rs +++ b/crates/runx-parser/tests/parser_catalog.rs @@ -69,6 +69,30 @@ runners: Ok(()) } +#[test] +fn catalog_audience_accepts_system_sync_profiles() -> Result<(), String> { + let manifest = parse_manifest( + r#" +catalog: + kind: skill + audience: system + visibility: internal + role: canonical +runners: + default: + source: + type: agent +"#, + )?; + + let catalog = manifest + .catalog + .ok_or_else(|| "expected catalog metadata".to_owned())?; + assert_eq!(catalog.audience, CatalogAudience::System); + assert_eq!(catalog.audience.as_str(), "system"); + Ok(()) +} + #[test] fn unknown_catalog_kind_fails_closed() -> Result<(), String> { let raw = parse_runner_manifest_yaml( diff --git a/crates/runx-runtime/src/registry/local/build.rs b/crates/runx-runtime/src/registry/local/build.rs index a52f3225e..0685adcd7 100644 --- a/crates/runx-runtime/src/registry/local/build.rs +++ b/crates/runx-runtime/src/registry/local/build.rs @@ -347,6 +347,7 @@ pub(super) fn normalize_registry_catalog( audience: match audience { Some("builder") => runx_parser::CatalogAudience::Builder, Some("operator") => runx_parser::CatalogAudience::Operator, + Some("system") => runx_parser::CatalogAudience::System, _ => runx_parser::CatalogAudience::Public, }, visibility: match visibility { diff --git a/tests/registry-fixtures.ts b/tests/registry-fixtures.ts index 1281bd69b..2bc7d62b5 100644 --- a/tests/registry-fixtures.ts +++ b/tests/registry-fixtures.ts @@ -38,7 +38,7 @@ export interface RegistrySkillVersion { readonly trust_tier: RegistryTrustTier; readonly maturity?: "alpha" | "beta" | "stable"; readonly catalog_kind?: "skill" | "graph"; - readonly catalog_audience?: "public" | "builder" | "operator"; + readonly catalog_audience?: "public" | "builder" | "operator" | "system"; readonly catalog_visibility?: "public" | "internal"; readonly attestations?: readonly RegistryAttestation[]; readonly required_scopes: readonly string[]; From c81b941cf8a9ad34153fe8da7998c76d81663318 Mon Sep 17 00:00:00 2001 From: kam Date: Sat, 20 Jun 2026 23:25:49 +1000 Subject: [PATCH 29/64] fix(thread): accept frantic reopen intents --- docs/thread-story-contract.md | 17 +++++++++-------- tools/thread/frantic_thread_outbox.d.mts | 2 +- tools/thread/frantic_thread_outbox.mjs | 4 ++-- 3 files changed, 12 insertions(+), 11 deletions(-) diff --git a/docs/thread-story-contract.md b/docs/thread-story-contract.md index 5ede8a027..0b005a1f1 100644 --- a/docs/thread-story-contract.md +++ b/docs/thread-story-contract.md @@ -47,14 +47,15 @@ TypeScript helper package. Frantic uses that provider lane for source-thread continuity. Frantic emits a typed outbox (`thread.create`, `thread.comment`, `thread.labels`, -`thread.close`) derived from its ledger; runx maps each intent to a provider -push frame with `tools/thread/frantic_thread_outbox.mjs`. `thread.create` -creates or updates the missing GitHub issue by deterministic outbox marker and -returns the observed provider locator. Bound lifecycle intents hydrate the -GitHub issue before writing, then apply comments, labels, or completion closure -through the GitHub provider adapter. Frantic remains the completion authority: -a GitHub issue may close only after a Frantic `thread.close` intent, and GitHub -state never completes a Frantic bounty. +`thread.open`, `thread.close`) derived from its ledger; runx maps each intent to +a provider push frame with `tools/thread/frantic_thread_outbox.mjs`. +`thread.create` creates or updates the missing GitHub issue by deterministic +outbox marker and returns the observed provider locator. Bound lifecycle intents +hydrate the GitHub issue before writing, then apply comments, labels, reopening, +or non-claimable closure through the GitHub provider adapter. Frantic remains +the completion authority: a GitHub issue may close only after a Frantic +`thread.close` intent, may reopen only after a Frantic `thread.open` intent, and +GitHub state never completes or reopens a Frantic bounty. The operational driver for that integration is `scripts/frantic-github-thread-sync.mjs` (`pnpm frantic:github-thread-sync` in diff --git a/tools/thread/frantic_thread_outbox.d.mts b/tools/thread/frantic_thread_outbox.d.mts index 3fb799cdd..160334854 100644 --- a/tools/thread/frantic_thread_outbox.d.mts +++ b/tools/thread/frantic_thread_outbox.d.mts @@ -1,5 +1,5 @@ export interface FranticThreadIntent { - readonly kind: "thread.create" | "thread.comment" | "thread.labels" | "thread.close"; + readonly kind: "thread.create" | "thread.comment" | "thread.labels" | "thread.close" | "thread.open"; readonly outbox_id: string; readonly provider: string; readonly thread_locator?: string; diff --git a/tools/thread/frantic_thread_outbox.mjs b/tools/thread/frantic_thread_outbox.mjs index e5f0d17c8..ebaec8b8f 100644 --- a/tools/thread/frantic_thread_outbox.mjs +++ b/tools/thread/frantic_thread_outbox.mjs @@ -70,7 +70,7 @@ export function normalizeFranticThreadIntent(intent) { const bountyNumber = requiredPositiveInteger(intent.bounty_number, "intent.bounty_number"); const occurredAt = requiredString(intent.occurred_at, "intent.occurred_at"); - if (!["thread.create", "thread.comment", "thread.labels", "thread.close"].includes(kind)) { + if (!["thread.create", "thread.comment", "thread.labels", "thread.close", "thread.open"].includes(kind)) { throw new Error(`unsupported Frantic thread intent kind '${kind}'.`); } @@ -240,7 +240,7 @@ function buildGitHubOutboxEntry(intent) { channel: "github_issue", source: "frantic", source_ref: intent.source_ref, - action: intent.kind === "thread.labels" ? "labels" : "close", + action: intent.kind === "thread.labels" ? "labels" : intent.kind === "thread.open" ? "open" : "close", add_labels: intent.add_labels, remove_labels: intent.remove_labels, close_reason: intent.reason, From 2f051c454f355c958d377eca1a2da718617b32c0 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 00:42:15 +1000 Subject: [PATCH 30/64] fix(skills): harden least privilege auditor harness --- skills/least-privilege-auditor/X.yaml | 80 ++++++++- skills/least-privilege-auditor/run.mjs | 233 +++++++++++++++++++++++++ 2 files changed, 310 insertions(+), 3 deletions(-) create mode 100644 skills/least-privilege-auditor/run.mjs diff --git a/skills/least-privilege-auditor/X.yaml b/skills/least-privilege-auditor/X.yaml index 0c0fd88f4..019fc76db 100644 --- a/skills/least-privilege-auditor/X.yaml +++ b/skills/least-privilege-auditor/X.yaml @@ -5,12 +5,86 @@ catalog: audience: operator visibility: public role: canonical +harness: + cases: + - name: unused-scope-attenuation-proposed + inputs: + subject: skills/report-exporter + granted_scopes: + - drive.files.read:/reports/* + - drive.files.write:/reports/* + - drive.files.delete:/reports/* + usage_summary: + receipt_ids: + - rx_101 + - rx_102 + observed: + - scope: drive.files.read:/reports/* + count: 8 + refs: + - rx_101:step_3 + - rx_102:step_2 + - scope: drive.files.write:/reports/* + count: 2 + refs: + - rx_101:step_6 + - rx_102:step_5 + objective: Prepare the skill for renewal by removing unused authority. + caller: + answers: + agent_task.least-privilege-auditor.output: + audit_report: + status: attenuation_proposed + subject: skills/report-exporter + evidence: + receipt_ids: + - rx_101 + - rx_102 + receipt_window: null + grant_source: null + limitations: [] + removed_scopes: + - drive.files.delete:/reports/* + narrowed_scopes: [] + kept_scopes: + - drive.files.read:/reports/* + - drive.files.write:/reports/* + deferred_scopes: [] + attenuated_grant: + - drive.files.read:/reports/* + - drive.files.write:/reports/* + residual_risk: + - The subject can still read and write under /reports/*. + reviewer_action: applyable_now + attenuation_proposals: + - action: remove + scope: drive.files.delete:/reports/* + rationale: No cited receipt exercised delete authority. + verdict: "over-privileged: remove drive.files.delete:/reports/*" + expect: + status: sealed + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + + - name: missing-granted-scopes-needs-agent + inputs: + subject: skills/report-exporter + usage_summary: + receipt_ids: + - rx_101 + observed: [] + expect: + status: failure + runners: audit: default: true - type: agent-task - agent: reviewer - task: least-privilege-auditor + type: cli-tool + command: node + args: + - run.mjs outputs: audit_report: object attenuation_proposals: array diff --git a/skills/least-privilege-auditor/run.mjs b/skills/least-privilege-auditor/run.mjs new file mode 100644 index 000000000..1a4da7c74 --- /dev/null +++ b/skills/least-privilege-auditor/run.mjs @@ -0,0 +1,233 @@ +import fs from "node:fs"; + +const inputs = readInputs(); +const subject = stringValue(inputs.subject) || "unknown"; +const grantedScopes = stringArray(inputs.granted_scopes, "granted_scopes"); +const usageSummary = readUsageSummary(inputs.usage_summary); +const observed = collectObservedUsage(usageSummary); + +const scopeDiff = grantedScopes.map((scope) => classifyScope(scope, observed)); +const removedScopes = scopeDiff.filter((entry) => entry.classification === "remove").map((entry) => entry.granted_scope); +const narrowedScopes = scopeDiff + .filter((entry) => entry.classification === "narrow" && entry.proposal) + .map((entry) => ({ from: entry.granted_scope, to: entry.proposal })); +const keptScopes = scopeDiff.filter((entry) => entry.classification === "keep").map((entry) => entry.granted_scope); +const deferredScopes = scopeDiff.filter((entry) => entry.classification === "defer").map((entry) => entry.granted_scope); +const attenuatedGrant = [ + ...keptScopes, + ...narrowedScopes.map((entry) => entry.to), + ...deferredScopes, +]; + +const limitations = []; +if (observed.size === 0) { + limitations.push("No observed scope usage was provided; the grant cannot be safely narrowed."); +} + +const status = observed.size === 0 + ? "needs_more_evidence" + : removedScopes.length > 0 || narrowedScopes.length > 0 + ? "attenuation_proposed" + : "no_change"; + +const packet = { + status, + subject, + evidence: { + receipt_ids: Array.isArray(usageSummary.receipt_ids) ? usageSummary.receipt_ids.map(String) : [], + receipt_window: stringValue(usageSummary.receipt_window) || null, + grant_source: stringValue(inputs.grant_source) || null, + limitations, + }, + scope_diff: scopeDiff, + attenuated_grant: attenuatedGrant, + removed_scopes: removedScopes, + narrowed_scopes: narrowedScopes, + kept_scopes: keptScopes, + deferred_scopes: deferredScopes, + residual_risk: residualRisk({ keptScopes, deferredScopes, limitations }), + reviewer_action: status === "attenuation_proposed" + ? "applyable_now" + : status === "needs_more_evidence" + ? "gather_more_receipts" + : "none", + receipt_expectations: { + classification_counts: countClassifications(scopeDiff), + stop_status: status, + unresolved_questions: limitations, + }, +}; + +const result = { + audit_report: packet, + attenuation_proposals: [ + ...removedScopes.map((scope) => ({ + action: "remove", + scope, + rationale: "No cited receipt exercised this authority.", + })), + ...narrowedScopes.map((entry) => ({ + action: "narrow", + from: entry.from, + to: entry.to, + rationale: "Observed use fits the narrower grant.", + })), + ], + verdict: renderVerdict(packet), +}; + +process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + +function readInputs() { + const raw = process.env.RUNX_INPUTS_PATH + ? fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8") + : process.env.RUNX_INPUTS_JSON || "{}"; + return JSON.parse(raw); +} + +function readUsageSummary(value) { + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new Error("usage_summary must be an object with receipt_ids and observed usage"); + } + return value; +} + +function stringArray(value, field) { + if (!Array.isArray(value) || value.length === 0) { + throw new Error(`${field} must be a non-empty array`); + } + return value.map((entry) => { + if (typeof entry !== "string" || entry.trim().length === 0) { + throw new Error(`${field} entries must be non-empty strings`); + } + return entry.trim(); + }); +} + +function collectObservedUsage(summary) { + const observed = new Map(); + const entries = Array.isArray(summary.observed) ? summary.observed : []; + for (const entry of entries) { + if (!entry || typeof entry !== "object") continue; + const scope = stringValue(entry.scope); + if (!scope) continue; + const current = observed.get(scope) || { count: 0, refs: [] }; + current.count += Number.isFinite(entry.count) ? Math.max(0, Math.trunc(entry.count)) : 1; + if (Array.isArray(entry.refs)) current.refs.push(...entry.refs.map(String)); + observed.set(scope, current); + } + return observed; +} + +function classifyScope(scope, observed) { + const normalized = normalizeScope(scope); + const exact = observed.get(scope); + if (exact && exact.count > 0) { + return diffEntry({ + scope, + normalized, + observedUse: { count: exact.count, receipt_refs: exact.refs }, + classification: "keep", + proposal: null, + rationale: "Observed receipt usage exercised this exact authority.", + }); + } + + const narrower = observedNarrowerScope(scope, observed); + if (narrower) { + return diffEntry({ + scope, + normalized, + observedUse: { count: narrower.count, receipt_refs: narrower.refs, scopes: narrower.scopes }, + classification: "narrow", + proposal: commonScopePrefix(narrower.scopes) || narrower.scopes[0], + rationale: "Observed usage fits a narrower scope than the granted wildcard.", + }); + } + + return diffEntry({ + scope, + normalized, + observedUse: { count: 0, receipt_refs: [] }, + classification: "remove", + proposal: null, + rationale: "No cited receipt exercised this authority.", + }); +} + +function observedNarrowerScope(scope, observed) { + if (!scope.endsWith("*")) return null; + const prefix = scope.slice(0, -1); + const matches = [...observed.entries()].filter(([used]) => used.startsWith(prefix)); + if (matches.length === 0) return null; + return { + scopes: matches.map(([used]) => used), + count: matches.reduce((sum, [, usage]) => sum + usage.count, 0), + refs: matches.flatMap(([, usage]) => usage.refs), + }; +} + +function normalizeScope(scope) { + const [verbPart, ...resourceParts] = scope.split(":"); + const resource = resourceParts.join(":") || null; + return { + verb: verbPart || null, + resource, + conditions: null, + }; +} + +function diffEntry({ scope, normalized, observedUse, classification, proposal, rationale }) { + return { + granted_scope: scope, + normalized, + observed_use: { + count: observedUse.count, + verbs: normalized.verb ? [normalized.verb] : [], + resources: normalized.resource ? [normalized.resource] : [], + receipt_refs: observedUse.receipt_refs || [], + scopes: observedUse.scopes || [], + }, + classification, + proposal, + rationale, + }; +} + +function commonScopePrefix(scopes) { + if (scopes.length !== 1) return null; + return scopes[0]; +} + +function countClassifications(entries) { + return entries.reduce((counts, entry) => { + counts[entry.classification] = (counts[entry.classification] || 0) + 1; + return counts; + }, {}); +} + +function residualRisk({ keptScopes, deferredScopes, limitations }) { + const risks = []; + if (keptScopes.length > 0) { + risks.push(`The subject still retains ${keptScopes.length} observed scope(s).`); + } + if (deferredScopes.length > 0) { + risks.push(`The subject has ${deferredScopes.length} deferred scope(s) requiring policy review.`); + } + risks.push(...limitations); + return risks; +} + +function renderVerdict(packet) { + if (packet.status === "attenuation_proposed") { + return `over-privileged: remove ${packet.removed_scopes.length}, narrow ${packet.narrowed_scopes.length}`; + } + if (packet.status === "needs_more_evidence") { + return "needs_more_evidence: no exercised scopes were provided"; + } + return "no_change: observed usage matches the grant"; +} + +function stringValue(value) { + return typeof value === "string" && value.trim().length > 0 ? value.trim() : null; +} From aad050dfc63c0b12a61271ffa79f8c9078701ea8 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 01:12:13 +1000 Subject: [PATCH 31/64] fix(cli): explain receipt publish scope errors --- crates/runx-cli/src/public_api.rs | 33 ++++++++++++++++++++++++++++ crates/runx-cli/src/publish.rs | 24 ++++++++++++++++++-- crates/runx-cli/src/publish_tests.rs | 15 +++++++++++++ 3 files changed, 70 insertions(+), 2 deletions(-) diff --git a/crates/runx-cli/src/public_api.rs b/crates/runx-cli/src/public_api.rs index 7e65116a0..a2f69ee34 100644 --- a/crates/runx-cli/src/public_api.rs +++ b/crates/runx-cli/src/public_api.rs @@ -37,6 +37,19 @@ pub(crate) fn parse_error(body: &str) -> Option { serde_json::from_str::(body) .ok() .map(|envelope| envelope.error) + .or_else(|| { + serde_json::from_str::(body) + .ok() + .and_then(|envelope| match envelope.error { + PlainError::Message(detail) => Some(ErrorPayload { + code: plain_error_code(&detail).to_owned(), + detail, + hint: None, + retry_after_seconds: None, + }), + PlainError::Payload(payload) => Some(payload), + }) + }) } fn normalize_non_empty_base_url(value: &str) -> Option { @@ -62,3 +75,23 @@ pub(crate) struct ErrorPayload { struct ErrorEnvelope { error: ErrorPayload, } + +#[derive(Deserialize)] +struct PlainErrorEnvelope { + error: PlainError, +} + +#[derive(Deserialize)] +#[serde(untagged)] +enum PlainError { + Message(String), + Payload(ErrorPayload), +} + +fn plain_error_code(detail: &str) -> &'static str { + if detail.contains("Missing required scope") { + "missing_scope" + } else { + "api_error" + } +} diff --git a/crates/runx-cli/src/publish.rs b/crates/runx-cli/src/publish.rs index 348f7f029..2833ef246 100644 --- a/crates/runx-cli/src/publish.rs +++ b/crates/runx-cli/src/publish.rs @@ -114,10 +114,13 @@ impl fmt::Display for PublishError { "runx-api publish returned invalid JSON: {message}" ) } - Self::RunxApi { code, detail, .. } => { + Self::RunxApi { + code, detail, hint, .. + } => { write!( formatter, - "runx-api publish returned error [{code}]: {detail}" + "{}", + publish_error_message(code, detail, hint.as_deref()) ) } } @@ -132,6 +135,23 @@ impl From for PublishError { } } +fn publish_error_message(code: &str, detail: &str, hint: Option<&str>) -> String { + if code == "missing_scope" && detail.contains("receipts:write") { + return [ + "This token can publish skills but not receipts.", + "The receipt notary requires `receipts:write`.", + "Use `runx publish --token ` or set `RUNX_PUBLIC_API_TOKEN` to a receipt-capable token.", + "Your stored login token is still valid for the scopes it was issued with.", + ] + .join(" "); + } + let mut message = format!("runx-api publish returned error [{code}]: {detail}"); + if let Some(hint) = hint.filter(|value| !value.trim().is_empty()) { + message.push_str(&format!(" Hint: {hint}")); + } + message +} + #[derive(Clone, Debug)] struct PublishOptions<'a> { base_url: &'a str, diff --git a/crates/runx-cli/src/publish_tests.rs b/crates/runx-cli/src/publish_tests.rs index 9fc288bc9..5e59c5b7f 100644 --- a/crates/runx-cli/src/publish_tests.rs +++ b/crates/runx-cli/src/publish_tests.rs @@ -250,6 +250,21 @@ fn human_output_reflects_notary_status() -> Result<(), PublishCliError> { Ok(()) } +#[test] +fn publish_error_explains_receipt_scope_mismatch() { + let message = PublishError::RunxApi { + code: "missing_scope".to_owned(), + detail: "Missing required scope: receipts:write.".to_owned(), + hint: None, + retry_after_seconds: None, + } + .to_string(); + + assert!(message.contains("can publish skills but not receipts")); + assert!(message.contains("receipts:write")); + assert!(message.contains("runx publish --token")); +} + fn request_json_body(request: &HttpRequest) -> Result { let body = request .body From 9ca7781e1a647ee971fa6fbae70f161350238754 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 01:12:18 +1000 Subject: [PATCH 32/64] fix(runtime): preserve http transport diagnostics --- crates/runx-runtime/src/runtime_http.rs | 16 ++++++++++++++-- 1 file changed, 14 insertions(+), 2 deletions(-) diff --git a/crates/runx-runtime/src/runtime_http.rs b/crates/runx-runtime/src/runtime_http.rs index c15702b41..bfd62d188 100644 --- a/crates/runx-runtime/src/runtime_http.rs +++ b/crates/runx-runtime/src/runtime_http.rs @@ -220,7 +220,7 @@ impl ReqwestHttpTransport { let client = builder .build() .map_err(|error| RuntimeHttpError::Transport { - message: error.to_string(), + message: transport_error_message(&error), })?; Ok(Self { client, @@ -303,7 +303,7 @@ impl RuntimeHttpTransport for ReqwestHttpTransport { .send() .await .map_err(|error| RuntimeHttpError::Transport { - message: error.to_string(), + message: transport_error_message(&error), })?; let status = response.status().as_u16(); let body = read_limited_response_body(response, MAX_HTTP_RESPONSE_BYTES).await?; @@ -312,6 +312,18 @@ impl RuntimeHttpTransport for ReqwestHttpTransport { } } +#[cfg(feature = "async-http")] +fn transport_error_message(error: &(dyn StdError + 'static)) -> String { + let mut parts = vec![error.to_string()]; + let mut source = error.source(); + while let Some(error) = source { + parts.push(error.to_string()); + source = error.source(); + } + parts.dedup(); + parts.join(": ") +} + #[cfg(feature = "async-http")] #[derive(Clone, Debug)] struct GuardedDnsResolver { From a9d4b15ddaa5da07f722a47f393e00944342aaac Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 01:12:49 +1000 Subject: [PATCH 33/64] fix(runtime): lengthen managed agent http timeout --- .../src/execution/skill_front/agent.rs | 2 +- crates/runx-runtime/src/runtime_http.rs | 31 +++++++++++++++---- 2 files changed, 26 insertions(+), 7 deletions(-) diff --git a/crates/runx-runtime/src/execution/skill_front/agent.rs b/crates/runx-runtime/src/execution/skill_front/agent.rs index 4bd9e4fe8..b6a27cb81 100644 --- a/crates/runx-runtime/src/execution/skill_front/agent.rs +++ b/crates/runx-runtime/src/execution/skill_front/agent.rs @@ -148,7 +148,7 @@ fn try_inline_agent_resolution( id: agent_act.id.clone(), invocation: Box::new(agent_act), }; - let transport = ReqwestHttpTransport::new().map_err(|error| { + let transport = ReqwestHttpTransport::for_managed_agent().map_err(|error| { SkillRunError::Invalid(format!("managed agent transport error: {error}")) })?; let resolver = AnthropicAgentResolver::new( diff --git a/crates/runx-runtime/src/runtime_http.rs b/crates/runx-runtime/src/runtime_http.rs index bfd62d188..487ae2486 100644 --- a/crates/runx-runtime/src/runtime_http.rs +++ b/crates/runx-runtime/src/runtime_http.rs @@ -120,6 +120,12 @@ pub struct ReqwestHttpTransport { #[cfg(feature = "async-http")] const MAX_HTTP_RESPONSE_BYTES: usize = 1024 * 1024; +#[cfg(feature = "async-http")] +const DEFAULT_HTTP_REQUEST_TIMEOUT: Duration = Duration::from_secs(30); +#[cfg(feature = "async-http")] +const DEFAULT_HTTP_CONNECT_TIMEOUT: Duration = Duration::from_secs(10); +#[cfg(feature = "async-http")] +const MANAGED_AGENT_REQUEST_TIMEOUT: Duration = Duration::from_secs(180); /// The default browser User-Agent the governed fetch transport presents (current /// stable Chrome). Overridable per run with `RUNX_HTTP_USER_AGENT`, opt-out with @@ -176,8 +182,8 @@ fn chrome_default_headers() -> reqwest::header::HeaderMap { impl ReqwestHttpTransport { pub fn new() -> Result { Self::with_timeouts_and_private_networks( - Duration::from_secs(30), - Duration::from_secs(10), + DEFAULT_HTTP_REQUEST_TIMEOUT, + DEFAULT_HTTP_CONNECT_TIMEOUT, false, None, ) @@ -234,13 +240,26 @@ impl ReqwestHttpTransport { /// `allowPrivateNetwork`) before choosing it, never as a default. pub fn with_private_network_access() -> Result { Self::with_timeouts_and_private_networks( - Duration::from_secs(30), - Duration::from_secs(10), + DEFAULT_HTTP_REQUEST_TIMEOUT, + DEFAULT_HTTP_CONNECT_TIMEOUT, true, None, ) } + /// Build the model-provider transport for managed-agent calls. These calls can + /// legitimately spend more than the generic governed HTTP timeout while the + /// provider thinks and emits tool use, but they still keep the same public-DNS + /// guard and short connect timeout. + pub fn for_managed_agent() -> Result { + Self::with_timeouts_and_private_networks( + MANAGED_AGENT_REQUEST_TIMEOUT, + DEFAULT_HTTP_CONNECT_TIMEOUT, + false, + None, + ) + } + /// Build the open-web fetch transport: the optional browser profile (a /// `Some(user_agent)` enables it; `None` is the plain client) plus the /// private-network flag. The `http` skill adapter uses this; `new()` and @@ -251,8 +270,8 @@ impl ReqwestHttpTransport { browser_user_agent: Option, ) -> Result { Self::with_timeouts_and_private_networks( - Duration::from_secs(30), - Duration::from_secs(10), + DEFAULT_HTTP_REQUEST_TIMEOUT, + DEFAULT_HTTP_CONNECT_TIMEOUT, allow_private_networks, browser_user_agent, ) From 1d51d3b2fb6e586245de3caba03711e88ad263f2 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 01:13:14 +1000 Subject: [PATCH 34/64] fix(runtime): use managed agent timeout in graphs --- crates/runx-runtime/src/execution/skill_front/graph.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/crates/runx-runtime/src/execution/skill_front/graph.rs b/crates/runx-runtime/src/execution/skill_front/graph.rs index b881a38f3..141bf898f 100644 --- a/crates/runx-runtime/src/execution/skill_front/graph.rs +++ b/crates/runx-runtime/src/execution/skill_front/graph.rs @@ -462,7 +462,7 @@ impl InlineResolver { Some(config) if config.provider.as_str().eq_ignore_ascii_case("anthropic") => config, _ => return Ok(None), }; - let transport = ReqwestHttpTransport::new() + let transport = ReqwestHttpTransport::for_managed_agent() .map_err(|error| fail(format!("managed agent transport error: {error}")))?; let resolver = AnthropicAgentResolver::new( transport, From 0db353e1aa0b33da54e553ce2a74208bb4d35851 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 01:29:58 +1000 Subject: [PATCH 35/64] fix(ci): clear runx release gates --- crates/runx-cli/src/doctor.rs | 2 ++ crates/runx-cli/src/launcher.rs | 2 ++ crates/runx-cli/src/official_skills.rs | 2 +- crates/runx-cli/src/skill/parser.rs | 2 ++ crates/runx-parser/src/graph/step.rs | 2 ++ crates/runx-parser/src/yaml.rs | 9 ++++++--- crates/runx-runtime/src/adapters/http.rs | 12 ++++++------ crates/runx-runtime/src/registry/local/build.rs | 2 ++ crates/runx-runtime/src/runtime_http.rs | 2 +- packages/cli/src/official-skills.lock.json | 2 +- 10 files changed, 25 insertions(+), 12 deletions(-) diff --git a/crates/runx-cli/src/doctor.rs b/crates/runx-cli/src/doctor.rs index 86623b777..a922bfabd 100644 --- a/crates/runx-cli/src/doctor.rs +++ b/crates/runx-cli/src/doctor.rs @@ -101,6 +101,8 @@ fn run_doctor_command( Ok(DoctorCliOutput { stdout, exit_code }) } +// rust-style-allow: long-function - this builds one structured diagnostic packet +// from env, config, and credential state so the evidence and repair stay together. fn managed_agent_config_diagnostic(env: &BTreeMap, cwd: &Path) -> DoctorDiagnostic { let config_dir = resolve_runx_home_dir(env, cwd); let config_path = config_dir.join("config.json"); diff --git a/crates/runx-cli/src/launcher.rs b/crates/runx-cli/src/launcher.rs index a534769c3..53fdaa918 100644 --- a/crates/runx-cli/src/launcher.rs +++ b/crates/runx-cli/src/launcher.rs @@ -490,6 +490,8 @@ fn mcp_runner_before_serve(args: &[OsString]) -> bool { }) } +// rust-style-allow: long-function - harness flag parsing stays local to the +// launcher boundary so native dispatch does not grow a second parser surface. fn native_harness_plan(args: &[OsString]) -> LauncherAction { let mut fixture_paths = Vec::new(); let mut receipt_dir = None; diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index e283a8e40..df447b099 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -117,7 +117,7 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/least-privilege-auditor", - version: "sha-b2913b95c069", + version: "sha-e5c3622556d9", digest: "244df5dd8eed7900d1987c76060893d3c9cd65f420c5b8c177b19fa4e0b81ac2", }, OfficialSkillLockEntry { diff --git a/crates/runx-cli/src/skill/parser.rs b/crates/runx-cli/src/skill/parser.rs index 290eb46a7..27b32f7af 100644 --- a/crates/runx-cli/src/skill/parser.rs +++ b/crates/runx-cli/src/skill/parser.rs @@ -1,3 +1,5 @@ +// rust-style-allow: large-file - skill CLI parsing keeps shared state and +// option finalization in one module until the native parser surface stabilizes. use std::collections::BTreeMap; use std::env; use std::ffi::OsString; diff --git a/crates/runx-parser/src/graph/step.rs b/crates/runx-parser/src/graph/step.rs index e58b31619..d8e6c6e42 100644 --- a/crates/runx-parser/src/graph/step.rs +++ b/crates/runx-parser/src/graph/step.rs @@ -1,3 +1,5 @@ +// rust-style-allow: large-file - graph step validation is kept together so +// field-level diagnostics stay consistent across graph target variants. use std::collections::{BTreeMap, BTreeSet}; use runx_contracts::{JsonObject, JsonValue}; diff --git a/crates/runx-parser/src/yaml.rs b/crates/runx-parser/src/yaml.rs index d26d32f46..1d20f6ba2 100644 --- a/crates/runx-parser/src/yaml.rs +++ b/crates/runx-parser/src/yaml.rs @@ -362,9 +362,12 @@ fn reject_duplicate_mapping_key( keys: HashSet::new(), }); } - let frame = stack - .last_mut() - .expect("mapping frame is created before key insertion"); + let Some(frame) = stack.last_mut() else { + return Err(ParseError::InvalidYaml { + field: field.to_owned(), + message: format!("could not track mapping key {key:?} in X.yaml at line {line_number}"), + }); + }; if !frame.keys.insert(key.to_owned()) { return Err(ParseError::InvalidYaml { field: field.to_owned(), diff --git a/crates/runx-runtime/src/adapters/http.rs b/crates/runx-runtime/src/adapters/http.rs index 440d6219f..69fd33436 100644 --- a/crates/runx-runtime/src/adapters/http.rs +++ b/crates/runx-runtime/src/adapters/http.rs @@ -544,12 +544,12 @@ mod tests { #[test] fn post_substitutes_secret_references_in_json_body() -> Result<(), RuntimeError> { let delivery = crate::credentials::CredentialDelivery::from_local_descriptor( - "github", + "api", "bearer", - "GITHUB_TOKEN", + "API_TOKEN", "credential:test", - vec!["github.issue-create".to_owned()], - "ghp_secret", + vec!["api.call".to_owned()], + "api_secret", ) .map_err(|error| failure(format!("building test credential: {error}")))?; let transport = stub(201, ""); @@ -561,7 +561,7 @@ mod tests { execute_http_call( &transport, &call, - &inputs(&[("token", "${secret:GITHUB_TOKEN}")]), + &inputs(&[("token", "${secret:API_TOKEN}")]), delivery.secret_env(), )?; let sent = transport.requests.borrow(); @@ -569,7 +569,7 @@ mod tests { sent[0] .body .as_deref() - .is_some_and(|body| body.contains(r#""token":"ghp_secret""#)), + .is_some_and(|body| body.contains(r#""token":"api_secret""#)), "POST body should substitute delivered secret refs; got: {:?}", sent[0].body ); diff --git a/crates/runx-runtime/src/registry/local/build.rs b/crates/runx-runtime/src/registry/local/build.rs index 0685adcd7..5de87f4b0 100644 --- a/crates/runx-runtime/src/registry/local/build.rs +++ b/crates/runx-runtime/src/registry/local/build.rs @@ -188,6 +188,8 @@ pub(super) fn registry_tags( ) } +// rust-style-allow: long-function - normalization validates the package digest, +// manifest, and registry row in one pass over the submitted version payload. pub fn normalize_registry_skill_version( payload: RegistrySkillVersionPayload, ) -> Result { diff --git a/crates/runx-runtime/src/runtime_http.rs b/crates/runx-runtime/src/runtime_http.rs index 487ae2486..84d21a2a6 100644 --- a/crates/runx-runtime/src/runtime_http.rs +++ b/crates/runx-runtime/src/runtime_http.rs @@ -248,7 +248,7 @@ impl ReqwestHttpTransport { } /// Build the model-provider transport for managed-agent calls. These calls can - /// legitimately spend more than the generic governed HTTP timeout while the + /// legitimately take longer than the generic governed HTTP timeout while the /// provider thinks and emits tool use, but they still keep the same public-DNS /// guard and short connect timeout. pub fn for_managed_agent() -> Result { diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index abcb922e1..ebba0c870 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -148,7 +148,7 @@ }, { "skill_id": "runx/least-privilege-auditor", - "version": "sha-b2913b95c069", + "version": "sha-e5c3622556d9", "digest": "244df5dd8eed7900d1987c76060893d3c9cd65f420c5b8c177b19fa4e0b81ac2", "catalog_visibility": "public", "catalog_role": "canonical" From dc85e3bc4beb388cd85e02b44948cac2493a3fe1 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 01:50:55 +1000 Subject: [PATCH 36/64] fix(thread): handle open lifecycle intents --- tests/github-thread.test.ts | 104 +++++++++++++++++++++++++++++++- tools/thread/github_adapter.mjs | 47 ++++++++++++++- 2 files changed, 147 insertions(+), 4 deletions(-) diff --git a/tests/github-thread.test.ts b/tests/github-thread.test.ts index 45738b84c..d14d813f3 100644 --- a/tests/github-thread.test.ts +++ b/tests/github-thread.test.ts @@ -528,6 +528,108 @@ describe("GitHub thread helper", () => { await rm(tempDir, { recursive: true, force: true }); } }); + + it("pushes Frantic open lifecycle operations through the GitHub adapter", async () => { + const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-frantic-github-")); + const ghBin = path.join(tempDir, "fake-gh.mjs"); + const logPath = path.join(tempDir, "gh.log"); + + try { + await writeFile(ghBin, fakeGhScript(logPath)); + await chmod(ghBin, 0o700); + const result = pushGitHubLifecycleIntent({ + thread: { + adapter: { + adapter_ref: "auscaster/frantic-board#issue/7", + }, + thread_locator: "github://auscaster/frantic-board/issues/7", + canonical_uri: "https://github.com/auscaster/frantic-board/issues/7", + metadata: { + repo: "auscaster/frantic-board", + }, + }, + outboxEntry: { + entry_id: "github:claim-1:thread.open", + kind: "provider_thread_lifecycle", + status: "pending", + metadata: { + action: "open", + }, + }, + env: { + ...process.env, + RUNX_GH_BIN: ghBin, + GH_FAKE_LOG: logPath, + GH_FAKE_ISSUE_STATE: "CLOSED", + }, + }); + + const calls = JSON.parse(await readFile(logPath, "utf8")); + expect(calls.map((call: { args: string[] }) => call.args.slice(0, 2).join(" "))).toEqual([ + "issue view", + "issue reopen", + ]); + expect(result).toMatchObject({ + outbox_entry: { + status: "published", + locator: "https://github.com/auscaster/frantic-board/issues/7", + }, + lifecycle: { + opened: true, + }, + }); + } finally { + await rm(tempDir, { recursive: true, force: true }); + } + }); + + it("publishes an already-open lifecycle operation without GitHub mutation", async () => { + const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-frantic-github-")); + const ghBin = path.join(tempDir, "fake-gh.mjs"); + const logPath = path.join(tempDir, "gh.log"); + + try { + await writeFile(ghBin, fakeGhScript(logPath)); + await chmod(ghBin, 0o700); + const result = pushGitHubLifecycleIntent({ + thread: { + adapter: { + adapter_ref: "auscaster/frantic-board#issue/7", + }, + thread_locator: "github://auscaster/frantic-board/issues/7", + canonical_uri: "https://github.com/auscaster/frantic-board/issues/7", + metadata: { + repo: "auscaster/frantic-board", + }, + }, + outboxEntry: { + entry_id: "github:claim-1:thread.open", + kind: "provider_thread_lifecycle", + status: "pending", + metadata: { + action: "open", + }, + }, + env: { + ...process.env, + RUNX_GH_BIN: ghBin, + GH_FAKE_LOG: logPath, + }, + }); + + const calls = JSON.parse(await readFile(logPath, "utf8")); + expect(calls.map((call: { args: string[] }) => call.args.slice(0, 2).join(" "))).toEqual([ + "issue view", + ]); + expect(result).toMatchObject({ + lifecycle: { + opened: true, + }, + }); + } finally { + await rm(tempDir, { recursive: true, force: true }); + } + }); }); function fakeGhScript(logPath: string): string { @@ -553,7 +655,7 @@ if (args[0] === "issue" && args[1] === "create") { } if (args[0] === "issue" && args[1] === "view") { process.stdout.write(JSON.stringify({ - state: "OPEN", + state: process.env.GH_FAKE_ISSUE_STATE || "OPEN", url: "https://github.com/auscaster/frantic-board/issues/7", labels: [{ name: "frantic:open" }] })); diff --git a/tools/thread/github_adapter.mjs b/tools/thread/github_adapter.mjs index 38baf3e9d..e565045ba 100644 --- a/tools/thread/github_adapter.mjs +++ b/tools/thread/github_adapter.mjs @@ -916,13 +916,19 @@ export function pushGitHubLifecycleIntent({ }); const addLabels = stringList(metadata.add_labels); const removeLabels = stringList(metadata.remove_labels); + const lifecycleAction = firstNonEmptyString(metadata.action); const closeReason = firstNonEmptyString(metadata.close_reason, "completed"); if (!repoSlug) { throw new Error("GitHub issue repo slug is required to push a provider thread lifecycle entry."); } - if (addLabels.length === 0 && removeLabels.length === 0 && metadata.action !== "close") { - throw new Error("provider_thread_lifecycle requires label changes or a close action."); + if ( + addLabels.length === 0 && + removeLabels.length === 0 && + lifecycleAction !== "close" && + lifecycleAction !== "open" + ) { + throw new Error("provider_thread_lifecycle requires label changes, an open action, or a close action."); } const labelResult = applyGitHubLabelChanges({ @@ -935,7 +941,8 @@ export function pushGitHubLifecycleIntent({ env, }); - const shouldClose = firstNonEmptyString(metadata.action) === "close"; + const shouldClose = lifecycleAction === "close"; + const shouldOpen = lifecycleAction === "open"; if (shouldClose && String(issueState.state ?? "").toUpperCase() !== "CLOSED") { closeGitHubIssue({ repoSlug, @@ -945,6 +952,14 @@ export function pushGitHubLifecycleIntent({ env, }); } + if (shouldOpen && String(issueState.state ?? "").toUpperCase() === "CLOSED") { + reopenGitHubIssue({ + repoSlug, + issueNumber: issueRef.issue_number, + cwd, + env, + }); + } return { outbox_entry: prune({ @@ -967,6 +982,7 @@ export function pushGitHubLifecycleIntent({ added_labels: labelResult.addedLabels, removed_labels: labelResult.removedLabels, closed: shouldClose, + opened: shouldOpen, close_reason: shouldClose ? closeReason : undefined, }), }; @@ -1261,6 +1277,31 @@ function closeGitHubIssue({ repoSlug, issueNumber, reason, cwd, env }) { }, { tokenFallback: true }); } +function reopenGitHubIssue({ repoSlug, issueNumber, cwd, env }) { + if (canUseGitHubRest(env)) { + runGitHubRest({ + method: "PATCH", + path: gitHubIssueApiPath(repoSlug, issueNumber), + env, + body: { + state: "open", + }, + acceptedStatuses: [200], + }); + return; + } + runGhCommand([ + "issue", + "reopen", + issueNumber, + "--repo", + repoSlug, + ], { + cwd, + env, + }, { tokenFallback: true }); +} + function selectExistingGitHubMessageOutboxEntry(thread, outboxEntry) { const existingOutbox = Array.isArray(thread.outbox) ? thread.outbox.filter(isRecord) : []; const requestedMetadata = optionalRecord(outboxEntry.metadata) ?? {}; From 123a287b0bb3352a6276d620d5125ef2665d8fb1 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 01:52:43 +1000 Subject: [PATCH 37/64] fix(ci): satisfy parser clippy gates --- crates/runx-parser/src/graph/step.rs | 13 +++++++------ crates/runx-parser/src/yaml.rs | 9 ++++++--- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/crates/runx-parser/src/graph/step.rs b/crates/runx-parser/src/graph/step.rs index d8e6c6e42..6a82413a6 100644 --- a/crates/runx-parser/src/graph/step.rs +++ b/crates/runx-parser/src/graph/step.rs @@ -99,13 +99,14 @@ fn reject_step_output_refs_in_input_value( field: &str, ) -> Result<(), ValidationError> { match value { - JsonValue::String(value) => { - if looks_like_previous_step_output_ref(value, previous_step_ids) { - return Err(validation_error(format!( - "{field} looks like step output reference {value:?}; move it to context if you meant to read a previous step output." - ))); - } + JsonValue::String(value) + if looks_like_previous_step_output_ref(value, previous_step_ids) => + { + return Err(validation_error(format!( + "{field} looks like step output reference {value:?}; move it to context if you meant to read a previous step output." + ))); } + JsonValue::String(_) => {} JsonValue::Object(object) => { for (key, value) in object { reject_step_output_refs_in_input_value( diff --git a/crates/runx-parser/src/yaml.rs b/crates/runx-parser/src/yaml.rs index 1d20f6ba2..a1b673d62 100644 --- a/crates/runx-parser/src/yaml.rs +++ b/crates/runx-parser/src/yaml.rs @@ -600,7 +600,7 @@ mod tests { "expected duplicate key rejection, got {result:?}" ); - assert_execution_profile_yaml_subset( + let sequence_result = assert_execution_profile_yaml_subset( "runner_manifest", r#" runners: @@ -614,8 +614,11 @@ runners: - id: second tool: two.tool "#, - ) - .expect("sequence item maps may reuse keys in separate items"); + ); + assert!( + sequence_result.is_ok(), + "sequence item maps may reuse keys in separate items: {sequence_result:?}" + ); } // Regression cases for the single-quote `''` escape. The earlier toggle From 6b147bd163fe328eb876540dad4fffaeace8e444 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 02:04:53 +1000 Subject: [PATCH 38/64] fix(ci): stabilize runx rust checks --- crates/runx-cli/src/doctor.rs | 22 +++++++++------- crates/runx-cli/src/public_api.rs | 8 +++--- crates/runx-cli/src/skill/parser.rs | 24 ++++++++++-------- .../src/adapters/agent_resolver.rs | 12 ++++----- .../src/execution/skill_front/graph.rs | 25 +++++++++++-------- crates/runx-runtime/tests/skill_run.rs | 4 +++ .../scaffold/new-docs-demo/files/SKILL.md | 1 + 7 files changed, 56 insertions(+), 40 deletions(-) diff --git a/crates/runx-cli/src/doctor.rs b/crates/runx-cli/src/doctor.rs index a922bfabd..1a55f492a 100644 --- a/crates/runx-cli/src/doctor.rs +++ b/crates/runx-cli/src/doctor.rs @@ -78,9 +78,9 @@ fn run_doctor_command( let root = resolve_doctor_root(plan, env, cwd); let mut report = run_doctor(&root, &default_doctor_options())?; - report - .diagnostics - .push(managed_agent_config_diagnostic(env, cwd)); + if let Some(diagnostic) = managed_agent_config_diagnostic(env, cwd) { + report.diagnostics.push(diagnostic); + } report.summary = summary(&report.diagnostics); if report .diagnostics @@ -103,7 +103,10 @@ fn run_doctor_command( // rust-style-allow: long-function - this builds one structured diagnostic packet // from env, config, and credential state so the evidence and repair stay together. -fn managed_agent_config_diagnostic(env: &BTreeMap, cwd: &Path) -> DoctorDiagnostic { +fn managed_agent_config_diagnostic( + env: &BTreeMap, + cwd: &Path, +) -> Option { let config_dir = resolve_runx_home_dir(env, cwd); let config_path = config_dir.join("config.json"); let config = load_runx_config_file(&config_path); @@ -181,6 +184,9 @@ fn managed_agent_config_diagnostic(env: &BTreeMap, cwd: &Path) - let complete = provider.is_some() && model.is_some() && api_key_configured; let partial = !complete && (provider.is_some() || model.is_some() || api_key_configured || config_error.is_some()); + if !complete && !partial { + return None; + } let severity = if partial { DoctorDiagnosticSeverity::Warning } else { @@ -190,13 +196,11 @@ fn managed_agent_config_diagnostic(env: &BTreeMap, cwd: &Path) - format!("Managed-agent config could not be read: {error}.") } else if complete { "Managed-agent config is complete; agent-task runners can execute in-process.".to_owned() - } else if partial { - "Managed-agent config is partial; set provider, model, and API key or unset the partial values. Otherwise agent-task runners may yield to the host or fail later.".to_owned() } else { - "Managed-agent config is not set; agent-task runners will use host-driven resolution unless a provider is configured.".to_owned() + "Managed-agent config is partial; set provider, model, and API key or unset the partial values. Otherwise agent-task runners may yield to the host or fail later.".to_owned() }; - DoctorDiagnostic { + Some(DoctorDiagnostic { id: "runx.agent.config".to_owned(), instance_id: "runx:doctor:runx.agent.config".to_owned(), severity, @@ -232,7 +236,7 @@ fn managed_agent_config_diagnostic(env: &BTreeMap, cwd: &Path) - } else { Vec::new() }, - } + }) } fn first_non_empty<'a>(values: impl IntoIterator>) -> Option<&'a str> { diff --git a/crates/runx-cli/src/public_api.rs b/crates/runx-cli/src/public_api.rs index a2f69ee34..00ae838ac 100644 --- a/crates/runx-cli/src/public_api.rs +++ b/crates/runx-cli/src/public_api.rs @@ -40,14 +40,14 @@ pub(crate) fn parse_error(body: &str) -> Option { .or_else(|| { serde_json::from_str::(body) .ok() - .and_then(|envelope| match envelope.error { - PlainError::Message(detail) => Some(ErrorPayload { + .map(|envelope| match envelope.error { + PlainError::Message(detail) => ErrorPayload { code: plain_error_code(&detail).to_owned(), detail, hint: None, retry_after_seconds: None, - }), - PlainError::Payload(payload) => Some(payload), + }, + PlainError::Payload(payload) => payload, }) }) } diff --git a/crates/runx-cli/src/skill/parser.rs b/crates/runx-cli/src/skill/parser.rs index 27b32f7af..903e4cac3 100644 --- a/crates/runx-cli/src/skill/parser.rs +++ b/crates/runx-cli/src/skill/parser.rs @@ -510,8 +510,8 @@ mod tests { runx_dir.join("credentials.json"), r#"{ "profiles": { - "frantic": { - "credential": "frantic:bearer:local://frantic/internal:frantic.review", + "example": { + "credential": "example:bearer:local://example/internal:example.review", "secret_env": "INTERNAL_SYNC_SECRET" } } @@ -520,8 +520,10 @@ mod tests { ) .map_err(|error| error.to_string())?; - let mut state = SkillParseState::default(); - state.credential_profile = Some("frantic".to_owned()); + let state = SkillParseState { + credential_profile: Some("example".to_owned()), + ..Default::default() + }; let env = [ ( "RUNX_PROJECT_DIR".to_owned(), @@ -534,12 +536,12 @@ mod tests { let credential = finalize_local_credential(&state, &env, &root)? .ok_or_else(|| "credential profile did not resolve".to_owned())?; - assert_eq!(credential.provider, "frantic"); + assert_eq!(credential.provider, "example"); assert_eq!(credential.auth_mode, "bearer"); - assert_eq!(credential.material_ref, "local://frantic/internal"); + assert_eq!(credential.material_ref, "local://example/internal"); assert_eq!(credential.env_var, "INTERNAL_SYNC_SECRET"); assert_eq!(credential.secret, "secret-value"); - assert_eq!(credential.scopes, vec!["frantic.review"]); + assert_eq!(credential.scopes, vec!["example.review"]); fs::remove_dir_all(root).map_err(|error| error.to_string())?; Ok(()) @@ -547,9 +549,11 @@ mod tests { #[test] fn credential_profile_rejects_manual_credential_flags() -> Result<(), String> { - let mut state = SkillParseState::default(); - state.credential_profile = Some("frantic".to_owned()); - state.secret_env = Some(("TOKEN".to_owned(), "secret".to_owned())); + let state = SkillParseState { + credential_profile: Some("example".to_owned()), + secret_env: Some(("TOKEN".to_owned(), "secret".to_owned())), + ..Default::default() + }; let error = finalize_local_credential(&state, &Default::default(), &std::env::temp_dir()) .err() .ok_or_else(|| "profile unexpectedly combined with manual flags".to_owned())?; diff --git a/crates/runx-runtime/src/adapters/agent_resolver.rs b/crates/runx-runtime/src/adapters/agent_resolver.rs index 4044a550a..d193e175a 100644 --- a/crates/runx-runtime/src/adapters/agent_resolver.rs +++ b/crates/runx-runtime/src/adapters/agent_resolver.rs @@ -269,7 +269,7 @@ mod tests { } #[test] - fn final_result_schema_uses_declared_outputs() { + fn final_result_schema_uses_declared_outputs() -> Result<(), String> { let outputs = BTreeMap::from([ ("decision".to_owned(), OutputField::Type(OutputType::String)), ("quality".to_owned(), OutputField::Type(OutputType::Object)), @@ -278,18 +278,17 @@ mod tests { let final_tool = tools .iter() .find(|tool| tool.name == FINAL_RESULT_TOOL) - .expect("missing final-result tool"); + .ok_or_else(|| "missing final-result tool".to_owned())?; let JsonValue::Object(schema) = &final_tool.input_schema else { - panic!("final result schema should be an object"); + return Err("final result schema should be an object".to_owned()); }; assert_eq!( schema.get("type"), Some(&JsonValue::String("object".to_owned())) ); - let JsonValue::Object(properties) = schema.get("properties").expect("missing properties") - else { - panic!("properties should be an object"); + let Some(JsonValue::Object(properties)) = schema.get("properties") else { + return Err("properties should be an object".to_owned()); }; assert!(properties.contains_key("decision")); assert!(properties.contains_key("quality")); @@ -304,6 +303,7 @@ mod tests { schema.get("additionalProperties"), Some(&JsonValue::Bool(false)) ); + Ok(()) } #[test] diff --git a/crates/runx-runtime/src/execution/skill_front/graph.rs b/crates/runx-runtime/src/execution/skill_front/graph.rs index 141bf898f..10eae4401 100644 --- a/crates/runx-runtime/src/execution/skill_front/graph.rs +++ b/crates/runx-runtime/src/execution/skill_front/graph.rs @@ -6,6 +6,7 @@ use super::{ contract_json_value, identifier_segment, invalid, needs_agent_output, sealed_output, }; +use std::collections::BTreeMap; use std::path::PathBuf; use runx_contracts::{ @@ -73,6 +74,7 @@ pub(super) fn execute_graph_skill_run( credential_delivery_from_invocation(workspace.env(), request.local_credential.as_ref())?; let inline_resolver = InlineResolver { skill_directory: skill_dir.clone(), + env: env.clone(), credential_delivery: credential_delivery.clone(), }; let runtime = Runtime::new( @@ -438,6 +440,8 @@ struct InlineResolver { #[cfg_attr(not(feature = "agent"), allow(dead_code))] skill_directory: PathBuf, #[cfg_attr(not(feature = "agent"), allow(dead_code))] + env: BTreeMap, + #[cfg_attr(not(feature = "agent"), allow(dead_code))] credential_delivery: CredentialDelivery, } @@ -452,23 +456,22 @@ impl InlineResolver { skill_name: "managed-agent".to_owned(), message, }; - // The same process-env snapshot the rest of the runtime reads, so the - // inline graph agent path resolves the provider exactly like the - // top-level agent path rather than reaching for raw `std::env`. - let env = crate::services::process_env_snapshot(); - let config = match crate::config::load_managed_agent_config(&env, &self.skill_directory) - .map_err(|error| fail(format!("managed agent config error: {error}")))? - { - Some(config) if config.provider.as_str().eq_ignore_ascii_case("anthropic") => config, - _ => return Ok(None), - }; + let config = + match crate::config::load_managed_agent_config(&self.env, &self.skill_directory) + .map_err(|error| fail(format!("managed agent config error: {error}")))? + { + Some(config) if config.provider.as_str().eq_ignore_ascii_case("anthropic") => { + config + } + _ => return Ok(None), + }; let transport = ReqwestHttpTransport::for_managed_agent() .map_err(|error| fail(format!("managed agent transport error: {error}")))?; let resolver = AnthropicAgentResolver::new( transport, config.api_key, config.model, - env, + self.env.clone(), self.skill_directory.clone(), self.credential_delivery.clone(), ); diff --git a/crates/runx-runtime/tests/skill_run.rs b/crates/runx-runtime/tests/skill_run.rs index 084cdc072..11efcad36 100644 --- a/crates/runx-runtime/tests/skill_run.rs +++ b/crates/runx-runtime/tests/skill_run.rs @@ -2178,6 +2178,10 @@ fn run_skill(request: SkillRunRequest) -> Result SkillRunRequest { crate::support::insert_test_signing_env(&mut request.env); request + .env + .entry("RUNX_HOME".to_owned()) + .or_insert_with(|| request.cwd.join(".runx").to_string_lossy().into_owned()); + request } fn write_agent_task_skill(root: &Path) -> Result> { diff --git a/fixtures/scaffold/new-docs-demo/files/SKILL.md b/fixtures/scaffold/new-docs-demo/files/SKILL.md index 4bbf62f39..82202f807 100644 --- a/fixtures/scaffold/new-docs-demo/files/SKILL.md +++ b/fixtures/scaffold/new-docs-demo/files/SKILL.md @@ -16,6 +16,7 @@ inputs: required: true description: Input the skill acts on. Replace with the real inputs. runx: + category: ops input_resolution: required: - message From 683f80caea6298b35ffb0dd7ada8684ee04aab14 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 03:33:13 +1000 Subject: [PATCH 39/64] docs: refresh runx readme --- README.md | 273 +++++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 221 insertions(+), 52 deletions(-) diff --git a/README.md b/README.md index bdf5a29a2..bdbbae683 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@

runx

-

the governed runtime for agent skills

+

accountable agency for agent skills

-

expertise as a URL, run under the authority you grant, sealed in a receipt you can replay.

+

Run skill URLs under explicit authority. Seal consequential work into receipts that can be verified, replayed, and learned from.

license: MIT @@ -14,26 +14,51 @@ --- -Agents are getting capable faster than we can trust them. They write code, move money, and reach into production. The missing piece is not more intelligence. It is a way to hand an agent a capability and still answer for what it did with it. +Agents are getting capable faster than we can answer for their work. They write +code, touch providers, move money, and reach into production. The missing layer +is not more intelligence. It is accountable agency: a way to hand an agent a +capability, bind what it may do, and preserve enough evidence that someone who +was not there can still trust the result. -runx is that layer. A skill is a `SKILL.md` you publish at a URL. Drop the URL into any agent and it runs in your environment, under the authority you grant, and every step seals into a signed receipt you can replay months later. +runx is that layer. A skill is a `SKILL.md` published at a URL. The runtime +admits it under the authority you grant, delivers credentials without turning +them into prompt material, runs the declared profile, and seals the act into a +receipt. ```text a skill is a URL. -a graph is what unfolds. +a run is a governed act. +a graph is the receipt-backed path between acts. authority narrows. it does not pass through. -every act produces a receipt. ``` -## quickstart +## the invariant -```bash -npm i -g @runxhq/cli # ships the native runx binary +Every governed execution passes through the same four stages: + +```text +admit -> deliver credentials -> sandbox -> seal ``` -Run the checked-in example and read its receipt. The signing key below is a public demo key, for local smoke tests only: +| Stage | What runx protects | +| --- | --- | +| `admit` | Policy checks the requested act before any step handler runs. An unadmitted act never reaches execution. | +| `deliver credentials` | Secret material crosses only a structured delivery boundary. Receipts carry grant refs, public observations, and hashes, not tokens. | +| `sandbox` | The declared cwd, env, filesystem, network, and enforcement posture are resolved and recorded. Runs can fail closed when OS-level enforcement is required. | +| `seal` | The runtime writes a signed `runx.receipt.v1` record with subject, authority witness, outputs, lineage, and closure. | + +The receipt is not the product by itself. It is where authority, action, +evidence, and future learning meet in one verifiable object. + +## quickstart + +Install the CLI wrapper, clone the examples, run one skill, then inspect what +was sealed. The demo signing key is public and exists only for local smoke +tests: ```bash +npm i -g @runxhq/cli + git clone https://github.com/runxhq/runx && cd runx/oss export RUNX_RECEIPT_SIGN_KID=runx-demo-key @@ -41,18 +66,73 @@ export RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64=QkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJ export RUNX_RECEIPT_SIGN_ISSUER_TYPE=hosted export RUNX_RECEIPT_DIR="$(mktemp -d)" -runx skill examples/hello-world --message "hello from runx" --json # -> status: "sealed" -runx history # what ran, under what authority, with what result +runx skill examples/hello-world --message "hello from runx" --json +runx history --receipt-dir "$RUNX_RECEIPT_DIR" ``` -Full walkthrough, including production signing keys, is in [docs/getting-started.md](docs/getting-started.md). +The first command should report `status: "sealed"` and include a receipt id. +Inspect that receipt directly when you want the proof object: -## a skill is a URL +```bash +runx history --receipt-dir "$RUNX_RECEIPT_DIR" --json +``` -A skill starts with one portable file, `SKILL.md`: prose for the model and the -human-readable contract. When the skill needs deterministic runners, graphs, -harness cases, or governed side effects, the package also carries an execution -profile named `X.yaml`. +For production-trusted verification, configure +`RUNX_RECEIPT_VERIFY_KID` and `RUNX_RECEIPT_VERIFY_ED25519_PUBLIC_KEY_BASE64`, +then use: + +```bash +runx verify --receipt-dir "$RUNX_RECEIPT_DIR" --json +``` + +The full walkthrough, including production signing keys, is in +[docs/getting-started.md](docs/getting-started.md). + +## what a receipt proves + +A runx receipt is designed to answer the questions that matter after the agent +has moved on: + +| Question | Receipt surface | +| --- | --- | +| What ran? | `subject`, skill ref, source type, runner metadata | +| Who or what admitted it? | `authority.actor_ref`, grant refs, authority proof refs | +| What was allowed? | requested scopes, granted scopes, sandbox policy, approval metadata | +| What happened? | act entries, output artifacts, exit status, closure summary | +| Can it be checked later? | content-addressed id, canonical digest, signature, lineage | +| Did secrets leak into proof? | redacted metadata, hashed material refs, banned raw credential bodies | + +Shape, abbreviated: + +```json +{ + "schema": "runx.receipt.v1", + "subject": { "kind": "skill" }, + "authority": { + "actor_ref": { "type": "principal", "uri": "runx:principal:local_runtime" }, + "grant_refs": [] + }, + "seal": { + "disposition": "closed", + "reason_code": "process_closed" + }, + "lineage": { + "parent": null, + "children": [] + } +} +``` + +Offline verification recomputes the canonical body digest, checks the +content-addressed id, verifies signatures when trusted keys are configured, and +can walk receipt ancestry from a receipt store. + +## skills and execution profiles + +A skill starts as a portable `SKILL.md`: prose for the model and a +human-readable contract for the operator. When the skill needs deterministic +runners, typed inputs, graph stages, receipt mapping, harness cases, or governed +side effects, it also carries an execution profile named `X.yaml`. ```yaml --- @@ -63,7 +143,7 @@ source: command: node args: [run.mjs] sandbox: - profile: readonly # what it is allowed to touch + profile: readonly cwd_policy: skill-directory inputs: message: { type: string, required: true } @@ -74,63 +154,152 @@ runx: Print one message so a new contributor can verify the local runx execution path. ``` -The prose tells the agent what to do. The execution profile tells runx how the -skill is allowed to run. `X.yaml` owns runner wiring, typed inputs/outputs, -receipt mapping, harness cases, and side-effect posture; it should not become a -strategy document, copy deck, target registry, or private state file. Publish it -and the URL is the skill. Browse the open catalog at -[runx.ai/x](https://runx.ai/x). +`SKILL.md` is the capability. `X.yaml` is the execution profile. Keep the +profile explicit: runner wiring, typed inputs and outputs, tool/context refs, +authority and receipt mapping, side-effect posture, and harness cases. Do not +use it as a strategy document, private state file, target registry, copy deck, +or secret container. -## the model +Browse the public catalog at [runx.ai/x](https://runx.ai/x). -Nine objects, one runtime. A run is a graph; every hop runs the same four steps, and authority only narrows as it descends. +## graphs make acts composable -- **skill**: expertise plus an optional checked-in execution profile. -- **graph**: skills calling skills. runx renders the topology from the skills themselves and scopes authority at every branch, with no orchestration layer to maintain. -- **bounds**: least privilege by default. Grants are explicit, and an over-scope request is refused before anything runs. -- **receipt**: every act is signed and linked into one reproducible record. The artifact a CISO accepts and a developer can replay. +Graphs let one governed act consume the receipt-backed output of another: -The full grammar (the four-step hop, guards, conditional `when` branches, the act model) lives in the [spec](https://runx.ai/spec). +```yaml +name: hello-graph +owner: runx +steps: + - id: first + skill: ../hello-world + inputs: + message: hello from graph + - id: second + skill: ../hello-world + context: + message: first.stdout +``` + +The important boundary is not "how many model calls happened." The boundary is +what must be guaranteed. Agents are for judgment and authoring. Required +mutations, API calls, payments, and provider writes belong in deterministic +steps, where the runtime can admit the authority, perform the act, and seal the +result. + +Use a graph when phases, approvals, or side effects need to be visible in the +execution record. Use one bounded skill run when a single act is enough. + +See [docs/skill-to-graph.md](docs/skill-to-graph.md). + +## authority without secret leakage + +runx receipts explain the authority boundary without becoming a secret side +channel. + +Public proof may include: + +- requested scopes, granted scopes, grant id, and admission decision; +- provider, connection id, grant reference, and credential material hash; +- sandbox profile, declared enforcement, runtime enforcer, and approval result; +- redaction status and output hashes. + +Public proof must not include: + +- raw access tokens, refresh tokens, API keys, passwords, or client secrets; +- full private stdout or stderr bodies; +- ambient environment dumps; +- unchecked provider output bodies in public evidence. + +Provider-permission effects fail closed unless the operator supplies explicit +grant evidence. Spend-class payment authority must carry aggregate caps, not +only per-call limits. `runx doctor authority --json` reports readiness without +printing secret values. + +See [docs/security-authority-proof.md](docs/security-authority-proof.md). -## three things you couldn't do before +## demos that prove boundaries -- **expertise ships as a link.** A skill is a URL any agent can run in its own environment, under its own grants and approval gates. -- **graphs compose themselves.** One skill calls another, which calls a third. The topology comes from the skills, not from glue code you maintain. -- **receipts are proof.** Signed, linked, replayable. Reputation becomes something you verify instead of something you take on faith. +These demos are runnable from this repo and produce receipts: -## run it yourself +| Demo | What it proves | Run | +| --- | --- | --- | +| `examples/hello-world` | Native CLI skill path, sealed receipt baseline | `runx harness examples/hello-world` | +| `examples/github-mcp-hero` | Governed GitHub read succeeds, out-of-scope write is refused, denial receipt verifies | `sh examples/github-mcp-hero/run.sh` | +| `examples/http-graph` | Governed HTTP front call against a local fixture seals a receipt tree | `sh examples/http-graph/run.sh` | +| `examples/openapi-graph` | OpenAPI operation runs through the external-adapter lane and seals | `sh examples/openapi-graph/run.sh` | +| `examples/governed-spend/skills/overspend-refused` | Spend above authority is refused before rail execution | `runx harness examples/governed-spend/skills/overspend-refused` | +| `examples/loop-orchestration` | Bounded outer loop submits governed turns, prints receipt ids, and demonstrates refusal | `sh examples/loop-orchestration/run.sh` | -runx is MIT and runs entirely in your environment. Your keys, your boundary; your data and network never leave your control. The trusted local runtime is Rust, with no hosted dependency for local execution: +For deterministic payment dogfood without funded wallets or provider keys: ```bash -cd oss && cargo build --manifest-path crates/Cargo.toml -p runx-cli +pnpm demos:check ``` -`@runxhq/cli` is the published distribution of that same binary. +See [docs/demos.md](docs/demos.md). -## author and publish +## publish and trust + +Community skills should be standalone packages: `SKILL.md`, optional `X.yaml`, +and only the files runx can consume. Publish locally first: + +```bash +runx registry publish ./skills//SKILL.md +``` + +Then publish to the hosted catalog when you want shared discovery: ```bash -npx @runxhq/cli new my-skill # cold-start with no install: downloads the launcher, runs the same native scaffold -runx new my-skill # scaffold a native cli-tool skill (SKILL.md + X.yaml + run.mjs, zero deps) +runx login --for publish +runx registry publish ./skills//SKILL.md --registry https://api.runx.ai ``` -Write the prose, declare the profile, run it locally, then publish from a public repo at [runx.ai/x/publish](https://runx.ai/x/publish) or with `runx login --for publish && runx registry publish`. This repo is the first-party lane for official skills and the runtime; community skills ship as standalone packages. +Hosted publishing reconstructs the submitted package, reruns the harness, rejects +failed cases, and stores immutable package digests. New rows start as +`community`; verification and evidence promote discovery. Publisher declaration +alone is not trust. + +See [docs/publishing.md](docs/publishing.md). + +## architecture + +Rust owns the trusted local runtime path. + +| Layer | Owner | +| --- | --- | +| policy, state machine, authority admission | `runx-core` | +| skill, graph, runner, and tool manifest parsing | `runx-parser` | +| canonical receipts, hashing, signatures, tree verification | `runx-receipts` | +| local runtime, adapters, sandbox planning, harness, registry, MCP, payment gates | `runx-runtime` | +| native binary | `runx-cli` | +| generated TypeScript contracts and npm wrapper | `@runxhq/contracts`, `@runxhq/cli` | + +TypeScript remains for generated contracts, client wrappers, cloud/product +integrations, host adapters, authoring tooling, and helper SDKs. It must not be +a fallback executor for trusted local behavior. + +See [docs/reference.md](docs/reference.md) and +[docs/rust-kernel-architecture.md](docs/rust-kernel-architecture.md). ## docs -| | | +| Read this | When you need | | --- | --- | -| [getting started](docs/getting-started.md) | install, first skill, first receipt | -| [skill to graph](docs/skill-to-graph.md) | compose skills into a governed graph | -| [the spec](https://runx.ai/spec) | the act model, the four-step hop, the grammar | -| [the catalog](https://runx.ai/x) | every governed skill, by URL | -| [architecture and reference](docs/reference.md) | crate topology, sandbox posture, tool authoring, the full surface | +| [getting started](docs/getting-started.md) | first skill, first receipt | +| [skill to graph](docs/skill-to-graph.md) | compose governed acts | +| [security authority proof](docs/security-authority-proof.md) | scope, credentials, grants, verification | +| [demos](docs/demos.md) | runnable proof paths | +| [publishing](docs/publishing.md) | local and hosted skill publishing | +| [reference](docs/reference.md) | CLI, crates, registry, receipts, extension protocols | +| [the spec](https://runx.ai/spec) | act model, receipt grammar, public contracts | +| [the catalog](https://runx.ai/x) | governed skills by URL | ## contributing -Setup, test selection, and sign-off rules are in [CONTRIBUTING.md](CONTRIBUTING.md). Security policy: [SECURITY.md](SECURITY.md). runx is MIT licensed; see [LICENSE](LICENSE). +Setup, test selection, and sign-off rules are in +[CONTRIBUTING.md](CONTRIBUTING.md). Security policy: +[SECURITY.md](SECURITY.md). runx is MIT licensed; see [LICENSE](LICENSE). --- -

built in Rust · MIT · runx.ai

+

MIT · runx.ai

From e602b300c193c54449cdf74ce3aa3c00f4286641 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 03:33:56 +1000 Subject: [PATCH 40/64] feat: add support triage reply skill --- skills/support-triage-reply/SKILL.md | 83 +++++++ skills/support-triage-reply/X.yaml | 90 +++++++ .../references/dogfood-receipt.json | 1 + .../references/evidence.json | 89 +++++++ .../support-triage-reply/references/report.md | 112 +++++++++ skills/support-triage-reply/run.mjs | 231 ++++++++++++++++++ 6 files changed, 606 insertions(+) create mode 100644 skills/support-triage-reply/SKILL.md create mode 100644 skills/support-triage-reply/X.yaml create mode 100644 skills/support-triage-reply/references/dogfood-receipt.json create mode 100644 skills/support-triage-reply/references/evidence.json create mode 100644 skills/support-triage-reply/references/report.md create mode 100644 skills/support-triage-reply/run.mjs diff --git a/skills/support-triage-reply/SKILL.md b/skills/support-triage-reply/SKILL.md new file mode 100644 index 000000000..b1986f22e --- /dev/null +++ b/skills/support-triage-reply/SKILL.md @@ -0,0 +1,83 @@ +--- +name: support-triage-reply +version: 0.1.0 +description: Classify a bounded support request, choose the safe next path, and draft a customer-ready reply only when a human-gated send is appropriate. +source: + type: cli-tool + command: node + args: + - run.mjs +links: + source: https://github.com/runxhq/runx/tree/main/oss/skills/support-triage-reply +runx: + category: ops + input_resolution: + required: + - support_request +--- + +# Support Triage Reply + +Classify one bounded support request and return a support-safe decision packet. +The skill is designed for day-to-day operator work where support, product, and +engineering signals arrive together, but a customer send must remain a separate +human-approved action. + +This skill never sends email, posts to Slack, creates issues, mutates accounts, +or touches billing. It returns a draft and a gated send proposal only when the +request is safe to answer from the supplied context. + +## Inputs + +- `support_request`: object with `subject`, `body`, optional `customer_name`, + optional `customer_email`, optional `source`, and optional `refs`. +- `policy`: optional object with `product_name`, `support_signature`, + `safe_reply_topics`, and `escalation_contacts`. + +## Output + +The runner emits these top-level fields: + +- `classification`: `how_to`, `billing`, `account_access`, `bug`, `abuse`, or + `unknown`. +- `severity`: `low`, `medium`, `high`, or `critical`. +- `confidence`: number from 0 to 1. +- `recommended_path`: one of `reply_draft`, `request_info`, + `engineering_intake`, `billing_review`, `account_review`, `abuse_review`, or + `manual_review`. +- `evidence`: object with matched signals, missing context, source summary, and + taxonomy coverage. +- `draft_email`: object with `proposed`, `subject`, and `body`. When a reply is + not safe from the supplied packet, `proposed` is `false` and `reason` explains + the blocker. +- `send_gate`: object whose `status` is always `requires_human_approval`. + +## Decision Rules + +Prefer safety over completeness: + +- `how_to`: draft a clear support email when the request is answerable from the + supplied text or common product-safe instructions. +- `billing`: route to billing review unless the supplied context already names + a public, non-account-specific policy. +- `account_access`: route to account review. Do not ask for passwords, recovery + secrets, or private tokens. +- `bug`: route to engineering intake when the report includes a failure mode, + product surface, or reproduction clue. +- `abuse`: route to abuse review and do not draft a customer-facing answer. +- `unknown`: request more information or manual review. Do not invent a fix. + +Customer-facing copy must be specific, calm, and sendable. It should include a +greeting, acknowledge the actual request, state the answer or next step, and end +with the configured support signature. Avoid filler, unsupported promises, and +fake certainty. + +## Safety Bar + +- No customer send occurs inside this skill. +- No private credentials, billing records, account identifiers, or inbox state + are required. +- A draft is a proposal, not permission. The caller must use a separate + governed send lane to deliver any message. +- When confidence is low or private account state is needed, return + `manual_review` or a review-specific route. diff --git a/skills/support-triage-reply/X.yaml b/skills/support-triage-reply/X.yaml new file mode 100644 index 000000000..f71b51bce --- /dev/null +++ b/skills/support-triage-reply/X.yaml @@ -0,0 +1,90 @@ +skill: support-triage-reply +version: "0.1.0" + +catalog: + kind: skill + audience: operator + visibility: public + role: canonical + +harness: + cases: + - name: safe-how-to-reply-draft + runner: triage + inputs: + support_request: + customer_name: Mira + customer_email: mira@example.test + subject: How do I verify my sending domain? + body: I added the DNS records for my domain. What should I check next so emails can send safely? + source: fixture:safe-how-to + policy: + product_name: Nitrosend + support_signature: Nitrosend Support + expect: + status: sealed + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_closed + + - name: account-access-escalates-without-draft + runner: triage + inputs: + support_request: + customer_name: Theo + customer_email: theo@example.test + subject: I cannot access my account + body: My login is blocked and I need someone to reset access for the team owner. + source: fixture:account-access + policy: + product_name: Nitrosend + support_signature: Nitrosend Support + expect: + status: sealed + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_closed + + - name: missing-request-fails + runner: triage + inputs: + support_request: {} + expect: + status: failure + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_failed + +runners: + triage: + default: true + type: cli-tool + command: node + args: + - run.mjs + outputs: + classification: string + severity: string + confidence: number + recommended_path: string + evidence: object + draft_email: object + send_gate: object + artifacts: + wrap_as: support_triage_packet + packet: runx.support.triage_reply.v1 + inputs: + support_request: + type: json + required: true + description: Bounded support request packet. + policy: + type: json + required: false + description: Product-safe support policy and signature hints. diff --git a/skills/support-triage-reply/references/dogfood-receipt.json b/skills/support-triage-reply/references/dogfood-receipt.json new file mode 100644 index 000000000..c47721c9b --- /dev/null +++ b/skills/support-triage-reply/references/dogfood-receipt.json @@ -0,0 +1 @@ +{"schema":"runx.receipt.v1","id":"sha256:0cae135b62adf38fb8512096b85c0111f4b76b980e4401ab793c44b2f8a8d279","created_at":"2026-06-20T17:31:31.292Z","canonicalization":"runx.receipt.c14n.v1","issuer":{"type":"hosted","kid":"runx-demo-key","public_key_sha256":"sha256:3097e2dee2cb4a34b53840cdb705aed71067c36f68db0e0f559c3f3fa043315f"},"signature":{"alg":"Ed25519","value":"base64:jQGbjSQLxXfv2UVxC_77CcgVe8kJZcK2NzArzhaZ_4NRINYas9hgfXxSY96eto339We5d2un2b4DI6iiygCIBg"},"digest":"sha256:4c3497960e95df635f82587bbed2579fca17f805a81cde53c585c5aedcbbd4db","idempotency":{"intent_key":"sha256:run_triage_32dc09449784-triage-intent","trigger_fingerprint":"sha256:run_triage_32dc09449784-triage-trigger","content_hash":"sha256:run_triage_32dc09449784-triage-content"},"subject":{"kind":"skill","ref":{"type":"harness","uri":"hrn_run_triage_32dc09449784_triage"},"commitments":[]},"authority":{"actor_ref":{"type":"principal","uri":"runx:principal:local_runtime"},"grant_refs":[],"scope_refs":[],"authority_proof_refs":[],"attenuation":{"parent_authority_ref":null,"subset_proof":null},"terms":[],"enforcement":{"profile_hash":"sha256:runtime-skeleton-enforcement","redaction_refs":[],"setup_refs":[],"teardown_refs":[]}},"signals":[],"decisions":[{"decision_id":"dec_triage","choice":"open","inputs":{"signal_refs":[],"target_ref":null,"opportunity_refs":[],"selection_ref":null},"proposed_intent":{"purpose":"Open runtime node triage","legitimacy":"Local graph execution requested this node","success_criteria":[],"constraints":[],"derived_from":[]},"selected_act_id":"act_triage","selected_harness_ref":null,"justification":{"summary":"runtime graph planner selected this node","evidence_refs":[]},"closure":null,"artifact_refs":[]}],"acts":[{"id":"act_triage","form":"observation","intent":{"purpose":"Run graph step triage","legitimacy":"Runtime graph execution was admitted by the local harness","success_criteria":[{"criterion_id":"process_exit","statement":"cli-tool exits successfully","required":true}],"constraints":[],"derived_from":[]},"summary":"Executed graph step triage","criterion_bindings":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}],"source_refs":[],"target_refs":[],"artifact_refs":[],"closure":{"disposition":"closed","reason_code":"process_exit","summary":"cli-tool exited successfully","closed_at":"2026-06-20T17:31:31.292Z"}}],"seal":{"disposition":"closed","reason_code":"process_closed","summary":"cli-tool triage completed","closed_at":"2026-06-20T17:31:31.292Z","last_observed_at":"2026-06-20T17:31:31.292Z","criteria":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}]},"lineage":{"children":[],"sync":[]}} \ No newline at end of file diff --git a/skills/support-triage-reply/references/evidence.json b/skills/support-triage-reply/references/evidence.json new file mode 100644 index 000000000..e66dbbd65 --- /dev/null +++ b/skills/support-triage-reply/references/evidence.json @@ -0,0 +1,89 @@ +{ + "schema": "runx.support_triage_reply.evidence.v1", + "skill": { + "name": "support-triage-reply", + "published_ref": "godfood/support-triage-reply@sha-7fee56e60e96", + "owner": "godfood", + "publisher_principal": "user_godfood_2190fb7211ca", + "registry": "https://api.runx.ai", + "public_url": "https://runx.ai/x/godfood/support-triage-reply", + "source_url": "https://github.com/runxhq/runx/tree/main/oss/skills/support-triage-reply", + "digest": "544b57d054d74832815c67fc244407a36c308b05041e0d85007587e3ac78178b", + "profile_digest": "362867317f6299483d754cef105e73057d1fe83ad7f60bd9c3086a844641765e", + "trust_tier": "community" + }, + "boundary": { + "nitrosend_private_skill_reused": false, + "source_shape": "A generic public Runx skill inspired by the same support-ops category as Nitrosend private triage/intake skills.", + "private_semantics_included": false, + "sends_or_mutates": false, + "send_gate": "requires_human_approval" + }, + "checks": { + "local_harness": { + "status": "passed", + "case_count": 3, + "case_names": [ + "safe-how-to-reply-draft", + "account-access-escalates-without-draft", + "missing-request-fails" + ], + "receipt_ids": [ + "sha256:d864febac35254bcf49995b68e3c71a77444f5ad73c0ac7d05150fa3df72d4e4", + "sha256:29ed6188a804af189b6772855305f5da08ed399127ebae1120491d69c3e8f6af", + "sha256:69d5d7d9ae0330c9b40c5739d874e54add6cd94c81da693188d237af996d6dec" + ] + }, + "registry_readback": { + "status": "passed", + "publisher_handle": "godfood", + "markdown_contract_checked": true, + "runner_names": [ + "triage" + ] + }, + "clean_install": { + "status": "installed", + "command": "runx add godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --installation-id godfood-support-triage-final --json" + }, + "dogfood_run": { + "status": "passed", + "command": "runx skill godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --input support_request= --input policy= --receipts --json", + "receipt_id": "sha256:0cae135b62adf38fb8512096b85c0111f4b76b980e4401ab793c44b2f8a8d279", + "receipt_file": "dogfood-receipt.json", + "verify_command": "runx verify --receipt dogfood-receipt.json --json", + "verify_note": "Verified with the public Ed25519 verification key for the demo signing key used by the local runtime.", + "verify_valid": true, + "classification": "how_to", + "severity": "low", + "confidence": 0.88, + "recommended_path": "reply_draft", + "send_gate_status": "requires_human_approval" + }, + "hosted_run_admission": { + "status": "accepted_pending_worker", + "run_id": "hr_7f1f591110f9458295eefe13f1d25e8b", + "app_url": "https://runx.ai/r/hr_7f1f591110f9458295eefe13f1d25e8b", + "inspect_url": "https://api.runx.ai/v1/runs/hr_7f1f591110f9458295eefe13f1d25e8b", + "observed_status": "pending", + "note": "Hosted control accepted the run under the godfood principal, but the worker did not drain it during the verification window. The execution proof for this delivery is the registry-resolved local run receipt." + } + }, + "credential_hygiene": { + "temporary_godfood_publish_credentials_revoked": true, + "temporary_godfood_run_credentials_revoked": true, + "live_godfood_self_serve_credentials_remaining": 0, + "tokens_in_artifacts": false + }, + "value_assessment": { + "real_operator_value": true, + "summary": "The skill handles a repeatable day-to-day support operation: classify one support request, select the safe lane, and draft a sendable reply only behind a human approval gate.", + "why_not_throwaway": "It is a reusable public Runx skill with a registry owner, source path, harness cases, typed outputs, safety gates, and receipt proof. It is not a one-off hosted webpage or private product-only wrapper.", + "review_bar": [ + "No automatic customer sends.", + "No private account or billing lookup is claimed.", + "Account, billing, abuse, bug, and unknown cases route away from unsafe customer replies.", + "The caller receives enough structured evidence to decide whether a human should send, escalate, or request more information." + ] + } +} diff --git a/skills/support-triage-reply/references/report.md b/skills/support-triage-reply/references/report.md new file mode 100644 index 000000000..96613edaf --- /dev/null +++ b/skills/support-triage-reply/references/report.md @@ -0,0 +1,112 @@ +# Support Triage Reply Dogfood Report + +## Result + +`support-triage-reply` is published as: + +- Registry ref: `godfood/support-triage-reply@sha-7fee56e60e96` +- Public page: https://runx.ai/x/godfood/support-triage-reply +- Source: https://github.com/runxhq/runx/tree/main/oss/skills/support-triage-reply +- Digest: `544b57d054d74832815c67fc244407a36c308b05041e0d85007587e3ac78178b` +- Profile digest: `362867317f6299483d754cef105e73057d1fe83ad7f60bd9c3086a844641765e` +- Trust tier: `community` + +The skill is intentionally generic. Nitrosend has private support-ops skills +for triage/intake, but this public artifact does not include Nitrosend-private +policy, credentials, customer data, or mutation paths. + +## What It Does + +The skill accepts one bounded `support_request` and optional `policy`, then +returns: + +- `classification` +- `severity` +- `confidence` +- `recommended_path` +- `evidence` +- `draft_email` +- `send_gate` + +The skill never sends email, posts comments, mutates accounts, opens issues, or +touches billing. A reply draft is only a proposal; `send_gate.status` remains +`requires_human_approval`. + +## Verification + +Local harness: + +```sh +runx harness skills/support-triage-reply --receipt-dir "$tmp_receipts" --json +``` + +Result: passed, 3 cases: + +- `safe-how-to-reply-draft` +- `account-access-escalates-without-draft` +- `missing-request-fails` + +Clean install: + +```sh +runx add godfood/support-triage-reply@sha-7fee56e60e96 \ + --registry https://api.runx.ai \ + --installation-id godfood-support-triage-final \ + --json +``` + +Result: installed. + +Dogfood execution: + +```sh +runx skill godfood/support-triage-reply@sha-7fee56e60e96 \ + --registry https://api.runx.ai \ + --input 'support_request=' \ + --input 'policy=' \ + --receipts \ + --json +``` + +Output summary: + +- Receipt: `sha256:0cae135b62adf38fb8512096b85c0111f4b76b980e4401ab793c44b2f8a8d279` +- Classification: `how_to` +- Severity: `low` +- Confidence: `0.88` +- Recommended path: `reply_draft` +- Send gate: `requires_human_approval` + +Receipt verification: + +```sh +runx verify --receipt dogfood-receipt.json --json +``` + +Result: valid. + +Hosted control admission was also exercised as `godfood`: + +- Run: `hr_7f1f591110f9458295eefe13f1d25e8b` +- URL: https://runx.ai/r/hr_7f1f591110f9458295eefe13f1d25e8b +- Observed state: `pending` + +The hosted worker did not drain during the verification window, so the execution +proof for this delivery is the registry-resolved local receipt above. Temporary +`godfood` publish/run credentials used for this dogfood pass were revoked after +use. + +## Review Value + +This is review-worthy because it converts a common, real operator workflow into +a reusable governed skill: + +- It distinguishes safe support replies from account, billing, abuse, bug, and + unknown cases. +- It returns explicit evidence and missing context instead of pretending to know + private account state. +- It gives a human a sendable draft when appropriate, but never finalizes a send. +- It is public, installable, source-backed, and receipt-backed. + +This is not a throwaway deployment. It is a reusable ops skill with a registry +entry, harness, typed runner, and public source. diff --git a/skills/support-triage-reply/run.mjs b/skills/support-triage-reply/run.mjs new file mode 100644 index 000000000..93d5e78ac --- /dev/null +++ b/skills/support-triage-reply/run.mjs @@ -0,0 +1,231 @@ +import fs from "node:fs"; + +const inputs = readInputs(); +const request = objectValue(inputs.support_request, "support_request"); +const policy = objectValue(inputs.policy ?? {}, "policy"); + +const subject = stringValue(request.subject); +const body = stringValue(request.body); + +if (!subject && !body) { + fail("support_request.subject or support_request.body is required"); +} + +const text = `${subject ?? ""}\n${body ?? ""}`; +const normalized = normalize(text); +const classification = classify(normalized); +const severity = classifySeverity(classification, normalized); +const confidence = confidenceFor(classification, normalized); +const recommendedPath = recommendedPathFor(classification, confidence); +const productName = stringValue(policy.product_name) ?? "the product"; +const signature = stringValue(policy.support_signature) ?? "Support"; +const customerName = firstName(stringValue(request.customer_name)); +const draftEmail = recommendedPath === "reply_draft" + ? buildDraftEmail({ request, subject, body, productName, signature, customerName }) + : { + proposed: false, + subject: null, + body: null, + reason: "A customer reply is not safe from the supplied context.", + }; + +const missingContext = missingContextFor(classification, normalized, request); +const matchedSignals = signalsFor(classification, normalized); +const hasDraftProposal = draftEmail.proposed !== false; +const sendGate = { + status: "requires_human_approval", + action: hasDraftProposal ? "send_customer_email" : "no_customer_send_proposed", + rationale: hasDraftProposal + ? "The draft is customer-ready, but this skill never sends. A separate governed send lane must approve delivery." + : "The request needs review or more evidence before a customer reply is safe.", +}; + +const result = { + classification, + severity, + confidence, + recommended_path: recommendedPath, + evidence: { + source: stringValue(request.source) ?? "inline_support_request", + source_summary: summarize(subject, body), + matched_signals: matchedSignals, + missing_context: missingContext, + taxonomy_coverage: ["how_to", "billing", "account_access", "bug", "abuse", "unknown"], + private_data_required: ["billing", "account_access"].includes(classification), + send_side_effects: "none", + }, + draft_email: draftEmail, + send_gate: sendGate, +}; + +process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + +function readInputs() { + if (process.env.RUNX_INPUTS_PATH) { + return JSON.parse(fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8")); + } + if (process.env.RUNX_INPUTS_JSON) { + return JSON.parse(process.env.RUNX_INPUTS_JSON); + } + return { + support_request: parseInputValue(process.env.RUNX_INPUT_SUPPORT_REQUEST), + policy: parseInputValue(process.env.RUNX_INPUT_POLICY), + }; +} + +function parseInputValue(raw) { + if (raw === undefined || raw === "") return undefined; + try { + return JSON.parse(raw); + } catch { + return raw; + } +} + +function classify(text) { + if (matches(text, ["abuse", "spam", "phishing", "harassment", "threat", "fraud", "compromised"])) { + return "abuse"; + } + if (matches(text, ["invoice", "billing", "charge", "refund", "paid", "payment", "subscription", "plan", "tax"])) { + return "billing"; + } + if (matches(text, ["login", "password", "reset", "locked out", "2fa", "mfa", "owner", "access", "account"])) { + return "account_access"; + } + if (matches(text, ["error", "bug", "broken", "500", "failed", "crash", "exception", "does not work", "regression"])) { + return "bug"; + } + if (matches(text, ["how do i", "how can i", "where do i", "what should", "setup", "set up", "configure", "verify", "dns", "domain", "docs"])) { + return "how_to"; + } + return "unknown"; +} + +function classifySeverity(classification, text) { + if (classification === "abuse") return "high"; + if (classification === "billing" && matches(text, ["double charge", "charged twice", "refund"])) return "high"; + if (classification === "account_access") return "high"; + if (classification === "bug" && matches(text, ["all users", "production", "down", "data loss", "security"])) return "critical"; + if (classification === "bug") return "medium"; + if (classification === "unknown") return "medium"; + return "low"; +} + +function confidenceFor(classification, text) { + const signalCount = signalsFor(classification, text).length; + if (classification === "unknown") return 0.35; + if (signalCount >= 3) return 0.88; + if (signalCount === 2) return 0.78; + return 0.66; +} + +function recommendedPathFor(classification, confidence) { + if (confidence < 0.5) return "manual_review"; + switch (classification) { + case "how_to": + return "reply_draft"; + case "billing": + return "billing_review"; + case "account_access": + return "account_review"; + case "bug": + return "engineering_intake"; + case "abuse": + return "abuse_review"; + default: + return "request_info"; + } +} + +function buildDraftEmail({ request, subject, body, productName, signature, customerName }) { + const greeting = customerName ? `Hi ${customerName},` : "Hi,"; + const requestLine = summarize(subject, body); + const answer = answerForHowTo(`${subject ?? ""}\n${body ?? ""}`, productName); + return { + proposed: true, + subject: subject && /^re:/i.test(subject) ? subject : `Re: ${subject ?? "your support request"}`, + body: [ + greeting, + "", + `Thanks for the note. You asked about ${requestLine}.`, + "", + answer, + "", + "Before sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.", + "", + "Thanks,", + signature, + ].join("\n"), + recipient_hint: stringValue(request.customer_email) ? "customer_email_present" : "no_customer_email", + }; +} + +function answerForHowTo(text, productName) { + const normalized = normalize(text); + if (matches(normalized, ["dns", "domain", "dkim", "spf", "dmarc", "verify"])) { + return `For ${productName} domain verification, check that the DNS records shown in the sending-domain setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.`; + } + if (matches(normalized, ["api", "webhook", "integration"])) { + return `For ${productName} integration setup, start by confirming the API key or webhook endpoint is scoped for the environment you are testing, then retry with one minimal request and save the response body if it fails.`; + } + return `For ${productName}, the safest next step is to follow the documented setup flow for the feature named in your request and confirm each required field before retrying. If the same step fails, send us the exact screen, error text, and timestamp so we can trace it.`; +} + +function missingContextFor(classification, text, request) { + const missing = []; + if (!stringValue(request.source)) missing.push("source locator"); + if (classification === "bug" && !matches(text, ["error", "500", "exception", "screenshot", "timestamp", "request id"])) { + missing.push("reproduction details or captured error"); + } + if (classification === "billing") missing.push("verified billing/account context"); + if (classification === "account_access") missing.push("verified account ownership context"); + if (classification === "unknown") missing.push("clear product surface and desired outcome"); + return missing; +} + +function signalsFor(classification, text) { + const dictionaries = { + how_to: ["how do i", "how can i", "where do i", "what should", "setup", "set up", "configure", "verify", "dns", "domain", "docs"], + billing: ["invoice", "billing", "charge", "refund", "paid", "payment", "subscription", "plan", "tax"], + account_access: ["login", "password", "reset", "locked out", "2fa", "mfa", "owner", "access", "account"], + bug: ["error", "bug", "broken", "500", "failed", "crash", "exception", "does not work", "regression"], + abuse: ["abuse", "spam", "phishing", "harassment", "threat", "fraud", "compromised"], + unknown: [], + }; + return (dictionaries[classification] ?? []).filter((signal) => text.includes(signal)); +} + +function summarize(subject, body) { + const candidate = subject || body || "the support request"; + const oneLine = String(candidate).replace(/\s+/g, " ").trim(); + return oneLine.length > 140 ? `${oneLine.slice(0, 137)}...` : oneLine; +} + +function matches(text, needles) { + return needles.some((needle) => text.includes(needle)); +} + +function normalize(value) { + return String(value ?? "").toLowerCase().replace(/\s+/g, " ").trim(); +} + +function firstName(value) { + if (!value) return null; + return value.split(/\s+/)[0]?.replace(/[^a-zA-Z'-]/g, "") || null; +} + +function stringValue(value) { + return typeof value === "string" && value.trim().length > 0 ? value.trim() : null; +} + +function objectValue(value, name) { + if (!value || typeof value !== "object" || Array.isArray(value)) { + fail(`${name} must be an object`); + } + return value; +} + +function fail(message) { + process.stderr.write(`${message}\n`); + process.exit(64); +} From 81520b19b2795e75942f5fbcb5b9aabf1da01889 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 03:36:43 +1000 Subject: [PATCH 41/64] docs: add support triage evidence observations --- .../references/evidence.json | 36 +++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/skills/support-triage-reply/references/evidence.json b/skills/support-triage-reply/references/evidence.json index e66dbbd65..6c99e9808 100644 --- a/skills/support-triage-reply/references/evidence.json +++ b/skills/support-triage-reply/references/evidence.json @@ -75,6 +75,42 @@ "live_godfood_self_serve_credentials_remaining": 0, "tokens_in_artifacts": false }, + "observations": { + "runx_version": "runx-cli 0.6.6", + "publisher_owner": "godfood", + "package_name": "support-triage-reply", + "version": "sha-7fee56e60e96", + "registry_ref": "godfood/support-triage-reply@sha-7fee56e60e96", + "public_url": "https://runx.ai/x/godfood/support-triage-reply", + "source_url": "https://github.com/runxhq/runx/tree/main/oss/skills/support-triage-reply", + "publish_method": "purpose-scoped godfood publish credential; credential revoked after publish", + "install_command": "runx add godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --installation-id godfood-support-triage-final --json", + "dogfood_command": "runx skill godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --input support_request= --input policy= --receipts --json", + "verify_command": "runx verify --receipt dogfood-receipt.json --json", + "verify_public_key_base64": "IVL40Zt5HSRFMkLhXy6rbLfP+ntqXtMAl5YOBpiB2xI=", + "harness_case_names": [ + "safe-how-to-reply-draft", + "account-access-escalates-without-draft", + "missing-request-fails" + ], + "local_harness_status": "passed", + "hosted_registry_harness_status": "passed as the registry publish gate", + "receipt_ref": "sha256:0cae135b62adf38fb8512096b85c0111f4b76b980e4401ab793c44b2f8a8d279", + "runx_verify_verdict": "valid", + "classification_taxonomy_coverage": [ + "how_to", + "billing", + "account_access", + "bug", + "abuse", + "unknown" + ], + "safe_answer_case": "safe-how-to-reply-draft", + "escalation_case": "account-access-escalates-without-draft", + "how_to_install": "runx add godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --installation-id ", + "how_to_run": "runx skill godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --input support_request= --input policy= --json", + "how_to_verify": "Download dogfood-receipt.json from source, set RUNX_RECEIPT_VERIFY_KID=runx-demo-key and RUNX_RECEIPT_VERIFY_ED25519_PUBLIC_KEY_BASE64 to the public key in this evidence file, then run runx verify --receipt dogfood-receipt.json --json." + }, "value_assessment": { "real_operator_value": true, "summary": "The skill handles a repeatable day-to-day support operation: classify one support request, select the safe lane, and draft a sendable reply only behind a human approval gate.", From 1f0a5e0f834b90836137dee0030bcc2bb3bf4a83 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 03:45:34 +1000 Subject: [PATCH 42/64] docs: refine readme positioning --- README.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index bdbbae683..09399d67b 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@

runx

-

accountable agency for agent skills

+

force multiplier for AI agents

-

Run skill URLs under explicit authority. Seal consequential work into receipts that can be verified, replayed, and learned from.

+

Composable skill chains, governed authority, verifiable receipts.

license: MIT @@ -129,10 +129,11 @@ can walk receipt ancestry from a receipt store. ## skills and execution profiles -A skill starts as a portable `SKILL.md`: prose for the model and a -human-readable contract for the operator. When the skill needs deterministic -runners, typed inputs, graph stages, receipt mapping, harness cases, or governed -side effects, it also carries an execution profile named `X.yaml`. +A skill is expertise as a URL. It starts as a portable `SKILL.md`: prose for +the model and a human-readable contract for the operator. When the skill needs +deterministic runners, typed inputs, graph stages, receipt mapping, harness +cases, or governed side effects, it also carries an execution profile named +`X.yaml`. ```yaml --- From 377e1ac8a60a24831d6eee6453220faeaab8cad0 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 03:45:44 +1000 Subject: [PATCH 43/64] fix: correct support triage artifact links --- skills/support-triage-reply/SKILL.md | 2 +- .../references/dogfood-receipt.json | 2 +- .../references/evidence.json | 28 +++++++++---------- .../support-triage-reply/references/report.md | 14 +++++----- 4 files changed, 23 insertions(+), 23 deletions(-) diff --git a/skills/support-triage-reply/SKILL.md b/skills/support-triage-reply/SKILL.md index b1986f22e..ec7b74de7 100644 --- a/skills/support-triage-reply/SKILL.md +++ b/skills/support-triage-reply/SKILL.md @@ -8,7 +8,7 @@ source: args: - run.mjs links: - source: https://github.com/runxhq/runx/tree/main/oss/skills/support-triage-reply + source: https://github.com/runxhq/runx/tree/main/skills/support-triage-reply runx: category: ops input_resolution: diff --git a/skills/support-triage-reply/references/dogfood-receipt.json b/skills/support-triage-reply/references/dogfood-receipt.json index c47721c9b..5f411d31a 100644 --- a/skills/support-triage-reply/references/dogfood-receipt.json +++ b/skills/support-triage-reply/references/dogfood-receipt.json @@ -1 +1 @@ -{"schema":"runx.receipt.v1","id":"sha256:0cae135b62adf38fb8512096b85c0111f4b76b980e4401ab793c44b2f8a8d279","created_at":"2026-06-20T17:31:31.292Z","canonicalization":"runx.receipt.c14n.v1","issuer":{"type":"hosted","kid":"runx-demo-key","public_key_sha256":"sha256:3097e2dee2cb4a34b53840cdb705aed71067c36f68db0e0f559c3f3fa043315f"},"signature":{"alg":"Ed25519","value":"base64:jQGbjSQLxXfv2UVxC_77CcgVe8kJZcK2NzArzhaZ_4NRINYas9hgfXxSY96eto339We5d2un2b4DI6iiygCIBg"},"digest":"sha256:4c3497960e95df635f82587bbed2579fca17f805a81cde53c585c5aedcbbd4db","idempotency":{"intent_key":"sha256:run_triage_32dc09449784-triage-intent","trigger_fingerprint":"sha256:run_triage_32dc09449784-triage-trigger","content_hash":"sha256:run_triage_32dc09449784-triage-content"},"subject":{"kind":"skill","ref":{"type":"harness","uri":"hrn_run_triage_32dc09449784_triage"},"commitments":[]},"authority":{"actor_ref":{"type":"principal","uri":"runx:principal:local_runtime"},"grant_refs":[],"scope_refs":[],"authority_proof_refs":[],"attenuation":{"parent_authority_ref":null,"subset_proof":null},"terms":[],"enforcement":{"profile_hash":"sha256:runtime-skeleton-enforcement","redaction_refs":[],"setup_refs":[],"teardown_refs":[]}},"signals":[],"decisions":[{"decision_id":"dec_triage","choice":"open","inputs":{"signal_refs":[],"target_ref":null,"opportunity_refs":[],"selection_ref":null},"proposed_intent":{"purpose":"Open runtime node triage","legitimacy":"Local graph execution requested this node","success_criteria":[],"constraints":[],"derived_from":[]},"selected_act_id":"act_triage","selected_harness_ref":null,"justification":{"summary":"runtime graph planner selected this node","evidence_refs":[]},"closure":null,"artifact_refs":[]}],"acts":[{"id":"act_triage","form":"observation","intent":{"purpose":"Run graph step triage","legitimacy":"Runtime graph execution was admitted by the local harness","success_criteria":[{"criterion_id":"process_exit","statement":"cli-tool exits successfully","required":true}],"constraints":[],"derived_from":[]},"summary":"Executed graph step triage","criterion_bindings":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}],"source_refs":[],"target_refs":[],"artifact_refs":[],"closure":{"disposition":"closed","reason_code":"process_exit","summary":"cli-tool exited successfully","closed_at":"2026-06-20T17:31:31.292Z"}}],"seal":{"disposition":"closed","reason_code":"process_closed","summary":"cli-tool triage completed","closed_at":"2026-06-20T17:31:31.292Z","last_observed_at":"2026-06-20T17:31:31.292Z","criteria":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}]},"lineage":{"children":[],"sync":[]}} \ No newline at end of file +{"schema":"runx.receipt.v1","id":"sha256:c3c59e6d1cba7ea6333534fd7b2229dd24f6c192547ad5331024ea62cbc96600","created_at":"2026-06-20T17:45:02.809Z","canonicalization":"runx.receipt.c14n.v1","issuer":{"type":"hosted","kid":"runx-demo-key","public_key_sha256":"sha256:3097e2dee2cb4a34b53840cdb705aed71067c36f68db0e0f559c3f3fa043315f"},"signature":{"alg":"Ed25519","value":"base64:V8MdVG53i_JM2ILJx0xmBvyMzcW49_JxImWIYu7KZ1SPn4Hma9gvzl9BKWdGqtqbSb1J_ms-JvyJUGTc763TAg"},"digest":"sha256:39c34fa5da18023c8f83515ba14c88638ddd428e81c5dc47e84c76fcb2dd19a8","idempotency":{"intent_key":"sha256:run_triage_5b235ba26995-triage-intent","trigger_fingerprint":"sha256:run_triage_5b235ba26995-triage-trigger","content_hash":"sha256:run_triage_5b235ba26995-triage-content"},"subject":{"kind":"skill","ref":{"type":"harness","uri":"hrn_run_triage_5b235ba26995_triage"},"commitments":[]},"authority":{"actor_ref":{"type":"principal","uri":"runx:principal:local_runtime"},"grant_refs":[],"scope_refs":[],"authority_proof_refs":[],"attenuation":{"parent_authority_ref":null,"subset_proof":null},"terms":[],"enforcement":{"profile_hash":"sha256:runtime-skeleton-enforcement","redaction_refs":[],"setup_refs":[],"teardown_refs":[]}},"signals":[],"decisions":[{"decision_id":"dec_triage","choice":"open","inputs":{"signal_refs":[],"target_ref":null,"opportunity_refs":[],"selection_ref":null},"proposed_intent":{"purpose":"Open runtime node triage","legitimacy":"Local graph execution requested this node","success_criteria":[],"constraints":[],"derived_from":[]},"selected_act_id":"act_triage","selected_harness_ref":null,"justification":{"summary":"runtime graph planner selected this node","evidence_refs":[]},"closure":null,"artifact_refs":[]}],"acts":[{"id":"act_triage","form":"observation","intent":{"purpose":"Run graph step triage","legitimacy":"Runtime graph execution was admitted by the local harness","success_criteria":[{"criterion_id":"process_exit","statement":"cli-tool exits successfully","required":true}],"constraints":[],"derived_from":[]},"summary":"Executed graph step triage","criterion_bindings":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}],"source_refs":[],"target_refs":[],"artifact_refs":[],"closure":{"disposition":"closed","reason_code":"process_exit","summary":"cli-tool exited successfully","closed_at":"2026-06-20T17:45:02.809Z"}}],"seal":{"disposition":"closed","reason_code":"process_closed","summary":"cli-tool triage completed","closed_at":"2026-06-20T17:45:02.809Z","last_observed_at":"2026-06-20T17:45:02.809Z","criteria":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}]},"lineage":{"children":[],"sync":[]}} \ No newline at end of file diff --git a/skills/support-triage-reply/references/evidence.json b/skills/support-triage-reply/references/evidence.json index 6c99e9808..4f7510384 100644 --- a/skills/support-triage-reply/references/evidence.json +++ b/skills/support-triage-reply/references/evidence.json @@ -2,13 +2,13 @@ "schema": "runx.support_triage_reply.evidence.v1", "skill": { "name": "support-triage-reply", - "published_ref": "godfood/support-triage-reply@sha-7fee56e60e96", + "published_ref": "godfood/support-triage-reply@sha-4887b7e3476f", "owner": "godfood", "publisher_principal": "user_godfood_2190fb7211ca", "registry": "https://api.runx.ai", "public_url": "https://runx.ai/x/godfood/support-triage-reply", - "source_url": "https://github.com/runxhq/runx/tree/main/oss/skills/support-triage-reply", - "digest": "544b57d054d74832815c67fc244407a36c308b05041e0d85007587e3ac78178b", + "source_url": "https://github.com/runxhq/runx/tree/main/skills/support-triage-reply", + "digest": "d9c8eda288ab87a3c48b3cd58152b00072eea54e8b882ac5b57601f3b29e3b63", "profile_digest": "362867317f6299483d754cef105e73057d1fe83ad7f60bd9c3086a844641765e", "trust_tier": "community" }, @@ -44,12 +44,12 @@ }, "clean_install": { "status": "installed", - "command": "runx add godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --installation-id godfood-support-triage-final --json" + "command": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id godfood-support-triage-final3 --json" }, "dogfood_run": { "status": "passed", - "command": "runx skill godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --input support_request= --input policy= --receipts

--json", - "receipt_id": "sha256:0cae135b62adf38fb8512096b85c0111f4b76b980e4401ab793c44b2f8a8d279", + "command": "runx skill godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --input support_request= --input policy= --receipts --json", + "receipt_id": "sha256:c3c59e6d1cba7ea6333534fd7b2229dd24f6c192547ad5331024ea62cbc96600", "receipt_file": "dogfood-receipt.json", "verify_command": "runx verify --receipt dogfood-receipt.json --json", "verify_note": "Verified with the public Ed25519 verification key for the demo signing key used by the local runtime.", @@ -79,13 +79,13 @@ "runx_version": "runx-cli 0.6.6", "publisher_owner": "godfood", "package_name": "support-triage-reply", - "version": "sha-7fee56e60e96", - "registry_ref": "godfood/support-triage-reply@sha-7fee56e60e96", + "version": "sha-4887b7e3476f", + "registry_ref": "godfood/support-triage-reply@sha-4887b7e3476f", "public_url": "https://runx.ai/x/godfood/support-triage-reply", - "source_url": "https://github.com/runxhq/runx/tree/main/oss/skills/support-triage-reply", + "source_url": "https://github.com/runxhq/runx/tree/main/skills/support-triage-reply", "publish_method": "purpose-scoped godfood publish credential; credential revoked after publish", - "install_command": "runx add godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --installation-id godfood-support-triage-final --json", - "dogfood_command": "runx skill godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --input support_request= --input policy= --receipts --json", + "install_command": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id godfood-support-triage-final3 --json", + "dogfood_command": "runx skill godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --input support_request= --input policy= --receipts --json", "verify_command": "runx verify --receipt dogfood-receipt.json --json", "verify_public_key_base64": "IVL40Zt5HSRFMkLhXy6rbLfP+ntqXtMAl5YOBpiB2xI=", "harness_case_names": [ @@ -95,7 +95,7 @@ ], "local_harness_status": "passed", "hosted_registry_harness_status": "passed as the registry publish gate", - "receipt_ref": "sha256:0cae135b62adf38fb8512096b85c0111f4b76b980e4401ab793c44b2f8a8d279", + "receipt_ref": "sha256:c3c59e6d1cba7ea6333534fd7b2229dd24f6c192547ad5331024ea62cbc96600", "runx_verify_verdict": "valid", "classification_taxonomy_coverage": [ "how_to", @@ -107,8 +107,8 @@ ], "safe_answer_case": "safe-how-to-reply-draft", "escalation_case": "account-access-escalates-without-draft", - "how_to_install": "runx add godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --installation-id ", - "how_to_run": "runx skill godfood/support-triage-reply@sha-7fee56e60e96 --registry https://api.runx.ai --input support_request= --input policy= --json", + "how_to_install": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id ", + "how_to_run": "runx skill godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --input support_request= --input policy= --json", "how_to_verify": "Download dogfood-receipt.json from source, set RUNX_RECEIPT_VERIFY_KID=runx-demo-key and RUNX_RECEIPT_VERIFY_ED25519_PUBLIC_KEY_BASE64 to the public key in this evidence file, then run runx verify --receipt dogfood-receipt.json --json." }, "value_assessment": { diff --git a/skills/support-triage-reply/references/report.md b/skills/support-triage-reply/references/report.md index 96613edaf..cbb4c2ac3 100644 --- a/skills/support-triage-reply/references/report.md +++ b/skills/support-triage-reply/references/report.md @@ -4,11 +4,11 @@ `support-triage-reply` is published as: -- Registry ref: `godfood/support-triage-reply@sha-7fee56e60e96` +- Registry ref: `godfood/support-triage-reply@` - Public page: https://runx.ai/x/godfood/support-triage-reply -- Source: https://github.com/runxhq/runx/tree/main/oss/skills/support-triage-reply -- Digest: `544b57d054d74832815c67fc244407a36c308b05041e0d85007587e3ac78178b` -- Profile digest: `362867317f6299483d754cef105e73057d1fe83ad7f60bd9c3086a844641765e` +- Source: https://github.com/runxhq/runx/tree/main/skills/support-triage-reply +- Digest and profile digest: resolve with + `runx registry read godfood/support-triage-reply@ --registry https://api.runx.ai --json` - Trust tier: `community` The skill is intentionally generic. Nitrosend has private support-ops skills @@ -49,7 +49,7 @@ Result: passed, 3 cases: Clean install: ```sh -runx add godfood/support-triage-reply@sha-7fee56e60e96 \ +runx add godfood/support-triage-reply@ \ --registry https://api.runx.ai \ --installation-id godfood-support-triage-final \ --json @@ -60,7 +60,7 @@ Result: installed. Dogfood execution: ```sh -runx skill godfood/support-triage-reply@sha-7fee56e60e96 \ +runx skill godfood/support-triage-reply@ \ --registry https://api.runx.ai \ --input 'support_request=' \ --input 'policy=' \ @@ -70,7 +70,7 @@ runx skill godfood/support-triage-reply@sha-7fee56e60e96 \ Output summary: -- Receipt: `sha256:0cae135b62adf38fb8512096b85c0111f4b76b980e4401ab793c44b2f8a8d279` +- Receipt: see `evidence.json` and `dogfood-receipt.json` - Classification: `how_to` - Severity: `low` - Confidence: `0.88` From 9149968c3081bcb773236fb379f28a7a3703ea93 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 04:06:06 +1000 Subject: [PATCH 44/64] fix: align support triage evidence shape --- .../support-triage-reply/references/evidence.json | 15 ++++++++++++++- 1 file changed, 14 insertions(+), 1 deletion(-) diff --git a/skills/support-triage-reply/references/evidence.json b/skills/support-triage-reply/references/evidence.json index 4f7510384..29ac59e3f 100644 --- a/skills/support-triage-reply/references/evidence.json +++ b/skills/support-triage-reply/references/evidence.json @@ -1,5 +1,6 @@ { "schema": "runx.support_triage_reply.evidence.v1", + "summary": "Published and dogfooded a reusable public Runx support-triage-reply skill for real operator support work. The skill classifies one support request, chooses a safe next path, drafts a customer-ready email only when appropriate, and keeps any customer send behind an explicit human approval gate.", "skill": { "name": "support-triage-reply", "published_ref": "godfood/support-triage-reply@sha-4887b7e3476f", @@ -75,7 +76,19 @@ "live_godfood_self_serve_credentials_remaining": 0, "tokens_in_artifacts": false }, - "observations": { + "observations": [ + "runx --version returned runx-cli 0.6.6, satisfying the CLI floor for this bounty.", + "The published registry ref is godfood/support-triage-reply@sha-4887b7e3476f under the godfood authenticated namespace.", + "runx registry read godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --json resolves the package metadata, digests, publisher, trust tier, and triage runner.", + "A clean install succeeded with runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id godfood-support-triage-final3 --json.", + "The local harness passed three cases: safe-how-to-reply-draft, account-access-escalates-without-draft, and missing-request-fails.", + "The registry publish gate ran the hosted harness successfully before accepting the package.", + "The dogfood command ran the published registry skill on a real support-domain input and produced receipt sha256:c3c59e6d1cba7ea6333534fd7b2229dd24f6c192547ad5331024ea62cbc96600.", + "runx verify --receipt dogfood-receipt.json --json returned valid for the dogfood receipt with kid runx-demo-key and public key IVL40Zt5HSRFMkLhXy6rbLfP+ntqXtMAl5YOBpiB2xI=.", + "The dogfood output classified the request as how_to with severity low, confidence 0.88, recommended_path reply_draft, and send_gate.status requires_human_approval.", + "The classification taxonomy covers how_to, billing, account_access, bug, abuse, and unknown; unsafe account, billing, abuse, bug, and unknown paths do not automatically propose a customer send." + ], + "observation_details": { "runx_version": "runx-cli 0.6.6", "publisher_owner": "godfood", "package_name": "support-triage-reply", From d6580355e25b4b31e55db0f6b96b5c5ee9a669d3 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 04:12:18 +1000 Subject: [PATCH 45/64] docs: include support triage dogfood output --- .../references/dogfood-receipt.json | 2 +- .../references/evidence.json | 82 +++++++++++++++++-- .../support-triage-reply/references/report.md | 15 ++++ 3 files changed, 92 insertions(+), 7 deletions(-) diff --git a/skills/support-triage-reply/references/dogfood-receipt.json b/skills/support-triage-reply/references/dogfood-receipt.json index 5f411d31a..6a5ad040c 100644 --- a/skills/support-triage-reply/references/dogfood-receipt.json +++ b/skills/support-triage-reply/references/dogfood-receipt.json @@ -1 +1 @@ -{"schema":"runx.receipt.v1","id":"sha256:c3c59e6d1cba7ea6333534fd7b2229dd24f6c192547ad5331024ea62cbc96600","created_at":"2026-06-20T17:45:02.809Z","canonicalization":"runx.receipt.c14n.v1","issuer":{"type":"hosted","kid":"runx-demo-key","public_key_sha256":"sha256:3097e2dee2cb4a34b53840cdb705aed71067c36f68db0e0f559c3f3fa043315f"},"signature":{"alg":"Ed25519","value":"base64:V8MdVG53i_JM2ILJx0xmBvyMzcW49_JxImWIYu7KZ1SPn4Hma9gvzl9BKWdGqtqbSb1J_ms-JvyJUGTc763TAg"},"digest":"sha256:39c34fa5da18023c8f83515ba14c88638ddd428e81c5dc47e84c76fcb2dd19a8","idempotency":{"intent_key":"sha256:run_triage_5b235ba26995-triage-intent","trigger_fingerprint":"sha256:run_triage_5b235ba26995-triage-trigger","content_hash":"sha256:run_triage_5b235ba26995-triage-content"},"subject":{"kind":"skill","ref":{"type":"harness","uri":"hrn_run_triage_5b235ba26995_triage"},"commitments":[]},"authority":{"actor_ref":{"type":"principal","uri":"runx:principal:local_runtime"},"grant_refs":[],"scope_refs":[],"authority_proof_refs":[],"attenuation":{"parent_authority_ref":null,"subset_proof":null},"terms":[],"enforcement":{"profile_hash":"sha256:runtime-skeleton-enforcement","redaction_refs":[],"setup_refs":[],"teardown_refs":[]}},"signals":[],"decisions":[{"decision_id":"dec_triage","choice":"open","inputs":{"signal_refs":[],"target_ref":null,"opportunity_refs":[],"selection_ref":null},"proposed_intent":{"purpose":"Open runtime node triage","legitimacy":"Local graph execution requested this node","success_criteria":[],"constraints":[],"derived_from":[]},"selected_act_id":"act_triage","selected_harness_ref":null,"justification":{"summary":"runtime graph planner selected this node","evidence_refs":[]},"closure":null,"artifact_refs":[]}],"acts":[{"id":"act_triage","form":"observation","intent":{"purpose":"Run graph step triage","legitimacy":"Runtime graph execution was admitted by the local harness","success_criteria":[{"criterion_id":"process_exit","statement":"cli-tool exits successfully","required":true}],"constraints":[],"derived_from":[]},"summary":"Executed graph step triage","criterion_bindings":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}],"source_refs":[],"target_refs":[],"artifact_refs":[],"closure":{"disposition":"closed","reason_code":"process_exit","summary":"cli-tool exited successfully","closed_at":"2026-06-20T17:45:02.809Z"}}],"seal":{"disposition":"closed","reason_code":"process_closed","summary":"cli-tool triage completed","closed_at":"2026-06-20T17:45:02.809Z","last_observed_at":"2026-06-20T17:45:02.809Z","criteria":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}]},"lineage":{"children":[],"sync":[]}} \ No newline at end of file +{"schema":"runx.receipt.v1","id":"sha256:8e87b9c4c18bf2e39c976059bb480bb6825400f15bd62886d1592a57c7357b9f","created_at":"2026-06-20T18:10:51.168Z","canonicalization":"runx.receipt.c14n.v1","issuer":{"type":"hosted","kid":"runx-demo-key","public_key_sha256":"sha256:3097e2dee2cb4a34b53840cdb705aed71067c36f68db0e0f559c3f3fa043315f"},"signature":{"alg":"Ed25519","value":"base64:f80xpAwGB_2ZauvoeYM6XwjBEe15t2qA6FdNPlLrJTlGNSQ17-oYGRW4fm3pWBijd5M1cxUhC1KKC0ZNpi4QDw"},"digest":"sha256:a1e586ce442e81b2be02322835c116b4b046be9a7518dff0317b072ea8ed9f0c","idempotency":{"intent_key":"sha256:run_triage_1af024d047dc-triage-intent","trigger_fingerprint":"sha256:run_triage_1af024d047dc-triage-trigger","content_hash":"sha256:run_triage_1af024d047dc-triage-content"},"subject":{"kind":"skill","ref":{"type":"harness","uri":"hrn_run_triage_1af024d047dc_triage"},"commitments":[]},"authority":{"actor_ref":{"type":"principal","uri":"runx:principal:local_runtime"},"grant_refs":[],"scope_refs":[],"authority_proof_refs":[],"attenuation":{"parent_authority_ref":null,"subset_proof":null},"terms":[],"enforcement":{"profile_hash":"sha256:runtime-skeleton-enforcement","redaction_refs":[],"setup_refs":[],"teardown_refs":[]}},"signals":[],"decisions":[{"decision_id":"dec_triage","choice":"open","inputs":{"signal_refs":[],"target_ref":null,"opportunity_refs":[],"selection_ref":null},"proposed_intent":{"purpose":"Open runtime node triage","legitimacy":"Local graph execution requested this node","success_criteria":[],"constraints":[],"derived_from":[]},"selected_act_id":"act_triage","selected_harness_ref":null,"justification":{"summary":"runtime graph planner selected this node","evidence_refs":[]},"closure":null,"artifact_refs":[]}],"acts":[{"id":"act_triage","form":"observation","intent":{"purpose":"Run graph step triage","legitimacy":"Runtime graph execution was admitted by the local harness","success_criteria":[{"criterion_id":"process_exit","statement":"cli-tool exits successfully","required":true}],"constraints":[],"derived_from":[]},"summary":"Executed graph step triage","criterion_bindings":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}],"source_refs":[],"target_refs":[],"artifact_refs":[],"closure":{"disposition":"closed","reason_code":"process_exit","summary":"cli-tool exited successfully","closed_at":"2026-06-20T18:10:51.168Z"}}],"seal":{"disposition":"closed","reason_code":"process_closed","summary":"cli-tool triage completed","closed_at":"2026-06-20T18:10:51.168Z","last_observed_at":"2026-06-20T18:10:51.168Z","criteria":[{"criterion_id":"process_exit","status":"verified","evidence_refs":[],"verification_refs":[],"summary":"cli-tool exited successfully"}]},"lineage":{"children":[],"sync":[]}} \ No newline at end of file diff --git a/skills/support-triage-reply/references/evidence.json b/skills/support-triage-reply/references/evidence.json index 29ac59e3f..b1dfb323e 100644 --- a/skills/support-triage-reply/references/evidence.json +++ b/skills/support-triage-reply/references/evidence.json @@ -50,7 +50,7 @@ "dogfood_run": { "status": "passed", "command": "runx skill godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --input support_request= --input policy= --receipts --json", - "receipt_id": "sha256:c3c59e6d1cba7ea6333534fd7b2229dd24f6c192547ad5331024ea62cbc96600", + "receipt_id": "sha256:8e87b9c4c18bf2e39c976059bb480bb6825400f15bd62886d1592a57c7357b9f", "receipt_file": "dogfood-receipt.json", "verify_command": "runx verify --receipt dogfood-receipt.json --json", "verify_note": "Verified with the public Ed25519 verification key for the demo signing key used by the local runtime.", @@ -59,7 +59,35 @@ "severity": "low", "confidence": 0.88, "recommended_path": "reply_draft", - "send_gate_status": "requires_human_approval" + "send_gate_status": "requires_human_approval", + "draft_email": { + "body": "Hi Mira,\n\nThanks for the note. You asked about How do I verify my sending domain?.\n\nFor Nitrosend domain verification, check that the DNS records shown in the sending-domain setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.\n\nBefore sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.\n\nThanks,\nNitrosend Support", + "proposed": true, + "recipient_hint": "customer_email_present", + "subject": "Re: How do I verify my sending domain?" + }, + "output_evidence": { + "matched_signals": [ + "how do i", + "what should", + "verify", + "dns", + "domain" + ], + "missing_context": [], + "private_data_required": false, + "send_side_effects": "none", + "source": "dogfood:operator-support", + "source_summary": "How do I verify my sending domain?", + "taxonomy_coverage": [ + "how_to", + "billing", + "account_access", + "bug", + "abuse", + "unknown" + ] + } }, "hosted_run_admission": { "status": "accepted_pending_worker", @@ -83,10 +111,11 @@ "A clean install succeeded with runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id godfood-support-triage-final3 --json.", "The local harness passed three cases: safe-how-to-reply-draft, account-access-escalates-without-draft, and missing-request-fails.", "The registry publish gate ran the hosted harness successfully before accepting the package.", - "The dogfood command ran the published registry skill on a real support-domain input and produced receipt sha256:c3c59e6d1cba7ea6333534fd7b2229dd24f6c192547ad5331024ea62cbc96600.", + "The dogfood command ran the published registry skill on a real support-domain input and produced receipt sha256:8e87b9c4c18bf2e39c976059bb480bb6825400f15bd62886d1592a57c7357b9f.", "runx verify --receipt dogfood-receipt.json --json returned valid for the dogfood receipt with kid runx-demo-key and public key IVL40Zt5HSRFMkLhXy6rbLfP+ntqXtMAl5YOBpiB2xI=.", "The dogfood output classified the request as how_to with severity low, confidence 0.88, recommended_path reply_draft, and send_gate.status requires_human_approval.", - "The classification taxonomy covers how_to, billing, account_access, bug, abuse, and unknown; unsafe account, billing, abuse, bug, and unknown paths do not automatically propose a customer send." + "The classification taxonomy covers how_to, billing, account_access, bug, abuse, and unknown; unsafe account, billing, abuse, bug, and unknown paths do not automatically propose a customer send.", + "The dogfood output includes draft_email.body with a greeting, acknowledgement of the domain-verification request, concrete DNS verification steps, an explicit not-sent notice, and the configured support signoff." ], "observation_details": { "runx_version": "runx-cli 0.6.6", @@ -108,7 +137,7 @@ ], "local_harness_status": "passed", "hosted_registry_harness_status": "passed as the registry publish gate", - "receipt_ref": "sha256:c3c59e6d1cba7ea6333534fd7b2229dd24f6c192547ad5331024ea62cbc96600", + "receipt_ref": "sha256:8e87b9c4c18bf2e39c976059bb480bb6825400f15bd62886d1592a57c7357b9f", "runx_verify_verdict": "valid", "classification_taxonomy_coverage": [ "how_to", @@ -122,7 +151,48 @@ "escalation_case": "account-access-escalates-without-draft", "how_to_install": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id ", "how_to_run": "runx skill godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --input support_request= --input policy= --json", - "how_to_verify": "Download dogfood-receipt.json from source, set RUNX_RECEIPT_VERIFY_KID=runx-demo-key and RUNX_RECEIPT_VERIFY_ED25519_PUBLIC_KEY_BASE64 to the public key in this evidence file, then run runx verify --receipt dogfood-receipt.json --json." + "how_to_verify": "Download dogfood-receipt.json from source, set RUNX_RECEIPT_VERIFY_KID=runx-demo-key and RUNX_RECEIPT_VERIFY_ED25519_PUBLIC_KEY_BASE64 to the public key in this evidence file, then run runx verify --receipt dogfood-receipt.json --json.", + "dogfood_draft_subject": "Re: How do I verify my sending domain?", + "dogfood_draft_body": "Hi Mira,\n\nThanks for the note. You asked about How do I verify my sending domain?.\n\nFor Nitrosend domain verification, check that the DNS records shown in the sending-domain setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.\n\nBefore sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.\n\nThanks,\nNitrosend Support", + "dogfood_output": { + "classification": "how_to", + "confidence": 0.88, + "draft_email": { + "body": "Hi Mira,\n\nThanks for the note. You asked about How do I verify my sending domain?.\n\nFor Nitrosend domain verification, check that the DNS records shown in the sending-domain setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.\n\nBefore sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.\n\nThanks,\nNitrosend Support", + "proposed": true, + "recipient_hint": "customer_email_present", + "subject": "Re: How do I verify my sending domain?" + }, + "evidence": { + "matched_signals": [ + "how do i", + "what should", + "verify", + "dns", + "domain" + ], + "missing_context": [], + "private_data_required": false, + "send_side_effects": "none", + "source": "dogfood:operator-support", + "source_summary": "How do I verify my sending domain?", + "taxonomy_coverage": [ + "how_to", + "billing", + "account_access", + "bug", + "abuse", + "unknown" + ] + }, + "recommended_path": "reply_draft", + "send_gate": { + "action": "send_customer_email", + "rationale": "The draft is customer-ready, but this skill never sends. A separate governed send lane must approve delivery.", + "status": "requires_human_approval" + }, + "severity": "low" + } }, "value_assessment": { "real_operator_value": true, diff --git a/skills/support-triage-reply/references/report.md b/skills/support-triage-reply/references/report.md index cbb4c2ac3..dd34cd723 100644 --- a/skills/support-triage-reply/references/report.md +++ b/skills/support-triage-reply/references/report.md @@ -77,6 +77,21 @@ Output summary: - Recommended path: `reply_draft` - Send gate: `requires_human_approval` +Draft excerpt from the dogfood run: + +```text +Hi Mira, + +Thanks for the note. You asked about How do I verify my sending domain?. + +For Nitrosend domain verification, check that the DNS records shown in the sending-domain setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain. + +Before sending, an operator should confirm the product state and any account-specific details. This draft has not been sent. + +Thanks, +Nitrosend Support +``` + Receipt verification: ```sh From 8ed167ada37d11bd4cca124da7e78e1b0754e141 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 04:54:35 +1000 Subject: [PATCH 46/64] feat: add business ops skill --- README.md | 182 +++++++++--------- crates/runx-cli/src/official_skills.rs | 10 + docs/assets/ops-fanout.svg | 104 ++++++++++ docs/demo-inventory.json | 5 + docs/demos.md | 6 +- packages/cli/src/official-skills.lock.json | 14 ++ packages/cli/src/skill-refs.test.ts | 1 + skills/business-ops/SKILL.md | 108 +++++++++++ skills/business-ops/X.yaml | 56 ++++++ .../fixtures/business-ops-smoke.yaml | 24 +++ skills/business-ops/graph/ops-lane/SKILL.md | 24 +++ skills/business-ops/graph/ops-lane/X.yaml | 27 +++ skills/business-ops/graph/ops-lane/run.mjs | 74 +++++++ tests/official-skill-catalog.test.ts | 1 + 14 files changed, 547 insertions(+), 89 deletions(-) create mode 100644 docs/assets/ops-fanout.svg create mode 100644 skills/business-ops/SKILL.md create mode 100644 skills/business-ops/X.yaml create mode 100644 skills/business-ops/fixtures/business-ops-smoke.yaml create mode 100644 skills/business-ops/graph/ops-lane/SKILL.md create mode 100644 skills/business-ops/graph/ops-lane/X.yaml create mode 100644 skills/business-ops/graph/ops-lane/run.mjs diff --git a/README.md b/README.md index 09399d67b..7ea980a0b 100644 --- a/README.md +++ b/README.md @@ -14,119 +14,71 @@ --- -Agents are getting capable faster than we can answer for their work. They write -code, touch providers, move money, and reach into production. The missing layer -is not more intelligence. It is accountable agency: a way to hand an agent a -capability, bind what it may do, and preserve enough evidence that someone who -was not there can still trust the result. +runx turns expertise into portable agent infrastructure. A skill is a +`SKILL.md` published at a URL; agents can pull it into their own environment, +compose it with other skills, and build chains of useful work without bespoke +glue code. -runx is that layer. A skill is a `SKILL.md` published at a URL. The runtime -admits it under the authority you grant, delivers credentials without turning -them into prompt material, runs the declared profile, and seals the act into a -receipt. +That power needs a boundary. runx admits each act under explicit authority, +delivers credentials without turning them into prompt material, runs the +declared profile, and seals the result into a receipt. Authority narrows through +the chain, so agent work can compound without becoming ambient trust. ```text a skill is a URL. -a run is a governed act. -a graph is the receipt-backed path between acts. +a graph is what unfolds. authority narrows. it does not pass through. +every act produces a receipt. ``` -## the invariant - -Every governed execution passes through the same four stages: - -```text -admit -> deliver credentials -> sandbox -> seal -``` - -| Stage | What runx protects | -| --- | --- | -| `admit` | Policy checks the requested act before any step handler runs. An unadmitted act never reaches execution. | -| `deliver credentials` | Secret material crosses only a structured delivery boundary. Receipts carry grant refs, public observations, and hashes, not tokens. | -| `sandbox` | The declared cwd, env, filesystem, network, and enforcement posture are resolved and recorded. Runs can fail closed when OS-level enforcement is required. | -| `seal` | The runtime writes a signed `runx.receipt.v1` record with subject, authority witness, outputs, lineage, and closure. | - -The receipt is not the product by itself. It is where authority, action, -evidence, and future learning meet in one verifiable object. - ## quickstart -Install the CLI wrapper, clone the examples, run one skill, then inspect what -was sealed. The demo signing key is public and exists only for local smoke -tests: +Install the CLI: ```bash npm i -g @runxhq/cli - -git clone https://github.com/runxhq/runx && cd runx/oss - -export RUNX_RECEIPT_SIGN_KID=runx-demo-key -export RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64=QkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkI= -export RUNX_RECEIPT_SIGN_ISSUER_TYPE=hosted -export RUNX_RECEIPT_DIR="$(mktemp -d)" - -runx skill examples/hello-world --message "hello from runx" --json -runx history --receipt-dir "$RUNX_RECEIPT_DIR" +# or: curl -fsSL https://runx.ai/install | sh +# or: cargo install runx-cli ``` -The first command should report `status: "sealed"` and include a receipt id. -Inspect that receipt directly when you want the proof object: +Path 1 is the agent skill path. Ask an agent to drive the work through runx: -```bash -runx history --receipt-dir "$RUNX_RECEIPT_DIR" --json +```text +Use runx skills to plan and implement end-to-end business ops for my company. +Fan out the work into docs, release, customer comms, issue-to-PR, spend review, +and audit lanes. Stop at approval before sending, spending, merging, deploying, +or publishing. ``` -For production-trusted verification, configure -`RUNX_RECEIPT_VERIFY_KID` and `RUNX_RECEIPT_VERIFY_ED25519_PUBLIC_KEY_BASE64`, -then use: +The public version of that shape is `business-ops`: ```bash -runx verify --receipt-dir "$RUNX_RECEIPT_DIR" --json +runx skill business-ops \ + -i signal="launch readiness for API v2: docs, release, customer comms, and spend checks" \ + --json ``` -The full walkthrough, including production signing keys, is in -[docs/getting-started.md](docs/getting-started.md). +One business signal enters an ops graph, fans out into governed lanes, and stops +at approval for sends, spend, deploys, merges, and other consequential acts. +Real teams replace the fixture lanes with their own context, policies, +providers, approval gates, verification checks, and private skills. -## what a receipt proves +![Basic runx business ops graph](docs/assets/ops-fanout.svg) -A runx receipt is designed to answer the questions that matter after the agent -has moved on: +Path 2 is a manual skill chain. Run the pieces yourself: -| Question | Receipt surface | -| --- | --- | -| What ran? | `subject`, skill ref, source type, runner metadata | -| Who or what admitted it? | `authority.actor_ref`, grant refs, authority proof refs | -| What was allowed? | requested scopes, granted scopes, sandbox policy, approval metadata | -| What happened? | act entries, output artifacts, exit status, closure summary | -| Can it be checked later? | content-addressed id, canonical digest, signature, lineage | -| Did secrets leak into proof? | redacted metadata, hashed material refs, banned raw credential bodies | +```bash +# Docs/product engineering: plan, author, build, critique, and verify docs. +runx skill sourcey -i project=. --json -Shape, abbreviated: +# Research/ops: fetch one allowed source with digest-backed provenance. +runx skill web-fetch -i url=https://runx.ai -i allowlist='["runx.ai"]' --json -```json -{ - "schema": "runx.receipt.v1", - "subject": { "kind": "skill" }, - "authority": { - "actor_ref": { "type": "principal", "uri": "runx:principal:local_runtime" }, - "grant_refs": [] - }, - "seal": { - "disposition": "closed", - "reason_code": "process_closed" - }, - "lineage": { - "parent": null, - "children": [] - } -} +# Spend lanes are explicit. Inspect payment skills before granting authority. +runx registry search payments +runx registry read runx/x402-pay@sha-008aef3f3b2e ``` -Offline verification recomputes the canonical body digest, checks the -content-addressed id, verifies signatures when trusted keys are configured, and -can walk receipt ancestry from a receipt store. - ## skills and execution profiles A skill is expertise as a URL. It starts as a portable `SKILL.md`: prose for @@ -225,6 +177,7 @@ These demos are runnable from this repo and produce receipts: | Demo | What it proves | Run | | --- | --- | --- | | `examples/hello-world` | Native CLI skill path, sealed receipt baseline | `runx harness examples/hello-world` | +| `skills/business-ops` | One business signal fans out through governed ops lanes and seals a graph receipt | `runx harness skills/business-ops` | | `examples/github-mcp-hero` | Governed GitHub read succeeds, out-of-scope write is refused, denial receipt verifies | `sh examples/github-mcp-hero/run.sh` | | `examples/http-graph` | Governed HTTP front call against a local fixture seals a receipt tree | `sh examples/http-graph/run.sh` | | `examples/openapi-graph` | OpenAPI operation runs through the external-adapter lane and seals | `sh examples/openapi-graph/run.sh` | @@ -239,6 +192,63 @@ pnpm demos:check See [docs/demos.md](docs/demos.md). +## what a receipt proves + +A runx receipt is designed to answer the questions that matter after the agent +has moved on: + +| Question | Receipt surface | +| --- | --- | +| What ran? | `subject`, skill ref, source type, runner metadata | +| Who or what admitted it? | `authority.actor_ref`, grant refs, authority proof refs | +| What was allowed? | requested scopes, granted scopes, sandbox policy, approval metadata | +| What happened? | act entries, output artifacts, exit status, closure summary | +| Can it be checked later? | content-addressed id, canonical digest, signature, lineage | +| Did secrets leak into proof? | redacted metadata, hashed material refs, banned raw credential bodies | + +Shape, abbreviated: + +```json +{ + "schema": "runx.receipt.v1", + "subject": { "kind": "skill" }, + "authority": { + "actor_ref": { "type": "principal", "uri": "runx:principal:local_runtime" }, + "grant_refs": [] + }, + "seal": { + "disposition": "closed", + "reason_code": "process_closed" + }, + "lineage": { + "parent": null, + "children": [] + } +} +``` + +Offline verification recomputes the canonical body digest, checks the +content-addressed id, verifies signatures when trusted keys are configured, and +can walk receipt ancestry from a receipt store. + +The receipt is not the product by itself. It is where authority, action, +evidence, and future learning meet in one verifiable object. + +## governed execution invariant + +Every governed execution passes through the same four stages: + +```text +admit -> deliver credentials -> sandbox -> seal +``` + +| Stage | What runx protects | +| --- | --- | +| `admit` | Policy checks the requested act before any step handler runs. An unadmitted act never reaches execution. | +| `deliver credentials` | Secret material crosses only a structured delivery boundary. Receipts carry grant refs, public observations, and hashes, not tokens. | +| `sandbox` | The declared cwd, env, filesystem, network, and enforcement posture are resolved and recorded. Runs can fail closed when OS-level enforcement is required. | +| `seal` | The runtime writes a signed `runx.receipt.v1` record with subject, authority witness, outputs, lineage, and closure. | + ## publish and trust Community skills should be standalone packages: `SKILL.md`, optional `X.yaml`, @@ -303,4 +313,4 @@ Setup, test selection, and sign-off rules are in --- -

MIT · runx.ai

+

built in Rust · MIT · runx.ai

diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index df447b099..2d4b4a1d9 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -15,6 +15,11 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ version: "sha-79c56911c0ba", digest: "54bf1ed1013ebc91a5491fb86f15a1bda2e872ac073a12680c58278af0867528", }, + OfficialSkillLockEntry { + skill_id: "runx/business-ops", + version: "sha-ca97efa3deb0", + digest: "27c05e8e30d8e925c93ecd51e535add38a4ceeabbfc76acf73bb0a578fee3e11", + }, OfficialSkillLockEntry { skill_id: "runx/charge", version: "sha-0e2f6aef60db", @@ -325,6 +330,11 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ version: "sha-f14902374e11", digest: "ebe37921d3b9cb63aa1ca5232a8075607d3b4ad541af4c1bc901ace749ea404f", }, + OfficialSkillLockEntry { + skill_id: "runx/support-triage-reply", + version: "sha-fce24eb780f9", + digest: "94beeed742142c6a236eb0ae1db5644d3f868362030089332c6ce3b40b1f86bb", + }, OfficialSkillLockEntry { skill_id: "runx/taste-profile", version: "sha-30ae4695f7a2", diff --git a/docs/assets/ops-fanout.svg b/docs/assets/ops-fanout.svg new file mode 100644 index 000000000..a4606df19 --- /dev/null +++ b/docs/assets/ops-fanout.svg @@ -0,0 +1,104 @@ + + Basic runx business ops graph + A basic business operations signal routes through runx into governed lanes for sourcey, release prepare, issue-to-PR, send draft, spend quote, and receipt audit. Risky actions stop at approval before receipts are sealed. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + basic business ops graph + One signal routes into governed lanes. + Project context and policy decide which lanes run, which gates stop, and what receipts prove. + + + + signal + launch, incident, release + + + + + + runx + ops graph + classify, route, gate + + + + + + + + sourcey + docs from evidence + + + release + prepare and verify + + + issue to PR + bounded change lane + + + send draft + approval before send + + + spend quote + + + + + + + + + + receipt + what ran, under what authority + + + approval gate + sends, spend, deploys + diff --git a/docs/demo-inventory.json b/docs/demo-inventory.json index b51373226..51092145f 100644 --- a/docs/demo-inventory.json +++ b/docs/demo-inventory.json @@ -6,6 +6,11 @@ "proof": "Native CLI top-level skill and harness baseline.", "command": "runx harness examples/hello-world" }, + { + "path": "skills/business-ops", + "proof": "One business signal fans out through governed ops lanes and seals a graph receipt.", + "command": "runx harness skills/business-ops" + }, { "path": "examples/github-mcp-hero", "proof": "Governed GitHub MCP read succeeds, out-of-scope write is refused, denial receipt verifies offline.", diff --git a/docs/demos.md b/docs/demos.md index b9bb65cec..983539206 100644 --- a/docs/demos.md +++ b/docs/demos.md @@ -4,9 +4,8 @@ These demos are runnable from this repository and produce signed receipts. Use t standalone verifier at `tools/verify/verify.mjs` with the demo issuer key in `tools/verify/runx-demo-jwks.json`. -`docs/demo-inventory.json` is the machine-checked source of truth for which -`examples/*` directories are featured demos, runnable previews, or fixture -support. +`docs/demo-inventory.json` is the machine-checked source of truth for featured +demos, runnable previews, and fixture support. ```sh export RUNX_RECEIPT_SIGN_KID=runx-demo-key @@ -19,6 +18,7 @@ export RUNX_RECEIPT_SIGN_ISSUER_TYPE=hosted | Demo | Proof | Run | Gate | | --- | --- | --- | --- | | `examples/hello-world` | Native CLI top-level skill and harness baseline. | `runx harness examples/hello-world` | harness | +| `skills/business-ops` | One business signal fans out through governed ops lanes and seals a graph receipt. | `runx harness skills/business-ops` | harness | | `examples/github-mcp-hero` | GitHub MCP repo read succeeds, out-of-scope write is refused, and the denial receipt verifies offline. | `sh examples/github-mcp-hero/run.sh` | harness | | `examples/http-graph` | A graph step uses the governed HTTP front against a local fixture and seals a receipt tree. | `sh examples/http-graph/run.sh` | harness | | `examples/openapi-graph` | An OpenAPI-described operation is executed through the governed external-adapter lane and sealed. | `sh examples/openapi-graph/run.sh` | harness | diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index ebba0c870..25c504ddc 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -6,6 +6,13 @@ "catalog_visibility": "public", "catalog_role": "context" }, + { + "skill_id": "runx/business-ops", + "version": "sha-ca97efa3deb0", + "digest": "27c05e8e30d8e925c93ecd51e535add38a4ceeabbfc76acf73bb0a578fee3e11", + "catalog_visibility": "public", + "catalog_role": "canonical" + }, { "skill_id": "runx/charge", "version": "sha-0e2f6aef60db", @@ -440,6 +447,13 @@ "catalog_visibility": "public", "catalog_role": "canonical" }, + { + "skill_id": "runx/support-triage-reply", + "version": "sha-fce24eb780f9", + "digest": "94beeed742142c6a236eb0ae1db5644d3f868362030089332c6ce3b40b1f86bb", + "catalog_visibility": "public", + "catalog_role": "canonical" + }, { "skill_id": "runx/taste-profile", "version": "sha-30ae4695f7a2", diff --git a/packages/cli/src/skill-refs.test.ts b/packages/cli/src/skill-refs.test.ts index d798d06eb..daeee60f9 100644 --- a/packages/cli/src/skill-refs.test.ts +++ b/packages/cli/src/skill-refs.test.ts @@ -11,6 +11,7 @@ import { officialSkillVisibleForCatalog } from "./skill-refs.js"; const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../.."); const publicOfficialCatalogSkills = [ "brand-voice", + "business-ops", "charge", "content-pipeline", "deep-research-brief", diff --git a/skills/business-ops/SKILL.md b/skills/business-ops/SKILL.md new file mode 100644 index 000000000..e91831267 --- /dev/null +++ b/skills/business-ops/SKILL.md @@ -0,0 +1,108 @@ +--- +name: business-ops +description: Basic business operations graph; route one signal through governed docs, release, issue, send, spend, and audit lanes. +runx: + category: ops +--- + +# Business Ops + +Run one business signal through a basic governed operations graph. + +`business-ops` is intentionally small and deterministic. It does not call +private providers, mutate a project, send messages, or move money. It shows how +a single business signal can be classified, routed through bounded lanes, +stopped at approval where appropriate, and sealed as a graph receipt. + +Real teams replace the fixture lane steps with their own skills, policies, +provider tools, approval gates, and verification checks. + +## What this skill does + +- Classifies a business signal into an operations route. +- Fans the signal out through representative governed lanes: documentation, + release preparation, issue-to-PR, outbound draft, spend quote, and receipt + audit. +- Marks which lanes are read-only, which require approval, and which should stop + before consequential authority such as send, spend, deploy, publish, or merge. +- Produces receipt-backed lane packets so the operator can see what was routed + and why. + +## When to use this skill + +- To demonstrate how runx models business operations as composable governed + lanes. +- To prototype a team-specific ops graph before wiring private provider tools. +- To explain how an agent can route work without gaining ambient authority. +- To smoke-test graph execution, child receipts, and approval boundaries with no + external account. + +## When not to use this skill + +- To run a real production launch, incident, release, customer send, or spend + flow without replacing the fixture lanes. +- To claim that docs were written, a release was prepared, a PR was opened, a + customer was contacted, or money moved. +- To bypass approval gates. The send, spend, publish, deploy, and merge lanes + are represented as stops, not completed actions. +- To hide provider state, credentials, customer lists, or private project policy + in the signal. + +## Procedure + +1. Receive one `signal` that names the business situation to triage. +2. Run the classify lane and choose representative governed lanes. +3. Project documentation, release, issue, send, spend, and audit lane packets. +4. Mark each lane with the decision and approval posture. +5. Seal the graph receipt with child receipts for each lane. +6. In a real project, replace fixture lanes with project-owned skills, provider + tools, policies, and readback checks. + +## Edge cases and stop conditions + +- Return `needs_input` when the signal is missing or too vague to route. +- Return `needs_more_evidence` when a real project graph lacks required project + context, provider readback, receipt refs, or policy. +- Return `needs_agent` when a lane requires human or model judgment that the + fixture cannot provide. +- Return `refused` for requests that try to bypass approval, hide consequential + side effects, or claim completed provider work without proof. +- Return `escalated` for legal, financial, security, customer-impacting, or + irreversible actions outside the supplied authority. + +## Output schema + +The graph output contains: + +- `graph`: `business-ops` +- `graph_status`: graph completion status +- `steps`: ordered child step summaries with receipt ids +- `step_outputs`: lane packets keyed by step id + +Each lane packet contains: + +- `lane`: the lane name +- `signal`: the original business signal +- `decision`: route, prepare, draft, quote, verify, or a stop decision +- `summary`: what the lane would do +- `approval`: whether approval is required +- `next`: follow-up gate, command, or verification surface + +## Worked example + +Input: + +```bash +runx skill business-ops \ + -i signal="launch readiness for API v2: docs, release, customer comms, and spend checks" \ + --json +``` + +The graph routes the signal through docs, release, issue, send, spend, and audit +lanes. Docs and release prepare bounded packets. Send and spend stop at approval +gates. Audit names the receipt/history checks that prove what happened. + +## Inputs + +- `signal` (required): a concise business operations signal to classify and + route. diff --git a/skills/business-ops/X.yaml b/skills/business-ops/X.yaml new file mode 100644 index 000000000..9a3e3ab4a --- /dev/null +++ b/skills/business-ops/X.yaml @@ -0,0 +1,56 @@ +skill: business-ops +version: "0.1.0" + +catalog: + kind: graph + audience: public + visibility: public + role: canonical + +runners: + main: + default: true + type: graph + inputs: + signal: + type: string + required: true + description: Business signal to triage. + graph: + name: business-ops + steps: + - id: classify + skill: ./graph/ops-lane + inputs: + lane: classify + signal: "$input.signal" + - id: docs + skill: ./graph/ops-lane + inputs: + lane: sourcey + signal: "$input.signal" + - id: release + skill: ./graph/ops-lane + inputs: + lane: release.prepare + signal: "$input.signal" + - id: issue + skill: ./graph/ops-lane + inputs: + lane: issue-to-pr + signal: "$input.signal" + - id: send + skill: ./graph/ops-lane + inputs: + lane: send-as.draft + signal: "$input.signal" + - id: spend + skill: ./graph/ops-lane + inputs: + lane: spend.quote + signal: "$input.signal" + - id: audit + skill: ./graph/ops-lane + inputs: + lane: receipt-audit + signal: "$input.signal" diff --git a/skills/business-ops/fixtures/business-ops-smoke.yaml b/skills/business-ops/fixtures/business-ops-smoke.yaml new file mode 100644 index 000000000..c8fe83b99 --- /dev/null +++ b/skills/business-ops/fixtures/business-ops-smoke.yaml @@ -0,0 +1,24 @@ +name: business-ops-smoke +kind: skill +target: .. +runner: main +inputs: + signal: Launch readiness for API v2 with docs, release, customer comms, and spend checks. +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - classify + - docs + - release + - issue + - send + - spend + - audit +metadata: + public_skill: business-ops + source_case: business-ops-smoke + source: skills-fixture + runner_kind: graph + graph_shape: ops_fanout diff --git a/skills/business-ops/graph/ops-lane/SKILL.md b/skills/business-ops/graph/ops-lane/SKILL.md new file mode 100644 index 000000000..3d3ab3cea --- /dev/null +++ b/skills/business-ops/graph/ops-lane/SKILL.md @@ -0,0 +1,24 @@ +--- +name: ops-lane +description: Deterministic fixture lane for the business-ops graph example. +source: + type: cli-tool + command: node + args: + - run.mjs + timeout_seconds: 10 + sandbox: + profile: readonly + cwd_policy: skill-directory +inputs: + lane: + type: string + required: true + description: Lane name to project. + signal: + type: string + required: true + description: Business signal being routed. +--- + +Project one business-ops lane as a deterministic fixture packet. diff --git a/skills/business-ops/graph/ops-lane/X.yaml b/skills/business-ops/graph/ops-lane/X.yaml new file mode 100644 index 000000000..c801d8ad6 --- /dev/null +++ b/skills/business-ops/graph/ops-lane/X.yaml @@ -0,0 +1,27 @@ +skill: ops-lane +version: "0.1.0" + +catalog: + kind: skill + audience: public + visibility: internal + role: graph-stage + part_of: + - runx/business-ops + +runners: + default: + default: true + type: cli-tool + command: node + args: + - run.mjs + inputs: + lane: + type: string + required: true + description: Lane name to project. + signal: + type: string + required: true + description: Business signal being routed. diff --git a/skills/business-ops/graph/ops-lane/run.mjs b/skills/business-ops/graph/ops-lane/run.mjs new file mode 100644 index 000000000..4dfe73a9c --- /dev/null +++ b/skills/business-ops/graph/ops-lane/run.mjs @@ -0,0 +1,74 @@ +function readInputs() { + if (process.env.RUNX_INPUTS_JSON) { + return JSON.parse(process.env.RUNX_INPUTS_JSON); + } + return { + lane: process.env.RUNX_INPUT_LANE ?? "", + signal: process.env.RUNX_INPUT_SIGNAL ?? "", + }; +} + +const inputs = readInputs(); +const lane = String(inputs.lane || "classify"); +const signal = String(inputs.signal || ""); + +const laneDetails = { + classify: { + decision: "route", + summary: "Classify the signal and choose the smallest governed lanes.", + approval: "not_required", + next: ["sourcey", "release.prepare", "issue-to-pr", "send-as.draft", "spend.quote", "receipt-audit"], + }, + sourcey: { + decision: "prepare", + summary: "Refresh docs or launch notes from repo evidence before publishing claims.", + approval: "plan_required", + next: ["approval.docs_plan"], + }, + "release.prepare": { + decision: "prepare", + summary: "Build a read-only release brief with checks, changelog, risks, and unresolved gates.", + approval: "publish_required", + next: ["release.publish.approval"], + }, + "issue-to-pr": { + decision: "prepare", + summary: "Turn a bounded issue signal into a scoped change packet and draft PR handoff.", + approval: "human_merge_required", + next: ["review", "merge_gate"], + }, + "send-as.draft": { + decision: "draft", + summary: "Draft outbound comms only; customer-visible send stops at approval.", + approval: "send_required", + next: ["approval.send"], + }, + "spend.quote": { + decision: "quote", + summary: "Quote spend intent and caps; money movement stops before settlement authority.", + approval: "spend_required", + next: ["approval.spend"], + }, + "receipt-audit": { + decision: "verify", + summary: "Check the receipts and readbacks that prove what happened.", + approval: "not_required", + next: ["history", "verify"], + }, +}; + +const packet = laneDetails[lane] ?? { + decision: "needs_input", + summary: `Unknown lane: ${lane}`, + approval: "not_required", + next: [], +}; + +process.stdout.write(JSON.stringify({ + lane_packet: { + lane, + signal, + ...packet, + }, +}, null, 2)); +process.stdout.write("\n"); diff --git a/tests/official-skill-catalog.test.ts b/tests/official-skill-catalog.test.ts index e06da8798..05c9e288a 100644 --- a/tests/official-skill-catalog.test.ts +++ b/tests/official-skill-catalog.test.ts @@ -17,6 +17,7 @@ import { resolveRunxBinary } from "./runx-binary.js"; const publicCatalogPackages = [ "brand-voice", + "business-ops", "charge", "content-pipeline", "deep-research-brief", From b4c47cdb5266752914ede2b22db28c6479aea31b Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 04:58:50 +1000 Subject: [PATCH 47/64] fix(docs): simplify ops fanout graph --- docs/assets/ops-fanout.svg | 178 +++++++++++++++++-------------------- 1 file changed, 82 insertions(+), 96 deletions(-) diff --git a/docs/assets/ops-fanout.svg b/docs/assets/ops-fanout.svg index a4606df19..deb823221 100644 --- a/docs/assets/ops-fanout.svg +++ b/docs/assets/ops-fanout.svg @@ -1,104 +1,90 @@ - + Basic runx business ops graph - A basic business operations signal routes through runx into governed lanes for sourcey, release prepare, issue-to-PR, send draft, spend quote, and receipt audit. Risky actions stop at approval before receipts are sealed. + A simple graph showing one business signal entering the runx business-ops skill, fanning out to docs, release, issue-to-PR, send draft, spend quote, and audit lanes, then stopping at approvals or producing receipts. - - - - - - - - - - - - - - - - - - - - - - - - - - - + + - - - - - basic business ops graph - One signal routes into governed lanes. - Project context and policy decide which lanes run, which gates stop, and what receipts prove. - - - - signal - launch, incident, release - - - - - - runx - ops graph - classify, route, gate - - - - - - - - sourcey - docs from evidence - - - release - prepare and verify - - - issue to PR - bounded change lane - - - send draft - approval before send - - - spend quote - - - - - - - - - - receipt - what ran, under what authority - - - approval gate - sends, spend, deploys + + + basic operator flow + One business signal becomes a small governed ops graph. + + + signal + launch readiness + + + + + runx skill + business-ops + classify, route, gate + + + + + + + + + + + + + docs from evidence + + + release checks + + + issue to PR + + + send draft + + + spend quote + + + receipt audit + + + + + + + + + + receipt + what ran, under authority + + + approval gate + send, spend, merge, deploy From c865f2554daa4ed4fcd48c83d3cd03c5221ebbdf Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 05:01:39 +1000 Subject: [PATCH 48/64] style(docs): refine ops fanout graph --- docs/assets/ops-fanout.svg | 177 +++++++++++++++++++++---------------- 1 file changed, 100 insertions(+), 77 deletions(-) diff --git a/docs/assets/ops-fanout.svg b/docs/assets/ops-fanout.svg index deb823221..8ac83de27 100644 --- a/docs/assets/ops-fanout.svg +++ b/docs/assets/ops-fanout.svg @@ -1,90 +1,113 @@ - + Basic runx business ops graph - A simple graph showing one business signal entering the runx business-ops skill, fanning out to docs, release, issue-to-PR, send draft, spend quote, and audit lanes, then stopping at approvals or producing receipts. + A product-style diagram showing one business signal entering the runx business-ops skill, fanning out to docs, release, issue-to-PR, send draft, spend quote, and audit lanes, then producing receipts or stopping at approval gates. - + - - - basic operator flow - One business signal becomes a small governed ops graph. - - - signal - launch readiness - - - - - runx skill - business-ops - classify, route, gate - - - - - - - - - - - - - docs from evidence - - - release checks - - - issue to PR - - - send draft - - - spend quote - - - receipt audit - - - - - - - - - - receipt - what ran, under authority - - - approval gate - send, spend, merge, deploy + + + + business-ops quickstart + One prompt becomes a governed operator graph. + The public skill is a fixture. Teams swap in private context, policies, tools, approval gates, and readbacks. + + + + input + signal + launch readiness + + + + + runx skill + business-ops + classify + route + gate + + + + + + + + + + + + + + + + docs from evidence + + + release checks + + + issue to PR + + + send draft + + + spend quote + + + receipt audit + + + + + + + + + + sealed receipt + what ran, under authority + + + approval gate + send, spend, merge, deploy From 1c4f89d421f4bc11a489bb16832dad77d19a305b Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 05:11:51 +1000 Subject: [PATCH 49/64] docs: refine business ops quickstart --- README.md | 25 +++--- docs/assets/ops-fanout.svg | 156 ++++++++++++++++--------------------- 2 files changed, 81 insertions(+), 100 deletions(-) diff --git a/README.md b/README.md index 7ea980a0b..7e202fafe 100644 --- a/README.md +++ b/README.md @@ -41,31 +41,34 @@ npm i -g @runxhq/cli # or: cargo install runx-cli ``` -Path 1 is the agent skill path. Ask an agent to drive the work through runx: +Path 1 is the agent skill path. Ask an agent to use runx as the operating +layer: ```text -Use runx skills to plan and implement end-to-end business ops for my company. -Fan out the work into docs, release, customer comms, issue-to-PR, spend review, +Use runx skills to plan and execute end-to-end business ops for my company. +Start from this goal: prepare API v2 for launch. +Fan out into docs, release readiness, customer comms, issue-to-PR, spend review, and audit lanes. Stop at approval before sending, spending, merging, deploying, -or publishing. +or publishing. Return receipts for what ran. ``` -The public version of that shape is `business-ops`: +The public version of that operator shape is `business-ops`: ```bash runx skill business-ops \ - -i signal="launch readiness for API v2: docs, release, customer comms, and spend checks" \ + -i signal="prepare API v2 for launch: docs, release, customer comms, issue-to-PR, spend review, and audit" \ --json ``` -One business signal enters an ops graph, fans out into governed lanes, and stops -at approval for sends, spend, deploys, merges, and other consequential acts. -Real teams replace the fixture lanes with their own context, policies, -providers, approval gates, verification checks, and private skills. +That is the shape: a business goal enters runx, becomes an operator graph, fans +out into lanes, and stops at approval before consequential acts. The public +skill is deliberately basic. Real teams replace the fixture lanes with company +context, policies, providers, approval gates, verification checks, and private +skills. ![Basic runx business ops graph](docs/assets/ops-fanout.svg) -Path 2 is a manual skill chain. Run the pieces yourself: +Path 2 is a manual skill chain. Drive the lanes yourself: ```bash # Docs/product engineering: plan, author, build, critique, and verify docs. diff --git a/docs/assets/ops-fanout.svg b/docs/assets/ops-fanout.svg index 8ac83de27..88ce27eb7 100644 --- a/docs/assets/ops-fanout.svg +++ b/docs/assets/ops-fanout.svg @@ -1,113 +1,91 @@ - - Basic runx business ops graph - A product-style diagram showing one business signal entering the runx business-ops skill, fanning out to docs, release, issue-to-PR, send draft, spend quote, and audit lanes, then producing receipts or stopping at approval gates. + + runx business operator graph + A clean graph showing a business goal entering the runx business-ops skill, fanning into governed lanes, and resolving into receipt or approval outcomes. - - + + - - + - business-ops quickstart - One prompt becomes a governed operator graph. - The public skill is a fixture. Teams swap in private context, policies, tools, approval gates, and readbacks. + + goal + prepare API v2 - - - input - signal - launch readiness + - + + + runx skill + business-ops + intake, plan, route, gate - - runx skill - business-ops - classify - route - gate - + + - - - - + + + + + + - - - - - - + + docs from evidence - - docs from evidence + + release readiness - - release checks + + receipt audit - - issue to PR + + issue-to-PR - - send draft + + customer comms - - spend quote + + spend review - - receipt audit + + - - - - - - + + receipt + prove the run - - sealed receipt - what ran, under authority - - - approval gate - send, spend, merge, deploy + + approval + approve first From 45460904121b9eefd66d38928d1553cbef82ac6e Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 11:23:39 +1000 Subject: [PATCH 50/64] docs: clarify quickstart paths --- README.md | 56 ++++++++++++++++++++++++++------------ docs/assets/ops-fanout.svg | 36 ++++++++---------------- 2 files changed, 50 insertions(+), 42 deletions(-) diff --git a/README.md b/README.md index 7e202fafe..a9bbe4e4b 100644 --- a/README.md +++ b/README.md @@ -41,18 +41,29 @@ npm i -g @runxhq/cli # or: cargo install runx-cli ``` -Path 1 is the agent skill path. Ask an agent to use runx as the operating -layer: +Then choose how you want to run skills. + +### agent path + +Paste [runx.ai/SKILL.md](https://runx.ai/SKILL.md) into your agent. It teaches +the agent how to use the runx CLI, discover skills from the catalog at +[runx.ai/x](https://runx.ai/x), and return receipts. ```text -Use runx skills to plan and execute end-to-end business ops for my company. -Start from this goal: prepare API v2 for launch. -Fan out into docs, release readiness, customer comms, issue-to-PR, spend review, -and audit lanes. Stop at approval before sending, spending, merging, deploying, -or publishing. Return receipts for what ran. +Use runx to plan and execute end-to-end business ops for my company. +Goal: prepare API v2 for launch. +Stop before sends, spend, merges, deploys, or publishing. Return receipts. +``` + +### CLI path + +Run any catalog skill directly: + +```bash +runx skill -i key=value --json ``` -The public version of that operator shape is `business-ops`: +`business-ops` is one prebuilt skill for managing a business goal: ```bash runx skill business-ops \ @@ -60,24 +71,33 @@ runx skill business-ops \ --json ``` -That is the shape: a business goal enters runx, becomes an operator graph, fans -out into lanes, and stops at approval before consequential acts. The public -skill is deliberately basic. Real teams replace the fixture lanes with company -context, policies, providers, approval gates, verification checks, and private -skills. - ![Basic runx business ops graph](docs/assets/ops-fanout.svg) -Path 2 is a manual skill chain. Drive the lanes yourself: +The graph is the core shape: goal in, governed lanes out, receipts and approval +gates back. Real teams replace the demo lanes with private context, policies, +tools, and readbacks. + +Some other examples: ```bash # Docs/product engineering: plan, author, build, critique, and verify docs. runx skill sourcey -i project=. --json -# Research/ops: fetch one allowed source with digest-backed provenance. -runx skill web-fetch -i url=https://runx.ai -i allowlist='["runx.ai"]' --json +# Research/strategy: produce a governed decision brief. +runx skill deep-research-brief \ + -i objective="Which launch risks should we resolve first?" \ + --json -# Spend lanes are explicit. Inspect payment skills before granting authority. +# Maintainer ops: draft a useful issue response. +runx skill issue-triage \ + -i issue_url=https://github.com/runxhq/runx/issues/241 \ + -i objective="Draft the next helpful maintainer response" \ + --json +``` + +For payment or spend lanes, inspect the skill before granting authority: + +```bash runx registry search payments runx registry read runx/x402-pay@sha-008aef3f3b2e ``` diff --git a/docs/assets/ops-fanout.svg b/docs/assets/ops-fanout.svg index 88ce27eb7..5c178b325 100644 --- a/docs/assets/ops-fanout.svg +++ b/docs/assets/ops-fanout.svg @@ -3,36 +3,24 @@ A clean graph showing a business goal entering the runx business-ops skill, fanning into governed lanes, and resolving into receipt or approval outcomes. - + From 269db296e15a6300339513fbd72ecdee458f4e3c Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 12:23:37 +1000 Subject: [PATCH 51/64] fix(ci): sync skill catalog checks --- packages/cli/src/skill-refs.test.ts | 1 + scripts/check-demo-inventory.mjs | 29 +++++++++++++++++++++++++++-- 2 files changed, 28 insertions(+), 2 deletions(-) diff --git a/packages/cli/src/skill-refs.test.ts b/packages/cli/src/skill-refs.test.ts index daeee60f9..ca90aa16e 100644 --- a/packages/cli/src/skill-refs.test.ts +++ b/packages/cli/src/skill-refs.test.ts @@ -65,6 +65,7 @@ const publicOfficialCatalogSkills = [ "sql-analyst", "stripe-pay", "structured-extraction", + "support-triage-reply", "taste-profile", "vault-unseal", "vuln-scan", diff --git a/scripts/check-demo-inventory.mjs b/scripts/check-demo-inventory.mjs index 0ba3cc15b..9bd191c95 100644 --- a/scripts/check-demo-inventory.mjs +++ b/scripts/check-demo-inventory.mjs @@ -29,7 +29,7 @@ for (const group of validGroups) { } for (const entry of entries) { const itemPath = typeof entry === "string" ? entry : entry?.path; - if (typeof itemPath !== "string" || !itemPath.startsWith("examples/")) { + if (typeof itemPath !== "string" || !isValidDemoPath(itemPath)) { failures.push(`${group} contains invalid path ${JSON.stringify(entry)}`); continue; } @@ -38,7 +38,7 @@ for (const group of validGroups) { failures.push(`${itemPath} is classified as both ${previous} and ${group}`); } classified.set(itemPath, group); - if (!actualExampleDirs.includes(itemPath)) { + if (!demoPathExists(itemPath)) { failures.push(`${itemPath} is classified but no directory exists`); } if (group !== "fixture_support" && typeof entry.command !== "string") { @@ -76,3 +76,28 @@ if (failures.length > 0) { } console.log(`demo inventory covers ${actualExampleDirs.length} example directories`); + +function isValidDemoPath(itemPath) { + return itemPath.startsWith("examples/") || itemPath.startsWith("skills/"); +} + +function demoPathExists(itemPath) { + if (itemPath.startsWith("examples/")) { + return actualExampleDirs.includes(itemPath); + } + if (!itemPath.startsWith("skills/")) { + return false; + } + const skillDir = path.join(root, itemPath); + return path.basename(itemPath) === itemPath.slice("skills/".length) + && hasFile(path.join(skillDir, "SKILL.md")) + && hasFile(path.join(skillDir, "X.yaml")); +} + +function hasFile(filePath) { + try { + return statSync(filePath).isFile(); + } catch { + return false; + } +} From 522f59c9a3161b8564d8efcc3feeef1b7781dbc1 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 17:02:48 +1000 Subject: [PATCH 52/64] docs(oss): clarify active CLI install channels --- README.md | 1 - docs/releasing.md | 10 +++++++--- 2 files changed, 7 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a9bbe4e4b..60673853d 100644 --- a/README.md +++ b/README.md @@ -38,7 +38,6 @@ Install the CLI: ```bash npm i -g @runxhq/cli # or: curl -fsSL https://runx.ai/install | sh -# or: cargo install runx-cli ``` Then choose how you want to run skills. diff --git a/docs/releasing.md b/docs/releasing.md index ba148c94b..9991e0783 100644 --- a/docs/releasing.md +++ b/docs/releasing.md @@ -8,12 +8,16 @@ The CLI ships from `github.com/runxhq/runx`. Release tags are `cli-vX.Y.Z` (prefixed so they do not collide with the repo's other release trains). The git tag is the single source of truth for the version. -The same product version is used on every channel: +The same product version is used on every active channel. The release workflow +is secret-gated, so package-manager channels that are not configured are skipped +with a warning instead of blocking the npm/GitHub release. - GitHub Release: `cli-vX.Y.Z` (the hub; serves the raw per-target archives) - npm: `@runxhq/cli@X.Y.Z` (+ `@runxhq/cli-@X.Y.Z`) -- crates.io: `runx-cli X.Y.Z` (`cargo install runx-cli`) -- Homebrew, Scoop, winget, AUR, Docker (GHCR): `X.Y.Z` +- Homebrew, Scoop, winget, AUR, Docker (GHCR): `X.Y.Z` when their channel + credentials are configured +- crates.io: `runx-cli X.Y.Z` (`cargo install runx-cli`) when the crate channel + is configured `runx --version` reports `CARGO_PKG_VERSION`, so the crate and npm versions are stamped from the tag at build time and the number is truthful regardless of how From ffb21e94ad148cd972bbaf60143ea7104fe251cc Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 18:13:32 +1000 Subject: [PATCH 53/64] fix(cli): align registry install commands Remove the user-facing installation-id flag from add/registry flows, keep native command help aligned, and update registry fixtures/docs to use versioned runx add plus runx skill execution commands. --- SECURITY.md | 2 +- .../icey-server-operator/binding.json | 4 +- crates/runx-cli/src/doctor.rs | 34 ++---- crates/runx-cli/src/launcher.rs | 114 +++++++++++++++--- crates/runx-cli/src/main.rs | 12 +- crates/runx-cli/src/registry.rs | 33 +++-- .../runx-cli/src/registry/remote_publish.rs | 4 +- crates/runx-cli/src/skill/resolver.rs | 41 +------ crates/runx-cli/tests/doctor.rs | 4 +- crates/runx-cli/tests/launcher.rs | 47 ++++++-- crates/runx-runtime/tests/registry_client.rs | 8 +- docs/publishing.md | 2 +- fixtures/cli-parity/commands.json | 1 - fixtures/registry/remote/search-success.json | 4 +- packages/cli/src/args.ts | 7 +- packages/cli/src/dispatch.ts | 21 ++-- packages/cli/src/index.test.ts | 38 +++--- packages/cli/src/skill-refs.ts | 8 -- scripts/generate-cli-feature-parity.ts | 2 +- .../references/evidence.json | 8 +- .../support-triage-reply/references/report.md | 1 - tests/registry-fixtures.ts | 2 +- tests/remote-registry-search.test.ts | 2 +- tests/skill-search.test.ts | 2 +- 24 files changed, 242 insertions(+), 159 deletions(-) diff --git a/SECURITY.md b/SECURITY.md index 4c478ff26..4356b8690 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -6,7 +6,7 @@ runx keeps execution, state, and receipts on your machine. Fetching a skill from The crate that holds receipts has no network access by design, so there is no telemetry to send. This is a property of the build, not a setting you toggle. -Credentials are supplied per run with `runx run --secret-env` and `runx run --credential`. They are never persisted. +Credentials are supplied per run with `runx skill --secret-env` and `runx skill --credential`. They are never persisted. Authority narrows at every hop. A hop's scopes are a subset of the grant it inherits, and widening is denied by construction, so a skill deep in a graph cannot reach past the authority its caller held. Every act produces a signed, reproducible receipt. diff --git a/bindings/nilstate/icey-server-operator/binding.json b/bindings/nilstate/icey-server-operator/binding.json index e5cc89d7a..e090b5708 100644 --- a/bindings/nilstate/icey-server-operator/binding.json +++ b/bindings/nilstate/icey-server-operator/binding.json @@ -24,8 +24,8 @@ "owner": "nilstate", "trust_tier": "verified", "version": "upstream-ee9aa1c", - "install_command": "runx add nilstate/icey-server-operator@upstream-ee9aa1c --registry https://runx.ai", - "run_command": "runx icey-server-operator", + "install_command": "runx add nilstate/icey-server-operator@upstream-ee9aa1c --registry https://api.runx.ai", + "run_command": "runx skill nilstate/icey-server-operator@upstream-ee9aa1c --registry https://api.runx.ai", "profile_path": "bindings/nilstate/icey-server-operator/X.yaml", "materialized_package_is_registry_artifact": true }, diff --git a/crates/runx-cli/src/doctor.rs b/crates/runx-cli/src/doctor.rs index 1a55f492a..158abe935 100644 --- a/crates/runx-cli/src/doctor.rs +++ b/crates/runx-cli/src/doctor.rs @@ -291,7 +291,6 @@ fn registry_probe_plan() -> RegistryPlan { version: None, expected_digest: None, destination: None, - installation_id: None, owner: None, profile: None, trust_tier: None, @@ -533,15 +532,11 @@ fn registry_remote_install_diagnostic( ) -> DoctorDiagnostic { let remote = matches!(target, registry::RegistryTarget::Remote { .. }); let configured = env_contains_non_empty(env, "RUNX_INSTALLATION_ID"); - let severity = if remote && !configured { - DoctorDiagnosticSeverity::Warning - } else { - DoctorDiagnosticSeverity::Info - }; + let severity = DoctorDiagnosticSeverity::Info; let message = if remote && configured { "Remote registry install identity configured.".to_owned() } else if remote { - "Remote registry install identity not configured; set RUNX_INSTALLATION_ID before remote registry install.".to_owned() + "Remote registry installs will use the local runx install identity; set RUNX_INSTALLATION_ID only when an explicit shared identity is needed.".to_owned() } else { "Remote registry install identity is not required for the selected local registry target." .to_owned() @@ -568,16 +563,7 @@ fn registry_remote_install_diagnostic( json_pointer: None, }, evidence: Some(evidence), - repairs: if remote && !configured { - vec![manual_env_repair( - "runx.registry.installation_id.configure_env", - &["RUNX_INSTALLATION_ID"], - "Set RUNX_INSTALLATION_ID before remote registry install so acquisition is bound to an installation principal.", - DoctorRepairRisk::Low, - )] - } else { - Vec::new() - }, + repairs: Vec::new(), } } @@ -1029,9 +1015,10 @@ mod tests { diagnostics: vec![DoctorDiagnostic { id: "runx.registry.installation_id".to_owned(), instance_id: "runx:doctor-registry:runx.registry.installation_id".to_owned(), - severity: DoctorDiagnosticSeverity::Warning, + severity: DoctorDiagnosticSeverity::Info, title: "Registry install identity".to_owned(), - message: "Remote registry install identity not configured.".to_owned(), + message: "Remote registry installs use an automatic local install identity." + .to_owned(), target: object([ ("kind", string_value("registry")), ("ref", string_value("runx.registry.installation_id")), @@ -1049,7 +1036,8 @@ mod tests { path: Some("environment".to_owned()), json_pointer: None, contents: Some( - "Set RUNX_INSTALLATION_ID before remote registry install.".to_owned(), + "Set RUNX_INSTALLATION_ID only when you need a shared install identity." + .to_owned(), ), patch: None, command: None, @@ -1060,8 +1048,8 @@ mod tests { let rendered = render_doctor_report(&report); - assert!( - rendered.contains("next: Set RUNX_INSTALLATION_ID before remote registry install.") - ); + assert!(rendered.contains( + "next: Set RUNX_INSTALLATION_ID only when you need a shared install identity." + )); } } diff --git a/crates/runx-cli/src/launcher.rs b/crates/runx-cli/src/launcher.rs index 53fdaa918..69a458c19 100644 --- a/crates/runx-cli/src/launcher.rs +++ b/crates/runx-cli/src/launcher.rs @@ -41,8 +41,13 @@ pub enum LauncherAction { RunTool(ToolPlan), RunUrlAdd(UrlAddPlan), PrintHelp, + PrintAddHelp, PrintHistoryHelp, + PrintListHelp, + PrintLoginHelp, PrintPublishHelp, + PrintRegistryHelp, + PrintRegistryUsageError, PrintSkillHelp, PrintVerifyHelp, PrintVersion, @@ -181,6 +186,9 @@ pub fn plan_launcher(args: Vec) -> LauncherAction { } if first_arg_is(&args, "login") { + if nested_help_requested(&args) { + return LauncherAction::PrintLoginHelp; + } return crate::login::parse_login_plan(&args) .map_or_else(LauncherAction::Error, LauncherAction::RunLogin); } @@ -236,6 +244,9 @@ pub fn plan_launcher(args: Vec) -> LauncherAction { } if first_arg_is(&args, "list") { + if nested_help_requested(&args) { + return LauncherAction::PrintListHelp; + } return parse_list_plan(&args).map_or_else(LauncherAction::Error, LauncherAction::RunList); } @@ -276,6 +287,12 @@ pub fn plan_launcher(args: Vec) -> LauncherAction { } if first_arg_is(&args, "registry") { + if nested_help_requested(&args) { + return LauncherAction::PrintRegistryHelp; + } + if args.len() == 1 { + return LauncherAction::PrintRegistryUsageError; + } return parse_registry_plan(&args).map_or_else( |message| json_or_human_error(&args, message), LauncherAction::RunRegistry, @@ -283,6 +300,9 @@ pub fn plan_launcher(args: Vec) -> LauncherAction { } if first_arg_is(&args, "add") { + if nested_help_requested(&args) { + return LauncherAction::PrintAddHelp; + } return parse_add_plan(&args).unwrap_or_else(|message| json_or_human_error(&args, message)); } @@ -337,7 +357,7 @@ Commands: runx export [skill-ref...] [--project] [--json] runx mcp serve [--receipt-dir dir] [--http-listen [addr]] [--http-allow-non-loopback] runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] [--run-id id --answers file] - runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--installation-id id] [--api-base-url url] [--json] + runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--api-base-url url] [--json] runx harness [-R dir] [-j|--json] runx tool build |--all [--json] runx tool search [--source source] [--json] @@ -368,6 +388,39 @@ Options: .to_owned() } +pub fn list_help_text() -> String { + "\ +runx list + +Usage: + runx list [tools|skills|graphs|packets|overlays] [--ok-only|--invalid-only] [-j|--json] + +Options: + --ok-only + --invalid-only + -j, --json +" + .to_owned() +} + +pub fn login_help_text() -> String { + "\ +runx login + +Usage: + runx login [--provider github|google|gitlab] [--for default|publish] [--api-url url] [--local-api] [-j|--json] + +Options: + --provider provider + --for purpose + --api-url url + --api-base-url url + --local-api + -j, --json +" + .to_owned() +} + pub fn publish_help_text() -> String { "\ runx publish @@ -386,6 +439,52 @@ Options: .to_owned() } +pub fn add_help_text() -> String { + "\ +runx add + +Usage: + runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--api-base-url url] [--json] + +Options: + --registry url|path Registry URL or local registry path for skill refs + --version version Registry version for skill refs + --ref git-ref Git ref for GitHub repository URLs + --digest sha256 Expected package digest for skill refs + --to dir Install destination for skill refs + --api-base-url url Hosted index API for GitHub repository URLs + -j, --json +" + .to_owned() +} + +pub fn registry_help_text() -> String { + "\ +runx registry + +Usage: + runx registry search [--registry url|path] [--registry-dir dir] [--limit n] [-j|--json] + runx registry read [--registry url|path] [--registry-dir dir] [--version version] [-j|--json] + runx registry resolve [--registry url|path] [--registry-dir dir] [--version version] [-j|--json] + runx registry install [--registry url|path] [--registry-dir dir] [--version version] [--digest sha256] [--to dir] [-j|--json] + runx registry publish [--registry url|path] [--owner owner] [--version version] [--profile X.yaml] [--trust-tier tier] [--upsert] [-j|--json] + +Options: + --registry url|path + --registry-dir dir + --version version + --digest sha256 + --to dir + --owner owner + --profile X.yaml + --trust-tier first_party|verified|community + --limit n + --upsert + -j, --json +" + .to_owned() +} + pub fn verify_help_text() -> String { "\ runx verify @@ -626,7 +725,6 @@ struct AddParseState { repo_ref: Option, expected_digest: Option, destination: Option, - installation_id: Option, api_base_url: Option, json: bool, } @@ -678,9 +776,6 @@ fn parse_add_flag( parsed.destination = Some(PathBuf::from(value)); Ok(next_index) } - "--installation-id" | "--installationId" => { - set_add_string(args, index, flag, inline_value, &mut parsed.installation_id) - } "--api-base-url" | "--apiBaseUrl" => { set_add_string(args, index, flag, inline_value, &mut parsed.api_base_url) } @@ -716,9 +811,6 @@ fn add_url_plan(parsed: AddParseState) -> Result { .to_owned(), ); } - if parsed.installation_id.is_some() { - return Err("runx add does not accept --installation-id".to_owned()); - } Ok(UrlAddPlan { repo: parsed.subject.unwrap_or_default(), repo_ref: parsed.repo_ref, @@ -744,7 +836,6 @@ fn add_registry_plan(parsed: AddParseState) -> Result { version: parsed.version, expected_digest: parsed.expected_digest, destination: parsed.destination, - installation_id: parsed.installation_id, owner: None, profile: None, trust_tier: None, @@ -1323,7 +1414,6 @@ fn parse_registry_plan(args: &[OsString]) -> Result { version: state.version, expected_digest: state.expected_digest, destination: state.destination, - installation_id: state.installation_id, owner: state.owner, profile: state.profile, trust_tier: state.trust_tier, @@ -1342,7 +1432,6 @@ struct RegistryParseState { version: Option, expected_digest: Option, destination: Option, - installation_id: Option, owner: Option, profile: Option, trust_tier: Option, @@ -1402,9 +1491,6 @@ fn parse_registry_flag( "--to" | "--destination" => { set_registry_path_flag(args, index, flag, inline_value, &mut state.destination) } - "--installation-id" | "--installationId" => { - set_registry_string_flag(args, index, flag, inline_value, &mut state.installation_id) - } "--owner" => set_registry_string_flag(args, index, flag, inline_value, &mut state.owner), "--profile" => set_registry_path_flag(args, index, flag, inline_value, &mut state.profile), "--trust-tier" | "--trustTier" => { diff --git a/crates/runx-cli/src/main.rs b/crates/runx-cli/src/main.rs index c989b2c95..a9bb1b993 100644 --- a/crates/runx-cli/src/main.rs +++ b/crates/runx-cli/src/main.rs @@ -7,8 +7,8 @@ use std::path::{Path, PathBuf}; use std::process::ExitCode; use runx_cli::launcher::{ - HarnessPlan, LauncherAction, help_text, history_help_text, publish_help_text, skill_help_text, - verify_help_text, + HarnessPlan, LauncherAction, add_help_text, help_text, history_help_text, list_help_text, + login_help_text, publish_help_text, registry_help_text, skill_help_text, verify_help_text, }; const INLINE_HARNESS_SIGNING_HINT: &str = "runx: hint: inline harnesses seal signed receipts; set RUNX_RECEIPT_SIGN_KID, RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64, and RUNX_RECEIPT_SIGN_ISSUER_TYPE, or run the example's run.sh when one is provided."; @@ -26,8 +26,16 @@ fn main() -> ExitCode { write_json_failure(&plan.message, &plan.code, plan.exit_code) } LauncherAction::PrintHelp => write_stdout(&help_text()), + LauncherAction::PrintAddHelp => write_stdout(&add_help_text()), LauncherAction::PrintHistoryHelp => write_stdout(&history_help_text()), + LauncherAction::PrintListHelp => write_stdout(&list_help_text()), + LauncherAction::PrintLoginHelp => write_stdout(&login_help_text()), LauncherAction::PrintPublishHelp => write_stdout(&publish_help_text()), + LauncherAction::PrintRegistryHelp => write_stdout(®istry_help_text()), + LauncherAction::PrintRegistryUsageError => { + let _ignored = write_stderr_line(®istry_help_text()); + ExitCode::from(64) + } LauncherAction::PrintSkillHelp => write_stdout(&skill_help_text()), LauncherAction::PrintVerifyHelp => write_stdout(&verify_help_text()), LauncherAction::PrintVersion => { diff --git a/crates/runx-cli/src/registry.rs b/crates/runx-cli/src/registry.rs index 9574e58bf..b4d1dd608 100644 --- a/crates/runx-cli/src/registry.rs +++ b/crates/runx-cli/src/registry.rs @@ -16,6 +16,7 @@ use runx_runtime::registry::{ install_local_skill, publish_skill_markdown, read_registry_skill, resolve_registry_skill, search_registry_with_options, }; +use runx_runtime::scaffold::{InitGeneratedValues, ensure_runx_install_state}; mod output; mod package; @@ -45,7 +46,6 @@ pub struct RegistryPlan { pub version: Option, pub expected_digest: Option, pub destination: Option, - pub installation_id: Option, pub owner: Option, pub profile: Option, pub trust_tier: Option, @@ -217,7 +217,7 @@ fn run_install( ) -> Result { let source = target.label(); let source_authority = target.manifest_source_authority(); - let (candidate, acquisition) = install_candidate(&plan, target, env)?; + let (candidate, acquisition) = install_candidate(&plan, target, env, cwd)?; let install = install_local_skill( &candidate, &InstallLocalSkillOptions { @@ -349,6 +349,7 @@ pub(crate) fn install_candidate( plan: &RegistryPlan, target: RegistryTarget, env: &BTreeMap, + cwd: &Path, ) -> Result< ( InstallCandidate, @@ -359,15 +360,11 @@ pub(crate) fn install_candidate( let source_authority = target.manifest_source_authority(); match target { RegistryTarget::Remote { registry_url } => { - let installation_id = plan - .installation_id - .as_deref() - .or_else(|| env.get("RUNX_INSTALLATION_ID").map(String::as_str)) - .ok_or_else(|| usage_error("remote registry install requires --installation-id"))?; + let installation_id = remote_installation_id(env, cwd)?; let acquired = RegistryClient::new(®istry_url)?.acquire( &plan.subject, AcquireOptions { - installation_id, + installation_id: &installation_id, version: plan.version.as_deref(), channel: Some("cli"), }, @@ -399,6 +396,26 @@ pub(crate) fn install_candidate( } } +fn remote_installation_id( + env: &BTreeMap, + cwd: &Path, +) -> Result { + if let Some(installation_id) = env + .get("RUNX_INSTALLATION_ID") + .map(String::as_str) + .map(str::trim) + .filter(|value| !value.is_empty()) + { + return Ok(installation_id.to_owned()); + } + + let generated = InitGeneratedValues::generate(); + let home = runx_runtime::resolve_runx_global_home_dir(env, cwd); + let state = ensure_runx_install_state(&home, &generated.installation_id, &generated.created_at) + .map_err(|error| usage_error(error.to_string()))?; + Ok(state.state.installation_id) +} + fn candidate_from_resolution( registry_ref: &str, resolution: RegistrySkillResolution, diff --git a/crates/runx-cli/src/registry/remote_publish.rs b/crates/runx-cli/src/registry/remote_publish.rs index 38dfb884a..70b5e37b4 100644 --- a/crates/runx-cli/src/registry/remote_publish.rs +++ b/crates/runx-cli/src/registry/remote_publish.rs @@ -150,8 +150,8 @@ mod tests { "version": "sha-123", "digest": "abc", "trust_tier": "community", - "install_command": "runx skill add kam/hello@sha-123", - "run_command": "runx skill hello", + "install_command": "runx add kam/hello@sha-123", + "run_command": "runx skill kam/hello@sha-123", "public_url": "https://runx.test/x/kam/hello" } }) diff --git a/crates/runx-cli/src/skill/resolver.rs b/crates/runx-cli/src/skill/resolver.rs index d140d444a..69abfccfe 100644 --- a/crates/runx-cli/src/skill/resolver.rs +++ b/crates/runx-cli/src/skill/resolver.rs @@ -8,7 +8,6 @@ use runx_runtime::registry::{ InstallCandidate, InstallLocalSkillOptions, materialization_cache_path, materialization_digest_marker, parse_registry_ref, split_skill_id, }; -use runx_runtime::scaffold::{InitGeneratedValues, ensure_runx_install_state}; use crate::official_skills::official_skill_entry_by_name; use crate::registry::{self, RegistryAction, RegistryPlan}; @@ -214,7 +213,6 @@ fn materialize_trusted_registry_skill( version: version.map(ToOwned::to_owned), expected_digest: expected_digest.map(ToOwned::to_owned), destination: None, - installation_id: remote_installation_id(registry, env, cwd)?, owner: None, profile: None, trust_tier: None, @@ -226,8 +224,8 @@ fn materialize_trusted_registry_skill( let source_description = registry::registry_source_description(&target); let source_fingerprint = registry_source_fingerprint(&target); let source_authority = target.manifest_source_authority(); - let (mut candidate, _acquisition) = - registry::install_candidate(&plan, target, env).map_err(|error| error.into_message())?; + let (mut candidate, _acquisition) = registry::install_candidate(&plan, target, env, cwd) + .map_err(|error| error.into_message())?; if cache_root == CacheRoot::Official { candidate.manifest_source_authority = Some(runx_runtime::registry::RegistryManifestSourceAuthority::OfficialRunx); @@ -397,41 +395,6 @@ fn registry_source_fingerprint(target: ®istry::RegistryTarget) -> String { .collect() } -fn remote_installation_id( - registry: Option<&str>, - env: &BTreeMap, - cwd: &Path, -) -> Result, String> { - let plan = RegistryPlan { - action: RegistryAction::Install, - subject: "runx/install-state-probe".to_owned(), - registry: registry.map(ToOwned::to_owned), - registry_dir: None, - version: None, - expected_digest: None, - destination: None, - installation_id: None, - owner: None, - profile: None, - trust_tier: None, - limit: None, - upsert: false, - json: true, - }; - let target = registry::resolve_registry_target(&plan, env, cwd); - if !matches!(target, registry::RegistryTarget::Remote { .. }) { - return Ok(None); - } - if let Some(installation_id) = env.get("RUNX_INSTALLATION_ID") { - return Ok(Some(installation_id.clone())); - } - let generated = InitGeneratedValues::generate(); - let home = runx_runtime::resolve_runx_global_home_dir(env, cwd); - let state = ensure_runx_install_state(&home, &generated.installation_id, &generated.created_at) - .map_err(|error| error.to_string())?; - Ok(Some(state.state.installation_id)) -} - fn official_registry_override( env: &BTreeMap, override_value: Option<&str>, diff --git a/crates/runx-cli/tests/doctor.rs b/crates/runx-cli/tests/doctor.rs index 43c318b3b..465aa19d3 100644 --- a/crates/runx-cli/tests/doctor.rs +++ b/crates/runx-cli/tests/doctor.rs @@ -179,7 +179,7 @@ fn doctor_registry_json_reports_readiness_without_key_material() assert_eq!(String::from_utf8(output.stderr)?, ""); let report = serde_json::from_slice::(&output.stdout)?; assert_eq!(report["status"], "success"); - assert_eq!(report["summary"]["warnings"], 1); + assert_eq!(report["summary"]["warnings"], 0); let rendered = serde_json::to_string(&report)?; assert!(rendered.contains("https://registry.runx.test/api")); assert!(rendered.contains("official-skills")); @@ -188,7 +188,7 @@ fn doctor_registry_json_reports_readiness_without_key_material() assert!(rendered.contains("acme/*")); assert!(rendered.contains("RUNX_INSTALLATION_ID")); assert!(!rendered.contains("AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=")); - assert!(diagnostic_has_repair( + assert!(!diagnostic_has_repair( &report, "runx.registry.installation_id" )); diff --git a/crates/runx-cli/tests/launcher.rs b/crates/runx-cli/tests/launcher.rs index e4b85120d..82c52e1fe 100644 --- a/crates/runx-cli/tests/launcher.rs +++ b/crates/runx-cli/tests/launcher.rs @@ -3,8 +3,9 @@ use runx_cli::export::{ExportPlan, Target}; use runx_cli::kernel::{KernelInputSource, KernelPlan}; use runx_cli::launcher::{ DevPlan, DoctorMode, DoctorPlan, FilterMode, HarnessPlan, HistoryPlan, InitPlan, JsonErrorPlan, - LauncherAction, ListKind, ListPlan, NewPlan, ToolAction, ToolPlan, UrlAddPlan, help_text, - history_help_text, plan_launcher, publish_help_text, skill_help_text, verify_help_text, + LauncherAction, ListKind, ListPlan, NewPlan, ToolAction, ToolPlan, UrlAddPlan, add_help_text, + help_text, history_help_text, list_help_text, login_help_text, plan_launcher, + publish_help_text, registry_help_text, skill_help_text, verify_help_text, }; use runx_cli::login::LoginPlan; use runx_cli::mcp::McpPlan; @@ -37,7 +38,7 @@ fn top_level_help_and_version_are_native() { ); assert_help_line( &help, - "runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--installation-id id] [--api-base-url url] [--json]", + "runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--api-base-url url] [--json]", ); assert_help_line(&help, "runx parser eval --input --json"); assert_help_line( @@ -118,6 +119,38 @@ fn nested_skill_history_verify_and_publish_help_are_native() { ); } +#[test] +fn documented_command_help_is_native() { + assert_eq!(plan(&["add", "--help"]), LauncherAction::PrintAddHelp); + assert_eq!(plan(&["add", "-h"]), LauncherAction::PrintAddHelp); + assert_eq!(plan(&["list", "--help"]), LauncherAction::PrintListHelp); + assert_eq!(plan(&["login", "--help"]), LauncherAction::PrintLoginHelp); + assert_eq!( + plan(&["registry", "--help"]), + LauncherAction::PrintRegistryHelp + ); + assert_eq!(plan(&["registry"]), LauncherAction::PrintRegistryUsageError); + + assert_help_line( + &add_help_text(), + "runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--api-base-url url] [--json]", + ); + assert!(!add_help_text().contains("--installation-id")); + assert_help_line( + &list_help_text(), + "runx list [tools|skills|graphs|packets|overlays] [--ok-only|--invalid-only] [-j|--json]", + ); + assert_help_line( + &login_help_text(), + "runx login [--provider github|google|gitlab] [--for default|publish] [--api-url url] [--local-api] [-j|--json]", + ); + assert_help_line( + ®istry_help_text(), + "runx registry search [--registry url|path] [--registry-dir dir] [--limit n] [-j|--json]", + ); + assert!(!registry_help_text().contains("--installation-id")); +} + #[test] fn routes_login_to_native_plan() { assert_eq!( @@ -447,12 +480,12 @@ fn routes_policy_to_native_plan_and_rejects_unknown_subcommands() { plan(&[ "policy", "inspect", - "fixtures/operational-policy/nitrosend-like.json", + "fixtures/operational-policy/provider-like.json", "--json", ]), LauncherAction::RunPolicy(PolicyPlan { action: PolicyAction::Inspect, - path: PathBuf::from("fixtures/operational-policy/nitrosend-like.json"), + path: PathBuf::from("fixtures/operational-policy/provider-like.json"), json: true, }) ); @@ -619,7 +652,6 @@ fn routes_registry_to_native_plan() { version: None, expected_digest: None, destination: None, - installation_id: None, owner: None, profile: None, trust_tier: None, @@ -642,8 +674,6 @@ fn routes_add_to_native_plan() { "skills", "--digest", "sha256:abc", - "--installation-id", - "inst_123", "--json", ]), LauncherAction::RunRegistry(RegistryPlan { @@ -654,7 +684,6 @@ fn routes_add_to_native_plan() { version: None, expected_digest: Some("sha256:abc".to_owned()), destination: Some(PathBuf::from("skills")), - installation_id: Some("inst_123".to_owned()), owner: None, profile: None, trust_tier: None, diff --git a/crates/runx-runtime/tests/registry_client.rs b/crates/runx-runtime/tests/registry_client.rs index 335fd0296..9027cd94b 100644 --- a/crates/runx-runtime/tests/registry_client.rs +++ b/crates/runx-runtime/tests/registry_client.rs @@ -99,8 +99,8 @@ fn search_rejects_unknown_trust_tier_with_field_path() -> Result<(), Box serde_json::Value "required_scopes": [], "tags": [], "trust_tier": "community", - "install_command": format!("runx add {skill_id}"), - "run_command": format!("runx run {skill_id}") + "install_command": format!("runx add {skill_id}@{version}"), + "run_command": format!("runx skill {skill_id}@{version}") }) } diff --git a/docs/publishing.md b/docs/publishing.md index 4238b2fe3..731e8aa58 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -152,7 +152,7 @@ runx treats it like every other governed action, with no special-casing: ```bash runx registry search runx registry read /@ --json - runx add / # the friendly install path + runx add /@ # the friendly install path ``` ## Links diff --git a/fixtures/cli-parity/commands.json b/fixtures/cli-parity/commands.json index 08a312ddc..c5c7c52e4 100644 --- a/fixtures/cli-parity/commands.json +++ b/fixtures/cli-parity/commands.json @@ -841,7 +841,6 @@ "--ref", "--digest", "--to", - "--installation-id", "--api-base-url", "--json" ], diff --git a/fixtures/registry/remote/search-success.json b/fixtures/registry/remote/search-success.json index 006cfc421..a5babdbc8 100644 --- a/fixtures/registry/remote/search-success.json +++ b/fixtures/registry/remote/search-success.json @@ -13,8 +13,8 @@ "required_scopes": [], "tags": ["utility"], "trust_tier": "verified", - "install_command": "runx add acme/echo", - "run_command": "runx run acme/echo" + "install_command": "runx add acme/echo@1.0.0", + "run_command": "runx skill acme/echo@1.0.0" } ] } diff --git a/packages/cli/src/args.ts b/packages/cli/src/args.ts index b4607a748..89225b643 100644 --- a/packages/cli/src/args.ts +++ b/packages/cli/src/args.ts @@ -63,7 +63,6 @@ export interface ParsedArgs { readonly addGitRef?: string; readonly addApiBaseUrl?: string; readonly addTo?: string; - readonly addInstallationId?: string; readonly publishOwner?: string; readonly publishVersion?: string; readonly publishProfile?: string; @@ -185,9 +184,6 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { ? String(inputs.apiBaseUrl ?? inputs["api-base-url"]) : undefined; const addTo = isTopLevelAdd && typeof inputs.to === "string" ? inputs.to : undefined; - const addInstallationId = isTopLevelAdd && typeof (inputs.installationId ?? inputs["installation-id"]) === "string" - ? String(inputs.installationId ?? inputs["installation-id"]) - : undefined; const publishOwner = isSkillPublish && typeof inputs.owner === "string" ? inputs.owner : undefined; const publishVersion = isSkillPublish && typeof inputs.version === "string" ? inputs.version : undefined; const publishProfile = isSkillPublish && typeof inputs.profile === "string" ? inputs.profile : undefined; @@ -215,7 +211,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { const effectiveInputs = isSkillSearch ? omitInputs(inputs, ["source", "registry"]) : isTopLevelAdd - ? omitInputs(inputs, ["version", "ref", "apiBaseUrl", "api-base-url", "to", "registry", "digest", "installationId", "installation-id"]) + ? omitInputs(inputs, ["version", "ref", "apiBaseUrl", "api-base-url", "to", "registry", "digest"]) : isReceiptPublish ? omitInputs(inputs, ["apiBaseUrl", "api-base-url", "token", "allowLocalApi", "allow-local-api"]) : isRetiredSkillAdd @@ -316,7 +312,6 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { addGitRef, addApiBaseUrl, addTo, - addInstallationId, publishOwner, publishVersion, publishProfile, diff --git a/packages/cli/src/dispatch.ts b/packages/cli/src/dispatch.ts index da1f63634..14cfb2e27 100644 --- a/packages/cli/src/dispatch.ts +++ b/packages/cli/src/dispatch.ts @@ -4,7 +4,6 @@ import { resolvePathFromUserInput, resolveRunxGlobalHomeDir, resolveRunxKnowledgeDir, - resolveRunxRegistryTarget, resolveSkillInstallRoot, } from "./cli-config.js"; import { createFileKnowledgeStore } from "./cli-knowledge.js"; @@ -55,7 +54,6 @@ import { renderToolCommandResult, type ToolCommandArgs, } from "./commands/tool.js"; -import { ensureRunxInstallState } from "./runx-state.js"; import { resolveBundledCliToolRoots } from "./runtime-assets.js"; import { runSkillSearch } from "./skill-refs.js"; import { streamTrainableReceipts } from "./trainable-receipts.js"; @@ -230,6 +228,13 @@ export async function dispatchCli( return await streamNativeRunxToIo(io, args, env); } + if (parsed.command === "add") { + const unknownFlag = firstUnknownAddFlag(parsed.inputs); + if (unknownFlag) { + return writeAddValidationError(io, parsed, `unknown add flag --${unknownFlag}`, 64); + } + } + if (parsed.command === "add" && parsed.addRef && isGithubRepoUrl(parsed.addRef)) { if (parsed.registryUrl) { return writeAddValidationError(io, parsed, "GitHub URL indexing uses --api-base-url for the hosted index API, not --registry."); @@ -248,9 +253,6 @@ export async function dispatchCli( "GitHub URL indexing does not support --to or --digest. Index the URL, then install the emitted registry ref with `runx add `.", ); } - if (parsed.addInstallationId) { - return writeAddValidationError(io, parsed, "GitHub URL indexing does not accept --installation-id."); - } try { const result = await publishUrlSkill({ repoUrl: parsed.addRef, @@ -277,10 +279,6 @@ export async function dispatchCli( if (parsed.addGitRef) { return writeAddValidationError(io, parsed, "--ref is only valid for GitHub repository URLs. Use --version for registry skill refs."); } - const registryTarget = resolveRunxRegistryTarget(env, { registry: parsed.registryUrl }); - const installState = registryTarget.mode === "remote" - ? await ensureRunxInstallState(resolveRunxGlobalHomeDir(env)) - : undefined; const args = [ "registry", "install", @@ -292,7 +290,6 @@ export async function dispatchCli( pushOptionalFlag(args, "--registry", parsed.registryUrl); pushOptionalFlag(args, "--version", parsed.addVersion); pushOptionalFlag(args, "--digest", parsed.expectedDigest); - pushOptionalFlag(args, "--installation-id", parsed.addInstallationId ?? installState?.state.installation_id); return await streamNativeRunxToIo(io, args, env); } @@ -374,6 +371,10 @@ export async function dispatchCli( return writeLocalSkillResult(io, env, parsed, result); } +function firstUnknownAddFlag(inputs: Readonly>): string | undefined { + return Object.keys(inputs).sort()[0]; +} + export function writeCliError(io: CliIo, message: string): number { io.stderr.write(renderCliError(message)); return 1; diff --git a/packages/cli/src/index.test.ts b/packages/cli/src/index.test.ts index 7aac21a6b..f8fa48c5c 100644 --- a/packages/cli/src/index.test.ts +++ b/packages/cli/src/index.test.ts @@ -225,8 +225,6 @@ Return the provided task id. "https://runx.example.test", "--to", "skills", - "--installation-id", - "inst_user", "--digest", "sha256:abc123", ]); @@ -235,7 +233,6 @@ Return the provided task id. expect(parsed.addRef).toBe("acme/sourcey"); expect(parsed.addVersion).toBe("1.0.0"); expect(parsed.addTo).toBe("skills"); - expect(parsed.addInstallationId).toBe("inst_user"); expect(parsed.registryUrl).toBe("https://runx.example.test"); expect(parsed.expectedDigest).toBe("abc123"); expect(parsed.inputs).toEqual({}); @@ -495,7 +492,7 @@ Return the provided task id. const stdout = createMemoryStream(); const stderr = createMemoryStream(); const exitCode = await runCli( - ["policy", "inspect", "fixtures/operational-policy/nitrosend-like.json", "--json"], + ["policy", "inspect", "fixtures/operational-policy/provider-like.json", "--json"], { stdin: process.stdin, stdout, stderr }, { ...process.env, RUNX_CWD: process.cwd() }, ); @@ -510,11 +507,11 @@ Return the provided task id. }; }; expect(result.status).toBe("success"); - expect(result.policy.policy_id).toBe("nitrosend-issue-flow"); + expect(result.policy.policy_id).toBe("provider-issue-flow"); expect(result.policy.sources[0]?.locator_count).toBe(1); expect(stdout.contents()).not.toContain(process.cwd()); - expect(stdout.contents()).not.toContain("slack://nitrosend/C0APFMY0V8Q"); - expect(stdout.contents()).not.toContain("sentry://nitrosend/production"); + expect(stdout.contents()).not.toContain("slack://example/C0APFMY0V8Q"); + expect(stdout.contents()).not.toContain("sentry://example/production"); }); it("fails policy lint when target actions have no available runner", async () => { @@ -991,8 +988,8 @@ Answer the prompt directly. await expect(readFile(path.join(installDir, "acme", "sourcey", "SKILL.md"), "utf8")).rejects.toThrow(); }); - it("forwards explicit add installation ids to the native subprocess", async () => { - const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-cli-add-installation-id-")); + it("delegates registry add without installation identity flags", async () => { + const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-cli-add-no-installation-id-")); tempDirs.push(tempDir); const nativeBin = path.join(tempDir, "fake-runx.js"); await writeFile( @@ -1011,8 +1008,6 @@ Answer the prompt directly. "https://runx.example.test", "--to", path.join(tempDir, "skills"), - "--installation-id", - "inst_user", "--json", ], { stdin: process.stdin, stdout, stderr }, @@ -1028,10 +1023,21 @@ Answer the prompt directly. expect(stderr.contents()).toBe(""); const argv = JSON.parse(stdout.contents()).argv as string[]; expect(argv).toEqual(expect.arrayContaining(["registry", "install", "acme/sourcey@1.0.0"])); - expect(argv.slice(argv.indexOf("--installation-id"), argv.indexOf("--installation-id") + 2)).toEqual([ - "--installation-id", - "inst_user", - ]); + expect(argv).not.toContain("--installation-id"); + }); + + it("rejects removed add installation identity flags", async () => { + const stdout = createMemoryStream(); + const stderr = createMemoryStream(); + const exitCode = await runCli( + ["add", "acme/sourcey@1.0.0", "--installation-id", "inst_user"], + { stdin: process.stdin, stdout, stderr }, + { ...process.env, RUNX_CWD: process.cwd() }, + ); + + expect(exitCode).toBe(64); + expect(stdout.contents()).toBe(""); + expect(stderr.contents()).toContain("unknown add flag --installation-id"); }); it("forwards receipt publish to the native subprocess", async () => { @@ -2404,7 +2410,7 @@ interface MutablePolicyFixture extends Record { } async function readFixturePolicy(): Promise { - return JSON.parse(await readFile("fixtures/operational-policy/nitrosend-like.json", "utf8")) as MutablePolicyFixture; + return JSON.parse(await readFile("fixtures/operational-policy/provider-like.json", "utf8")) as MutablePolicyFixture; } async function createFakeAgentBin(commands: readonly string[]): Promise { diff --git a/packages/cli/src/skill-refs.ts b/packages/cli/src/skill-refs.ts index d39d03817..e26094b04 100644 --- a/packages/cli/src/skill-refs.ts +++ b/packages/cli/src/skill-refs.ts @@ -6,7 +6,6 @@ import { parseDocument } from "yaml"; import { resolvePathFromUserInput, - resolveRunxGlobalHomeDir, resolveRunxOfficialSkillsDir, resolveRunxProjectDir, resolveSkillInstallRoot, @@ -17,7 +16,6 @@ import { asRecord, errorMessage, firstNonEmpty, hashString, parsePositiveInt, re import { searchRegistryViaRustCli } from "./native-registry.js"; import { runNativeRunx } from "./native-runx.js"; -import { ensureRunxInstallState } from "./runx-state.js"; let cachedBundledSkillsDir: string | undefined | null = null; let cachedOfficialSkillLock: readonly OfficialSkillLockEntry[] | undefined; @@ -103,13 +101,10 @@ export function createOfficialSkillResolver(env: NodeJS.ProcessEnv): OfficialSki if (parsed.version && entry.version !== parsed.version) { return undefined; } - const globalHomeDir = resolveRunxGlobalHomeDir(env); - const install = await ensureRunxInstallState(globalHomeDir); const registryBaseUrl = env.RUNX_REGISTRY_URL ?? "https://runx.ai"; const cache = await ensureOfficialSkillCached({ cacheRoot: resolveRunxOfficialSkillsDir(env), registryBaseUrl, - installationId: install.state.installation_id, entry, env, }); @@ -122,7 +117,6 @@ export function createOfficialSkillResolver(env: NodeJS.ProcessEnv): OfficialSki async function ensureOfficialSkillCached(options: { readonly cacheRoot: string; readonly registryBaseUrl: string; - readonly installationId: string; readonly entry: OfficialSkillLockEntry; readonly env: NodeJS.ProcessEnv; }): Promise<{ readonly skillPath: string; readonly fromCache: boolean }> { @@ -150,8 +144,6 @@ async function ensureOfficialSkillCached(options: { options.entry.version, "--digest", options.entry.digest, - "--installation-id", - options.installationId, "--to", options.cacheRoot, "--json", diff --git a/scripts/generate-cli-feature-parity.ts b/scripts/generate-cli-feature-parity.ts index 7335458bc..e926ba0ef 100644 --- a/scripts/generate-cli-feature-parity.ts +++ b/scripts/generate-cli-feature-parity.ts @@ -80,7 +80,7 @@ const commands: readonly CommandMatrixEntry[] = [ command("tool.search", "runx tool search ", [], ["--source", "--json"], "external-stub", ["tool-catalog", "adapter-catalog"], ["tool.search.validate"]), command("tool.inspect", "runx tool inspect ", [], ["--source", "--json"], "external-stub", ["tool-catalog", "adapter-catalog"], ["tool.inspect.validate"]), command("registry", "runx registry search|read|resolve|install|publish ... --json", [], ["--registry", "--registry-dir", "--version", "--digest", "--to", "--owner", "--profile", "--limit", "--upsert", "--json"], "external-stub", ["registry", "cli-presentation"], ["registry.validate"]), - command("add", "runx add ", [], ["--registry", "--version", "--ref", "--digest", "--to", "--installation-id", "--api-base-url", "--json"], "external-stub", ["registry", "cli-presentation"], ["add.validate"]), + command("add", "runx add ", [], ["--registry", "--version", "--ref", "--digest", "--to", "--api-base-url", "--json"], "external-stub", ["registry", "cli-presentation"], ["add.validate"]), ]; const surfaces: readonly RuntimeSurface[] = [ diff --git a/skills/support-triage-reply/references/evidence.json b/skills/support-triage-reply/references/evidence.json index b1dfb323e..2d54864f9 100644 --- a/skills/support-triage-reply/references/evidence.json +++ b/skills/support-triage-reply/references/evidence.json @@ -45,7 +45,7 @@ }, "clean_install": { "status": "installed", - "command": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id godfood-support-triage-final3 --json" + "command": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --json" }, "dogfood_run": { "status": "passed", @@ -108,7 +108,7 @@ "runx --version returned runx-cli 0.6.6, satisfying the CLI floor for this bounty.", "The published registry ref is godfood/support-triage-reply@sha-4887b7e3476f under the godfood authenticated namespace.", "runx registry read godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --json resolves the package metadata, digests, publisher, trust tier, and triage runner.", - "A clean install succeeded with runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id godfood-support-triage-final3 --json.", + "A clean install succeeded with runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --json.", "The local harness passed three cases: safe-how-to-reply-draft, account-access-escalates-without-draft, and missing-request-fails.", "The registry publish gate ran the hosted harness successfully before accepting the package.", "The dogfood command ran the published registry skill on a real support-domain input and produced receipt sha256:8e87b9c4c18bf2e39c976059bb480bb6825400f15bd62886d1592a57c7357b9f.", @@ -126,7 +126,7 @@ "public_url": "https://runx.ai/x/godfood/support-triage-reply", "source_url": "https://github.com/runxhq/runx/tree/main/skills/support-triage-reply", "publish_method": "purpose-scoped godfood publish credential; credential revoked after publish", - "install_command": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id godfood-support-triage-final3 --json", + "install_command": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --json", "dogfood_command": "runx skill godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --input support_request= --input policy= --receipts --json", "verify_command": "runx verify --receipt dogfood-receipt.json --json", "verify_public_key_base64": "IVL40Zt5HSRFMkLhXy6rbLfP+ntqXtMAl5YOBpiB2xI=", @@ -149,7 +149,7 @@ ], "safe_answer_case": "safe-how-to-reply-draft", "escalation_case": "account-access-escalates-without-draft", - "how_to_install": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --installation-id ", + "how_to_install": "runx add godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai", "how_to_run": "runx skill godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --input support_request= --input policy= --json", "how_to_verify": "Download dogfood-receipt.json from source, set RUNX_RECEIPT_VERIFY_KID=runx-demo-key and RUNX_RECEIPT_VERIFY_ED25519_PUBLIC_KEY_BASE64 to the public key in this evidence file, then run runx verify --receipt dogfood-receipt.json --json.", "dogfood_draft_subject": "Re: How do I verify my sending domain?", diff --git a/skills/support-triage-reply/references/report.md b/skills/support-triage-reply/references/report.md index dd34cd723..b2c09d37e 100644 --- a/skills/support-triage-reply/references/report.md +++ b/skills/support-triage-reply/references/report.md @@ -51,7 +51,6 @@ Clean install: ```sh runx add godfood/support-triage-reply@ \ --registry https://api.runx.ai \ - --installation-id godfood-support-triage-final \ --json ``` diff --git a/tests/registry-fixtures.ts b/tests/registry-fixtures.ts index 2bc7d62b5..faccb9904 100644 --- a/tests/registry-fixtures.ts +++ b/tests/registry-fixtures.ts @@ -369,7 +369,7 @@ function runxLinkForVersion(record: RegistrySkillVersion, registryUrl?: string): digest: record.digest, registry_url: registryUrl, install_command: `runx add ${ref}${registryFlag}`, - run_command: `runx skill ${record.name}`, + run_command: `runx skill ${ref}${registryFlag}`, }; } diff --git a/tests/remote-registry-search.test.ts b/tests/remote-registry-search.test.ts index 7da250bde..254f6964e 100644 --- a/tests/remote-registry-search.test.ts +++ b/tests/remote-registry-search.test.ts @@ -49,7 +49,7 @@ process.stdout.write(JSON.stringify({ trust_tier: "community", trust_signals: [], install_command: "runx add acme/sourcey@1.0.0 --registry https://runx.example.test", - run_command: "runx skill sourcey" + run_command: "runx skill acme/sourcey@1.0.0 --registry https://runx.example.test" } ] } diff --git a/tests/skill-search.test.ts b/tests/skill-search.test.ts index ac31bf8d5..00d8d15c4 100644 --- a/tests/skill-search.test.ts +++ b/tests/skill-search.test.ts @@ -146,7 +146,7 @@ process.stdout.write(JSON.stringify({ profile_mode: "portable", runner_names: [], install_command: "runx add rust/sourcey@1.0.0", - run_command: "runx skill sourcey", + run_command: "runx skill rust/sourcey@1.0.0", version: "1.0.0" }] } From 5ccb9ed48de0883f9075416f9cb9f9afa14c42e4 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 19:08:48 +1000 Subject: [PATCH 54/64] feat(skills): cut over ops desk catalog Rename the bundled runx operator skill to ops-desk, remove product-specific fixture names, keep newer maturing skills internal until they meet the public catalog bar, and make graph skills fail closed when required graph inputs are missing. --- crates/runx-cli/src/official_skills.rs | 42 +-- crates/runx-cli/tests/policy.rs | 12 +- ...fixture.rs => example_external_fixture.rs} | 20 +- crates/runx-contracts/tests/integration.rs | 2 +- .../tests/operational_policy.rs | 47 ++-- .../tests/schema_wire_conformance/corpora.rs | 2 +- .../src/execution/skill_front/graph.rs | 50 ++++ crates/runx-runtime/tests/skill_run.rs | 66 +++++ docs/demo-inventory.json | 2 +- docs/demos.md | 2 +- docs/developer-issue-inbox.md | 2 +- docs/issue-to-pr.md | 8 +- docs/operator-console.md | 29 +- docs/operator-skills.md | 11 +- docs/reference.md | 5 +- docs/thread-story-contract.md | 3 +- .../invalid-product-specific-field.json | 2 +- .../issue-intake/api-source-thread.json | 28 ++ .../issue-intake/api-source-thread.json | 28 -- ...nitrosend-like.json => provider-like.json} | 38 +-- .../runner-manifests/harness-basic.json | 2 +- packages/cli/src/official-skills.lock.json | 56 ++-- packages/cli/src/skill-refs.test.ts | 5 +- packages/contracts/src/index.test.ts | 8 +- .../src/schemas/operational-policy.test.ts | 64 ++--- skills/business-ops/SKILL.md | 208 +++++++++----- skills/business-ops/X.yaml | 15 +- skills/business-ops/graph/ops-lane/SKILL.md | 7 + skills/business-ops/graph/ops-lane/X.yaml | 6 +- skills/business-ops/graph/ops-lane/run.mjs | 253 +++++++++++++++--- skills/dependency-cve-audit/X.yaml | 2 +- skills/github-sync/X.yaml | 7 +- skills/governed-outbound/SKILL.md | 8 +- skills/governed-outbound/X.yaml | 42 ++- skills/issue-to-pr/push-outbox/SKILL.md | 1 + skills/lead-router/SKILL.md | 14 +- skills/lead-router/X.yaml | 8 +- skills/least-privilege-auditor/X.yaml | 73 ----- skills/{runx-operator => ops-desk}/SKILL.md | 85 +++--- skills/{runx-operator => ops-desk}/X.yaml | 38 +-- .../action-review-awaits-approval.yaml | 6 +- .../fixtures/payment-status.yaml | 46 ++-- .../references/communications.md | 5 +- .../references/dashboard.md | 2 +- .../references/delegation.md | 4 +- skills/ops-desk/references/payments.md | 70 +++++ .../references/providers.md | 4 +- .../references/receipts.md | 0 skills/runx-operator/references/payments.md | 115 -------- skills/send-as/SKILL.md | 13 +- skills/send-as/X.yaml | 2 +- .../fixtures/campaign-send-plan-ready.yaml | 20 +- .../missing-audience-needs-input.yaml | 4 +- skills/slack-notify/X.yaml | 7 +- skills/structured-extraction/X.yaml | 2 +- skills/support-triage-reply/SKILL.md | 2 +- skills/support-triage-reply/X.yaml | 12 +- .../references/evidence.json | 10 +- .../support-triage-reply/references/report.md | 10 +- skills/work-plan/X.yaml | 16 +- tests/official-skill-catalog.test.ts | 2 +- 61 files changed, 979 insertions(+), 674 deletions(-) rename crates/runx-contracts/tests/{nitrosend_external_fixture.rs => example_external_fixture.rs} (81%) create mode 100644 fixtures/external/example/issue-intake/api-source-thread.json delete mode 100644 fixtures/external/nitrosend/issue-intake/api-source-thread.json rename fixtures/operational-policy/{nitrosend-like.json => provider-like.json} (83%) rename skills/{runx-operator => ops-desk}/SKILL.md (80%) rename skills/{runx-operator => ops-desk}/X.yaml (81%) rename skills/{runx-operator => ops-desk}/fixtures/action-review-awaits-approval.yaml (91%) rename skills/{runx-operator => ops-desk}/fixtures/payment-status.yaml (62%) rename skills/{runx-operator => ops-desk}/references/communications.md (87%) rename skills/{runx-operator => ops-desk}/references/dashboard.md (96%) rename skills/{runx-operator => ops-desk}/references/delegation.md (95%) create mode 100644 skills/ops-desk/references/payments.md rename skills/{runx-operator => ops-desk}/references/providers.md (93%) rename skills/{runx-operator => ops-desk}/references/receipts.md (100%) delete mode 100644 skills/runx-operator/references/payments.md diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index 2d4b4a1d9..a5a9e2776 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -17,8 +17,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/business-ops", - version: "sha-ca97efa3deb0", - digest: "27c05e8e30d8e925c93ecd51e535add38a4ceeabbfc76acf73bb0a578fee3e11", + version: "sha-542469f72fa2", + digest: "f319e45b875aab442ead32ecddd194c715bfd585f1504d9e9c3d7bcbb914e342", }, OfficialSkillLockEntry { skill_id: "runx/charge", @@ -37,7 +37,7 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/dependency-cve-audit", - version: "sha-e9e461e41ea3", + version: "sha-016cc407efa2", digest: "c19ec9fdeb088daab950b7c2e1f3757880de9702e31e40b57e2f65c0c4033348", }, OfficialSkillLockEntry { @@ -72,13 +72,13 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/github-sync", - version: "sha-67a1011141aa", + version: "sha-703346713bf3", digest: "83b0f4cd98cf23ff81ec71727543e6d811e75aa970cf957bec4267575a16efcc", }, OfficialSkillLockEntry { skill_id: "runx/governed-outbound", - version: "sha-c15ec36034f2", - digest: "bb01d4097b48693f68b7a96810ee685828d17e81ec4f55fda2ffee981af61604", + version: "sha-c93e1c732950", + digest: "e177cd002efb896e0bba7a6352f19f4d1ec575db1ef548849244ea42725356a6", }, OfficialSkillLockEntry { skill_id: "runx/improve-skill", @@ -117,12 +117,12 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/lead-router", - version: "sha-e488a0d01d46", - digest: "cc13bfdf7d586ecd9117c6e33efd0f897134d3950cbf695e89290cf7a3523527", + version: "sha-4345afde1d16", + digest: "4a27b60d2cdd54a5f02163473f756185f9fa5cb57e32c1f59f65fe3472ed3202", }, OfficialSkillLockEntry { skill_id: "runx/least-privilege-auditor", - version: "sha-e5c3622556d9", + version: "sha-a31f1c09aa5c", digest: "244df5dd8eed7900d1987c76060893d3c9cd65f420c5b8c177b19fa4e0b81ac2", }, OfficialSkillLockEntry { @@ -190,6 +190,11 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ version: "sha-5d9f95438c9a", digest: "041e0ec18fa4b646b46b72d34662eabbbfbc43ab5a3a65423b49b3e94e81d159", }, + OfficialSkillLockEntry { + skill_id: "runx/ops-desk", + version: "sha-57c1b0df97f6", + digest: "d468d7984b8a7736cb760373c5348007eed1f387567814f39ac82eb39e58150a", + }, OfficialSkillLockEntry { skill_id: "runx/overlay-generator", version: "sha-b5dc11a7088d", @@ -255,11 +260,6 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ version: "sha-0ec78eb20018", digest: "1a1441365a20b74442998656478fc3d530f2d09f25f811d970b403a8a7920df4", }, - OfficialSkillLockEntry { - skill_id: "runx/runx-operator", - version: "sha-0fed07a0dc00", - digest: "9de1d9dffb46b6bb14872b66738d5e9b26f271c6f11595c6a685d4c30e539176", - }, OfficialSkillLockEntry { skill_id: "runx/sandbox-harden", version: "sha-e5f346fbac0f", @@ -267,8 +267,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/send-as", - version: "sha-151a237afe0b", - digest: "b5c9c3cbd9ecb737cc8b40228602e71f5aef1fab3ca6ba85bd0851bb983a5646", + version: "sha-ab821b54b4e6", + digest: "ee71759e8099dba9a4925a81b2da69c1d83e73a6fd57b3e21839a6bb637e9ca1", }, OfficialSkillLockEntry { skill_id: "runx/settle-invoice", @@ -292,7 +292,7 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/slack-notify", - version: "sha-3282402f7a8b", + version: "sha-33d69b8fb325", digest: "9e0abd47c54455add3c715e18c371c427e0bbb0d617ed0212f60d766f62c2856", }, OfficialSkillLockEntry { @@ -327,13 +327,13 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/structured-extraction", - version: "sha-f14902374e11", + version: "sha-a826aca27a7a", digest: "ebe37921d3b9cb63aa1ca5232a8075607d3b4ad541af4c1bc901ace749ea404f", }, OfficialSkillLockEntry { skill_id: "runx/support-triage-reply", - version: "sha-fce24eb780f9", - digest: "94beeed742142c6a236eb0ae1db5644d3f868362030089332c6ce3b40b1f86bb", + version: "sha-a605f6b30db4", + digest: "e945d181db20fbb0f2432ad7fd5b5fbc438deb1cdbe4eacad169641e24670416", }, OfficialSkillLockEntry { skill_id: "runx/taste-profile", @@ -362,7 +362,7 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/work-plan", - version: "sha-d2b3abc77e97", + version: "sha-e6dd3bc7d087", digest: "ba007b997503258ca52e6a067e0dd6ed12ec7250add5dae35e048663b2a502a2", }, OfficialSkillLockEntry { diff --git a/crates/runx-cli/tests/policy.rs b/crates/runx-cli/tests/policy.rs index 926e5634f..c279ea582 100644 --- a/crates/runx-cli/tests/policy.rs +++ b/crates/runx-cli/tests/policy.rs @@ -9,7 +9,7 @@ fn policy_inspect_json_redacts_raw_locators() -> Result<(), Box Result<(), Box Result<(), Box Result<(), Box Result Result<(), Box> { - let fixture: ExternalNitrosendFixture = serde_json::from_str(FIXTURE_JSON)?; + let fixture: ExternalExampleFixture = serde_json::from_str(FIXTURE_JSON)?; let policy: OperationalPolicy = serde_json::from_str(POLICY_JSON)?; assert_eq!(fixture.schema, "runx.external_dogfood_fixture.v1"); - assert_eq!(fixture.fixture_id, "nitrosend-api-source-thread"); + assert_eq!(fixture.fixture_id, "example-api-source-thread"); assert_eq!(fixture.source.provider.as_str(), "slack"); - assert_eq!(fixture.source.locator, "slack://nitrosend/C0APFMY0V8Q"); + assert_eq!(fixture.source.locator, "slack://example/C0APFMY0V8Q"); assert_eq!(fixture.source.thread_ts, "1778834840.485629"); assert!(fixture.source.issue_url.contains("/issues/")); - assert_eq!(fixture.signal.fingerprint, "sha256:nitrosend-source-482"); + assert_eq!(fixture.signal.fingerprint, "sha256:example-source-482"); assert_eq!(fixture.target.action, "issue-to-pr"); let admission = admit_operational_policy_request( @@ -89,9 +89,9 @@ fn nitrosend_external_fixture_is_admitted_by_operational_policy() } #[test] -fn nitrosend_external_fixture_cites_existing_runtime_fixtures() +fn example_external_fixture_cites_existing_runtime_fixtures() -> Result<(), Box> { - let fixture: ExternalNitrosendFixture = serde_json::from_str(FIXTURE_JSON)?; + let fixture: ExternalExampleFixture = serde_json::from_str(FIXTURE_JSON)?; let root = repo_root()?; for runtime_fixture in &fixture.runtime_fixtures { diff --git a/crates/runx-contracts/tests/integration.rs b/crates/runx-contracts/tests/integration.rs index 2f0e72a4d..51581bc54 100644 --- a/crates/runx-contracts/tests/integration.rs +++ b/crates/runx-contracts/tests/integration.rs @@ -8,11 +8,11 @@ mod act_assignment_fixtures; mod credential_delivery_fixtures; mod doctor_fixtures; +mod example_external_fixture; mod execution_fixtures; mod external_adapter_fixtures; mod harness_spine_fixtures; mod host_protocol_fixtures; -mod nitrosend_external_fixture; mod operational_policy; mod operational_proposal_fixtures; mod reference; diff --git a/crates/runx-contracts/tests/operational_policy.rs b/crates/runx-contracts/tests/operational_policy.rs index 97ae1e412..68e265b13 100644 --- a/crates/runx-contracts/tests/operational_policy.rs +++ b/crates/runx-contracts/tests/operational_policy.rs @@ -6,8 +6,7 @@ use runx_contracts::{ validate_operational_policy_contract, validate_operational_policy_semantics, }; -const NITROSEND_LIKE: &str = - include_str!("../../../fixtures/operational-policy/nitrosend-like.json"); +const PROVIDER_LIKE: &str = include_str!("../../../fixtures/operational-policy/provider-like.json"); const MINIMAL_SINGLE_REPO: &str = include_str!("../../../fixtures/operational-policy/minimal-single-repo.json"); const INVALID_UNKNOWN_RUNNER: &str = @@ -25,7 +24,7 @@ const INVALID_SECRET_FIELD: &str = #[test] fn positive_operational_policy_fixtures_are_valid() -> Result<(), Box> { - for fixture in [NITROSEND_LIKE, MINIMAL_SINGLE_REPO] { + for fixture in [PROVIDER_LIKE, MINIMAL_SINGLE_REPO] { let policy: OperationalPolicy = serde_json::from_str(fixture)?; validate_operational_policy_contract(&policy)?; @@ -66,7 +65,7 @@ fn schema_invalid_fixtures_are_rejected() { #[test] fn invalid_created_at_is_rejected_like_typescript_schema() -> Result<(), Box> { - let mut policy: OperationalPolicy = serde_json::from_str(NITROSEND_LIKE)?; + let mut policy: OperationalPolicy = serde_json::from_str(PROVIDER_LIKE)?; policy.created_at = Some("2026-05-19 00:00:00".into()); let missing_t = validate_operational_policy_contract(&policy); @@ -81,22 +80,22 @@ fn invalid_created_at_is_rejected_like_typescript_schema() -> Result<(), Box Result<(), Box> { - let policy: OperationalPolicy = serde_json::from_str(NITROSEND_LIKE)?; + let policy: OperationalPolicy = serde_json::from_str(PROVIDER_LIKE)?; let readback = project_operational_policy_readback(&policy)?; let json = serde_json::to_string(&readback)?; assert!(readback.valid); assert_eq!(readback.sources[0].locator_count, 1); assert!(json.contains(r#""locator_count":1"#)); - assert!(!json.contains("slack://nitrosend")); + assert!(!json.contains("slack://example")); Ok(()) } #[test] -fn nitrosend_policy_admits_each_target_repo_route() -> Result<(), Box> { - let policy: OperationalPolicy = serde_json::from_str(NITROSEND_LIKE)?; +fn provider_policy_admits_each_target_repo_route() -> Result<(), Box> { + let policy: OperationalPolicy = serde_json::from_str(PROVIDER_LIKE)?; - for repo in ["nitrosend/nitrosend", "nitrosend/api", "nitrosend/app"] { + for repo in ["example/project", "example/api", "example/app"] { let admission = admit_operational_policy_request( &policy, &OperationalPolicyAdmissionRequest { @@ -105,19 +104,19 @@ fn nitrosend_policy_admits_each_target_repo_route() -> Result<(), Box Result<(), Box Result<(), Box> { - let policy: OperationalPolicy = serde_json::from_str(NITROSEND_LIKE)?; + let policy: OperationalPolicy = serde_json::from_str(PROVIDER_LIKE)?; let admission = admit_operational_policy_request( &policy, &OperationalPolicyAdmissionRequest { source_id: Some("bugs-fixes".to_owned()), - target_repo: Some("nitrosend/unknown".to_owned()), + target_repo: Some("example/unknown".to_owned()), action: OperationalPolicyAction::IssueToPr, runner_id: None, - source_thread_locator: Some( - "slack://nitrosend/C0APFMY0V8Q/1778834840.485629".to_owned(), - ), + source_thread_locator: Some("slack://example/C0APFMY0V8Q/1778834840.485629".to_owned()), }, )?; @@ -164,23 +161,23 @@ fn nitrosend_policy_denies_unknown_target_before_runner_selection() } #[test] -fn nitrosend_policy_denies_pr_admission_without_source_thread() +fn provider_policy_denies_pr_admission_without_source_thread() -> Result<(), Box> { - let policy: OperationalPolicy = serde_json::from_str(NITROSEND_LIKE)?; + let policy: OperationalPolicy = serde_json::from_str(PROVIDER_LIKE)?; let admission = admit_operational_policy_request( &policy, &OperationalPolicyAdmissionRequest { source_id: Some("bugs-fixes".to_owned()), - target_repo: Some("nitrosend/api".to_owned()), + target_repo: Some("example/api".to_owned()), action: OperationalPolicyAction::IssueToPr, - runner_id: Some("aster-production".to_owned()), + runner_id: Some("local-review".to_owned()), source_thread_locator: None, }, )?; assert_eq!(admission.status, OperationalPolicyAdmissionStatus::Deny); - assert_eq!(admission.target_repo.as_deref(), Some("nitrosend/api")); - assert_eq!(admission.runner_id.as_deref(), Some("aster-production")); + assert_eq!(admission.target_repo.as_deref(), Some("example/api")); + assert_eq!(admission.runner_id.as_deref(), Some("local-review")); assert!( admission .findings diff --git a/crates/runx-contracts/tests/schema_wire_conformance/corpora.rs b/crates/runx-contracts/tests/schema_wire_conformance/corpora.rs index 499dbc5d8..7b2367369 100644 --- a/crates/runx-contracts/tests/schema_wire_conformance/corpora.rs +++ b/crates/runx-contracts/tests/schema_wire_conformance/corpora.rs @@ -1462,7 +1462,7 @@ pub(super) fn operational_policy_corpus() -> Vec<(&'static str, Value)> { let valid = json!({ "schema": "runx.operational_policy.v1", "schema_version": "runx.operational_policy.v1", - "policy_id": "nitrosend.intake", + "policy_id": "provider.intake", "sources": [{ "source_id": "slack.intake", "provider": "slack", diff --git a/crates/runx-runtime/src/execution/skill_front/graph.rs b/crates/runx-runtime/src/execution/skill_front/graph.rs index 10eae4401..8540000d6 100644 --- a/crates/runx-runtime/src/execution/skill_front/graph.rs +++ b/crates/runx-runtime/src/execution/skill_front/graph.rs @@ -121,6 +121,13 @@ pub(super) fn execute_graph_skill_run( } }) .unwrap_or_else(|| request_graph_inputs.clone()); + if let Some(missing_request) = missing_required_graph_input_request(runner, &graph_inputs) { + return Ok(JsonValue::Object(needs_agent_output( + &run_id, + "graph.required-inputs", + missing_request, + ))); + } let graph = materialize_graph_inputs(graph, &graph_inputs); let mut host = SkillRunGraphHost::with_inline(answers, inline_resolver); let mut checkpoint = if let Some(state) = resumed_state.take() { @@ -248,6 +255,49 @@ pub(super) fn execute_graph_skill_run( } } +fn missing_required_graph_input_request( + runner: &SkillRunnerDefinition, + graph_inputs: &JsonObject, +) -> Option { + let missing = runner + .inputs + .iter() + .filter(|(_, input)| input.required) + .filter(|(name, _)| match graph_inputs.get(name.as_str()) { + Some(JsonValue::Null) => true, + Some(_) => false, + None => true, + }) + .map(|(name, input)| { + let mut entry = JsonObject::new(); + entry.insert("name".to_owned(), JsonValue::String(name.clone())); + entry.insert( + "type".to_owned(), + JsonValue::String(input.input_type.clone()), + ); + if let Some(description) = &input.description { + entry.insert( + "description".to_owned(), + JsonValue::String(description.clone()), + ); + } + JsonValue::Object(entry) + }) + .collect::>(); + if missing.is_empty() { + return None; + } + + let mut request = JsonObject::new(); + request.insert( + "kind".to_owned(), + JsonValue::String("graph.required_inputs".to_owned()), + ); + request.insert("runner".to_owned(), JsonValue::String(runner.name.clone())); + request.insert("missing_inputs".to_owned(), JsonValue::Array(missing)); + Some(JsonValue::Object(request)) +} + struct BlockedGraphSkillRun<'a> { request: &'a SkillRunRequest, workspace: &'a WorkspaceEnv, diff --git a/crates/runx-runtime/tests/skill_run.rs b/crates/runx-runtime/tests/skill_run.rs index 11efcad36..a0b2dc177 100644 --- a/crates/runx-runtime/tests/skill_run.rs +++ b/crates/runx-runtime/tests/skill_run.rs @@ -1660,6 +1660,38 @@ fn native_graph_skill_run_omits_missing_optional_graph_input_references() Ok(()) } +#[test] +fn native_graph_skill_run_requires_declared_graph_inputs() -> Result<(), Box> +{ + let temp = tempdir()?; + let skill_dir = write_graph_required_input_skill(temp.path())?; + let receipt_dir = temp.path().join("receipts"); + + let result = run_skill(SkillRunRequest { + skill_path: skill_dir, + receipt_dir: Some(receipt_dir), + run_id: None, + answers_path: None, + inputs: BTreeMap::new(), + env: BTreeMap::new(), + cwd: temp.path().to_path_buf(), + local_credential: None, + })?; + + let output = object(&result.output, "graph required input result")?; + assert_eq!(string_field(output, "status"), Some("needs_agent")); + let requests = array_field(output, "requests").ok_or("missing requests")?; + let request = object(&requests[0], "missing input request")?; + assert_eq!(string_field(request, "id"), Some("graph.required-inputs")); + assert_eq!(string_field(request, "kind"), Some("graph.required_inputs")); + let missing = array_field(request, "missing_inputs").ok_or("missing input list")?; + let lead = object(&missing[0], "lead missing input")?; + assert_eq!(string_field(lead, "name"), Some("lead")); + assert_eq!(string_field(lead, "type"), Some("json")); + + Ok(()) +} + #[cfg(feature = "catalog")] #[test] fn native_graph_skill_run_uses_canonical_tool_root() -> Result<(), Box> { @@ -2578,6 +2610,40 @@ runners: Ok(skill_dir) } +fn write_graph_required_input_skill(root: &Path) -> Result> { + let skill_dir = root.join("graph-required-input"); + fs::create_dir_all(&skill_dir)?; + fs::write( + skill_dir.join("SKILL.md"), + "---\nname: graph-required-input\n---\n# Graph Required Input\n", + )?; + fs::write( + skill_dir.join("X.yaml"), + r#" +skill: graph-required-input +runners: + graph: + default: true + type: graph + inputs: + lead: + type: json + required: true + description: Lead packet to route. + graph: + name: graph-required-input + steps: + - id: approve + run: + type: approval + inputs: + gate_id: graph-required-input.approve + reason: approve the graph +"#, + )?; + Ok(skill_dir) +} + #[cfg(feature = "catalog")] fn write_echo_tool(root: &Path) -> Result<(), Box> { write_echo_tool_at(&root.join("tools/test/echo"), "Graph tool bug") diff --git a/docs/demo-inventory.json b/docs/demo-inventory.json index 51092145f..ed6ed4b26 100644 --- a/docs/demo-inventory.json +++ b/docs/demo-inventory.json @@ -9,7 +9,7 @@ { "path": "skills/business-ops", "proof": "One business signal fans out through governed ops lanes and seals a graph receipt.", - "command": "runx harness skills/business-ops" + "command": "runx harness skills/business-ops/fixtures/business-ops-smoke.yaml" }, { "path": "examples/github-mcp-hero", diff --git a/docs/demos.md b/docs/demos.md index 983539206..bbffb5773 100644 --- a/docs/demos.md +++ b/docs/demos.md @@ -18,7 +18,7 @@ export RUNX_RECEIPT_SIGN_ISSUER_TYPE=hosted | Demo | Proof | Run | Gate | | --- | --- | --- | --- | | `examples/hello-world` | Native CLI top-level skill and harness baseline. | `runx harness examples/hello-world` | harness | -| `skills/business-ops` | One business signal fans out through governed ops lanes and seals a graph receipt. | `runx harness skills/business-ops` | harness | +| `skills/business-ops` | One business signal fans out through governed ops lanes and seals a graph receipt. | `runx harness skills/business-ops/fixtures/business-ops-smoke.yaml` | harness | | `examples/github-mcp-hero` | GitHub MCP repo read succeeds, out-of-scope write is refused, and the denial receipt verifies offline. | `sh examples/github-mcp-hero/run.sh` | harness | | `examples/http-graph` | A graph step uses the governed HTTP front against a local fixture and seals a receipt tree. | `sh examples/http-graph/run.sh` | harness | | `examples/openapi-graph` | An OpenAPI-described operation is executed through the governed external-adapter lane and sealed. | `sh examples/openapi-graph/run.sh` | harness | diff --git a/docs/developer-issue-inbox.md b/docs/developer-issue-inbox.md index 578616201..884d6761e 100644 --- a/docs/developer-issue-inbox.md +++ b/docs/developer-issue-inbox.md @@ -51,7 +51,7 @@ locators. Use the CLI gate before wiring a policy into a live runner: ```bash -runx policy lint fixtures/operational-policy/nitrosend-like.json --json +runx policy lint fixtures/operational-policy/provider-like.json --json ``` `runx policy inspect` returns the same redacted readback shape for admin diff --git a/docs/issue-to-pr.md b/docs/issue-to-pr.md index b340e0ef4..6e147814f 100644 --- a/docs/issue-to-pr.md +++ b/docs/issue-to-pr.md @@ -47,10 +47,10 @@ Consuming repos own product policy: - whether GitHub Projects, labels, or milestones are used - deployment and live bot credentials -That split keeps `issue-to-pr` reusable. A service repo can normalize Slack or -Sentry into a `runx.thread.v1` source and a redacted -artifact refs and verification evidence, but runx core should not know that Nitrosend uses a -particular channel, label, Sentry project, or owner map. +That split keeps `issue-to-pr` reusable. A service repo can normalize Slack, +Sentry, GitHub, support, or local sources into a `runx.thread.v1` source and a +redacted artifact bundle with verification evidence, but runx core should not +know the consuming product's channel, label, project, or owner map. For Slack/Sentry/GitHub command entrypoints, adapters should normalize source commands locally into the shared source-event and operational-policy packets. diff --git a/docs/operator-console.md b/docs/operator-console.md index 1324828ba..671f8867d 100644 --- a/docs/operator-console.md +++ b/docs/operator-console.md @@ -1,8 +1,8 @@ # Operator Console -The operator console is the manager surface for a runx tenant. It is not a -second control plane. It is a projection plus an action catalog over the same -governed lanes an agent can use. +The operator console is the manager surface for a project, workspace, product, +or account. It is not a second control plane. It is a projection plus an action +catalog over the same governed lanes an agent can use. See [Operator Skills](./operator-skills.md) for the reusable skill boundary: operator skills reason, gate, route, and verify; the CLI, hosted API, workflow, @@ -11,7 +11,7 @@ or provider tool remains the execution interface. ## Shape ```text -tenant projections -> runx-operator -> governed action lane -> receipt -> projection +state projections -> ops-desk -> governed action lane -> receipt -> projection ``` The dashboard shows state. The agent explains and routes action. The runtime @@ -30,15 +30,16 @@ The console may show: The console must not add bespoke mutation routes for convenience. A dashboard button maps to a governed lane such as `send-as`, `ledger`, `refund`, -`messageboard`, `nitrosend`, `least-privilege-auditor`, or a tenant skill. -If the lane ultimately runs a CLI command or GitHub workflow, the dashboard and -agent both reference that existing interface. They do not duplicate its logic in -the UI or in skill prose. +`messageboard`, `provider.send`, `least-privilege-auditor`, or a product skill. +If the lane ultimately runs a CLI command, provider adapter, or repository +workflow, the dashboard and agent both reference that existing interface. They +do not duplicate its logic in the UI or in skill prose. ## Agent Contract -Use `runx-operator` when an agent is asked to manage a tenant. It reads the same -projection the UI shows and emits `runx.operator_packet.v1`: +Use `ops-desk` when an agent is asked to manage a project, workspace, product, +or account. It reads the same projection the UI shows and emits +`runx.ops_desk.packet.v1`: - findings grounded in evidence; - proposed governed lanes; @@ -47,7 +48,7 @@ projection the UI shows and emits `runx.operator_packet.v1`: - receipt/effect/readback expectations. The packet is a plan/proposal surface. Consequential work still executes through -the named lane and seals its own receipt. `runx-operator` may name the command, +the named lane and seals its own receipt. `ops-desk` may name the command, workflow, hosted endpoint, or skill runner to use, but it does not implement those operations itself. @@ -60,9 +61,9 @@ those operations itself. credential changes, deploys, and destructive actions: explicit approval. - Post-action success: receipt/effect/readback required. -## Tenant Policy +## Product Policy -Product-specific operator skills should provide tenant policy and vocabulary. +Product-specific operator skills should provide product policy and vocabulary. They should not fork the dashboard model or copy private product behavior into OSS skills. The core loop stays: @@ -70,7 +71,7 @@ OSS skills. The core loop stays: snapshot -> findings -> proposals -> approval -> governed lane -> receipt ``` -Project profiles may describe tenant topology, existing workflows, and +Project profiles may describe product topology, existing workflows, and verification URLs. They are not alternate execution engines. If a profile needs a behavior the CLI or hosted API cannot perform cleanly, fix that underlying interface instead of teaching an operator skill a private workaround. diff --git a/docs/operator-skills.md b/docs/operator-skills.md index 562844ee6..582c1e17f 100644 --- a/docs/operator-skills.md +++ b/docs/operator-skills.md @@ -1,9 +1,10 @@ # Operator Skills Operator skills are the agent-facing control layer for running a project, -tenant, or product through runx. They are not a second CLI and not a second -backend. They turn evidence into a bounded plan, name the existing governed lane -that should execute, require the right approval, and verify the result. +workspace, product, or account through runx. They are not a second CLI and not a +second backend. They turn evidence into a bounded plan, name the existing +governed lane that should execute, require the right approval, and verify the +result. ## Boundary @@ -36,8 +37,8 @@ A project operator skill uses runx the right way: - The receipt seals the domain act: target, authority, decision, reason, and effect. -Project-owned operator skills should copy that shape. Keep tenant vocabulary and -policy in the tenant skill or project profile. Keep OSS skills generic and +Project-owned operator skills should copy that shape. Keep product vocabulary +and policy in the project skill or project profile. Keep OSS skills generic and consume them from the project skill. ## Project Profiles diff --git a/docs/reference.md b/docs/reference.md index a13f14181..00bc8769f 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -295,7 +295,7 @@ The official catalog is explicit about why each package is public: - canonical governed skills: `charge`, `dispute-respond`, `evolve`, `improve-skill`, `least-privilege-auditor`, `overlay-generator`, - `policy-author`, `receipt-auditor`, `refund`, `runx-operator`, `send-as`, `spend`, + `policy-author`, `receipt-auditor`, `refund`, `ops-desk`, `send-as`, `spend`, `weather-forecast` - branded provider skills: `nitrosend`, `nws-weather-forecast`, `stripe-pay`, `x402-pay` @@ -313,7 +313,8 @@ the current runx catalog, surface maintainer decisions cleanly, and avoid builder residue or placeholder targets. See `docs/operator-console.md` for the manager-dashboard model that lets agents -operate tenants through the same governed lanes as the UI. +operate projects, workspaces, products, or accounts through the same governed +lanes as the UI. Each ships as a portable `SKILL.md` plus a colocated execution profile at `skills//X.yaml` when it exposes deterministic runners or inline harness diff --git a/docs/thread-story-contract.md b/docs/thread-story-contract.md index 0b005a1f1..0cbaca03d 100644 --- a/docs/thread-story-contract.md +++ b/docs/thread-story-contract.md @@ -166,4 +166,5 @@ reviewer-safe while preserving artifact refs for reconstruction. - This contract does not decide whether an issue deserves a PR. - This contract does not merge PRs. - This contract does not replace receipts, ledgers, or scafld status. -- This contract does not encode Nitrosend, Aster, or runx.ai hosted policy. +- This contract does not encode consuming-product, runner-provider, or hosted + deployment policy. diff --git a/fixtures/contracts/operational-proposal/invalid-product-specific-field.json b/fixtures/contracts/operational-proposal/invalid-product-specific-field.json index 61b373de0..b4264ceba 100644 --- a/fixtures/contracts/operational-proposal/invalid-product-specific-field.json +++ b/fixtures/contracts/operational-proposal/invalid-product-specific-field.json @@ -1 +1 @@ -{"description":"Invalid operational proposal fixture with product-specific public fields.","expected":{"authority":{"final_decision_authority_granted":false,"mutation_authority_granted":false,"proposal_only":true,"publication_authority_granted":false},"confidence":0.8,"decision_summary":"Product-specific public fields must fail.","hydrated_context_ref":{"type":"artifact","uri":"runx:artifact:hydrated_context_invalid"},"idempotency":{"fingerprint":"sha256:invalid-product-field","key":"operational-proposal:invalid:product-field"},"nitrosend_owner":"Kam","owner_route_id":"api-owner","proposal_id":"proposal_invalid_product_field","proposal_kind":"escalation","public_summary":"Invalid proposal with product-specific field.","rationale":"Public contracts use abstract owner routes, not product-specific owner fields.","recommended_actions":[{"action_intent":"tracking-to-change","mutating":true,"summary":"Build a fix."}],"redaction_status":"redacted","schema":"runx.operational_proposal.v1","source_event_id":"source_event_invalid","source_ref":{"locator":"thread/invalid","provider":"generic","type":"provider_thread","uri":"provider://source/thread/invalid"}},"fixture_kind":"operational_proposal_invalid","name":"invalid-product-specific-field","scope":"operational-proposal"} +{"description":"Invalid operational proposal fixture with product-specific public fields.","expected":{"authority":{"final_decision_authority_granted":false,"mutation_authority_granted":false,"proposal_only":true,"publication_authority_granted":false},"confidence":0.8,"decision_summary":"Product-specific public fields must fail.","hydrated_context_ref":{"type":"artifact","uri":"runx:artifact:hydrated_context_invalid"},"idempotency":{"fingerprint":"sha256:invalid-product-field","key":"operational-proposal:invalid:product-field"},"product_owner":"Kam","owner_route_id":"api-owner","proposal_id":"proposal_invalid_product_field","proposal_kind":"escalation","public_summary":"Invalid proposal with product-specific field.","rationale":"Public contracts use abstract owner routes, not product-specific owner fields.","recommended_actions":[{"action_intent":"tracking-to-change","mutating":true,"summary":"Build a fix."}],"redaction_status":"redacted","schema":"runx.operational_proposal.v1","source_event_id":"source_event_invalid","source_ref":{"locator":"thread/invalid","provider":"generic","type":"provider_thread","uri":"provider://source/thread/invalid"}},"fixture_kind":"operational_proposal_invalid","name":"invalid-product-specific-field","scope":"operational-proposal"} diff --git a/fixtures/external/example/issue-intake/api-source-thread.json b/fixtures/external/example/issue-intake/api-source-thread.json new file mode 100644 index 000000000..8d9417100 --- /dev/null +++ b/fixtures/external/example/issue-intake/api-source-thread.json @@ -0,0 +1,28 @@ +{ + "schema": "runx.external_dogfood_fixture.v1", + "fixture_id": "example-api-source-thread", + "description": "Sanitized example issue-intake fixture that routes a Slack source thread to the example/api target without live replay.", + "source": { + "source_id": "bugs-fixes", + "provider": "slack", + "locator": "slack://example/C0APFMY0V8Q", + "thread_locator": "slack://example/C0APFMY0V8Q/1778834840.485629", + "thread_ts": "1778834840.485629", + "issue_url": "https://github.com/example/project/issues/482" + }, + "signal": { + "fingerprint": "sha256:example-source-482", + "title": "API webhook retries fail when metadata is missing", + "summary": "A sanitized source thread reports that example/api retries fail without metadata propagation." + }, + "target": { + "repo": "example/api", + "action": "issue-to-pr", + "runner_id": "local-review" + }, + "policy_fixture": "fixtures/operational-policy/provider-like.json", + "runtime_fixtures": [ + "fixtures/runtime/skills/issue-intake/cases/bounded-docs-fix.yaml", + "fixtures/runtime/skills/issue-to-pr/cases/issue-to-pr-reaches-fix-boundary.yaml" + ] +} diff --git a/fixtures/external/nitrosend/issue-intake/api-source-thread.json b/fixtures/external/nitrosend/issue-intake/api-source-thread.json deleted file mode 100644 index df26f7a8d..000000000 --- a/fixtures/external/nitrosend/issue-intake/api-source-thread.json +++ /dev/null @@ -1,28 +0,0 @@ -{ - "schema": "runx.external_dogfood_fixture.v1", - "fixture_id": "nitrosend-api-source-thread", - "description": "Sanitized Nitrosend issue-intake fixture that routes a Slack source thread to the nitrosend/api target without live replay.", - "source": { - "source_id": "bugs-fixes", - "provider": "slack", - "locator": "slack://nitrosend/C0APFMY0V8Q", - "thread_locator": "slack://nitrosend/C0APFMY0V8Q/1778834840.485629", - "thread_ts": "1778834840.485629", - "issue_url": "https://github.com/nitrosend/nitrosend/issues/482" - }, - "signal": { - "fingerprint": "sha256:nitrosend-source-482", - "title": "API webhook retries fail when metadata is missing", - "summary": "A sanitized source thread reports that nitrosend/api retries fail without metadata propagation." - }, - "target": { - "repo": "nitrosend/api", - "action": "issue-to-pr", - "runner_id": "aster-production" - }, - "policy_fixture": "fixtures/operational-policy/nitrosend-like.json", - "runtime_fixtures": [ - "fixtures/runtime/skills/issue-intake/cases/bounded-docs-fix.yaml", - "fixtures/runtime/skills/issue-to-pr/cases/issue-to-pr-reaches-fix-boundary.yaml" - ] -} diff --git a/fixtures/operational-policy/nitrosend-like.json b/fixtures/operational-policy/provider-like.json similarity index 83% rename from fixtures/operational-policy/nitrosend-like.json rename to fixtures/operational-policy/provider-like.json index 9f86a6d5a..a424171d5 100644 --- a/fixtures/operational-policy/nitrosend-like.json +++ b/fixtures/operational-policy/provider-like.json @@ -1,14 +1,14 @@ { "schema": "runx.operational_policy.v1", "schema_version": "runx.operational_policy.v1", - "policy_id": "nitrosend-issue-flow", + "policy_id": "provider-issue-flow", "created_at": "2026-05-19T00:00:00.000Z", "sources": [ { "source_id": "bugs-fixes", "provider": "slack", "allowed_locators": [ - "slack://nitrosend/C0APFMY0V8Q" + "slack://example/C0APFMY0V8Q" ], "allowed_actions": [ "issue-intake", @@ -26,7 +26,7 @@ "source_id": "sentry-alerts", "provider": "sentry", "allowed_locators": [ - "sentry://nitrosend/production" + "sentry://example/production" ], "allowed_actions": [ "issue-intake", @@ -49,8 +49,8 @@ ], "runners": [ { - "runner_id": "aster-production", - "kind": "aster", + "runner_id": "local-review", + "kind": "local", "state": "available", "allowed_actions": [ "issue-intake", @@ -60,9 +60,9 @@ "pr-fix-up" ], "target_repos": [ - "nitrosend/nitrosend", - "nitrosend/api", - "nitrosend/app" + "example/project", + "example/api", + "example/app" ], "scafld_required": true } @@ -71,25 +71,25 @@ { "route_id": "product-surface", "owners": [ - "Kam" + "Ops" ], "target_repos": [ - "nitrosend/nitrosend", - "nitrosend/api", - "nitrosend/app" + "example/project", + "example/api", + "example/app" ], "labels": [ "runx", "bug" ], - "project": "Nitrosend Engineering" + "project": "Example Engineering" } ], "targets": [ { - "repo": "nitrosend/nitrosend", + "repo": "example/project", "runner_ids": [ - "aster-production" + "local-review" ], "allowed_actions": [ "issue-intake", @@ -101,9 +101,9 @@ "base_branch": "main" }, { - "repo": "nitrosend/api", + "repo": "example/api", "runner_ids": [ - "aster-production" + "local-review" ], "allowed_actions": [ "issue-intake", @@ -115,9 +115,9 @@ "base_branch": "main" }, { - "repo": "nitrosend/app", + "repo": "example/app", "runner_ids": [ - "aster-production" + "local-review" ], "allowed_actions": [ "issue-intake", diff --git a/fixtures/parser/runner-manifests/harness-basic.json b/fixtures/parser/runner-manifests/harness-basic.json index f8a9b09f8..4383a2b38 100644 --- a/fixtures/parser/runner-manifests/harness-basic.json +++ b/fixtures/parser/runner-manifests/harness-basic.json @@ -1 +1 @@ -{"expected":{"validated":{"harness":{"cases":[{"caller":{"approvals":{"mutate":true}},"env":{},"expect":{"receipt":{"source_type":"agent-task","status":"sealed"},"status":"sealed"},"inputs":{"harness_context":{"artifact_refs":[{"type":"packet","uri":"artifact://issue-intake"}],"evidence_refs":[{"type":"github_issue","uri":"gh://nitrosend/nitrosend/issues/1"}],"receipt_ref":"runx:receipt:1"}},"name":"issue thread","runner":"intake"}]},"raw":{"document":{"harness":{"cases":[{"caller":{"approvals":{"mutate":true}},"expect":{"receipt":{"source_type":"agent-task","status":"sealed"},"status":"sealed"},"inputs":{"harness_context":{"artifact_refs":[{"type":"packet","uri":"artifact://issue-intake"}],"evidence_refs":[{"type":"github_issue","uri":"gh://nitrosend/nitrosend/issues/1"}],"receipt_ref":"runx:receipt:1"}},"name":"issue thread","runner":"intake"}]},"runners":{"intake":{"runx":{"post_run":{"reflect":"auto"}},"source":{"agent":"codex","outputs":{"packet":"issue_intake_packet"},"task":"triage","type":"agent-task"}}},"skill":"issue-intake"},"raw":"skill: issue-intake\nrunners:\n intake:\n source:\n type: agent-task\n agent: codex\n task: triage\n outputs:\n packet: issue_intake_packet\n runx:\n post_run:\n reflect: auto\nharness:\n cases:\n - name: issue thread\n runner: intake\n inputs:\n harness_context:\n receipt_ref: runx:receipt:1\n evidence_refs:\n - type: github_issue\n uri: gh://nitrosend/nitrosend/issues/1\n artifact_refs:\n - type: packet\n uri: artifact://issue-intake\n caller:\n approvals:\n mutate: true\n expect:\n status: sealed\n receipt:\n status: sealed\n source_type: agent-task\n"},"runners":{"intake":{"default":false,"inputs":{},"name":"intake","raw":{"runx":{"post_run":{"reflect":"auto"}},"source":{"agent":"codex","outputs":{"packet":"issue_intake_packet"},"task":"triage","type":"agent-task"}},"runx":{"post_run":{"reflect":"auto"}},"source":{"agent":"codex","args":[],"outputs":{"packet":"issue_intake_packet"},"raw":{"agent":"codex","outputs":{"packet":"issue_intake_packet"},"task":"triage","type":"agent-task"},"task":"triage","type":"agent-task"}}},"skill":"issue-intake"}},"input":{"yaml":"skill: issue-intake\nrunners:\n intake:\n source:\n type: agent-task\n agent: codex\n task: triage\n outputs:\n packet: issue_intake_packet\n runx:\n post_run:\n reflect: auto\nharness:\n cases:\n - name: issue thread\n runner: intake\n inputs:\n harness_context:\n receipt_ref: runx:receipt:1\n evidence_refs:\n - type: github_issue\n uri: gh://nitrosend/nitrosend/issues/1\n artifact_refs:\n - type: packet\n uri: artifact://issue-intake\n caller:\n approvals:\n mutate: true\n expect:\n status: sealed\n receipt:\n status: sealed\n source_type: agent-task\n"},"name":"harness-basic","scope":"runner-manifests"} +{"expected":{"validated":{"harness":{"cases":[{"caller":{"approvals":{"mutate":true}},"env":{},"expect":{"receipt":{"source_type":"agent-task","status":"sealed"},"status":"sealed"},"inputs":{"harness_context":{"artifact_refs":[{"type":"packet","uri":"artifact://issue-intake"}],"evidence_refs":[{"type":"github_issue","uri":"gh://example/project/issues/1"}],"receipt_ref":"runx:receipt:1"}},"name":"issue thread","runner":"intake"}]},"raw":{"document":{"harness":{"cases":[{"caller":{"approvals":{"mutate":true}},"expect":{"receipt":{"source_type":"agent-task","status":"sealed"},"status":"sealed"},"inputs":{"harness_context":{"artifact_refs":[{"type":"packet","uri":"artifact://issue-intake"}],"evidence_refs":[{"type":"github_issue","uri":"gh://example/project/issues/1"}],"receipt_ref":"runx:receipt:1"}},"name":"issue thread","runner":"intake"}]},"runners":{"intake":{"runx":{"post_run":{"reflect":"auto"}},"source":{"agent":"codex","outputs":{"packet":"issue_intake_packet"},"task":"triage","type":"agent-task"}}},"skill":"issue-intake"},"raw":"skill: issue-intake\nrunners:\n intake:\n source:\n type: agent-task\n agent: codex\n task: triage\n outputs:\n packet: issue_intake_packet\n runx:\n post_run:\n reflect: auto\nharness:\n cases:\n - name: issue thread\n runner: intake\n inputs:\n harness_context:\n receipt_ref: runx:receipt:1\n evidence_refs:\n - type: github_issue\n uri: gh://example/project/issues/1\n artifact_refs:\n - type: packet\n uri: artifact://issue-intake\n caller:\n approvals:\n mutate: true\n expect:\n status: sealed\n receipt:\n status: sealed\n source_type: agent-task\n"},"runners":{"intake":{"default":false,"inputs":{},"name":"intake","raw":{"runx":{"post_run":{"reflect":"auto"}},"source":{"agent":"codex","outputs":{"packet":"issue_intake_packet"},"task":"triage","type":"agent-task"}},"runx":{"post_run":{"reflect":"auto"}},"source":{"agent":"codex","args":[],"outputs":{"packet":"issue_intake_packet"},"raw":{"agent":"codex","outputs":{"packet":"issue_intake_packet"},"task":"triage","type":"agent-task"},"task":"triage","type":"agent-task"}}},"skill":"issue-intake"}},"input":{"yaml":"skill: issue-intake\nrunners:\n intake:\n source:\n type: agent-task\n agent: codex\n task: triage\n outputs:\n packet: issue_intake_packet\n runx:\n post_run:\n reflect: auto\nharness:\n cases:\n - name: issue thread\n runner: intake\n inputs:\n harness_context:\n receipt_ref: runx:receipt:1\n evidence_refs:\n - type: github_issue\n uri: gh://example/project/issues/1\n artifact_refs:\n - type: packet\n uri: artifact://issue-intake\n caller:\n approvals:\n mutate: true\n expect:\n status: sealed\n receipt:\n status: sealed\n source_type: agent-task\n"},"name":"harness-basic","scope":"runner-manifests"} diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index 25c504ddc..578f82565 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -8,8 +8,8 @@ }, { "skill_id": "runx/business-ops", - "version": "sha-ca97efa3deb0", - "digest": "27c05e8e30d8e925c93ecd51e535add38a4ceeabbfc76acf73bb0a578fee3e11", + "version": "sha-542469f72fa2", + "digest": "f319e45b875aab442ead32ecddd194c715bfd585f1504d9e9c3d7bcbb914e342", "catalog_visibility": "public", "catalog_role": "canonical" }, @@ -36,9 +36,9 @@ }, { "skill_id": "runx/dependency-cve-audit", - "version": "sha-e9e461e41ea3", + "version": "sha-016cc407efa2", "digest": "c19ec9fdeb088daab950b7c2e1f3757880de9702e31e40b57e2f65c0c4033348", - "catalog_visibility": "public", + "catalog_visibility": "internal", "catalog_role": "canonical" }, { @@ -85,15 +85,15 @@ }, { "skill_id": "runx/github-sync", - "version": "sha-67a1011141aa", + "version": "sha-703346713bf3", "digest": "83b0f4cd98cf23ff81ec71727543e6d811e75aa970cf957bec4267575a16efcc", "catalog_visibility": "public", - "catalog_role": "canonical" + "catalog_role": "branded" }, { "skill_id": "runx/governed-outbound", - "version": "sha-c15ec36034f2", - "digest": "bb01d4097b48693f68b7a96810ee685828d17e81ec4f55fda2ffee981af61604", + "version": "sha-c93e1c732950", + "digest": "e177cd002efb896e0bba7a6352f19f4d1ec575db1ef548849244ea42725356a6", "catalog_visibility": "public", "catalog_role": "context" }, @@ -148,14 +148,14 @@ }, { "skill_id": "runx/lead-router", - "version": "sha-e488a0d01d46", - "digest": "cc13bfdf7d586ecd9117c6e33efd0f897134d3950cbf695e89290cf7a3523527", + "version": "sha-4345afde1d16", + "digest": "4a27b60d2cdd54a5f02163473f756185f9fa5cb57e32c1f59f65fe3472ed3202", "catalog_visibility": "public", "catalog_role": "context" }, { "skill_id": "runx/least-privilege-auditor", - "version": "sha-e5c3622556d9", + "version": "sha-a31f1c09aa5c", "digest": "244df5dd8eed7900d1987c76060893d3c9cd65f420c5b8c177b19fa4e0b81ac2", "catalog_visibility": "public", "catalog_role": "canonical" @@ -251,6 +251,13 @@ "catalog_visibility": "internal", "catalog_role": "branded" }, + { + "skill_id": "runx/ops-desk", + "version": "sha-57c1b0df97f6", + "digest": "d468d7984b8a7736cb760373c5348007eed1f387567814f39ac82eb39e58150a", + "catalog_visibility": "public", + "catalog_role": "canonical" + }, { "skill_id": "runx/overlay-generator", "version": "sha-b5dc11a7088d", @@ -342,13 +349,6 @@ "catalog_visibility": "public", "catalog_role": "context" }, - { - "skill_id": "runx/runx-operator", - "version": "sha-0fed07a0dc00", - "digest": "9de1d9dffb46b6bb14872b66738d5e9b26f271c6f11595c6a685d4c30e539176", - "catalog_visibility": "public", - "catalog_role": "canonical" - }, { "skill_id": "runx/sandbox-harden", "version": "sha-e5f346fbac0f", @@ -358,8 +358,8 @@ }, { "skill_id": "runx/send-as", - "version": "sha-151a237afe0b", - "digest": "b5c9c3cbd9ecb737cc8b40228602e71f5aef1fab3ca6ba85bd0851bb983a5646", + "version": "sha-ab821b54b4e6", + "digest": "ee71759e8099dba9a4925a81b2da69c1d83e73a6fd57b3e21839a6bb637e9ca1", "catalog_visibility": "public", "catalog_role": "canonical" }, @@ -393,10 +393,10 @@ }, { "skill_id": "runx/slack-notify", - "version": "sha-3282402f7a8b", + "version": "sha-33d69b8fb325", "digest": "9e0abd47c54455add3c715e18c371c427e0bbb0d617ed0212f60d766f62c2856", "catalog_visibility": "public", - "catalog_role": "canonical" + "catalog_role": "branded" }, { "skill_id": "runx/sourcey", @@ -442,16 +442,16 @@ }, { "skill_id": "runx/structured-extraction", - "version": "sha-f14902374e11", + "version": "sha-a826aca27a7a", "digest": "ebe37921d3b9cb63aa1ca5232a8075607d3b4ad541af4c1bc901ace749ea404f", - "catalog_visibility": "public", + "catalog_visibility": "internal", "catalog_role": "canonical" }, { "skill_id": "runx/support-triage-reply", - "version": "sha-fce24eb780f9", - "digest": "94beeed742142c6a236eb0ae1db5644d3f868362030089332c6ce3b40b1f86bb", - "catalog_visibility": "public", + "version": "sha-a605f6b30db4", + "digest": "e945d181db20fbb0f2432ad7fd5b5fbc438deb1cdbe4eacad169641e24670416", + "catalog_visibility": "internal", "catalog_role": "canonical" }, { @@ -491,7 +491,7 @@ }, { "skill_id": "runx/work-plan", - "version": "sha-d2b3abc77e97", + "version": "sha-e6dd3bc7d087", "digest": "ba007b997503258ca52e6a067e0dd6ed12ec7250add5dae35e048663b2a502a2", "catalog_visibility": "public", "catalog_role": "context" diff --git a/packages/cli/src/skill-refs.test.ts b/packages/cli/src/skill-refs.test.ts index ca90aa16e..5dd7dbef5 100644 --- a/packages/cli/src/skill-refs.test.ts +++ b/packages/cli/src/skill-refs.test.ts @@ -15,7 +15,6 @@ const publicOfficialCatalogSkills = [ "charge", "content-pipeline", "deep-research-brief", - "dependency-cve-audit", "design-skill", "dispute-respond", "draft-content", @@ -52,7 +51,7 @@ const publicOfficialCatalogSkills = [ "review-receipt", "review-skill", "run-history-analyst", - "runx-operator", + "ops-desk", "sandbox-harden", "send-as", "settle-invoice", @@ -64,8 +63,6 @@ const publicOfficialCatalogSkills = [ "spend", "sql-analyst", "stripe-pay", - "structured-extraction", - "support-triage-reply", "taste-profile", "vault-unseal", "vuln-scan", diff --git a/packages/contracts/src/index.test.ts b/packages/contracts/src/index.test.ts index da01a822e..9a66d8d00 100644 --- a/packages/contracts/src/index.test.ts +++ b/packages/contracts/src/index.test.ts @@ -468,8 +468,8 @@ describe("@runxhq/contracts", () => { }, }], runners: [{ - runner_id: "aster-primary", - kind: "aster", + runner_id: "local-review", + kind: "local", state: "available", allowed_actions: ["issue-to-pr", "merge-assist"], target_repos: ["example/api"], @@ -477,12 +477,12 @@ describe("@runxhq/contracts", () => { }], owner_routes: [{ route_id: "api-owner", - owners: ["Kam"], + owners: ["Ops"], target_repos: ["example/api"], }], targets: [{ repo: "example/api", - runner_ids: ["aster-primary"], + runner_ids: ["local-review"], allowed_actions: ["issue-to-pr", "merge-assist"], default_owner_route: "api-owner", scafld_required: true, diff --git a/packages/contracts/src/schemas/operational-policy.test.ts b/packages/contracts/src/schemas/operational-policy.test.ts index c86b00855..82336f2b9 100644 --- a/packages/contracts/src/schemas/operational-policy.test.ts +++ b/packages/contracts/src/schemas/operational-policy.test.ts @@ -19,7 +19,7 @@ const fixtureRoot = new URL("../../../../fixtures/operational-policy/", import.m const validPolicy: OperationalPolicyContract = { schema: "runx.operational_policy.v1", schema_version: operationalPolicySchemaVersion, - policy_id: "nitrosend-dev-flow", + policy_id: "provider-dev-flow", created_at: "2026-05-19T02:00:00Z", sources: [ { @@ -37,7 +37,7 @@ const validPolicy: OperationalPolicyContract = { { source_id: "sentry-production", provider: "sentry", - allowed_locators: ["sentry://nitrosend/production"], + allowed_locators: ["sentry://example/production"], allowed_actions: ["issue-intake", "issue-to-pr", "manual-review"], source_thread: { required: true, @@ -55,41 +55,41 @@ const validPolicy: OperationalPolicyContract = { ], runners: [ { - runner_id: "aster-primary", - kind: "aster", + runner_id: "local-review", + kind: "local", state: "available", allowed_actions: ["issue-to-pr", "pr-review", "pr-fix-up", "merge-assist"], - target_repos: ["nitrosend/api", "nitrosend/app"], + target_repos: ["example/api", "example/app"], scafld_required: true, }, ], owner_routes: [ { route_id: "api-kam", - owners: ["Kam"], - target_repos: ["nitrosend/api"], + owners: ["Ops"], + target_repos: ["example/api"], labels: ["runx", "api"], - project: "Nitrosend Engineering", + project: "Example Engineering", }, { route_id: "app-chong", - owners: ["Chong"], - target_repos: ["nitrosend/app"], + owners: ["Design"], + target_repos: ["example/app"], labels: ["runx", "app"], }, ], targets: [ { - repo: "nitrosend/api", - runner_ids: ["aster-primary"], + repo: "example/api", + runner_ids: ["local-review"], allowed_actions: ["issue-to-pr", "pr-review", "pr-fix-up", "merge-assist"], default_owner_route: "api-kam", scafld_required: true, base_branch: "main", }, { - repo: "nitrosend/app", - runner_ids: ["aster-primary"], + repo: "example/app", + runner_ids: ["local-review"], allowed_actions: ["issue-to-pr", "pr-review", "pr-fix-up", "merge-assist"], default_owner_route: "app-chong", scafld_required: true, @@ -118,7 +118,7 @@ describe("operational-policy schema", () => { it("accepts a valid multi-source, multi-target policy", () => { expect(contractSchemaMatches(operationalPolicySchema, validPolicy)).toBe(true); expect(validateOperationalPolicyContract(validPolicy)).toMatchObject({ - policy_id: "nitrosend-dev-flow", + policy_id: "provider-dev-flow", permissions: { auto_merge: false, require_human_merge_gate: true, @@ -126,12 +126,12 @@ describe("operational-policy schema", () => { }); expect(lintOperationalPolicyContract(validPolicy)).toEqual([]); expect(validateOperationalPolicySemantics(validPolicy)).toMatchObject({ - policy_id: "nitrosend-dev-flow", + policy_id: "provider-dev-flow", }); }); it.each([ - "nitrosend-like.json", + "provider-like.json", "minimal-single-repo.json", ])("accepts positive fixture %s", (fixtureName) => { const policy = readPolicyFixture(fixtureName); @@ -200,7 +200,7 @@ describe("operational-policy schema", () => { ...validPolicy, targets: [{ ...validPolicy.targets[0], - repo: "nitrosend", + repo: "example", }], })).toBe(false); }); @@ -281,7 +281,7 @@ describe("operational-policy schema", () => { it("projects an admin-safe readback without raw source locators", () => { expect(projectOperationalPolicyReadback(validPolicy)).toMatchObject({ - policy_id: "nitrosend-dev-flow", + policy_id: "provider-dev-flow", valid: true, findings: [], sources: [ @@ -302,13 +302,13 @@ describe("operational-policy schema", () => { ], targets: [ { - repo: "nitrosend/api", + repo: "example/api", default_owner_route: "api-kam", owner_count: 1, available_runner_count: 1, }, { - repo: "nitrosend/app", + repo: "example/app", default_owner_route: "app-chong", owner_count: 1, available_runner_count: 1, @@ -322,19 +322,19 @@ describe("operational-policy schema", () => { it("admits a concrete request against target, source, runner, dedupe, and outcome policy", () => { expect(admitOperationalPolicyRequest(validPolicy, { source_id: "slack-bugs", - target_repo: "nitrosend/api", + target_repo: "example/api", action: "issue-to-pr", - runner_id: "aster-primary", + runner_id: "local-review", source_thread_locator: "slack://team/T123/channel/CBUGS/thread/168", })).toMatchObject({ status: "allow", findings: [], - policy_id: "nitrosend-dev-flow", + policy_id: "provider-dev-flow", source_id: "slack-bugs", - target_repo: "nitrosend/api", - runner_id: "aster-primary", + target_repo: "example/api", + runner_id: "local-review", owner_route_id: "api-kam", - owners: ["Kam"], + owners: ["Ops"], dedupe_strategy: "source_fingerprint", outcome_close_mode: "when_verified", source_thread_required: true, @@ -346,7 +346,7 @@ describe("operational-policy schema", () => { it("denies request-time admission before unknown target or runner mutation boundaries", () => { const admission = admitOperationalPolicyRequest(validPolicy, { source_id: "slack-bugs", - target_repo: "nitrosend/unknown", + target_repo: "example/unknown", action: "issue-to-pr", runner_id: "missing-runner", source_thread_locator: "slack://team/T123/channel/CBUGS/thread/168", @@ -364,9 +364,9 @@ describe("operational-policy schema", () => { it("denies PR-producing admission without recoverable source-thread routing", () => { const admission = admitOperationalPolicyRequest(validPolicy, { source_id: "slack-bugs", - target_repo: "nitrosend/api", + target_repo: "example/api", action: "issue-to-pr", - runner_id: "aster-primary", + runner_id: "local-review", }); expect(admission).toMatchObject({ @@ -386,9 +386,9 @@ describe("operational-policy schema", () => { }], }, { source_id: "slack-bugs", - target_repo: "nitrosend/api", + target_repo: "example/api", action: "issue-to-pr", - runner_id: "aster-primary", + runner_id: "local-review", source_thread_locator: "slack://team/T123/channel/CBUGS/thread/168", }); diff --git a/skills/business-ops/SKILL.md b/skills/business-ops/SKILL.md index e91831267..f8269412f 100644 --- a/skills/business-ops/SKILL.md +++ b/skills/business-ops/SKILL.md @@ -1,108 +1,182 @@ --- name: business-ops -description: Basic business operations graph; route one signal through governed docs, release, issue, send, spend, and audit lanes. +description: "Route one business signal through a replayable governed ops graph: classify, docs, release, work, outreach, spend, and proof, with consequential actions stopping at the right gate." runx: category: ops --- # Business Ops -Run one business signal through a basic governed operations graph. +Turn one business signal into a replayable operations graph. -`business-ops` is intentionally small and deterministic. It does not call -private providers, mutate a project, send messages, or move money. It shows how -a single business signal can be classified, routed through bounded lanes, -stopped at approval where appropriate, and sealed as a graph receipt. +`business-ops` is the generic public example for how runx makes agentic +business work composable without giving the agent ambient authority. It is a +deterministic graph skeleton: it classifies one signal, fans it into bounded +lanes, records why each lane exists, names the real skill or provider lane that +would replace the fixture, and stops before any live send, spend, publish, +merge, deploy, or customer-visible action. -Real teams replace the fixture lane steps with their own skills, policies, -provider tools, approval gates, and verification checks. +This is not a provider integration and not an operator dashboard. It is the +small core shape that teams copy when they want one objective to fan out into a +chain of skills, then replay that chain with receipts. ## What this skill does -- Classifies a business signal into an operations route. -- Fans the signal out through representative governed lanes: documentation, - release preparation, issue-to-PR, outbound draft, spend quote, and receipt - audit. -- Marks which lanes are read-only, which require approval, and which should stop - before consequential authority such as send, spend, deploy, publish, or merge. -- Produces receipt-backed lane packets so the operator can see what was routed - and why. +- Classifies one business signal before doing work. +- Fans the signal through representative lanes: docs, release, issue/PR, + outreach planning, spend quoting, and proof audit. +- Produces structured lane packets with authority, gate, handoff, evidence, and + readback fields. +- Demonstrates the runx split between proposal work and consequential action: + drafts and plans can be produced, but sends, spend, merges, publishes, and + deploys require a separate approval and execution lane. +- Gives downstream agents a clear handoff target instead of vague prose. + +## What this skill deliberately does not do + +- It does not call private providers, mutate a repo, post to GitHub, send email, + schedule campaigns, move money, publish releases, or deploy services. +- It does not duplicate `ops-desk`, product operator skills, `send-as`, + vendor-specific provider skills, `release`, `issue-to-pr`, `spend`, or + receipt-audit skills. +- It does not turn "outbound marketing" into a hidden side effect. Outreach is + a plan lane here; real delivery routes to `send-as` and then a provider + adapter. Branded provider skills are concrete adapters, not branches in this + core graph. +- It does not treat the graph receipt as proof that an external provider action + happened. Provider actions need provider evidence and their own receipt. ## When to use this skill -- To demonstrate how runx models business operations as composable governed - lanes. +- To show how runx chains skills into replayable business operations. - To prototype a team-specific ops graph before wiring private provider tools. -- To explain how an agent can route work without gaining ambient authority. -- To smoke-test graph execution, child receipts, and approval boundaries with no - external account. +- To route a product signal without giving the agent blanket repo, email, + wallet, or deployment access. +- To explain why a governed workflow is more useful than a one-shot prompt: + the route, stops, handoffs, and readbacks are explicit and replayable. +- To smoke-test graph execution and child receipts with no external account. ## When not to use this skill -- To run a real production launch, incident, release, customer send, or spend - flow without replacing the fixture lanes. -- To claim that docs were written, a release was prepared, a PR was opened, a - customer was contacted, or money moved. -- To bypass approval gates. The send, spend, publish, deploy, and merge lanes - are represented as stops, not completed actions. -- To hide provider state, credentials, customer lists, or private project policy - in the signal. +- To run a production launch, incident, release, campaign, support reply, + payout, or spend flow as-is. Replace fixture lanes with real skills first. +- To approve a live send, spend, merge, publish, deploy, or customer-visible + action. +- To hide project policy, customer lists, credentials, wallet keys, provider + dumps, or private review context in the signal. +- To claim external work completed when only this fixture graph ran. -## Procedure +## Mental model -1. Receive one `signal` that names the business situation to triage. -2. Run the classify lane and choose representative governed lanes. -3. Project documentation, release, issue, send, spend, and audit lane packets. -4. Mark each lane with the decision and approval posture. -5. Seal the graph receipt with child receipts for each lane. -6. In a real project, replace fixture lanes with project-owned skills, provider - tools, policies, and readback checks. +```text +signal -> classify -> fanout lanes -> approval stops -> governed handoffs -> proof +``` -## Edge cases and stop conditions +The useful part is the chain. A single objective becomes several typed packets: +some read-only, some draft-only, some blocked until approval, and one proof lane +that states how success should be verified later. A human, agent, dashboard, or +CI loop can replay the same route and see the same stops. + +## How this maps to real runx work + +- **Docs and public proof** route to a docs skill such as `sourcey` or a + product-owned documentation lane. +- **Release preparation** routes to `release`, with publish held behind a + release approval. +- **Code work** routes to `issue-to-pr` or a project-owned implementation lane, + with merge held behind review. +- **Outreach and customer communication** route first to `send-as`, then to a + provider adapter that implements the send lane. Branded provider skills are + the right place for vendor-specific compose, test, review, schedule, or send + details. Broad outbound marketing should be its own skill or product broadcast + skill, not extra logic hidden in this graph. +- **Spend and payments** route to quote or payout skills with caps, recipient, + rail, and settlement proof separated from the planning lane. +- **Proof** routes to receipt/history/audit skills and provider readbacks. + +The fixture `ops-lane` step simply returns these packets without performing the +handoff. In a real project, replace each fixture lane with the named governed +skill runner or provider tool. -- Return `needs_input` when the signal is missing or too vague to route. -- Return `needs_more_evidence` when a real project graph lacks required project - context, provider readback, receipt refs, or policy. -- Return `needs_agent` when a lane requires human or model judgment that the - fixture cannot provide. -- Return `refused` for requests that try to bypass approval, hide consequential - side effects, or claim completed provider work without proof. -- Return `escalated` for legal, financial, security, customer-impacting, or - irreversible actions outside the supplied authority. +## Procedure -## Output schema +1. Receive one concise `signal`. +2. Optionally receive `operator_context` with project constraints, policy, or + the concrete business situation. +3. Run `classify` first. It decides which lanes are relevant and what authority + class each lane belongs to. +4. Fan out docs, release, issue, outreach, spend, and proof packets. +5. Mark each lane as read-only, draft-only, approval-required, or proof-only. +6. Name the exact downstream handoff that should replace the fixture in a real + workflow. +7. Seal the graph so the route itself is replayable. -The graph output contains: +## Edge cases and stop conditions -- `graph`: `business-ops` -- `graph_status`: graph completion status -- `steps`: ordered child step summaries with receipt ids -- `step_outputs`: lane packets keyed by step id +- **Missing signal:** return `needs_input`. There is no safe route. +- **Vague objective:** return a narrow classify packet and ask for the missing + product, audience, repo, release, amount, or provider context. +- **Live send without principal, audience, consent, digest, and approval:** stop + at the outreach lane and route to `send-as`. +- **Spend without amount, cap, recipient, rail, and approval:** stop at the + spend lane and route to a quote or payment skill. +- **Merge, publish, deploy, or destructive mutation without approval:** stop at + the relevant lane and name the missing gate. +- **Provider success without provider evidence:** do not mark complete. Route to + proof audit. +- **Secret or private data in the signal:** refuse to echo it into outputs; + require redacted context or a provider-side readback instead. -Each lane packet contains: +## Output schema -- `lane`: the lane name -- `signal`: the original business signal -- `decision`: route, prepare, draft, quote, verify, or a stop decision -- `summary`: what the lane would do -- `approval`: whether approval is required -- `next`: follow-up gate, command, or verification surface +The graph output contains child step receipts plus one `lane_packet` per lane: + +```yaml +lane_packet: + schema: runx.business_ops_lane.v1 + lane: string + signal: string + status: ready | awaiting_approval | needs_input | refused + decision: route | prepare | draft | quote | verify | stop + kind: router | docs | release | work | outreach | spend | proof + consequence: read_only | draft | live_mutation | public_send | money_movement | proof + summary: string + why: string + authority: + requested: [string] + provided: fixture_only + gate: + approval_required: boolean + approval_gate: string | null + stop_reason: string | null + handoff: + interface: skill | graph | cli | hosted_api | workflow | provider_tool + lane_ref: string + runner_ref: string | null + command_hint: string | null + evidence: + inputs_required: [string] + readbacks: [string] + receipt_refs: [string] + risks: [string] + next: [string] +``` ## Worked example -Input: - ```bash runx skill business-ops \ -i signal="launch readiness for API v2: docs, release, customer comms, and spend checks" \ --json ``` -The graph routes the signal through docs, release, issue, send, spend, and audit -lanes. Docs and release prepare bounded packets. Send and spend stop at approval -gates. Audit names the receipt/history checks that prove what happened. +The graph classifies the launch signal, prepares docs/release/work packets, +routes customer communication to an outreach plan, stops spend at a quote gate, +and names receipt/history checks that would prove later execution. No external +provider is called. ## Inputs -- `signal` (required): a concise business operations signal to classify and - route. +- `signal` (required): concise business operations signal to classify and route. +- `operator_context` (optional): product policy, project topology, audience + constraints, or known provider state. Context only, not authority. diff --git a/skills/business-ops/X.yaml b/skills/business-ops/X.yaml index 9a3e3ab4a..7a47a05ef 100644 --- a/skills/business-ops/X.yaml +++ b/skills/business-ops/X.yaml @@ -1,5 +1,5 @@ skill: business-ops -version: "0.1.0" +version: "0.1.1" catalog: kind: graph @@ -16,6 +16,10 @@ runners: type: string required: true description: Business signal to triage. + operator_context: + type: string + required: false + description: Optional product policy, topology, audience constraints, or provider state. Context only, not authority. graph: name: business-ops steps: @@ -24,33 +28,40 @@ runners: inputs: lane: classify signal: "$input.signal" + operator_context: "$input.operator_context" - id: docs skill: ./graph/ops-lane inputs: lane: sourcey signal: "$input.signal" + operator_context: "$input.operator_context" - id: release skill: ./graph/ops-lane inputs: lane: release.prepare signal: "$input.signal" + operator_context: "$input.operator_context" - id: issue skill: ./graph/ops-lane inputs: lane: issue-to-pr signal: "$input.signal" + operator_context: "$input.operator_context" - id: send skill: ./graph/ops-lane inputs: - lane: send-as.draft + lane: outreach.plan signal: "$input.signal" + operator_context: "$input.operator_context" - id: spend skill: ./graph/ops-lane inputs: lane: spend.quote signal: "$input.signal" + operator_context: "$input.operator_context" - id: audit skill: ./graph/ops-lane inputs: lane: receipt-audit signal: "$input.signal" + operator_context: "$input.operator_context" diff --git a/skills/business-ops/graph/ops-lane/SKILL.md b/skills/business-ops/graph/ops-lane/SKILL.md index 3d3ab3cea..b055559cf 100644 --- a/skills/business-ops/graph/ops-lane/SKILL.md +++ b/skills/business-ops/graph/ops-lane/SKILL.md @@ -19,6 +19,13 @@ inputs: type: string required: true description: Business signal being routed. + operator_context: + type: string + required: false + description: Optional product policy, topology, audience constraints, or provider state. Context only, not authority. --- Project one business-ops lane as a deterministic fixture packet. + +The output names the real downstream skill or provider lane that would replace +this fixture in production. It never performs the handoff itself. diff --git a/skills/business-ops/graph/ops-lane/X.yaml b/skills/business-ops/graph/ops-lane/X.yaml index c801d8ad6..11e751648 100644 --- a/skills/business-ops/graph/ops-lane/X.yaml +++ b/skills/business-ops/graph/ops-lane/X.yaml @@ -1,5 +1,5 @@ skill: ops-lane -version: "0.1.0" +version: "0.1.1" catalog: kind: skill @@ -25,3 +25,7 @@ runners: type: string required: true description: Business signal being routed. + operator_context: + type: string + required: false + description: Optional product policy, topology, audience constraints, or provider state. Context only, not authority. diff --git a/skills/business-ops/graph/ops-lane/run.mjs b/skills/business-ops/graph/ops-lane/run.mjs index 4dfe73a9c..e2f1b7d62 100644 --- a/skills/business-ops/graph/ops-lane/run.mjs +++ b/skills/business-ops/graph/ops-lane/run.mjs @@ -5,70 +5,253 @@ function readInputs() { return { lane: process.env.RUNX_INPUT_LANE ?? "", signal: process.env.RUNX_INPUT_SIGNAL ?? "", + operator_context: process.env.RUNX_INPUT_OPERATOR_CONTEXT ?? "", + }; +} + +function authority(scopes) { + return { + requested: scopes, + provided: "fixture_only", + }; +} + +function gate(approvalRequired, approvalGate, stopReason) { + return { + approval_required: approvalRequired, + approval_gate: approvalGate, + stop_reason: stopReason, + }; +} + +function handoff({ interfaceName, laneRef, runnerRef = null, commandHint = null }) { + return { + interface: interfaceName, + lane_ref: laneRef, + runner_ref: runnerRef, + command_hint: commandHint, + }; +} + +function evidence(inputsRequired, readbacks, receiptRefs = []) { + return { + inputs_required: inputsRequired, + readbacks, + receipt_refs: receiptRefs, }; } const inputs = readInputs(); const lane = String(inputs.lane || "classify"); -const signal = String(inputs.signal || ""); +const signal = String(inputs.signal || "").trim(); +const operatorContext = String(inputs.operator_context || "").trim(); const laneDetails = { classify: { + status: "ready", decision: "route", - summary: "Classify the signal and choose the smallest governed lanes.", - approval: "not_required", - next: ["sourcey", "release.prepare", "issue-to-pr", "send-as.draft", "spend.quote", "receipt-audit"], + kind: "router", + consequence: "read_only", + summary: "Classify the signal before any lane receives authority.", + why: "A business signal can touch docs, release, work, outreach, money, and proof. Classification keeps that fanout explicit instead of letting the agent improvise.", + authority: authority([]), + gate: gate(false, null, null), + handoff: handoff({ + interfaceName: "graph", + laneRef: "business-ops", + runnerRef: "main", + commandHint: "runx skill business-ops -i signal=\"...\"", + }), + evidence: evidence( + ["signal", "operator_context_if_available"], + ["lane packets for docs, release, issue, outreach, spend, and proof"], + ), + risks: ["over-routing a vague signal", "mistaking fixture packets for provider effects"], + next: ["sourcey", "release.prepare", "issue-to-pr", "outreach.plan", "spend.quote", "receipt-audit"], }, sourcey: { + status: "ready", decision: "prepare", - summary: "Refresh docs or launch notes from repo evidence before publishing claims.", - approval: "plan_required", - next: ["approval.docs_plan"], + kind: "docs", + consequence: "draft", + summary: "Prepare documentation or launch-note work from repo evidence before publishing claims.", + why: "Docs are usually safe to draft, but public claims should be grounded in source files, release state, and receipts.", + authority: authority(["repo.read", "docs.draft"]), + gate: gate(false, null, "publish waits for a docs or release approval lane"), + handoff: handoff({ + interfaceName: "skill", + laneRef: "sourcey", + runnerRef: "sourcey", + commandHint: "runx skill sourcey ...", + }), + evidence: evidence( + ["repo evidence", "current docs", "claim being made"], + ["diff or rendered docs preview", "source references", "public URL after publish"], + ), + risks: ["ungrounded marketing claims", "stale docs", "public proof missing after publish"], + next: ["approval.docs_publish", "receipt-audit"], }, "release.prepare": { + status: "awaiting_approval", decision: "prepare", - summary: "Build a read-only release brief with checks, changelog, risks, and unresolved gates.", - approval: "publish_required", - next: ["release.publish.approval"], + kind: "release", + consequence: "live_mutation", + summary: "Build a release packet with checks, changelog, risk notes, and unresolved gates.", + why: "Release prep is useful without authority. Publishing tags, packages, or deploys is a separate consequential act.", + authority: authority(["repo.read", "release.prepare"]), + gate: gate(true, "approval.release_publish", "tag, package, deploy, and announcement steps are not authorized by this fixture"), + handoff: handoff({ + interfaceName: "skill", + laneRef: "release", + runnerRef: "prepare", + commandHint: "runx skill release -i objective=\"...\"", + }), + evidence: evidence( + ["version", "changelog", "checks", "release target"], + ["green CI", "package dry-run", "tag or registry readback after approval"], + ), + risks: ["version drift", "publishing before checks finish", "site or changelog stale after release"], + next: ["approval.release_publish", "receipt-audit"], }, "issue-to-pr": { + status: "awaiting_approval", decision: "prepare", - summary: "Turn a bounded issue signal into a scoped change packet and draft PR handoff.", - approval: "human_merge_required", - next: ["review", "merge_gate"], + kind: "work", + consequence: "live_mutation", + summary: "Turn the signal into a scoped issue or PR handoff, with review and merge held separately.", + why: "Implementation work can be proposed and reviewed, but repo mutation and merge authority need explicit project gates.", + authority: authority(["repo.read", "work.plan"]), + gate: gate(true, "approval.pr_create_or_merge", "opening PRs, pushing branches, and merging are project mutations"), + handoff: handoff({ + interfaceName: "skill", + laneRef: "issue-to-pr", + runnerRef: "issue-to-pr", + commandHint: "runx skill issue-to-pr ...", + }), + evidence: evidence( + ["issue or objective", "repo context", "acceptance criteria"], + ["branch or PR URL", "review result", "merge receipt after approval"], + ), + risks: ["scope creep", "unreviewed merge", "claiming completion without tests or review"], + next: ["review", "merge_gate", "receipt-audit"], }, - "send-as.draft": { + "outreach.plan": { + status: "awaiting_approval", decision: "draft", - summary: "Draft outbound comms only; customer-visible send stops at approval.", - approval: "send_required", - next: ["approval.send"], + kind: "outreach", + consequence: "public_send", + summary: "Plan outbound, customer, or operator communication, then stop before live delivery.", + why: "Real outreach needs principal, audience, content digest, consent, provider readiness, and human approval. The core graph stays provider-neutral; vendor details belong in the selected provider adapter skill.", + authority: authority(["comms.draft"]), + gate: gate(true, "approval.send", "live send, campaign schedule, broad audience, or public post requires a send gate"), + handoff: handoff({ + interfaceName: "skill", + laneRef: "send-as -> provider.send", + runnerRef: "send-as plan, then the selected vendor-specific send runner", + commandHint: "runx skill send-as ...; runx skill --runner ...", + }), + evidence: evidence( + ["principal", "audience", "content digest", "consent basis", "provider status"], + ["provider preflight", "test send result", "delivery receipt after approval"], + ), + risks: ["wrong audience", "missing consent", "mutable content", "provider send treated as a draft"], + next: ["send-as", "provider.send", "approval.send", "receipt-audit"], }, "spend.quote": { + status: "awaiting_approval", decision: "quote", - summary: "Quote spend intent and caps; money movement stops before settlement authority.", - approval: "spend_required", - next: ["approval.spend"], + kind: "spend", + consequence: "money_movement", + summary: "Quote spend intent, amount, cap, recipient, and rail, then stop before settlement.", + why: "Money movement is never implied by a business plan. Quote, cap, approval, settlement, and readback stay distinct.", + authority: authority(["spend.quote"]), + gate: gate(true, "approval.spend", "settlement requires amount, recipient, rail, cap, and approval"), + handoff: handoff({ + interfaceName: "skill", + laneRef: "spend | charge | payout | refund", + runnerRef: "spend.mock or rail-specific payment runner", + commandHint: "runx skill spend ...", + }), + evidence: evidence( + ["amount", "cap", "recipient", "rail", "purpose"], + ["quote", "approval ref", "settlement transaction or provider readback after approval"], + ), + risks: ["network mismatch", "recipient ambiguity", "uncapped spend", "settlement marked complete from local state only"], + next: ["approval.spend", "settlement_lane", "receipt-audit"], }, "receipt-audit": { + status: "ready", decision: "verify", - summary: "Check the receipts and readbacks that prove what happened.", - approval: "not_required", - next: ["history", "verify"], + kind: "proof", + consequence: "proof", + summary: "State which receipts and provider readbacks would prove the lane chain after execution.", + why: "The graph receipt proves routing. External effects need child receipts and provider readbacks so another agent can replay what happened.", + authority: authority(["receipt.read"]), + gate: gate(false, null, null), + handoff: handoff({ + interfaceName: "skill", + laneRef: "receipt-auditor | run-history-analyst | ledger", + runnerRef: "verify", + commandHint: "runx skill receipt-auditor ...", + }), + evidence: evidence( + ["graph receipt", "child receipt refs", "provider readbacks"], + ["receipt chain", "effect packets", "public evidence URL where applicable"], + ), + risks: ["confusing route proof with effect proof", "missing provider readback", "unpublished receipt"], + next: ["history", "verify", "publish evidence if intended"], }, }; -const packet = laneDetails[lane] ?? { - decision: "needs_input", - summary: `Unknown lane: ${lane}`, - approval: "not_required", - next: [], -}; - -process.stdout.write(JSON.stringify({ - lane_packet: { +function missingSignalPacket() { + return { + schema: "runx.business_ops_lane.v1", lane, signal, - ...packet, - }, -}, null, 2)); + operator_context: operatorContext || null, + status: "needs_input", + decision: "stop", + kind: "router", + consequence: "read_only", + summary: "No business signal was provided.", + why: "The graph cannot choose safe lanes without a concrete objective.", + authority: authority([]), + gate: gate(false, null, null), + handoff: handoff({ + interfaceName: "graph", + laneRef: "business-ops", + runnerRef: "main", + commandHint: "runx skill business-ops -i signal=\"...\"", + }), + evidence: evidence(["signal"], []), + risks: ["routing vague or empty work into consequential lanes"], + next: [], + }; +} + +const detail = laneDetails[lane]; +const lanePacket = signal + ? { + schema: "runx.business_ops_lane.v1", + lane, + signal, + operator_context: operatorContext || null, + ...(detail ?? { + status: "needs_input", + decision: "stop", + kind: "router", + consequence: "read_only", + summary: `Unknown lane: ${lane}`, + why: "The requested lane is not part of the business-ops graph.", + authority: authority([]), + gate: gate(false, null, null), + handoff: handoff({ interfaceName: "graph", laneRef: "business-ops" }), + evidence: evidence(["known lane"], []), + risks: ["private or misspelled lane invoked without a contract"], + next: [], + }), + } + : missingSignalPacket(); + +process.stdout.write(JSON.stringify({ lane_packet: lanePacket }, null, 2)); process.stdout.write("\n"); diff --git a/skills/dependency-cve-audit/X.yaml b/skills/dependency-cve-audit/X.yaml index bb3808809..5eb7d1cb5 100644 --- a/skills/dependency-cve-audit/X.yaml +++ b/skills/dependency-cve-audit/X.yaml @@ -4,7 +4,7 @@ version: "0.1.1" catalog: kind: skill audience: public - visibility: public + visibility: internal role: canonical runx: diff --git a/skills/github-sync/X.yaml b/skills/github-sync/X.yaml index c8950e6f1..a270db39f 100644 --- a/skills/github-sync/X.yaml +++ b/skills/github-sync/X.yaml @@ -1,11 +1,14 @@ skill: github-sync -version: "0.1.0" +version: "0.1.1" catalog: kind: skill audience: public visibility: public - role: canonical + role: branded + canonical_skill: runx/messageboard + provider: github + runtime_path: github runners: github-sync: diff --git a/skills/governed-outbound/SKILL.md b/skills/governed-outbound/SKILL.md index 59c2487be..3cc1b39cd 100644 --- a/skills/governed-outbound/SKILL.md +++ b/skills/governed-outbound/SKILL.md @@ -19,8 +19,8 @@ It composes four catalog skills into one governed run: of it can leave the boundary. 3. an approval gate holds the send for a human, who sees the redaction verdict and the residual risk, not the raw content. -4. `slack-notify` plans the delivery of the scrubbed content to the channel; a - connector lane runs the actual post. +4. `send-as` plans delivery of the scrubbed content to the configured provider + adapter; the adapter lane runs the actual post. 5. `sign-receipt` seals the run so the gather, the scrub, the approval, and the send link into one auditable receipt. @@ -51,7 +51,7 @@ and span offsets, never the values it found. ## When not to use this skill - To post content that was authored in-house and carries no external data. Call - `slack-notify` directly. + `send-as` directly with the configured provider adapter. - To gather a source with no intent to send it onward. Call `web-fetch`. - To deliver without a human in the loop. The approval gate is the point; a send that needs no review does not need this chain. @@ -91,7 +91,7 @@ and span offsets, never the values it found. The run seals to `runx.receipt.v1`, linking each step's packet: `fetch_result` (source + digest), `redaction_report` (verdict + spans + redacted -digest), `approval_decision` (the gate), `notify_plan` (the delivery), and the +digest), `approval_decision` (the gate), `send_plan` (the delivery), and the `attestation` (the seal). The receipt proves the path without reconstructing the personal data that was removed along the way. diff --git a/skills/governed-outbound/X.yaml b/skills/governed-outbound/X.yaml index 10284c2ac..a09f5260a 100644 --- a/skills/governed-outbound/X.yaml +++ b/skills/governed-outbound/X.yaml @@ -1,5 +1,5 @@ skill: governed-outbound -version: "0.1.0" +version: "0.1.1" catalog: kind: graph @@ -9,6 +9,9 @@ catalog: harness: cases: - name: governed-outbound-approved-post + env: + RUNX_PROVIDER_PERMISSION_GRANT_ID: provider-send-demo + RUNX_PROVIDER_PERMISSION_GRANTED_SCOPES: runx:net:allowlist inputs: url: https://status.example.com/incidents/2026-06-14 allowlist: @@ -48,10 +51,11 @@ harness: - person - account_id mode: redact - agent_task.slack-notify.output: - notify_plan: + agent_task.send-as.output: + send_plan: decision: ready - channel: "#incidents" + audience: + channel: "#incidents" content: ref: redaction:redacted digest: "sha256:9b1d4c0e2af7b53c8e51a0d9f4c2b18e7a3d5c0f9e2b4a16d8c3f0a7b9e1d2c4" @@ -62,8 +66,10 @@ harness: approval_required: true preflight_required: true blockers: [] + runtime_path: provider.send provider_actions: - - slack.post_message + - provider.preflight + - provider.send agent_task.sign-receipt.output: attestation: action: governed outbound post @@ -126,6 +132,8 @@ runners: - runx:net:allowlist inputs: extract: text + artifacts: + wrap_as: fetch_result - id: scrub-content label: scrub personal data before the boundary skill: ../redact-pii @@ -135,7 +143,9 @@ runners: inputs: mode: redact context: - content: fetch-source.fetch_result_packet.data.extracted + content: fetch-source.fetch_result.extracted + artifacts: + wrap_as: redaction_report - id: approve-send label: human approval before delivery run: @@ -144,20 +154,26 @@ runners: gate_id: governed-outbound.send.approval reason: Approve delivery of the scrubbed content; review the redaction verdict and residual risk before it leaves the boundary. context: - decision: scrub-content.redaction_report_packet.data.decision - residual_risk: scrub-content.redaction_report_packet.data.residual_risk - redacted_digest: scrub-content.redaction_report_packet.data.redacted_digest + decision: scrub-content.redaction_report.decision + residual_risk: scrub-content.redaction_report.residual_risk + redacted_digest: scrub-content.redaction_report.redacted_digest artifacts: wrap_as: approval_decision packet: runx.approval.decision.v1 - id: post-notice label: post the governed notification - skill: ../slack-notify + skill: ../send-as runner: plan scopes: - runx:net:allowlist + inputs: + objective: Deliver the approved scrubbed update to the configured provider surface. + audience: "$input.channel" + provider_context: "$input.operator_context" context: - content: scrub-content.redaction_report_packet.data + content_ref: scrub-content.redaction_report + artifacts: + wrap_as: send_plan - id: seal-run label: seal the run to the ledger skill: ../sign-receipt @@ -167,12 +183,12 @@ runners: inputs: action: governed outbound post context: - evidence: post-notice.notify_plan_packet.data + evidence: post-notice.send_plan policy: guards: - step: post-notice field: approve-send.approval_decision.data.approved equals: true - step: post-notice - field: scrub-content.redaction_report_packet.data.decision + field: scrub-content.redaction_report.decision equals: ready diff --git a/skills/issue-to-pr/push-outbox/SKILL.md b/skills/issue-to-pr/push-outbox/SKILL.md index 2d0dd16ca..28daef3f3 100644 --- a/skills/issue-to-pr/push-outbox/SKILL.md +++ b/skills/issue-to-pr/push-outbox/SKILL.md @@ -1,5 +1,6 @@ --- name: issue-to-pr-push-outbox +version: 0.1.0 description: Publish issue-to-PR outbox entries through the governed Rust thread-outbox-provider front. runx: category: code diff --git a/skills/lead-router/SKILL.md b/skills/lead-router/SKILL.md index 4c912f577..1298deb20 100644 --- a/skills/lead-router/SKILL.md +++ b/skills/lead-router/SKILL.md @@ -29,8 +29,8 @@ decision: `reach_out`, `nurture`, or `hold`, with a rationale. 2. `when route == reach_out`, the `send-as` skill plans a direct, approval-gated outreach message. -3. `when route == nurture`, the `nitrosend` skill enrolls the lead in a governed - nurture campaign. +3. `when route == nurture`, the `send-as` skill plans a governed nurture + campaign handoff for whichever provider adapter the operator has configured. 4. `when route == hold`, a hold is recorded with the reason, and nothing is sent. Exactly one branch runs. The unselected branches are skipped, not blocked, and @@ -49,8 +49,8 @@ the hold branch sends nothing at all. ## When not to use this skill -- To send the same message to everyone. That is a campaign; call `nitrosend` - directly. +- To send the same message to everyone. That is a campaign; route through + `send-as` and then a provider adapter. - To draft copy only. Use a drafting skill; this skill decides and routes. - To contact a lead with no consent basis or against a suppression list. The `hold` route exists for exactly that case. @@ -78,9 +78,9 @@ the hold branch sends nothing at all. ## Output The run seals to `runx.receipt.v1`. The receipt links `qualify` (the route and -rationale) and the single branch that executed (`send_plan`, `campaign_plan`, or -`hold_record`). The branches that did not match are recorded as skipped, so the -receipt proves both the decision and the one action taken. +rationale) and the single branch that executed (`send_plan` or `hold_record`). +The branches that did not match are recorded as skipped, so the receipt proves +both the decision and the one action taken. ## Inputs diff --git a/skills/lead-router/X.yaml b/skills/lead-router/X.yaml index 37b18eb03..7de83cdc8 100644 --- a/skills/lead-router/X.yaml +++ b/skills/lead-router/X.yaml @@ -1,5 +1,5 @@ skill: lead-router -version: "0.1.0" +version: "0.1.1" catalog: kind: graph @@ -104,10 +104,12 @@ runners: when: field: qualify.route equals: nurture - skill: ../nitrosend - runner: send-campaign + skill: ../send-as + runner: plan scopes: - runx:net:allowlist + context: + audience: qualify.segment - id: hold label: record a do-not-contact hold when: diff --git a/skills/least-privilege-auditor/X.yaml b/skills/least-privilege-auditor/X.yaml index 019fc76db..c98dadbed 100644 --- a/skills/least-privilege-auditor/X.yaml +++ b/skills/least-privilege-auditor/X.yaml @@ -5,79 +5,6 @@ catalog: audience: operator visibility: public role: canonical -harness: - cases: - - name: unused-scope-attenuation-proposed - inputs: - subject: skills/report-exporter - granted_scopes: - - drive.files.read:/reports/* - - drive.files.write:/reports/* - - drive.files.delete:/reports/* - usage_summary: - receipt_ids: - - rx_101 - - rx_102 - observed: - - scope: drive.files.read:/reports/* - count: 8 - refs: - - rx_101:step_3 - - rx_102:step_2 - - scope: drive.files.write:/reports/* - count: 2 - refs: - - rx_101:step_6 - - rx_102:step_5 - objective: Prepare the skill for renewal by removing unused authority. - caller: - answers: - agent_task.least-privilege-auditor.output: - audit_report: - status: attenuation_proposed - subject: skills/report-exporter - evidence: - receipt_ids: - - rx_101 - - rx_102 - receipt_window: null - grant_source: null - limitations: [] - removed_scopes: - - drive.files.delete:/reports/* - narrowed_scopes: [] - kept_scopes: - - drive.files.read:/reports/* - - drive.files.write:/reports/* - deferred_scopes: [] - attenuated_grant: - - drive.files.read:/reports/* - - drive.files.write:/reports/* - residual_risk: - - The subject can still read and write under /reports/*. - reviewer_action: applyable_now - attenuation_proposals: - - action: remove - scope: drive.files.delete:/reports/* - rationale: No cited receipt exercised delete authority. - verdict: "over-privileged: remove drive.files.delete:/reports/*" - expect: - status: sealed - receipt: - schema: runx.receipt.v1 - state: sealed - disposition: closed - - - name: missing-granted-scopes-needs-agent - inputs: - subject: skills/report-exporter - usage_summary: - receipt_ids: - - rx_101 - observed: [] - expect: - status: failure - runners: audit: default: true diff --git a/skills/runx-operator/SKILL.md b/skills/ops-desk/SKILL.md similarity index 80% rename from skills/runx-operator/SKILL.md rename to skills/ops-desk/SKILL.md index cfa3e6197..7e4060292 100644 --- a/skills/runx-operator/SKILL.md +++ b/skills/ops-desk/SKILL.md @@ -1,29 +1,30 @@ --- -name: runx-operator -description: "Operate a runx-managed tenant from an agent or manager dashboard: inspect state, triage risks, prepare governed actions, route to the right skill lane, require approvals for consequential acts, and verify receipts after execution." +name: ops-desk +description: "Operate a project, workspace, or account from an agent or manager dashboard: inspect state, triage risks, prepare governed actions, route to the right skill lane, require approvals for consequential acts, and verify receipts after execution." runx: category: ops --- -# Runx Operator +# Ops Desk -Operate a runx-managed project or tenant from an agent-controlled desk. +Operate a project, workspace, or account from an agent-controlled desk. -This skill is the umbrella operations layer. It turns a tenant snapshot, an -operator objective, and receipt-backed evidence into one safe operator packet: +This skill is the generic operations desk layer. It turns a state snapshot, an +operator objective, and receipt-backed evidence into one safe ops desk packet: what is happening, what needs attention, what can be checked read-only, what requires approval, which governed lane should execute, and how success will be verified. It is not the authority and it is not a second CLI. It does not replace -`release`, `send-as`, `ledger`, `refund`, `spend`, `messageboard`, `nitrosend`, -provider-specific skills, hosted API routes, GitHub workflows, or deploy -commands. It routes to the existing interface with the smallest sufficient -context and stops before any consequential act that lacks the right gate. +`release`, `send-as`, `ledger`, `refund`, `spend`, `messageboard`, +provider-specific adapter skills, hosted API routes, repository workflows, or +deploy commands. It routes to the existing interface with the smallest +sufficient context and stops before any consequential act that lacks the right +gate. ## What this skill does -`runx-operator` produces an operator packet for a manager dashboard, agent +`ops-desk` produces an ops desk packet for a manager dashboard, agent session, or self-operation run. It reads projected state, classifies findings, ranks the next action, selects the governed lane, names blockers, writes the approval prompt when a human decision is required, and states the @@ -40,11 +41,12 @@ API route, workflow, or provider tool. ## When to use this skill -- An operator asks an agent to manage a runx tenant or product. +- An operator asks an agent to manage a project, workspace, product, account, + or other bounded operating surface. - A dashboard needs an agent-readable plan from the current projected state. - A runbook needs to decide between read-only checks, proposals, approval-gated actions, and post-action verification. -- A tenant-specific operator skill needs a generic cockpit spine instead of +- A product-specific operator skill needs a generic cockpit spine instead of inventing its own action model. - Runx needs to dogfood its own release, registry, hosted, receipt, or provider operations through the same governed lanes it exposes to users. @@ -55,11 +57,12 @@ API route, workflow, or provider tool. - To duplicate a CLI command, release script, GitHub workflow, hosted endpoint, registry client, or provider SDK. - To bypass a human gate because the agent or UI believes the action is obvious. -- To replace a domain skill such as `send-as`, `nitrosend`, `messageboard`, - `release`, `ledger`, `refund`, `spend`, or `least-privilege-auditor`. +- To replace a domain skill such as `send-as`, `messageboard`, `release`, + `ledger`, `refund`, `spend`, `least-privilege-auditor`, or a provider + adapter. - To operate from stale, missing, or unverifiable state while claiming readiness. - To put secrets, private keys, raw customer lists, or provider dumps into the - operator packet. + ops desk packet. ## Operating Model @@ -75,13 +78,13 @@ the same governed lane, not separate backdoors. ## Delegation Model -Operator packets name existing execution surfaces; they do not implement them. +Ops desk packets name existing execution surfaces; they do not implement them. - `release` owns release preparation, approval, publish handoff, and post-release verification. - `ledger`, `receipt-auditor`, and `run-history-analyst` own proof questions. -- `send-as` owns authority for live communications; provider skills such as - `nitrosend` own provider details. +- `send-as` owns authority for live communications; provider adapter skills own + provider-specific execution details. - `spend`, `charge`, `refund`, and branded payment skills own money movement. - Project skills own product vocabulary and product-specific actions. - CLI commands, hosted API routes, and GitHub workflows remain deterministic @@ -94,10 +97,10 @@ product gap. Do not invent a private workaround. ## Procedure 1. Scope the objective. - - Identify the tenant, surface, time window, and whether the ask is + - Identify the workspace, project, account, surface, time window, and whether the ask is read-only, proposal-only, or execution-prep. - Read `project_profile` or `operator_policy` as context, not authority. - - If the tenant or objective is ambiguous, return `needs_input`. + - If the operating scope or objective is ambiguous, return `needs_input`. 2. Classify state from evidence. - Use `dashboard_snapshot`, `receipt_summary`, `effect_summary`, and @@ -115,12 +118,11 @@ product gap. Do not invent a private workaround. existing release workflow/commands. - Audit questions route to `ledger`, `receipt-auditor`, `run-history-analyst`, or `least-privilege-auditor`. - - Live communication routes through `send-as` and then a provider skill such - as `nitrosend`. + - Live communication routes through `send-as` and then a provider adapter. - Payment collection, payout, refund, chargeback, or target changes route to the matching payment lane. - - Board/thread/provider actions route to `messageboard`, `github-sync`, - `issue-intake`, `issue-to-pr`, or the product's tenant skill. + - Board, thread, and provider actions route to `messageboard`, a provider + adapter, `issue-intake`, `issue-to-pr`, or the product's own skill. - Deploy and config changes route to the product-owned deploy lane. 4. Decide gates. @@ -135,7 +137,7 @@ product gap. Do not invent a private workaround. rail, target class, and verification receipt expected after settlement. - Missing approval means `awaiting_approval`, not "ready". -5. Produce the operator packet. +5. Produce the ops desk packet. - Lead with the few issues an operator should act on now. - Name the exact lane for each proposed action. - Include the existing execution interface as a handoff, not as a duplicated @@ -144,7 +146,7 @@ product gap. Do not invent a private workaround. - Include verification steps that will prove the action happened. 6. Stop cleanly. - - Return `needs_input` for missing tenant, objective, identity, authority, + - Return `needs_input` for missing scope, objective, identity, authority, evidence, approval, or target. - Return `refused` for requests to bypass gates, hide material facts, leak secrets, spoof receipts, mark unsettled money as settled, or send without a @@ -152,8 +154,8 @@ product gap. Do not invent a private workaround. ## Edge cases and stop conditions -- **No tenant or objective:** return `needs_input`; there is no safe operating - frame. +- **No project/workspace/account or objective:** return `needs_input`; there is + no safe operating frame. - **No projection or receipt evidence:** return `needs_input` or `unknown` status; do not convert silence into `ok`. - **Requested action has unknown consequence:** stop at `needs_input` with the @@ -169,7 +171,7 @@ product gap. Do not invent a private workaround. Load only the reference needed for the objective: -- Payments, payouts, refunds, x402, Stripe, reconciliation: +- Payments, payouts, refunds, payment rail adapters, reconciliation: `references/payments.md` - Email, campaigns, notifications, customer/public communication: `references/communications.md` @@ -184,12 +186,12 @@ Load only the reference needed for the objective: ## Output schema -Return one `operator_packet`: +Return one `ops_desk_packet`: ```yaml -operator_packet: +ops_desk_packet: decision: ready | awaiting_approval | needs_input | no_action | refused - tenant_ref: string + scope_ref: string objective: string mode: read_only | proposal | execution_prep | post_action_review dashboard: @@ -248,19 +250,20 @@ operator_packet: - Never widen authority because a dashboard widget would be convenient. - Never duplicate an existing CLI command, workflow, hosted endpoint, or domain skill in operator prose. Route to it. -- Keep tenant-specific policy in tenant context. Keep this skill generic. +- Keep product-specific policy in product context. Keep this skill generic. ## Inputs - `objective` (required): operator request, e.g. "check payments and unblock funding", "prepare a campaign send", or "review stuck receipts". -- `tenant_ref` (required): the tenant or product being operated. +- `scope_ref` (required): the project, workspace, account, product, or bounded + surface being operated. - `dashboard_snapshot` (optional): JSON summary of current projected state. - `receipt_summary` (optional): JSON or prose receipt/effect summary. - `provider_status` (optional): JSON or prose provider health/account state. - `approval_context` (optional): existing operator approvals, denials, or policy gates. -- `operator_policy` (optional): tenant-specific constraints and lane names. +- `operator_policy` (optional): project-specific constraints and lane names. - `project_profile` (optional): project topology, existing interfaces, and verification expectations. It is context, not authority. - `requested_action` (optional): preselected action lane or dashboard action id. @@ -268,11 +271,11 @@ operator_packet: ## Worked example Input: "Check payment readiness and tell me what to do next" with a dashboard -snapshot showing runx healthy, Base/Arbitrum/Polygon x402 targets, three funded -items, no unfunded approved items, and card webhook status `needs_review`. +snapshot showing healthy quote/readback state, three funded items, no unfunded +approved items, and one rail adapter webhook status `needs_review`. Output: `decision: ready`, money status `ok`, providers status -`needs_attention`, one warning finding for Stripe webhook readiness, and one +`needs_attention`, one warning finding for rail webhook readiness, and one proposal routing to `provider.webhook_check` with no money movement. It does -not propose marking anything funded, because no unfunded approved posting is -present and the latest x402 funding receipt is already verified. +not propose marking anything funded, because no unfunded approved item is +present and the latest funding receipt is already verified. diff --git a/skills/runx-operator/X.yaml b/skills/ops-desk/X.yaml similarity index 81% rename from skills/runx-operator/X.yaml rename to skills/ops-desk/X.yaml index 411d961aa..456a40be5 100644 --- a/skills/runx-operator/X.yaml +++ b/skills/ops-desk/X.yaml @@ -1,5 +1,5 @@ -skill: runx-operator -version: "0.1.0" +skill: ops-desk +version: "0.1.2" catalog: kind: skill @@ -12,24 +12,26 @@ runners: default: true type: agent-task agent: operator - task: runx-operator + task: ops-desk outputs: - operator_packet: object + ops_desk_packet: object artifacts: - wrap_as: operator_packet - packet: runx.operator_packet.v1 + wrap_as: ops_desk_packet + packet: runx.ops_desk.packet.v1 runx: category: ops instructions: > - Produce one runx.operator_packet.v1 for the requested tenant objective. + Produce one runx.ops_desk.packet.v1 for the requested project, workspace, + account, or product objective. Treat dashboard_snapshot, receipt_summary, provider_status, approval_context, operator_policy, and project_profile as evidence, not as authority. Classify health, money, communications, providers, receipts, access, release, registry, and deploy state; rank the smallest useful next action; route every proposal to a named governed lane such as release, ledger, - receipt-auditor, least-privilege-auditor, send-as, nitrosend, messageboard, - payment.quote, payment.payout, payment.refund, provider.health_check, - deploy.smoke, or a tenant skill. For each consequential proposal include + receipt-auditor, least-privilege-auditor, send-as, provider.send, + messageboard, payment.quote, payment.payout, payment.refund, + provider.health_check, deploy.smoke, or a product skill. For each + consequential proposal include an execution handoff naming the existing skill, CLI command, hosted API, workflow, provider tool, or manual gate that should execute it; never duplicate that implementation in operator prose. Read-only checks do not @@ -40,7 +42,7 @@ runners: secrets, raw customer lists, wallet private keys, tokens, or provider dumps. Never claim settled, sent, paid, refunded, deployed, released, or fixed without a receipt, effect, or provider readback expectation. Return - needs_input for missing tenant/objective/evidence/authority/approval or + needs_input for missing scope/objective/evidence/authority/approval or missing execution lane; return refused for gate bypass, forged proof, secret leakage, or hidden private workarounds. inputs: @@ -48,14 +50,14 @@ runners: type: string required: true description: The bounded operator objective. - tenant_ref: + scope_ref: type: string required: true - description: Tenant or product being operated. + description: Project, workspace, account, product, or bounded operating surface being operated. dashboard_snapshot: type: json required: false - description: Current projected tenant state. + description: Current projected state for the operating scope. receipt_summary: type: json required: false @@ -84,16 +86,16 @@ runners: review-action: type: agent-task agent: reviewer - task: runx-operator-action-review + task: ops-desk-action-review outputs: action_review: object artifacts: wrap_as: action_review_packet - packet: runx.operator_action_review.v1 + packet: runx.ops_desk.action_review.v1 runx: category: ops instructions: > - Review one proposed operator action. Classify its consequence, approval + Review one proposed ops desk action. Classify its consequence, approval requirement, blockers, and verification evidence. If the proposal moves money, sends publicly, mutates a provider, changes targets or credentials, deploys, publishes a release, deletes, or broadens authority, require @@ -110,7 +112,7 @@ runners: action_packet: type: json required: true - description: Proposed operator action or operator_packet.proposals item. + description: Proposed ops desk action or ops_desk_packet.proposals item. receipt_summary: type: json required: false diff --git a/skills/runx-operator/fixtures/action-review-awaits-approval.yaml b/skills/ops-desk/fixtures/action-review-awaits-approval.yaml similarity index 91% rename from skills/runx-operator/fixtures/action-review-awaits-approval.yaml rename to skills/ops-desk/fixtures/action-review-awaits-approval.yaml index dc951b84e..8240c1762 100644 --- a/skills/runx-operator/fixtures/action-review-awaits-approval.yaml +++ b/skills/ops-desk/fixtures/action-review-awaits-approval.yaml @@ -1,4 +1,4 @@ -name: runx-operator-action-review-awaits-approval +name: ops-desk-action-review-awaits-approval kind: skill target: .. runner: review-action @@ -8,7 +8,7 @@ inputs: lane: payment.refund consequence: money_movement amount_cents: 2500 - rail: x402 + rail: rail-demo settlement_ref: hfr_a1a4b34d30076835ce88807d391951ac approval_required: true execution: @@ -27,7 +27,7 @@ inputs: approvals: [] caller: answers: - agent_task.runx-operator-action-review.output: + agent_task.ops-desk-action-review.output: action_review: decision: awaiting_approval consequence: money_movement diff --git a/skills/runx-operator/fixtures/payment-status.yaml b/skills/ops-desk/fixtures/payment-status.yaml similarity index 62% rename from skills/runx-operator/fixtures/payment-status.yaml rename to skills/ops-desk/fixtures/payment-status.yaml index ebcedd9d5..7625c620d 100644 --- a/skills/runx-operator/fixtures/payment-status.yaml +++ b/skills/ops-desk/fixtures/payment-status.yaml @@ -1,19 +1,19 @@ -name: runx-operator-payment-status +name: ops-desk-payment-status kind: skill target: .. runner: operate inputs: objective: Check payment readiness and tell me what to do next. - tenant_ref: tenant:example + scope_ref: workspace:example dashboard_snapshot: health: api: ok money: - x402_targets: - - network: base + rail_targets: + - network: primary-net recommended: true - - network: arbitrum - - network: polygon + - network: secondary-net-a + - network: secondary-net-b unfunded_approved_items: 0 funded_open_items: 3 communications: @@ -24,22 +24,22 @@ inputs: receipts: - id: hfr_example_funding status: verified - rail: x402 - network: base + rail: primary-rail + network: primary-net provider_status: runx_api: ok - card_webhook: needs_review + secondary_rail_webhook: needs_review approval_context: approvals: [] operator_policy: > - x402 is primary. Card payments are secondary until webhook readiness is - re-verified. + The primary rail is preferred. Secondary rails stay disabled until webhook + readiness is re-verified. caller: answers: - agent_task.runx-operator.output: - operator_packet: + agent_task.ops-desk.output: + ops_desk_packet: decision: ready - tenant_ref: tenant:example + scope_ref: workspace:example objective: Check payment readiness and tell me what to do next. mode: read_only dashboard: @@ -51,15 +51,15 @@ caller: findings: - severity: warning area: providers - summary: Card webhook readiness needs review, but x402 funding is healthy. + summary: Secondary rail webhook readiness needs review, but primary rail funding is healthy. evidence_refs: - - provider_status.card_webhook + - provider_status.secondary_rail_webhook proposals: - - action_id: card_webhook_check + - action_id: secondary_rail_webhook_check lane: provider.webhook_check - reason: The secondary card rail should not be trusted until webhook readiness is checked. + reason: The secondary rail should not be trusted until webhook readiness is checked. inputs_summary: - provider: card + provider: secondary_rail consequence: read_only approval_required: false approval_prompt: null @@ -70,21 +70,21 @@ caller: readback: webhook delivery endpoint health and latest event status execution: interface: skill - lane_ref: runx-operator + lane_ref: ops-desk profile_ref: null command_ref: null workflow_ref: null approval_gate: null verifier_ref: provider.webhook_check ordered_next_steps: - - step: Run a card webhook health check before relying on card payouts. + - step: Run a secondary rail webhook health check before relying on secondary payouts. lane: provider.webhook_check requires_confirmation: false refused_reasons: [] needs_input: [] success_checkpoint: - milestone: x402 funding ready - description: x402 funding has a verified receipt and no approved item is waiting on funding. + milestone: primary rail funding ready + description: Primary rail funding has a verified receipt and no approved item is waiting on funding. expect: status: sealed receipt: diff --git a/skills/runx-operator/references/communications.md b/skills/ops-desk/references/communications.md similarity index 87% rename from skills/runx-operator/references/communications.md rename to skills/ops-desk/references/communications.md index ca463dd1e..e9e92c8da 100644 --- a/skills/runx-operator/references/communications.md +++ b/skills/ops-desk/references/communications.md @@ -37,5 +37,6 @@ policy basis, provider readiness, and approval. Drafting is not sending. - Missing consent, unsubscribe, suppression, preflight, or verified sender. - Request to send from a provider preview or draft without approval. -Route provider-specific execution to skills such as `nitrosend`; keep the -authority model in `send-as`. +Route provider-specific execution to the selected provider adapter skill; keep +the authority model in `send-as`. Branded providers belong in their own adapter +skills, not in this ops desk spine. diff --git a/skills/runx-operator/references/dashboard.md b/skills/ops-desk/references/dashboard.md similarity index 96% rename from skills/runx-operator/references/dashboard.md rename to skills/ops-desk/references/dashboard.md index 46f5383c8..577f708b3 100644 --- a/skills/runx-operator/references/dashboard.md +++ b/skills/ops-desk/references/dashboard.md @@ -80,7 +80,7 @@ Actions should be small named lanes: - `deploy.smoke` - `access.audit` -Tenant products may alias these for UX, but the operator packet should still +Products may alias these for UX, but the ops desk packet should still include the canonical lane. ## Stop Conditions diff --git a/skills/runx-operator/references/delegation.md b/skills/ops-desk/references/delegation.md similarity index 95% rename from skills/runx-operator/references/delegation.md rename to skills/ops-desk/references/delegation.md index 19b88391e..8cf04086d 100644 --- a/skills/runx-operator/references/delegation.md +++ b/skills/ops-desk/references/delegation.md @@ -5,7 +5,7 @@ deploy, hosted operations, project profiles, CLI handoff, or dogfooding runx. ## Rule -`runx-operator` reasons and routes. It does not implement the operation. +`ops-desk` reasons and routes. It does not implement the operation. The execution surface is one of: @@ -17,7 +17,7 @@ The execution surface is one of: - a manual human gate. If a command, workflow, or API already exists, reference it. Do not restate its -logic in the operator packet. +logic in the ops desk packet. ## Project Profiles diff --git a/skills/ops-desk/references/payments.md b/skills/ops-desk/references/payments.md new file mode 100644 index 000000000..c231e97eb --- /dev/null +++ b/skills/ops-desk/references/payments.md @@ -0,0 +1,70 @@ +# Payments Reference + +Use this reference for funding, payouts, refunds, target changes, chargebacks, +settlement health, and payment reconciliation. + +## Rule + +Money state changes only after rail proof becomes a receipt/effect. UI state, +provider optimism, local API success, or agent narration is not settlement. + +The ops desk spine is rail-neutral. It selects the governed payment family and +the configured rail adapter, then stops at the right approval or signature gate. +Rail-specific funding, wallet, webhook, dispute, and settlement details belong +in the rail adapter skill or the product-owned operator skill that owns that rail. + +## Common Lanes + +- `payment.quote`: read-only or proposal; no approval. +- `payment.reserve`: authority reservation or cap check; may require approval. +- `payment.fund`: money movement; approval or payer signature required. +- `payment.payout`: money movement; approval required. +- `payment.refund`: money movement; approval required. +- `payment.target_update`: rail configuration; approval required. +- `payment.reconcile`: read-only unless it creates corrections. +- `payment.dispute_response`: customer/provider communication; approval + depends on whether it submits externally. + +## Rail Adapter Contract + +A payment rail adapter must make these fields explicit before settlement: + +- operation: quote, reserve, fund, payout, refund, dispute, or reconcile; +- amount and currency; +- payer, payee, counterparty, or refund target; +- network, rail, account, asset, or processor path; +- cap, expiry, and idempotency key; +- approval or payer-signature requirement; +- settlement proof shape; +- readback source after settlement. + +Do not infer cross-rail compatibility. A balance, address, token, processor +account, webhook, or credential on one rail does not imply readiness on another +rail. If a product supports multiple rails, each rail has its own adapter status, +target configuration, proof, and reconciliation readback. + +## Operator Packet Requirements + +For each payment proposal include: + +- payer/payee refs, redacted when necessary; +- amount and currency; +- rail adapter and network/account path; +- quote, reservation, approval, or settlement refs; +- expiry or idempotency key; +- approval requirement; +- expected receipt/effect; +- reconciliation readback. + +## Stop Conditions + +- Missing amount, payee, rail adapter, quote, approval, signature, or + idempotency key. +- Requested manual funded/paid/refunded marking without receipt-backed proof. +- Network, asset, account, or rail mismatch between quote and payer funds. +- Target update requested without explicit operator approval. +- Refund or payout amount not tied to the original settlement or policy. +- Payout requested for a claim, invoice, or obligation that has not reached the + product's payable state. +- Rail-specific funding or recovery requested without loading the rail adapter + or product runbook that owns that procedure. diff --git a/skills/runx-operator/references/providers.md b/skills/ops-desk/references/providers.md similarity index 93% rename from skills/runx-operator/references/providers.md rename to skills/ops-desk/references/providers.md index 0dac8581a..58ac052a0 100644 --- a/skills/runx-operator/references/providers.md +++ b/skills/ops-desk/references/providers.md @@ -6,7 +6,7 @@ and incident triage. ## Rule Provider state is observed through governed checks and redacted refs. Secrets -are never copied into operator packets. +are never copied into ops desk packets. ## Common Lanes @@ -21,7 +21,7 @@ are never copied into operator packets. ## Required Evidence -- provider name and account/tenant ref; +- provider name and account/workspace/product ref; - status timestamp; - credential ref, never raw credential; - webhook endpoint and latest delivery status when relevant; diff --git a/skills/runx-operator/references/receipts.md b/skills/ops-desk/references/receipts.md similarity index 100% rename from skills/runx-operator/references/receipts.md rename to skills/ops-desk/references/receipts.md diff --git a/skills/runx-operator/references/payments.md b/skills/runx-operator/references/payments.md deleted file mode 100644 index 85b495f01..000000000 --- a/skills/runx-operator/references/payments.md +++ /dev/null @@ -1,115 +0,0 @@ -# Payments Reference - -Use this reference for funding, payouts, refunds, target changes, chargebacks, -settlement health, and payment reconciliation. - -## Rule - -Money state changes only after rail proof becomes a receipt/effect. UI state, -provider optimism, local API success, or agent narration is not settlement. - -## Common Lanes - -- `payment.quote`: read-only or proposal; no approval. -- `payment.fund`: money movement; approval or payer signature required. -- `payment.payout`: money movement; approval required. -- `payment.refund`: money movement; approval required. -- `payment.target_update`: rail configuration; approval required. -- `payment.reconcile`: read-only unless it creates corrections. -- `payment.dispute_response`: customer/provider communication; approval - depends on whether it submits externally. - -## x402 - -An x402 requirement is exact. The payer must satisfy the quoted network, asset, -amount, pay-to address, and token domain. Do not treat USDC as a cross-network -balance. - -For EVM networks, the same address can receive on multiple chains, but balances -are separate. Base, Arbitrum, Polygon, and Ethereum require separate -reconciliation and separate gas planning. Solana is a different rail family. - -## Stripe - -Treat Stripe/card flows as a separate readiness track. A healthy x402 rail does -not imply Stripe webhook, Connect, payout, refund, or chargeback readiness. - -## Funding a wallet (fiat onto a network) - -Bringing new money in is a human step. The CDP SDK and the x402 facilitator only -move USDC that is **already onchain** (gasless EIP-3009 between wallets whose keys -we hold; the smart-account float is sponsored by the CDP paymaster, a plain EOA is -not). They cannot pull an exchange or bank balance, and CDP Onramp is not -server-automatable (the owner must complete a hosted KYC + payment flow). An -operator requests a human top-up; it never auto-funds from fiat. - -**Network trap (this has cost real time more than once):** the retail Coinbase -send does not reliably offer the network you want. For USDC it has shown an -**Ethereum-only** withdrawal with **no Base option**, regardless of Coinbase's -generic "assets on multiple networks" help docs. Never assume the exchange can -send to Base. Verify the live send flow first; reach Base through a Base-native -route (the Base app, or a bridge), not a direct exchange withdrawal. A receiving -address needs no ETH/gas to receive USDC. - -Getting USDC onto Base when the exchange is ETH-only has one proven route: the -human sends USDC on **Ethereum** from the exchange, then **CCTP** (Circle's native -USDC burn-and-mint) carries it to Base. The operator burns the USDC on Ethereum -(approve, then depositForBurn on Circle's TokenMessenger), Circle attests the burn -once the source chain finalizes, and native USDC mints on Base. A **Standard** -transfer waits Ethereum finality (about 13 to 19 minutes) and is free; a **fast** -transfer settles in seconds for a small fee. Contract addresses are identical on -every EVM chain and the domain ids are fixed (Ethereum 0, Base 6); read the exact -addresses and the attestation endpoint from developers.circle.com, never from -memory. Two properties matter when operating it. A standing CCTP relayer -auto-submits the destination mint for Standard transfers, so the USDC usually -arrives on Base without the operator minting at all. And the Ethereum burn is the -only irreversible step, with attestations that never expire, so a pending or -failed mint is always recoverable by re-submitting the saved attestation. If the -operator self-mints, the caller needs gas on Base (a sponsored smart-account -works, a zero-gas EOA does not). The Coinbase **Base app** is receive-only here -(Deposit/Receive QR, no in-app Buy), so it is not a funding path by itself; a fiat -on-ramp that delivers USDC straight to a Base address also works but requires a -production on-ramp application. - -Once USDC is on the target network in a wallet we hold keys for, every later move -(top-up, payout, sweep, round-trip) is free and gasless via the facilitator, with -no further human step. - -## Paying out an accepted claim - -Settle only after a claim is delivered and accepted at its bar, to a known payout -address, in this order: - -1. **Move the USDC**, gasless via the facilitator (the same EIP-3009 path as a top-up), - the funded house wallet to the payee's payout address. The returned on-chain tx is the - rail proof. -2. **Record the board state** only after that tx exists. On Frantic the `gpayout` runner - records the payout with `payment_ref` set to the settlement reference (e.g. - `base:`); it records, it never moves money, and the ref must already exist. - -Supplying the tx as proof settles a known address even when the payee has no registered -payout identity in the read model. It does not loosen the stop condition below: if the -destination is unknown (no identity on file and no known wallet), do not pay. - -## Operator Packet Requirements - -For each payment proposal include: - -- payer/payee refs, redacted when necessary; -- amount and currency; -- rail and network; -- quote or settlement refs; -- expiry or idempotency key; -- approval requirement; -- expected receipt/effect; -- reconciliation readback. - -## Stop Conditions - -- Missing amount, payee, rail, quote, approval, or idempotency key. -- Requested manual funded/paid/refunded marking without receipt-backed proof. -- Network mismatch between quote and payer asset. -- Target update requested without explicit operator approval. -- Refund or payout amount not tied to the original settlement/claim policy. -- Payout requested for a claim that is not delivered and accepted at its policy - bar, or for a payee with no payout identity on file. diff --git a/skills/send-as/SKILL.md b/skills/send-as/SKILL.md index cf1798829..5782e23e5 100644 --- a/skills/send-as/SKILL.md +++ b/skills/send-as/SKILL.md @@ -9,11 +9,10 @@ runx: Govern a message, campaign, or notification sent on behalf of a principal. -`send-as` is the canonical communication-action family. Provider skills such as -`nitrosend` select a concrete sending surface, but this skill owns -the common authority model: who is allowed to speak, to whom, through which -channel, with what content, under which proof, and where the send must stop for -human approval. +`send-as` is the canonical communication-action family. Provider adapter skills +select concrete sending surfaces, but this skill owns the common authority +model: who is allowed to speak, to whom, through which channel, with what +content, under which proof, and where the send must stop for human approval. ## What this skill does @@ -25,7 +24,7 @@ after the provider-specific lane records delivery evidence and the runx receipt seals. This skill may be used directly for provider-neutral planning, or as the -canonical family beneath branded provider skills. +canonical family beneath branded provider adapters. ## When to use this skill @@ -125,7 +124,7 @@ send_plan: ## Worked example Input: "Schedule the June newsletter to the subscribers list" with a campaign -draft digest, verified sender, named list, and Nitrosend account snapshot. +draft digest, verified sender, named list, and provider account snapshot. Output: `decision: ready`; `send_class: campaign`; audience is the named subscribers list; content is digest-bound; preflight and human approval are diff --git a/skills/send-as/X.yaml b/skills/send-as/X.yaml index 573ca4fc0..d72be897b 100644 --- a/skills/send-as/X.yaml +++ b/skills/send-as/X.yaml @@ -1,5 +1,5 @@ skill: send-as -version: "0.1.0" +version: "0.1.1" catalog: kind: skill audience: public diff --git a/skills/send-as/fixtures/campaign-send-plan-ready.yaml b/skills/send-as/fixtures/campaign-send-plan-ready.yaml index b9db08eb9..ba09a04d6 100644 --- a/skills/send-as/fixtures/campaign-send-plan-ready.yaml +++ b/skills/send-as/fixtures/campaign-send-plan-ready.yaml @@ -4,11 +4,11 @@ target: .. runner: plan inputs: objective: Schedule the June newsletter to the subscribers list. - principal: account:nitrosend-demo + principal: account:growth-demo provider_context: - provider: nitrosend + provider: provider-send-demo account_ref: acct_demo - runtime_path: mcp + runtime_path: provider.send domain_verified: true audience: type: list @@ -27,11 +27,11 @@ caller: action_family: send-as principal: type: account - ref: account:nitrosend-demo + ref: account:growth-demo provider: - name: nitrosend + name: provider-send-demo account_ref: acct_demo - runtime_path: mcp + runtime_path: provider.send send_class: campaign channel: email audience: @@ -48,11 +48,11 @@ caller: approval_ref: approval:pending blockers: [] provider_actions: - - nitro_review_delivery - - nitro_send_test_message - - nitro_control_delivery + - provider.review_delivery + - provider.send_test + - provider.schedule_or_send evidence_refs: - - provider_context:nitrosend + - provider_context:provider-send-demo success_checkpoint: milestone: send_ready_for_approval description: A digest-bound campaign send is ready for preflight and explicit approval. diff --git a/skills/send-as/fixtures/missing-audience-needs-input.yaml b/skills/send-as/fixtures/missing-audience-needs-input.yaml index 93bb20083..608979294 100644 --- a/skills/send-as/fixtures/missing-audience-needs-input.yaml +++ b/skills/send-as/fixtures/missing-audience-needs-input.yaml @@ -4,7 +4,7 @@ target: .. runner: plan inputs: objective: Send the launch update today. - principal: account:nitrosend-demo + principal: account:growth-demo content_ref: draft_ref: campaign:launch digest: sha256:bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb @@ -17,7 +17,7 @@ caller: action_family: send-as principal: type: account - ref: account:nitrosend-demo + ref: account:growth-demo provider: name: unknown account_ref: "" diff --git a/skills/slack-notify/X.yaml b/skills/slack-notify/X.yaml index 5531e2c71..daa21cc68 100644 --- a/skills/slack-notify/X.yaml +++ b/skills/slack-notify/X.yaml @@ -1,11 +1,14 @@ skill: slack-notify -version: "0.1.0" +version: "0.1.1" catalog: kind: skill audience: public visibility: public - role: canonical + role: branded + canonical_skill: runx/send-as + provider: slack + runtime_path: slack runners: plan: diff --git a/skills/structured-extraction/X.yaml b/skills/structured-extraction/X.yaml index 0ff54732a..5344a009c 100644 --- a/skills/structured-extraction/X.yaml +++ b/skills/structured-extraction/X.yaml @@ -4,7 +4,7 @@ version: "0.1.0" catalog: kind: skill audience: public - visibility: public + visibility: internal role: canonical runtime_path: local diff --git a/skills/support-triage-reply/SKILL.md b/skills/support-triage-reply/SKILL.md index ec7b74de7..dfddaa3a1 100644 --- a/skills/support-triage-reply/SKILL.md +++ b/skills/support-triage-reply/SKILL.md @@ -1,6 +1,6 @@ --- name: support-triage-reply -version: 0.1.0 +version: 0.1.1 description: Classify a bounded support request, choose the safe next path, and draft a customer-ready reply only when a human-gated send is appropriate. source: type: cli-tool diff --git a/skills/support-triage-reply/X.yaml b/skills/support-triage-reply/X.yaml index f71b51bce..b8332cd81 100644 --- a/skills/support-triage-reply/X.yaml +++ b/skills/support-triage-reply/X.yaml @@ -1,10 +1,10 @@ skill: support-triage-reply -version: "0.1.0" +version: "0.1.1" catalog: kind: skill audience: operator - visibility: public + visibility: internal role: canonical harness: @@ -19,8 +19,8 @@ harness: body: I added the DNS records for my domain. What should I check next so emails can send safely? source: fixture:safe-how-to policy: - product_name: Nitrosend - support_signature: Nitrosend Support + product_name: ExampleDesk + support_signature: ExampleDesk Support expect: status: sealed receipt: @@ -39,8 +39,8 @@ harness: body: My login is blocked and I need someone to reset access for the team owner. source: fixture:account-access policy: - product_name: Nitrosend - support_signature: Nitrosend Support + product_name: ExampleDesk + support_signature: ExampleDesk Support expect: status: sealed receipt: diff --git a/skills/support-triage-reply/references/evidence.json b/skills/support-triage-reply/references/evidence.json index 2d54864f9..b457e37c6 100644 --- a/skills/support-triage-reply/references/evidence.json +++ b/skills/support-triage-reply/references/evidence.json @@ -14,8 +14,8 @@ "trust_tier": "community" }, "boundary": { - "nitrosend_private_skill_reused": false, - "source_shape": "A generic public Runx skill inspired by the same support-ops category as Nitrosend private triage/intake skills.", + "private_product_skill_reused": false, + "source_shape": "A generic public Runx skill for the same support-ops category that product-specific triage/intake skills can compose.", "private_semantics_included": false, "sends_or_mutates": false, "send_gate": "requires_human_approval" @@ -61,7 +61,7 @@ "recommended_path": "reply_draft", "send_gate_status": "requires_human_approval", "draft_email": { - "body": "Hi Mira,\n\nThanks for the note. You asked about How do I verify my sending domain?.\n\nFor Nitrosend domain verification, check that the DNS records shown in the sending-domain setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.\n\nBefore sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.\n\nThanks,\nNitrosend Support", + "body": "Hi Mira,\n\nThanks for the note. You asked about How do I verify my sending domain?.\n\nFor sending-domain verification, check that the DNS records shown in the setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.\n\nBefore sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.\n\nThanks,\nExampleDesk Support", "proposed": true, "recipient_hint": "customer_email_present", "subject": "Re: How do I verify my sending domain?" @@ -153,12 +153,12 @@ "how_to_run": "runx skill godfood/support-triage-reply@sha-4887b7e3476f --registry https://api.runx.ai --input support_request= --input policy= --json", "how_to_verify": "Download dogfood-receipt.json from source, set RUNX_RECEIPT_VERIFY_KID=runx-demo-key and RUNX_RECEIPT_VERIFY_ED25519_PUBLIC_KEY_BASE64 to the public key in this evidence file, then run runx verify --receipt dogfood-receipt.json --json.", "dogfood_draft_subject": "Re: How do I verify my sending domain?", - "dogfood_draft_body": "Hi Mira,\n\nThanks for the note. You asked about How do I verify my sending domain?.\n\nFor Nitrosend domain verification, check that the DNS records shown in the sending-domain setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.\n\nBefore sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.\n\nThanks,\nNitrosend Support", + "dogfood_draft_body": "Hi Mira,\n\nThanks for the note. You asked about How do I verify my sending domain?.\n\nFor sending-domain verification, check that the DNS records shown in the setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.\n\nBefore sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.\n\nThanks,\nExampleDesk Support", "dogfood_output": { "classification": "how_to", "confidence": 0.88, "draft_email": { - "body": "Hi Mira,\n\nThanks for the note. You asked about How do I verify my sending domain?.\n\nFor Nitrosend domain verification, check that the DNS records shown in the sending-domain setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.\n\nBefore sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.\n\nThanks,\nNitrosend Support", + "body": "Hi Mira,\n\nThanks for the note. You asked about How do I verify my sending domain?.\n\nFor sending-domain verification, check that the DNS records shown in the setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain.\n\nBefore sending, an operator should confirm the product state and any account-specific details. This draft has not been sent.\n\nThanks,\nExampleDesk Support", "proposed": true, "recipient_hint": "customer_email_present", "subject": "Re: How do I verify my sending domain?" diff --git a/skills/support-triage-reply/references/report.md b/skills/support-triage-reply/references/report.md index b2c09d37e..b4f2f1c95 100644 --- a/skills/support-triage-reply/references/report.md +++ b/skills/support-triage-reply/references/report.md @@ -11,9 +11,9 @@ `runx registry read godfood/support-triage-reply@ --registry https://api.runx.ai --json` - Trust tier: `community` -The skill is intentionally generic. Nitrosend has private support-ops skills -for triage/intake, but this public artifact does not include Nitrosend-private -policy, credentials, customer data, or mutation paths. +The skill is intentionally generic. Product-specific support-ops skills can +compose it, but this public artifact does not include private product policy, +credentials, customer data, or mutation paths. ## What It Does @@ -83,12 +83,12 @@ Hi Mira, Thanks for the note. You asked about How do I verify my sending domain?. -For Nitrosend domain verification, check that the DNS records shown in the sending-domain setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain. +For sending-domain verification, check that the DNS records shown in the setup are published exactly, then run the domain verification check again after DNS propagation. If a record still fails, compare the host/name and value fields character for character, including whether your DNS provider automatically appends the root domain. Before sending, an operator should confirm the product state and any account-specific details. This draft has not been sent. Thanks, -Nitrosend Support +ExampleDesk Support ``` Receipt verification: diff --git a/skills/work-plan/X.yaml b/skills/work-plan/X.yaml index ae4842f3d..b376126c1 100644 --- a/skills/work-plan/X.yaml +++ b/skills/work-plan/X.yaml @@ -1,5 +1,5 @@ skill: work-plan -version: "0.1.1" +version: "0.1.2" catalog: kind: skill @@ -121,7 +121,7 @@ harness: - name: work-plan-phased-workspace-plan inputs: objective: Roll out abandoned cart recovery across api, app, and mcp - project_context: Nitrosend workspace with repo-local worker lanes + project_context: Example workspace with repo-local worker lanes change_set: change_set_id: change_set_abandoned_cart_982 thread_locator: support://request/982 @@ -199,7 +199,7 @@ harness: parallelizable: false repo_change_requests: - id: api-abandoned-cart - repo: nitrosend/api + repo: acme/api task_id: issue-982-api objective: Implement backend abandoned cart flow rules and emit the contract surface. depends_on: [] @@ -215,7 +215,7 @@ harness: parallelizable: true repo_change_requests: - id: app-abandoned-cart - repo: nitrosend/app + repo: acme/app task_id: issue-982-app objective: Update operator and user-facing app surfaces to match the backend flow contract. depends_on: @@ -226,7 +226,7 @@ harness: - pnpm test mutating: true - id: mcp-abandoned-cart - repo: nitrosend/mcp + repo: acme/mcp task_id: issue-982-mcp objective: Align MCP capabilities and exposed operations with the frozen backend contract. depends_on: @@ -248,7 +248,7 @@ harness: - git.write mutating: true inputs: - target_repo: nitrosend/api + target_repo: acme/api context_from: - change_set description: Implement the backend contract first and freeze the shared interface. @@ -258,7 +258,7 @@ harness: - git.write mutating: true inputs: - target_repo: nitrosend/app + target_repo: acme/app context_from: - freeze-contract description: Update the app against the frozen backend contract. @@ -268,7 +268,7 @@ harness: - git.write mutating: true inputs: - target_repo: nitrosend/mcp + target_repo: acme/mcp context_from: - freeze-contract description: Update the MCP layer against the frozen backend contract. diff --git a/tests/official-skill-catalog.test.ts b/tests/official-skill-catalog.test.ts index 05c9e288a..7b82b5172 100644 --- a/tests/official-skill-catalog.test.ts +++ b/tests/official-skill-catalog.test.ts @@ -57,7 +57,7 @@ const publicCatalogPackages = [ "review-receipt", "review-skill", "run-history-analyst", - "runx-operator", + "ops-desk", "sandbox-harden", "send-as", "settle-invoice", From 0b4bb75e09b12315e988c8b244150f5c740aa45e Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 19:55:09 +1000 Subject: [PATCH 55/64] test(cli): align sourcey native graph expectation --- packages/cli/src/index.test.ts | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/packages/cli/src/index.test.ts b/packages/cli/src/index.test.ts index f8fa48c5c..c04d0a871 100644 --- a/packages/cli/src/index.test.ts +++ b/packages/cli/src/index.test.ts @@ -389,8 +389,8 @@ Return the provided task id. status: "needs_agent", requests: [ { - id: "agent_task.sourcey-discover.output", - kind: "agent_act", + id: "graph.required-inputs", + kind: "graph.required_inputs", }, ], }); @@ -1310,8 +1310,8 @@ Answer the prompt directly. status: "needs_agent", requests: [ { - id: "agent_task.sourcey-discover.output", - kind: "agent_act", + id: "graph.required-inputs", + kind: "graph.required_inputs", }, ], }); From 69696fd1cb9475d0d4c8b20ab52ea133c6016d3a Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 20:01:08 +1000 Subject: [PATCH 56/64] fix(skills): repair release validation fixtures --- .../invalid-product-specific-field.json | 2 +- skills/governed-outbound/X.yaml | 14 +++++++------- 2 files changed, 8 insertions(+), 8 deletions(-) diff --git a/fixtures/contracts/operational-proposal/invalid-product-specific-field.json b/fixtures/contracts/operational-proposal/invalid-product-specific-field.json index b4264ceba..9af0a0ee8 100644 --- a/fixtures/contracts/operational-proposal/invalid-product-specific-field.json +++ b/fixtures/contracts/operational-proposal/invalid-product-specific-field.json @@ -1 +1 @@ -{"description":"Invalid operational proposal fixture with product-specific public fields.","expected":{"authority":{"final_decision_authority_granted":false,"mutation_authority_granted":false,"proposal_only":true,"publication_authority_granted":false},"confidence":0.8,"decision_summary":"Product-specific public fields must fail.","hydrated_context_ref":{"type":"artifact","uri":"runx:artifact:hydrated_context_invalid"},"idempotency":{"fingerprint":"sha256:invalid-product-field","key":"operational-proposal:invalid:product-field"},"product_owner":"Kam","owner_route_id":"api-owner","proposal_id":"proposal_invalid_product_field","proposal_kind":"escalation","public_summary":"Invalid proposal with product-specific field.","rationale":"Public contracts use abstract owner routes, not product-specific owner fields.","recommended_actions":[{"action_intent":"tracking-to-change","mutating":true,"summary":"Build a fix."}],"redaction_status":"redacted","schema":"runx.operational_proposal.v1","source_event_id":"source_event_invalid","source_ref":{"locator":"thread/invalid","provider":"generic","type":"provider_thread","uri":"provider://source/thread/invalid"}},"fixture_kind":"operational_proposal_invalid","name":"invalid-product-specific-field","scope":"operational-proposal"} +{"description":"Invalid operational proposal fixture with product-specific public fields.","expected":{"authority":{"final_decision_authority_granted":false,"mutation_authority_granted":false,"proposal_only":true,"publication_authority_granted":false},"confidence":0.8,"decision_summary":"Product-specific public fields must fail.","hydrated_context_ref":{"type":"artifact","uri":"runx:artifact:hydrated_context_invalid"},"idempotency":{"fingerprint":"sha256:invalid-product-field","key":"operational-proposal:invalid:product-field"},"owner_route_id":"api-owner","product_owner":"Kam","proposal_id":"proposal_invalid_product_field","proposal_kind":"escalation","public_summary":"Invalid proposal with product-specific field.","rationale":"Public contracts use abstract owner routes, not product-specific owner fields.","recommended_actions":[{"action_intent":"tracking-to-change","mutating":true,"summary":"Build a fix."}],"redaction_status":"redacted","schema":"runx.operational_proposal.v1","source_event_id":"source_event_invalid","source_ref":{"locator":"thread/invalid","provider":"generic","type":"provider_thread","uri":"provider://source/thread/invalid"}},"fixture_kind":"operational_proposal_invalid","name":"invalid-product-specific-field","scope":"operational-proposal"} diff --git a/skills/governed-outbound/X.yaml b/skills/governed-outbound/X.yaml index a09f5260a..9c692c163 100644 --- a/skills/governed-outbound/X.yaml +++ b/skills/governed-outbound/X.yaml @@ -143,7 +143,7 @@ runners: inputs: mode: redact context: - content: fetch-source.fetch_result.extracted + content: fetch-source.fetch_result_packet.data.extracted artifacts: wrap_as: redaction_report - id: approve-send @@ -154,9 +154,9 @@ runners: gate_id: governed-outbound.send.approval reason: Approve delivery of the scrubbed content; review the redaction verdict and residual risk before it leaves the boundary. context: - decision: scrub-content.redaction_report.decision - residual_risk: scrub-content.redaction_report.residual_risk - redacted_digest: scrub-content.redaction_report.redacted_digest + decision: scrub-content.redaction_report_packet.data.decision + residual_risk: scrub-content.redaction_report_packet.data.residual_risk + redacted_digest: scrub-content.redaction_report_packet.data.redacted_digest artifacts: wrap_as: approval_decision packet: runx.approval.decision.v1 @@ -171,7 +171,7 @@ runners: audience: "$input.channel" provider_context: "$input.operator_context" context: - content_ref: scrub-content.redaction_report + content_ref: scrub-content.redaction_report_packet.data artifacts: wrap_as: send_plan - id: seal-run @@ -183,12 +183,12 @@ runners: inputs: action: governed outbound post context: - evidence: post-notice.send_plan + evidence: post-notice.send_plan_packet.data policy: guards: - step: post-notice field: approve-send.approval_decision.data.approved equals: true - step: post-notice - field: scrub-content.redaction_report.decision + field: scrub-content.redaction_report_packet.data.decision equals: ready From be3157f588961dad5452946167219da77541f975 Mon Sep 17 00:00:00 2001 From: kam Date: Sun, 21 Jun 2026 20:07:32 +1000 Subject: [PATCH 57/64] fix(skills): declare send plan packet schema --- crates/runx-cli/src/official_skills.rs | 2 +- dist/packets/send-as.plan.v1.schema.json | 41 ++++++++++++++++++++++ packages/cli/src/official-skills.lock.json | 2 +- skills/governed-outbound/X.yaml | 1 + 4 files changed, 44 insertions(+), 2 deletions(-) create mode 100644 dist/packets/send-as.plan.v1.schema.json diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index a5a9e2776..156e98563 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -77,7 +77,7 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/governed-outbound", - version: "sha-c93e1c732950", + version: "sha-07106d71a184", digest: "e177cd002efb896e0bba7a6352f19f4d1ec575db1ef548849244ea42725356a6", }, OfficialSkillLockEntry { diff --git a/dist/packets/send-as.plan.v1.schema.json b/dist/packets/send-as.plan.v1.schema.json new file mode 100644 index 000000000..28849247b --- /dev/null +++ b/dist/packets/send-as.plan.v1.schema.json @@ -0,0 +1,41 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.runx.dev/runx/send-as/plan/v1.json", + "x-runx-packet-id": "runx.send_as.plan.v1", + "$defs": { + "sendPlan": { + "type": "object", + "properties": { + "decision": { "type": "string" }, + "audience": { + "type": "object", + "additionalProperties": true + }, + "content": { + "type": "object", + "additionalProperties": true + }, + "principal": { "type": "string" }, + "send_class": { "type": "string" }, + "gates": { + "type": "object", + "additionalProperties": true + }, + "blockers": { "type": "array" }, + "runtime_path": { "type": "string" }, + "provider_actions": { + "type": "array", + "items": { "type": "string" } + } + }, + "additionalProperties": true + } + }, + "allOf": [ + { "$ref": "#/$defs/sendPlan" } + ], + "properties": { + "data": { "$ref": "#/$defs/sendPlan" } + }, + "additionalProperties": true +} diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index 578f82565..cd35da07f 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -92,7 +92,7 @@ }, { "skill_id": "runx/governed-outbound", - "version": "sha-c93e1c732950", + "version": "sha-07106d71a184", "digest": "e177cd002efb896e0bba7a6352f19f4d1ec575db1ef548849244ea42725356a6", "catalog_visibility": "public", "catalog_role": "context" diff --git a/skills/governed-outbound/X.yaml b/skills/governed-outbound/X.yaml index 9c692c163..577212f6a 100644 --- a/skills/governed-outbound/X.yaml +++ b/skills/governed-outbound/X.yaml @@ -174,6 +174,7 @@ runners: content_ref: scrub-content.redaction_report_packet.data artifacts: wrap_as: send_plan + packet: runx.send_as.plan.v1 - id: seal-run label: seal the run to the ledger skill: ../sign-receipt From 3af96ccfa487c6606b30243f5b8d2b9aaeaffdbf Mon Sep 17 00:00:00 2001 From: kam Date: Mon, 22 Jun 2026 01:14:11 +1000 Subject: [PATCH 58/64] docs: sharpen business ops readme trace --- README.md | 2 +- docs/assets/ops-fanout.svg | 148 +++++++++++++++++++++++-------------- 2 files changed, 94 insertions(+), 56 deletions(-) diff --git a/README.md b/README.md index 60673853d..0df368c4e 100644 --- a/README.md +++ b/README.md @@ -70,7 +70,7 @@ runx skill business-ops \ --json ``` -![Basic runx business ops graph](docs/assets/ops-fanout.svg) +![runx business ops execution trace](docs/assets/ops-fanout.svg) The graph is the core shape: goal in, governed lanes out, receipts and approval gates back. Real teams replace the demo lanes with private context, policies, diff --git a/docs/assets/ops-fanout.svg b/docs/assets/ops-fanout.svg index 5c178b325..d2a4363c8 100644 --- a/docs/assets/ops-fanout.svg +++ b/docs/assets/ops-fanout.svg @@ -1,79 +1,117 @@ - - runx business operator graph - A clean graph showing a business goal entering the runx business-ops skill, fanning into governed lanes, and resolving into receipt or approval outcomes. + + runx business ops trace + A runx business ops trace showing one command becoming a classified route, fanning into governed skill lanes, stopping consequential work at approval gates, linking child receipts into one graph receipt, and returning as a replay loop. - - + + - + + + - - goal - prepare API v2 + execution trace + one business goal becomes a replayable chain of skills + safe work fans out. consequential work stops at gates. proof comes back as receipts. - + + + + + $ runx skill business-ops + signal: prepare API v2 + stop before live actions - - - runx skill - business-ops - intake, plan, route, gate + - - + + runx graph + classify route + authority, lanes, gates, + handoffs, readbacks + - - - - - - + - - docs from evidence + + route packet + typed instructions + for each lane + not ambient trust - - release readiness + + + + + + - - receipt audit + + + draft lane + sourcey docs + draft from evidence - - issue-to-PR + + + release gate + release.prepare + publish waits - - customer comms + + + operator gate + issue-to-pr + merge waits - - spend review + + + send and spend gates + send-as + spend.quote + send and payment wait - - + - - receipt - prove the run + + receipt braid + child receipts link + into one graph receipt + replayable audit trail + - - approval - approve first + receipt-backed replay + same route, same gates From 4e3609641fcad7c3a761ce51cde3cb82979fd7c5 Mon Sep 17 00:00:00 2001 From: kam Date: Mon, 22 Jun 2026 02:05:32 +1000 Subject: [PATCH 59/64] feat(cli): harden skills and governed data plane Update the native CLI skill execution/export surfaces, add governed data-plane contracts and fixtures, refresh official skill catalog coverage, and remove local .ai state from Git tracking. Validation: pnpm bindings:check; pnpm exec tsc --noEmit --allowJs --checkJs --module NodeNext --moduleResolution NodeNext --target ES2022 --skipLibCheck scripts/check-upstream-skill-bindings.mjs; git diff --check --- .gitignore | 4 +- bindings/README.md | 28 + crates/runx-cli/Cargo.toml | 2 +- crates/runx-cli/src/export.rs | 1 + crates/runx-cli/src/export/managed.rs | 11 +- crates/runx-cli/src/export/shim.rs | 14 +- crates/runx-cli/src/history.rs | 18 +- crates/runx-cli/src/launcher.rs | 38 +- crates/runx-cli/src/lib.rs | 2 +- crates/runx-cli/src/main.rs | 5 +- crates/runx-cli/src/official_skills.rs | 33 +- crates/runx-cli/src/registry/package.rs | 331 +++++++++- crates/runx-cli/src/resume.rs | 188 +++++- crates/runx-cli/src/skill.rs | 326 +++++++++- crates/runx-cli/src/skill/inputs.rs | 53 ++ crates/runx-cli/src/skill/output.rs | 36 +- crates/runx-cli/src/skill/parser.rs | 157 ++++- crates/runx-cli/tests/export.rs | 17 +- crates/runx-cli/tests/launcher.rs | 21 +- crates/runx-cli/tests/skill.rs | 5 +- crates/runx-runtime/src/adapter.rs | 37 ++ crates/runx-runtime/src/adapters/catalog.rs | 263 +++++++- .../runx-runtime/src/adapters/mcp/server.rs | 2 +- .../src/execution/runner/steps.rs | 19 +- .../runx-runtime/src/registry/trust_anchor.rs | 54 ++ crates/runx-runtime/src/services.rs | 2 +- crates/runx-runtime/src/services/env.rs | 62 +- crates/runx-runtime/tests/catalog_adapter.rs | 493 +++++++++++++++ crates/runx-runtime/tests/skill_run.rs | 100 +++ docs/cli-exit-codes.md | 2 +- docs/demo-inventory.json | 9 +- docs/demos.md | 3 +- docs/governed-data-plane.md | 406 +++++++++++++ docs/loop-orchestration.md | 5 + docs/orchestrator-integrations.md | 7 +- docs/reference.md | 25 +- docs/skill-quality-standard.md | 15 +- docs/skill-to-graph.md | 45 ++ package.json | 1 + packages/cli/src/args.ts | 11 +- packages/cli/src/commands/history.ts | 2 +- packages/cli/src/dispatch.ts | 3 + packages/cli/src/index.test.ts | 29 +- packages/cli/src/official-skills.lock.json | 41 +- packages/cli/src/presentation/needs-agent.ts | 3 +- packages/cli/src/skill-refs.test.ts | 84 +-- packages/contracts/src/index.test.ts | 65 ++ packages/contracts/src/index.ts | 12 + packages/contracts/src/internal.ts | 2 + .../contracts/src/schemas/data-operation.ts | 72 +++ packages/langchain/src/index.test.ts | 20 +- packages/langchain/src/index.ts | 19 +- packages/sdk-python/runx/__init__.py | 8 +- packages/sdk-python/tests/test_runx.py | 5 +- scripts/check-upstream-skill-bindings.mjs | 180 ++++++ scripts/verify-fast.mjs | 1 + skills/business-ops/SKILL.md | 9 + skills/business-ops/X.yaml | 61 +- .../fixtures/route-and-append-sqlite.yaml | 28 + skills/data-store/SKILL.md | 272 +++++++++ skills/data-store/X.yaml | 207 +++++++ .../fixtures/append-local-event.yaml | 27 + .../append-read-default-sqlite-event.yaml | 30 + .../fixtures/append-read-local-event.yaml | 31 + .../fixtures/append-read-sqlite-event.yaml | 32 + .../fixtures/append-version-conflict.yaml | 27 + .../fixtures/read-local-events.yaml | 22 + .../fixtures/read-local-projection.yaml | 21 + .../data-store/tools/data/local/manifest.json | 77 +++ skills/data-store/tools/data/local/run.mjs | 335 ++++++++++ skills/data-store/tools/data/redis/README.md | 42 ++ .../data-store/tools/data/redis/manifest.json | 87 +++ skills/data-store/tools/data/redis/run.mjs | 426 +++++++++++++ skills/data-store/tools/data/sqlite/README.md | 63 ++ .../tools/data/sqlite/manifest.json | 82 +++ skills/data-store/tools/data/sqlite/run.mjs | 546 +++++++++++++++++ skills/dependency-cve-audit/SKILL.md | 15 +- skills/dependency-cve-audit/X.yaml | 17 +- .../fixtures/nodegoat-direct-production.yaml | 19 + skills/github-sync/SKILL.md | 17 + skills/github-sync/X.yaml | 83 ++- .../plan-and-append-cursor-sqlite.yaml | 53 ++ .../fixtures/issue-to-pr-harness-scafld.mjs | 5 + .../scafld/fixtures/scafld-v2-harness.mjs | 5 + skills/messageboard/SKILL.md | 29 +- skills/messageboard/X.yaml | 290 ++++++++- .../fixtures/accept-and-append-sqlite.yaml | 48 ++ .../fixtures/claim-and-append-conflict.yaml | 45 ++ .../fixtures/claim-and-append-sqlite.yaml | 45 ++ .../fixtures/deliver-and-append-sqlite.yaml | 47 ++ .../fixtures/post-and-append-sqlite.yaml | 58 ++ skills/ops-desk/SKILL.md | 9 + skills/ops-desk/X.yaml | 77 ++- .../operate-from-sqlite-projection.yaml | 63 ++ skills/structured-extraction/README.md | 21 - skills/structured-extraction/SKILL.md | 150 ++++- skills/structured-extraction/X.yaml | 20 +- .../fixtures/rfc9110-http-semantics.yaml | 13 +- skills/support-triage-reply/SKILL.md | 172 ++++-- skills/support-triage-reply/X.yaml | 58 +- ...ccount-access-escalates-without-draft.yaml | 25 + .../fixtures/missing-request-fails.yaml | 17 + .../fixtures/safe-how-to-reply-draft.yaml | 25 + tests/cli-skill-registry-profile.test.ts | 32 +- tests/data-adapter-conformance.test.ts | 574 ++++++++++++++++++ tests/data-store-skill.test.ts | 50 ++ tests/official-skill-catalog.test.ts | 75 +-- tests/official-skill-fetch.test.ts | 151 +++-- 108 files changed, 7555 insertions(+), 575 deletions(-) create mode 100644 docs/governed-data-plane.md create mode 100644 packages/contracts/src/schemas/data-operation.ts create mode 100644 scripts/check-upstream-skill-bindings.mjs create mode 100644 skills/business-ops/fixtures/route-and-append-sqlite.yaml create mode 100644 skills/data-store/SKILL.md create mode 100644 skills/data-store/X.yaml create mode 100644 skills/data-store/fixtures/append-local-event.yaml create mode 100644 skills/data-store/fixtures/append-read-default-sqlite-event.yaml create mode 100644 skills/data-store/fixtures/append-read-local-event.yaml create mode 100644 skills/data-store/fixtures/append-read-sqlite-event.yaml create mode 100644 skills/data-store/fixtures/append-version-conflict.yaml create mode 100644 skills/data-store/fixtures/read-local-events.yaml create mode 100644 skills/data-store/fixtures/read-local-projection.yaml create mode 100644 skills/data-store/tools/data/local/manifest.json create mode 100644 skills/data-store/tools/data/local/run.mjs create mode 100644 skills/data-store/tools/data/redis/README.md create mode 100644 skills/data-store/tools/data/redis/manifest.json create mode 100644 skills/data-store/tools/data/redis/run.mjs create mode 100644 skills/data-store/tools/data/sqlite/README.md create mode 100644 skills/data-store/tools/data/sqlite/manifest.json create mode 100644 skills/data-store/tools/data/sqlite/run.mjs create mode 100644 skills/dependency-cve-audit/fixtures/nodegoat-direct-production.yaml create mode 100644 skills/github-sync/fixtures/plan-and-append-cursor-sqlite.yaml create mode 100644 skills/messageboard/fixtures/accept-and-append-sqlite.yaml create mode 100644 skills/messageboard/fixtures/claim-and-append-conflict.yaml create mode 100644 skills/messageboard/fixtures/claim-and-append-sqlite.yaml create mode 100644 skills/messageboard/fixtures/deliver-and-append-sqlite.yaml create mode 100644 skills/messageboard/fixtures/post-and-append-sqlite.yaml create mode 100644 skills/ops-desk/fixtures/operate-from-sqlite-projection.yaml delete mode 100644 skills/structured-extraction/README.md create mode 100644 skills/support-triage-reply/fixtures/account-access-escalates-without-draft.yaml create mode 100644 skills/support-triage-reply/fixtures/missing-request-fails.yaml create mode 100644 skills/support-triage-reply/fixtures/safe-how-to-reply-draft.yaml create mode 100644 tests/data-adapter-conformance.test.ts create mode 100644 tests/data-store-skill.test.ts diff --git a/.gitignore b/.gitignore index 6ecafe16f..54a5e43a3 100644 --- a/.gitignore +++ b/.gitignore @@ -3,9 +3,7 @@ **/.DS_Store # scafld -.ai/logs/ -.ai/reviews/ -.ai/runs/ +.ai/ # dependencies node_modules/ diff --git a/bindings/README.md b/bindings/README.md index d4ea5f16b..e07ee5248 100644 --- a/bindings/README.md +++ b/bindings/README.md @@ -10,6 +10,14 @@ document. This directory stores runx-owned binding data: - `X.yaml`: the execution profile artifact containing runner metadata, harness cases, policy, scopes, and receipt expectations. +Use `bindings/` only when runx does **not** own the upstream `SKILL.md`. +First-party runx packages belong in `skills//`. Product-specific operator +wrappers belong in the product repo that owns their policy. + +Do not add candidate or placeholder directories here. A binding is eligible only +after the upstream repository has a merged, pinned `SKILL.md` that starts with +YAML frontmatter and a `name` matching `bindings//`. + Publishing materializes a pinned registry package into `dist/` from the upstream `SKILL.md` plus the local binding artifact. The generated package is an immutable registry artifact, not the source document. @@ -21,3 +29,23 @@ node scripts/materialize-upstream-skill-binding.mjs \ bindings/nilstate/icey-server-operator/binding.json \ --output-dir dist/upstream-bindings/nilstate/icey-server-operator ``` + +Validate the checked-in binding catalog: + +```bash +pnpm bindings:check +``` + +## Candidate Queue + +These are good candidates once their upstream repositories own the source +`SKILL.md`; they must not appear as binding directories before that happens. + +- `nilstate/scafld-operator` — scafld governs agent work. Add this after + `nilstate/scafld` owns a merged `SKILL.md` at a pinned commit. +- `sourcey/` — only if Sourcey moves the portable + instructions into a Sourcey-owned upstream repo. If runx owns the skill, + keep it under `skills/sourcey`. +- Real OSS project operator skills such as `contentauth/c2pa-rs`, + `napi-rs`, `hono`, or `drizzle` — only after the project accepts or hosts + its own `SKILL.md`. diff --git a/crates/runx-cli/Cargo.toml b/crates/runx-cli/Cargo.toml index fa3a39a5d..fbc9849e4 100644 --- a/crates/runx-cli/Cargo.toml +++ b/crates/runx-cli/Cargo.toml @@ -32,9 +32,9 @@ runx-receipts.workspace = true runx-runtime = { workspace = true, features = ["cli-tool", "catalog", "mcp", "mcp-http-server", "external-adapter", "agent", "http", "thread-outbox-provider"] } serde.workspace = true serde_json.workspace = true +serde_norway.workspace = true [dev-dependencies] -serde_norway.workspace = true [[bin]] name = "runx" diff --git a/crates/runx-cli/src/export.rs b/crates/runx-cli/src/export.rs index 0064c63cd..09636ff18 100644 --- a/crates/runx-cli/src/export.rs +++ b/crates/runx-cli/src/export.rs @@ -19,6 +19,7 @@ const CODEX_MARKER: &str = "runx-export:codex"; const CODEX_RULE_START: &str = "# >>> runx-export start (managed) >>>"; const CODEX_RULE_END: &str = "# <<< runx-export end <<<"; const CODEX_RULE_RUNX_ON_PATH: &str = "prefix_rule(pattern = [\"runx\", \"skill\"], decision = \"allow\", justification = \"runx skill invocations are trusted\")"; +const CODEX_RULE_RUNX_RESUME_ON_PATH: &str = "prefix_rule(pattern = [\"runx\", \"resume\"], decision = \"allow\", justification = \"runx resume invocations are trusted\")"; #[derive(Clone, Debug, Eq, PartialEq)] pub struct ExportPlan { diff --git a/crates/runx-cli/src/export/managed.rs b/crates/runx-cli/src/export/managed.rs index bb226c5e0..982b0b5eb 100644 --- a/crates/runx-cli/src/export/managed.rs +++ b/crates/runx-cli/src/export/managed.rs @@ -3,8 +3,8 @@ use std::fs; use std::path::{Path, PathBuf}; use super::{ - CODEX_RULE_END, CODEX_RULE_RUNX_ON_PATH, CODEX_RULE_START, ExportError, GeneratedFile, Target, - display_path, + CODEX_RULE_END, CODEX_RULE_RUNX_ON_PATH, CODEX_RULE_RUNX_RESUME_ON_PATH, CODEX_RULE_START, + ExportError, GeneratedFile, Target, display_path, }; pub(super) fn write_files(files: &[GeneratedFile]) -> Result<(), ExportError> { @@ -87,7 +87,7 @@ pub(super) fn merge_codex_rules(path: &Path, runx_bin: &Path) -> Result Result String { + let path = + serde_json::to_string(&display_path(runx_bin)).unwrap_or_else(|_| "\"runx\"".to_owned()); format!( - "prefix_rule(pattern = [{}, \"skill\"], decision = \"allow\", justification = \"runx skill invocations are trusted\")", - serde_json::to_string(&display_path(runx_bin)).unwrap_or_else(|_| "\"runx\"".to_owned()) + "prefix_rule(pattern = [{path}, \"skill\"], decision = \"allow\", justification = \"runx skill invocations are trusted\")\nprefix_rule(pattern = [{path}, \"resume\"], decision = \"allow\", justification = \"runx resume invocations are trusted\")" ) } diff --git a/crates/runx-cli/src/export/shim.rs b/crates/runx-cli/src/export/shim.rs index 9d4550cce..644082055 100644 --- a/crates/runx-cli/src/export/shim.rs +++ b/crates/runx-cli/src/export/shim.rs @@ -71,10 +71,7 @@ If they are absent, runx fails closed instead of creating an unverifiable receip output.push_str("\n```\n\n"); output.push_str(&render_inputs(&skill.inputs)); output.push('\n'); - output.push_str(&render_continuation( - command_target, - &display_path(runx_bin), - )); + output.push_str(&render_continuation(&display_path(runx_bin))); output.push_str(&format!( "\n", target.marker(), @@ -120,7 +117,7 @@ fn render_inputs(inputs: &BTreeMap) -> String { format!("{}\n", lines.join("\n")) } -fn render_continuation(command_target: &str, runx_bin: &str) -> String { +fn render_continuation(runx_bin: &str) -> String { format!( "\ Interpret the runx JSON result exactly: @@ -146,17 +143,14 @@ Interpret the runx JSON result exactly: Then resume the same run with the `run_id` printed by runx: ```bash -{} skill {} \\ - --run-id \"\" \\ - --answers \"\" \\ +{} resume \"\" \"\" \\ --json ``` Repeat this loop until the result is sealed or runx asks for operator approval/input. If approval or human input is required, relay the exact runx request instead of fabricating an answer. Never place signing seeds, provider tokens, or raw credentials in the answers file or response. ", - shell_quote(runx_bin), - shell_quote(command_target) + shell_quote(runx_bin) ) } diff --git a/crates/runx-cli/src/history.rs b/crates/runx-cli/src/history.rs index 5a44fd9fc..e8087b963 100644 --- a/crates/runx-cli/src/history.rs +++ b/crates/runx-cli/src/history.rs @@ -313,7 +313,7 @@ fn push_pending_run_lines( lines.push(format!(" next {resume_command}")); } else { lines.push(format!( - " next write answers.json, then rerun the original skill with --run-id {} --answers answers.json", + " next write answers.json, then resume the pending run with runx resume {} answers.json", pending.id )); } @@ -477,18 +477,13 @@ mod tests { assert!( result .output - .contains("next runx skill ../skills/sourcey --runner agent-task") + .contains("next runx resume gx_needs_agent_oracle answers.json") ); assert!( result .output .contains(&format!("--receipt-dir {}", receipt_dir_arg)) ); - assert!( - result - .output - .contains("--run-id gx_needs_agent_oracle --answers answers.json") - ); assert!( result .output @@ -512,18 +507,13 @@ mod tests { assert!( result .output - .contains("next runx skill ../skills/sourcey --runner agent-task") + .contains("next runx resume gx_needs_agent_oracle answers.json") ); assert!( !result.output.contains("--receipt-dir"), "default receipt dir must not be echoed into resume commands:\n{}", result.output ); - assert!( - result - .output - .contains("--run-id gx_needs_agent_oracle --answers answers.json") - ); Ok(()) } @@ -550,7 +540,7 @@ mod tests { assert!( result .output - .contains("with --run-id gx_needs_agent_oracle"), + .contains("runx resume gx_needs_agent_oracle answers.json"), "history output should give non-fabricated continuation guidance:\n{}", result.output ); diff --git a/crates/runx-cli/src/launcher.rs b/crates/runx-cli/src/launcher.rs index 69a458c19..fe24da58c 100644 --- a/crates/runx-cli/src/launcher.rs +++ b/crates/runx-cli/src/launcher.rs @@ -13,6 +13,7 @@ use crate::payment::{PaymentAction, PaymentAdmissionPlan, PaymentInputSource, Pa use crate::policy::{PolicyAction, PolicyPlan}; use crate::publish::PublishPlan; use crate::registry::{RegistryAction, RegistryPlan}; +use crate::resume::ResumePlan; use crate::skill::SkillPlan; #[derive(Debug, PartialEq)] @@ -37,6 +38,7 @@ pub enum LauncherAction { RunPolicy(PolicyPlan), RunPublish(PublishPlan), RunRegistry(RegistryPlan), + RunResume(ResumePlan), RunSkill(SkillPlan), RunTool(ToolPlan), RunUrlAdd(UrlAddPlan), @@ -48,6 +50,7 @@ pub enum LauncherAction { PrintPublishHelp, PrintRegistryHelp, PrintRegistryUsageError, + PrintResumeHelp, PrintSkillHelp, PrintVerifyHelp, PrintVersion, @@ -265,6 +268,16 @@ pub fn plan_launcher(args: Vec) -> LauncherAction { return LauncherAction::RunHistory(HistoryPlan { args }); } + if first_arg_is(&args, "resume") { + if nested_help_requested(&args) { + return LauncherAction::PrintResumeHelp; + } + return crate::resume::parse_resume_plan(&args).map_or_else( + |message| json_or_human_error(&args, message), + LauncherAction::RunResume, + ); + } + if first_arg_is(&args, "verify") { if nested_help_requested(&args) { return LauncherAction::PrintVerifyHelp; @@ -344,6 +357,7 @@ Commands: runx init [-g|--global] [--prefetch official] [--json] runx verify [receipt-id] [--receipt-dir dir] [--receipt ] [--notary --notary-key trusted.pem] [-j|--json] runx history [query] [--skill s] [--status s] [--source s] [--actor a] [--artifact-type t] [--since iso] [--until iso] [--receipt-dir dir] [--json] + runx resume [-R dir] [-j|--json] runx list [tools|skills|graphs|packets|overlays] [--ok-only|--invalid-only] [-j|--json] runx login [--provider github|google|gitlab] [--for default|publish] [--api-url url] [--local-api] [-j|--json] runx config set|get|list [provider|model|api-key|public-token] [value] [-j|--json] @@ -356,7 +370,7 @@ Commands: runx dev [root] [--lane lane] [--json] runx export [skill-ref...] [--project] [--json] runx mcp serve [--receipt-dir dir] [--http-listen [addr]] [--http-allow-non-loopback] - runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] [--run-id id --answers file] + runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [--run] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--api-base-url url] [--json] runx harness [-R dir] [-j|--json] runx tool build |--all [--json] @@ -388,6 +402,21 @@ Options: .to_owned() } +pub fn resume_help_text() -> String { + "\ +runx resume + +Usage: + runx resume [-R dir] [-j|--json] + +Options: + -R, --receipts dir + --receipt-dir dir + -j, --json +" + .to_owned() +} + pub fn list_help_text() -> String { "\ runx list @@ -507,22 +536,21 @@ pub fn skill_help_text() -> String { runx skill Usage: - runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] [--run-id id --answers file] + runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [--run] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] Options: -p, --profile name Use a local credential profile from .runx/credentials.json -i, --input key=value Set a structured input; repeat for multiple inputs + --input-json key=json Set an input that must parse as JSON + --run Execute a zero-input runner instead of inspecting it -R, --receipts dir Write receipts under dir --receipt-dir dir Alias for --receipts -j, --json Print machine-readable output - --runner name Select a named runner from X.yaml --registry url|path --digest sha256 --flag value --credential descriptor One-shot local credential descriptor --secret-env NAME Env var holding the one-shot credential secret - --run-id id - --answers file " .to_owned() } diff --git a/crates/runx-cli/src/lib.rs b/crates/runx-cli/src/lib.rs index 893158a07..7b0efdf5a 100644 --- a/crates/runx-cli/src/lib.rs +++ b/crates/runx-cli/src/lib.rs @@ -18,7 +18,7 @@ pub(crate) mod public_api; pub(crate) mod public_api_token; pub mod publish; pub mod registry; -pub(crate) mod resume; +pub mod resume; pub mod runtime; pub mod scaffold; pub mod skill; diff --git a/crates/runx-cli/src/main.rs b/crates/runx-cli/src/main.rs index a9bb1b993..03f6df4ac 100644 --- a/crates/runx-cli/src/main.rs +++ b/crates/runx-cli/src/main.rs @@ -8,7 +8,8 @@ use std::process::ExitCode; use runx_cli::launcher::{ HarnessPlan, LauncherAction, add_help_text, help_text, history_help_text, list_help_text, - login_help_text, publish_help_text, registry_help_text, skill_help_text, verify_help_text, + login_help_text, publish_help_text, registry_help_text, resume_help_text, skill_help_text, + verify_help_text, }; const INLINE_HARNESS_SIGNING_HINT: &str = "runx: hint: inline harnesses seal signed receipts; set RUNX_RECEIPT_SIGN_KID, RUNX_RECEIPT_SIGN_ED25519_SEED_BASE64, and RUNX_RECEIPT_SIGN_ISSUER_TYPE, or run the example's run.sh when one is provided."; @@ -36,6 +37,7 @@ fn main() -> ExitCode { let _ignored = write_stderr_line(®istry_help_text()); ExitCode::from(64) } + LauncherAction::PrintResumeHelp => write_stdout(&resume_help_text()), LauncherAction::PrintSkillHelp => write_stdout(&skill_help_text()), LauncherAction::PrintVerifyHelp => write_stdout(&verify_help_text()), LauncherAction::PrintVersion => { @@ -56,6 +58,7 @@ fn main() -> ExitCode { LauncherAction::RunPolicy(plan) => runx_cli::policy::run_native_policy(plan), LauncherAction::RunPublish(plan) => runx_cli::publish::run_native_publish(plan), LauncherAction::RunRegistry(plan) => runx_cli::registry::run_native_registry(plan), + LauncherAction::RunResume(plan) => runx_cli::resume::run_native_resume(plan), LauncherAction::RunSkill(plan) => runx_cli::skill::run_native_skill(plan), LauncherAction::RunDoctor(plan) => runx_cli::doctor::run_native_doctor(plan), LauncherAction::RunDev(plan) => runx_cli::dev::run_native_dev(plan), diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index 156e98563..8469e4b01 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -17,8 +17,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/business-ops", - version: "sha-542469f72fa2", - digest: "f319e45b875aab442ead32ecddd194c715bfd585f1504d9e9c3d7bcbb914e342", + version: "sha-fd875c18ba3d", + digest: "7801492f5b8fa34f0f6e91f9f2729396744c35fe517ae275885e07204bc52b6f", }, OfficialSkillLockEntry { skill_id: "runx/charge", @@ -30,6 +30,11 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ version: "sha-0efcbf2abed1", digest: "b93475f254b458a92936cd4612b8d01a59c371876b810eb242b06ce184f2b798", }, + OfficialSkillLockEntry { + skill_id: "runx/data-store", + version: "sha-1b3887a55009", + digest: "05ed91ab2873f7ccf1a898166f79c1ebae2542924e5444fa8b504a9aa2f22f76", + }, OfficialSkillLockEntry { skill_id: "runx/deep-research-brief", version: "sha-c2d071df7f50", @@ -37,8 +42,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/dependency-cve-audit", - version: "sha-016cc407efa2", - digest: "c19ec9fdeb088daab950b7c2e1f3757880de9702e31e40b57e2f65c0c4033348", + version: "sha-6db720882ba0", + digest: "427c964bccd3f5f41c71a90905dd74225547e8b7af11015978e4550db3c27249", }, OfficialSkillLockEntry { skill_id: "runx/design-skill", @@ -72,8 +77,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/github-sync", - version: "sha-703346713bf3", - digest: "83b0f4cd98cf23ff81ec71727543e6d811e75aa970cf957bec4267575a16efcc", + version: "sha-1a2573539bb7", + digest: "6981adc877736f05a41d764b3e42d479d87de3bc2d69a65992dff457b635bd9a", }, OfficialSkillLockEntry { skill_id: "runx/governed-outbound", @@ -132,8 +137,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/messageboard", - version: "sha-a694b4c2d459", - digest: "0f65121f1cfe18d13f6da323cf1bc6edcf492e521360888e2bb21920cb1b8967", + version: "sha-7b9930ac9727", + digest: "7fb6092161a234fbea28681ec5e72afd9c2d380e547cf4ef97683f28bb9a6427", }, OfficialSkillLockEntry { skill_id: "runx/mock-charge", @@ -192,8 +197,8 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/ops-desk", - version: "sha-57c1b0df97f6", - digest: "d468d7984b8a7736cb760373c5348007eed1f387567814f39ac82eb39e58150a", + version: "sha-5e1d3dc7c252", + digest: "386e43482f0bb6eaacd50fd836cd0dc112ad70eca8625bcaf50d8a86e6226f07", }, OfficialSkillLockEntry { skill_id: "runx/overlay-generator", @@ -327,13 +332,13 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ }, OfficialSkillLockEntry { skill_id: "runx/structured-extraction", - version: "sha-a826aca27a7a", - digest: "ebe37921d3b9cb63aa1ca5232a8075607d3b4ad541af4c1bc901ace749ea404f", + version: "sha-22eeb86d17f4", + digest: "2c83db0c1f170af2e84ca0237e0850108254415bdcffdc57d2a6e66197cef133", }, OfficialSkillLockEntry { skill_id: "runx/support-triage-reply", - version: "sha-a605f6b30db4", - digest: "e945d181db20fbb0f2432ad7fd5b5fbc438deb1cdbe4eacad169641e24670416", + version: "sha-93233458fd14", + digest: "5c6fc18bf3013a1845de83641147f8421ceb1599269e4b3ed111d25e75053fda", }, OfficialSkillLockEntry { skill_id: "runx/taste-profile", diff --git a/crates/runx-cli/src/registry/package.rs b/crates/runx-cli/src/registry/package.rs index d37a8af23..92e03729c 100644 --- a/crates/runx-cli/src/registry/package.rs +++ b/crates/runx-cli/src/registry/package.rs @@ -65,8 +65,21 @@ pub(super) fn read_skill_package( } else { Vec::new() }; + let harness_package_files = if include_harness { + collect_publish_harness_package_files( + &markdown_path, + profile_path.as_deref(), + &package_files, + )? + } else { + Vec::new() + }; let harness_package = if include_harness { - publish_harness_package(&markdown, profile_document.as_deref(), &package_files)? + publish_harness_package( + &markdown, + profile_document.as_deref(), + &harness_package_files, + )? } else { PublishHarnessPackage { path: None, @@ -208,7 +221,7 @@ fn publish_harness_package( )) })?; } - fs::write(&destination, &file.content).map_err(|error| { + write_publish_harness_file(&destination, &file.content).map_err(|error| { internal_error(format!( "failed to write publish harness package file {}: {error}", destination.display() @@ -221,6 +234,28 @@ fn publish_harness_package( }) } +fn write_publish_harness_file(path: &Path, content: &str) -> Result<(), std::io::Error> { + fs::write(path, content)?; + mark_executable_if_script(path, content) +} + +#[cfg(unix)] +fn mark_executable_if_script(path: &Path, content: &str) -> Result<(), std::io::Error> { + if !content.starts_with("#!") { + return Ok(()); + } + use std::os::unix::fs::PermissionsExt; + + let mut permissions = fs::metadata(path)?.permissions(); + permissions.set_mode(permissions.mode() | 0o111); + fs::set_permissions(path, permissions) +} + +#[cfg(not(unix))] +fn mark_executable_if_script(_path: &Path, _content: &str) -> Result<(), std::io::Error> { + Ok(()) +} + fn collect_publish_package_files( markdown_path: &Path, profile_path: Option<&Path>, @@ -253,6 +288,150 @@ fn collect_publish_package_files( ) } +fn collect_publish_harness_package_files( + markdown_path: &Path, + profile_path: Option<&Path>, + package_files: &[HostedSkillPackageFile], +) -> Result, RegistryCliError> { + let mut files = package_files + .iter() + .cloned() + .map(|file| (file.path.clone(), file)) + .collect::>(); + let Some(profile_path) = profile_path else { + return Ok(files.into_values().collect()); + }; + let Some(package_dir) = markdown_path.parent() else { + return Ok(files.into_values().collect()); + }; + let package_dir = fs::canonicalize(package_dir).map_err(|error| { + internal_error(format!( + "failed to canonicalize skill package directory {}: {error}", + package_dir.display() + )) + })?; + let dependencies = consumed_harness_dependency_files_from_profile(profile_path)?; + let mut total_bytes = files + .values() + .map(|file| file.content.len() as u64) + .sum::(); + for declared_relative in dependencies { + for relative in resolve_publish_harness_dependency_paths(&package_dir, &declared_relative)? + { + if files.contains_key(&relative) { + continue; + } + copy_publish_harness_dependency(&package_dir, &relative, &mut files, &mut total_bytes)?; + } + } + Ok(files.into_values().collect()) +} + +fn resolve_publish_harness_dependency_paths( + package_dir: &Path, + declared_relative: &str, +) -> Result, RegistryCliError> { + if package_dir.join(declared_relative).exists() { + return Ok(vec![declared_relative.to_owned()]); + } + let graph_dir = package_dir.join("graph"); + let mut matches = Vec::new(); + let Ok(entries) = fs::read_dir(&graph_dir) else { + return Ok(vec![declared_relative.to_owned()]); + }; + for entry in entries { + let entry = entry.map_err(|error| { + internal_error(format!( + "failed to read publish harness graph dependency entry in {}: {error}", + graph_dir.display() + )) + })?; + let stage_dir = entry.path(); + if stage_dir.join(declared_relative).exists() { + let stage_name = entry.file_name().to_string_lossy().to_string(); + matches.push(format!("graph/{stage_name}/{declared_relative}")); + } + } + if matches.len() == 1 { + return Ok(matches); + } + Ok(vec![declared_relative.to_owned()]) +} + +fn copy_publish_harness_dependency( + package_dir: &Path, + relative: &str, + files: &mut BTreeMap, + total_bytes: &mut u64, +) -> Result<(), RegistryCliError> { + if files.contains_key(relative) { + return Ok(()); + } + if should_reject_remote_publish_file(relative) { + return Err(internal_error(format!( + "publish harness dependency {relative} looks like a secret or local credential" + ))); + } + let candidate = package_dir.join(relative); + let metadata = fs::symlink_metadata(&candidate).map_err(|error| { + internal_error(format!( + "failed to inspect publish harness dependency {}: {error}", + candidate.display() + )) + })?; + if !metadata.file_type().is_file() { + return Err(internal_error(format!( + "publish harness dependency {} is not a regular file", + candidate.display() + ))); + } + if metadata.len() > MAX_REMOTE_PUBLISH_FILE_BYTES { + return Err(internal_error(format!( + "publish harness dependency {} exceeds {} bytes", + candidate.display(), + MAX_REMOTE_PUBLISH_FILE_BYTES + ))); + } + *total_bytes += metadata.len(); + if *total_bytes > MAX_REMOTE_PUBLISH_TOTAL_BYTES { + return Err(internal_error(format!( + "publish harness dependencies exceed {} total bytes", + MAX_REMOTE_PUBLISH_TOTAL_BYTES + ))); + } + if files.len() >= MAX_REMOTE_PUBLISH_FILE_COUNT { + return Err(internal_error(format!( + "publish harness package cannot contain more than {MAX_REMOTE_PUBLISH_FILE_COUNT} files" + ))); + } + let canonical = fs::canonicalize(&candidate).map_err(|error| { + internal_error(format!( + "failed to canonicalize publish harness dependency {}: {error}", + candidate.display() + )) + })?; + if !canonical.starts_with(package_dir) { + return Err(internal_error(format!( + "publish harness dependency {} escapes the skill package", + candidate.display() + ))); + } + let content = fs::read_to_string(&canonical).map_err(|error| { + internal_error(format!( + "publish harness dependency {} must be UTF-8 text: {error}", + canonical.display() + )) + })?; + files.insert( + relative.to_owned(), + HostedSkillPackageFile { + path: relative.to_owned(), + content, + }, + ); + Ok(()) +} + fn collect_allowed_publish_package_files( package_dir: &Path, markdown_path: &Path, @@ -473,6 +652,91 @@ fn consumed_root_scripts_from_profile( Ok(scripts) } +fn consumed_harness_dependency_files_from_profile( + profile_path: &Path, +) -> Result, RegistryCliError> { + let document = fs::read_to_string(profile_path).map_err(|error| { + internal_error(format!( + "failed to read profile while selecting publish harness files {}: {error}", + profile_path.display() + )) + })?; + let manifest = runx_runtime::validate_runner_manifest( + runx_runtime::parse_runner_manifest_yaml(&document).map_err(|error| { + internal_error(format!( + "failed to parse profile while selecting publish harness files {}: {error}", + profile_path.display() + )) + })?, + ) + .map_err(|error| { + internal_error(format!( + "failed to validate profile while selecting publish harness files {}: {error}", + profile_path.display() + )) + })?; + let mut files = BTreeSet::new(); + if let Some(harness) = manifest.harness { + for case in harness.cases { + for value in case.inputs.values() { + collect_harness_dependency_from_value(value, &mut files); + } + for value in case.env.values() { + collect_harness_dependency_from_string(value, &mut files); + } + if let Some(answers) = case.caller.answers { + for value in answers.values() { + collect_harness_dependency_from_value(value, &mut files); + } + } + } + } + Ok(files) +} + +fn collect_harness_dependency_from_value(value: &JsonValue, files: &mut BTreeSet) { + match value { + JsonValue::String(value) => collect_harness_dependency_from_string(value, files), + JsonValue::Array(values) => { + for value in values { + collect_harness_dependency_from_value(value, files); + } + } + JsonValue::Object(values) => { + for value in values.values() { + collect_harness_dependency_from_value(value, files); + } + } + JsonValue::Bool(_) | JsonValue::Null | JsonValue::Number(_) => {} + } +} + +fn collect_harness_dependency_from_string(value: &str, files: &mut BTreeSet) { + if let Some(path) = normalize_harness_dependency_file(value) { + files.insert(path); + } +} + +fn normalize_harness_dependency_file(value: &str) -> Option { + let path = value + .trim() + .strip_prefix("./") + .unwrap_or_else(|| value.trim()); + if !(path.ends_with(".mjs") || path.ends_with(".js")) { + return None; + } + if path.is_empty() + || path.starts_with('/') + || path.contains('\\') + || path + .split('/') + .any(|segment| segment.is_empty() || segment == "." || segment == "..") + { + return None; + } + Some(path.to_owned()) +} + fn collect_root_scripts_from_source( source: &runx_runtime::SkillSource, scripts: &mut BTreeSet, @@ -604,8 +868,8 @@ fn publish_harness_report( mod tests { use super::{ PUBLISH_HARNESS_SIGNING_ISSUER_TYPE, PUBLISH_HARNESS_SIGNING_KID, - collect_publish_package_files, ensure_publish_harness_signing_env, - should_reject_remote_publish_file, unique_temp_dir, + collect_publish_harness_package_files, collect_publish_package_files, + ensure_publish_harness_signing_env, should_reject_remote_publish_file, unique_temp_dir, }; use std::fs; @@ -784,4 +1048,63 @@ runners: let _ignored = fs::remove_dir_all(dir); Ok(()) } + + #[test] + fn publish_harness_package_includes_explicit_harness_dependencies_only() + -> Result<(), Box> { + let dir = unique_temp_dir("runx-publish-harness-dependency-test")?; + fs::write( + dir.join("SKILL.md"), + "---\nname: harness-deps\n---\n# Harness deps\n", + )?; + fs::write( + dir.join("X.yaml"), + r#"skill: harness-deps +harness: + cases: + - name: fixture-helper + runner: main + inputs: + helper: ./fixtures/helper.mjs + ignored_text: ./fixtures/not-a-script.txt + expect: + status: sealed +runners: + main: + default: true + type: cli-tool + command: node + args: + - ./run.mjs + input_mode: stdin +"#, + )?; + fs::write(dir.join("run.mjs"), "console.log('run')\n")?; + fs::create_dir_all(dir.join("fixtures"))?; + fs::write(dir.join("fixtures/helper.mjs"), "console.log('helper')\n")?; + fs::write(dir.join("fixtures/not-a-script.txt"), "not copied\n")?; + + let package_files = + collect_publish_package_files(&dir.join("SKILL.md"), Some(&dir.join("X.yaml")))?; + let package_paths = package_files + .iter() + .map(|file| file.path.as_str()) + .collect::>(); + assert!(!package_paths.contains(&"fixtures/helper.mjs")); + + let harness_files = collect_publish_harness_package_files( + &dir.join("SKILL.md"), + Some(&dir.join("X.yaml")), + &package_files, + )?; + let harness_paths = harness_files + .iter() + .map(|file| file.path.as_str()) + .collect::>(); + assert!(harness_paths.contains(&"fixtures/helper.mjs")); + assert!(!harness_paths.contains(&"fixtures/not-a-script.txt")); + + let _ignored = fs::remove_dir_all(dir); + Ok(()) + } } diff --git a/crates/runx-cli/src/resume.rs b/crates/runx-cli/src/resume.rs index 0ad673826..d9d9c6b92 100644 --- a/crates/runx-cli/src/resume.rs +++ b/crates/runx-cli/src/resume.rs @@ -1,4 +1,24 @@ -use std::path::Path; +use std::collections::BTreeMap; +use std::env; +use std::ffi::OsString; +use std::io::{self, Write}; +use std::path::{Path, PathBuf}; +use std::process::ExitCode; + +use runx_runtime::journal::list_local_history; +use runx_runtime::{ + LocalReceiptStore, ReceiptPathInputs, RuntimeReceiptConfig, resolve_receipt_path, +}; + +use crate::skill::{SkillAction, SkillPlan}; + +#[derive(Debug, PartialEq, Eq)] +pub struct ResumePlan { + pub run_id: String, + pub answers_path: PathBuf, + pub receipt_dir: Option, + pub json: bool, +} pub(crate) struct SkillResumeCommand<'a> { pub(crate) skill_ref: Option<&'a str>, @@ -8,30 +28,140 @@ pub(crate) struct SkillResumeCommand<'a> { pub(crate) answers_path: Option<&'a Path>, } +pub fn parse_resume_plan(args: &[OsString]) -> Result { + if args.first().and_then(|arg| arg.to_str()) != Some("resume") { + return Err("internal error: resume dispatcher received non-resume command".to_owned()); + } + let mut receipt_dir = None; + let mut json = false; + let mut positionals = Vec::new(); + let mut index = 1; + while index < args.len() { + let token = string_arg(args, index)?; + match token.as_str() { + "--json" | "-j" => { + json = true; + index += 1; + } + "--non-interactive" => { + index += 1; + } + value if value.starts_with("--receipt-dir=") => { + receipt_dir = Some(PathBuf::from(value.trim_start_matches("--receipt-dir="))); + index += 1; + } + value if value.starts_with("--receipts=") => { + receipt_dir = Some(PathBuf::from(value.trim_start_matches("--receipts="))); + index += 1; + } + value if value.starts_with("-R=") => { + receipt_dir = Some(PathBuf::from(value.trim_start_matches("-R="))); + index += 1; + } + "--receipt-dir" | "--receipts" | "-R" => { + index += 1; + receipt_dir = Some(PathBuf::from(string_arg(args, index)?)); + index += 1; + } + value if value.starts_with('-') => { + return Err(format!("unknown runx resume option {value}")); + } + value => { + positionals.push(value.to_owned()); + index += 1; + } + } + } + if positionals.len() != 2 { + return Err("runx resume requires ".to_owned()); + } + Ok(ResumePlan { + run_id: positionals.remove(0), + answers_path: PathBuf::from(positionals.remove(0)), + receipt_dir, + json, + }) +} + +pub fn run_native_resume(plan: ResumePlan) -> ExitCode { + let cwd = env::current_dir().unwrap_or_else(|_| PathBuf::from(".")); + let env = crate::cli_io::env_map(); + let receipt_config = RuntimeReceiptConfig::default(); + let resolved = resolve_receipt_path(ReceiptPathInputs { + explicit_dir: plan.receipt_dir.as_deref(), + runtime_config: Some(&receipt_config), + env: &env, + cwd: &cwd, + }); + let store = LocalReceiptStore::new(&resolved.path); + let history = match list_local_history( + &store, + &resolved.workspace_base, + &resolved.project_runx_dir, + &Default::default(), + ) { + Ok(history) => history, + Err(error) => { + return write_resume_failure( + &format!("could not read receipt history: {error}"), + plan.json, + 1, + ); + } + }; + let Some(pending) = history + .pending_runs + .iter() + .find(|pending| pending.id == plan.run_id) + else { + return write_resume_failure( + &format!("no pending run found for {}", plan.run_id), + plan.json, + 1, + ); + }; + let Some(skill_ref) = pending.resume_skill_ref.as_deref() else { + return write_resume_failure( + "pending run does not record a resume skill ref; rerun the original skill manually", + plan.json, + 1, + ); + }; + let skill_plan = SkillPlan { + action: SkillAction::Run, + skill_path: PathBuf::from(skill_ref), + runner: pending.selected_runner.clone(), + receipt_dir: plan.receipt_dir, + run_id: Some(plan.run_id), + answers: Some(plan.answers_path), + registry: None, + expected_digest: None, + json: plan.json, + inputs: BTreeMap::new(), + local_credential: None, + }; + crate::skill::run_native_skill(skill_plan) +} + pub(crate) fn render_skill_resume_command(command: SkillResumeCommand<'_>) -> String { let mut parts = vec![ "runx".to_owned(), - "skill".to_owned(), - shell_token(command.skill_ref.unwrap_or("SKILL.md")), - ]; - if let Some(runner) = command.selected_runner.and_then(non_empty) { - parts.push("--runner".to_owned()); - parts.push(shell_token(runner)); - } - if let Some(receipt_dir) = command.receipt_dir { - parts.push("--receipt-dir".to_owned()); - parts.push(shell_token(&receipt_dir.to_string_lossy())); - } - parts.extend([ - "--run-id".to_owned(), + "resume".to_owned(), shell_token(command.run_id), - "--answers".to_owned(), - ]); + ]; parts.push(shell_token( &command .answers_path .map_or_else(|| "answers.json".into(), Path::to_string_lossy), )); + if let Some(receipt_dir) = command.receipt_dir { + parts.push("--receipt-dir".to_owned()); + parts.push(shell_token(&receipt_dir.to_string_lossy())); + } + let _legacy_context = ( + command.skill_ref, + command.selected_runner.and_then(non_empty), + ); parts.join(" ") } @@ -52,6 +182,25 @@ fn shell_token(value: &str) -> String { format!("'{}'", value.replace('\'', "'\\''")) } +fn string_arg(args: &[OsString], index: usize) -> Result { + args.get(index) + .ok_or_else(|| "missing value for runx resume argument".to_owned())? + .to_str() + .map(ToOwned::to_owned) + .ok_or_else(|| "runx resume arguments must be UTF-8".to_owned()) +} + +fn write_resume_failure(message: &str, json: bool, exit_code: u8) -> ExitCode { + if json { + return crate::cli_io::write_stdout_code( + &crate::launcher::json_failure_output(message, "resume_error"), + exit_code, + ); + } + let _ignored = writeln!(io::stderr(), "runx: {message}"); + ExitCode::from(exit_code) +} + #[cfg(test)] mod tests { use std::path::Path; @@ -70,7 +219,7 @@ mod tests { assert_eq!( command, - "runx skill 'skills/support reply' --runner 'agent task' --receipt-dir 'custom receipts' --run-id 'run abc' --answers 'my answers.json'" + "runx resume 'run abc' 'my answers.json' --receipt-dir 'custom receipts'" ); } @@ -84,9 +233,6 @@ mod tests { answers_path: None, }); - assert_eq!( - command, - "runx skill SKILL.md --run-id rx_123 --answers answers.json" - ); + assert_eq!(command, "runx resume rx_123 answers.json"); } } diff --git a/crates/runx-cli/src/skill.rs b/crates/runx-cli/src/skill.rs index 2a3165962..84ecfdc16 100644 --- a/crates/runx-cli/src/skill.rs +++ b/crates/runx-cli/src/skill.rs @@ -1,7 +1,8 @@ use std::collections::BTreeMap; use std::env; +use std::fs; use std::io::{self, Write}; -use std::path::PathBuf; +use std::path::{Path, PathBuf}; use std::process::ExitCode; use runx_contracts::{JsonObject, JsonValue}; @@ -19,6 +20,7 @@ use resolver::{RegistryTrustState, ResolvedSkillRef, resolve_skill_ref_details}; #[derive(Debug, PartialEq)] pub struct SkillPlan { + pub action: SkillAction, pub skill_path: PathBuf, pub runner: Option, pub receipt_dir: Option, @@ -36,6 +38,12 @@ pub struct SkillPlan { pub local_credential: Option, } +#[derive(Debug, PartialEq)] +pub enum SkillAction { + Inspect, + Run, +} + pub fn run_native_skill(plan: SkillPlan) -> ExitCode { let cwd = env::current_dir().unwrap_or_else(|_| PathBuf::from(".")); let env = env::vars().collect(); @@ -55,6 +63,14 @@ pub fn run_native_skill(plan: SkillPlan) -> ExitCode { } }; let skill_path = resolved.runnable_path.clone(); + if plan.action == SkillAction::Inspect { + return write_skill_inspection( + &skill_path, + plan.runner.as_deref(), + plan.json, + registry_provenance(&resolved), + ); + } let resume = SkillOutputResume { skill_ref: Some(&resume_skill_ref), selected_runner: plan.runner.as_deref(), @@ -92,6 +108,314 @@ pub fn run_native_skill(plan: SkillPlan) -> ExitCode { } } +fn write_skill_inspection( + skill_path: &Path, + runner: Option<&str>, + json: bool, + provenance: Option, +) -> ExitCode { + match inspect_skill(skill_path, runner, provenance) { + Ok(value) if json => crate::cli_io::write_stdout_code( + &format!( + "{}\n", + serde_json::to_string_pretty(&value).unwrap_or_else(|_| "{}".to_owned()) + ), + 0, + ), + Ok(value) => write_inspection_text(&value), + Err(message) => write_skill_failure(&message, json, "skill_error", 1, None), + } +} + +fn inspect_skill( + skill_path: &Path, + selected_runner: Option<&str>, + provenance: Option, +) -> Result { + let skill_dir = skill_directory(skill_path); + let skill_md = fs::read_to_string(skill_dir.join("SKILL.md")).map_err(|error| { + format!( + "could not read skill markdown {}: {error}", + skill_dir.join("SKILL.md").display() + ) + })?; + let frontmatter = parse_skill_frontmatter(&skill_md)?; + let x_yaml_path = skill_dir.join("X.yaml"); + let profile = match fs::read_to_string(&x_yaml_path) { + Ok(contents) => parse_yaml_object(&contents, &x_yaml_path)?, + Err(error) if error.kind() == std::io::ErrorKind::NotFound => JsonObject::new(), + Err(error) => { + return Err(format!("could not read {}: {error}", x_yaml_path.display())); + } + }; + let runners = profile + .get("runners") + .and_then(JsonValue::as_object) + .cloned() + .unwrap_or_default(); + let mut output = JsonObject::new(); + output.insert( + "schema".to_owned(), + JsonValue::String("runx.skill.inspect.v1".to_owned()), + ); + output.insert("status".to_owned(), JsonValue::String("ok".to_owned())); + insert_frontmatter_string(&mut output, &frontmatter, "name", "name"); + insert_frontmatter_string(&mut output, &frontmatter, "description", "description"); + if let Some(version) = profile.get("version").and_then(JsonValue::as_str) { + output.insert("version".to_owned(), JsonValue::String(version.to_owned())); + } + if let Some(provenance) = provenance { + output.insert( + "registry_provenance".to_owned(), + JsonValue::Object(provenance), + ); + } + output.insert( + "skill_path".to_owned(), + JsonValue::String(skill_dir.to_string_lossy().into_owned()), + ); + output.insert( + "runners".to_owned(), + JsonValue::Array( + runners + .keys() + .map(|runner| JsonValue::String(runner.clone())) + .collect(), + ), + ); + if let Some(runner) = selected_runner { + let runner_def = runners + .get(runner) + .and_then(JsonValue::as_object) + .ok_or_else(|| format!("skill has no runner '{runner}'"))?; + output.insert("runner".to_owned(), inspect_runner(runner, runner_def)); + output.insert( + "examples".to_owned(), + JsonValue::Array(fixture_examples(&skill_dir, runner)), + ); + output.insert( + "resume".to_owned(), + JsonValue::Object(JsonObject::from([ + ( + "may_pause".to_owned(), + JsonValue::Bool(runner_may_pause(runner_def)), + ), + ( + "command".to_owned(), + JsonValue::String("runx resume answers.json".to_owned()), + ), + ])), + ); + } + Ok(JsonValue::Object(output)) +} + +fn write_inspection_text(value: &JsonValue) -> ExitCode { + let Some(object) = value.as_object() else { + return crate::cli_io::write_stdout_code("{}\n", 0); + }; + let mut out = String::new(); + out.push_str(&format!( + "skill: {}\n", + object_string(object, "name").unwrap_or("") + )); + if let Some(description) = object_string(object, "description") { + out.push_str(&format!("description: {description}\n")); + } + if let Some(version) = object_string(object, "version") { + out.push_str(&format!("version: {version}\n")); + } + if let Some(runner) = object.get("runner").and_then(JsonValue::as_object) { + out.push_str(&format!( + "runner: {}\n", + object_string(runner, "name").unwrap_or("") + )); + if let Some(kind) = object_string(runner, "type") { + out.push_str(&format!("type: {kind}\n")); + } + if let Some(inputs) = runner.get("inputs").and_then(JsonValue::as_array) { + if !inputs.is_empty() { + out.push_str("inputs:\n"); + for input in inputs { + if let Some(input) = input.as_object() { + let name = object_string(input, "name").unwrap_or(""); + let kind = object_string(input, "type").unwrap_or("json"); + let required = input + .get("required") + .and_then(JsonValue::as_bool) + .unwrap_or(false); + let marker = if required { "required" } else { "optional" }; + out.push_str(&format!(" - {name}: {kind} ({marker})\n")); + } + } + } + } + if let Some(examples) = object.get("examples").and_then(JsonValue::as_array) + && !examples.is_empty() + { + out.push_str("examples:\n"); + for example in examples { + if let Some(example) = example.as_str() { + out.push_str(&format!(" - {example}\n")); + } + } + } + if let Some(resume) = object.get("resume").and_then(JsonValue::as_object) + && resume + .get("may_pause") + .and_then(JsonValue::as_bool) + .unwrap_or(false) + { + out.push_str(&format!( + "resume: {}\n", + object_string(resume, "command").unwrap_or("runx resume answers.json") + )); + } + out.push_str("run: add inputs, or pass --run for a zero-input runner\n"); + } else if let Some(runners) = object.get("runners").and_then(JsonValue::as_array) { + out.push_str("runners:\n"); + for runner in runners { + if let Some(runner) = runner.as_str() { + out.push_str(&format!(" - {runner}\n")); + } + } + out.push_str("next: runx skill \n"); + } + crate::cli_io::write_stdout_code(&out, 0) +} + +fn skill_directory(skill_path: &Path) -> PathBuf { + if skill_path.file_name().and_then(|name| name.to_str()) == Some("SKILL.md") { + return skill_path.parent().unwrap_or(skill_path).to_path_buf(); + } + skill_path.to_path_buf() +} + +fn parse_skill_frontmatter(markdown: &str) -> Result { + let Some(rest) = markdown.strip_prefix("---") else { + return Ok(JsonObject::new()); + }; + let Some((frontmatter, _body)) = rest.split_once("\n---") else { + return Ok(JsonObject::new()); + }; + serde_norway::from_str::(frontmatter) + .map_err(|error| format!("skill frontmatter is invalid YAML: {error}")) + .and_then(|value| match value { + JsonValue::Object(object) => Ok(object), + _ => Ok(JsonObject::new()), + }) +} + +fn parse_yaml_object(contents: &str, path: &Path) -> Result { + serde_norway::from_str::(contents) + .map_err(|error| format!("{} is invalid YAML: {error}", path.display())) + .and_then(|value| match value { + JsonValue::Object(object) => Ok(object), + _ => Err(format!("{} must contain a YAML object", path.display())), + }) +} + +fn insert_frontmatter_string( + output: &mut JsonObject, + frontmatter: &JsonObject, + source_key: &str, + output_key: &str, +) { + if let Some(value) = object_string(frontmatter, source_key) { + output.insert(output_key.to_owned(), JsonValue::String(value.to_owned())); + } +} + +fn inspect_runner(name: &str, runner: &JsonObject) -> JsonValue { + let mut output = JsonObject::new(); + output.insert("name".to_owned(), JsonValue::String(name.to_owned())); + if let Some(kind) = object_string(runner, "type") { + output.insert("type".to_owned(), JsonValue::String(kind.to_owned())); + } + let inputs = runner + .get("inputs") + .and_then(JsonValue::as_object) + .map(|inputs| { + inputs + .iter() + .map(|(name, input)| inspect_input(name, input)) + .collect::>() + }) + .unwrap_or_default(); + output.insert("inputs".to_owned(), JsonValue::Array(inputs)); + JsonValue::Object(output) +} + +fn inspect_input(name: &str, value: &JsonValue) -> JsonValue { + let mut output = JsonObject::new(); + output.insert("name".to_owned(), JsonValue::String(name.to_owned())); + if let Some(input) = value.as_object() { + if let Some(kind) = object_string(input, "type") { + output.insert("type".to_owned(), JsonValue::String(kind.to_owned())); + } + output.insert( + "required".to_owned(), + JsonValue::Bool( + input + .get("required") + .and_then(JsonValue::as_bool) + .unwrap_or(false), + ), + ); + if let Some(description) = object_string(input, "description") { + output.insert( + "description".to_owned(), + JsonValue::String(description.to_owned()), + ); + } + } + JsonValue::Object(output) +} + +fn object_string<'a>(object: &'a JsonObject, key: &str) -> Option<&'a str> { + object.get(key).and_then(JsonValue::as_str) +} + +fn fixture_examples(skill_dir: &Path, runner: &str) -> Vec { + let fixtures_dir = skill_dir.join("fixtures"); + let Ok(entries) = fs::read_dir(fixtures_dir) else { + return Vec::new(); + }; + let mut fixtures = entries + .filter_map(Result::ok) + .filter_map(|entry| { + let path = entry.path(); + let name = path.file_name()?.to_str()?.to_owned(); + (name.ends_with(".yaml") && fixture_targets_runner(&path, runner)).then_some(name) + }) + .map(JsonValue::String) + .collect::>(); + fixtures.sort_by(|left, right| left.as_str().cmp(&right.as_str())); + fixtures +} + +fn fixture_targets_runner(path: &Path, runner: &str) -> bool { + fs::read_to_string(path) + .ok() + .and_then(|contents| serde_norway::from_str::(&contents).ok()) + .and_then(|value| value.as_object().cloned()) + .and_then(|object| { + object + .get("runner") + .and_then(JsonValue::as_str) + .map(str::to_owned) + }) + .is_some_and(|fixture_runner| fixture_runner == runner) +} + +fn runner_may_pause(runner: &JsonObject) -> bool { + match object_string(runner, "type") { + Some("agent") | Some("agent-task") => true, + Some("graph") => true, + _ => false, + } +} + fn attach_registry_provenance(output: &mut JsonValue, resolved: &ResolvedSkillRef) { let Some(provenance) = registry_provenance(resolved) else { return; diff --git a/crates/runx-cli/src/skill/inputs.rs b/crates/runx-cli/src/skill/inputs.rs index e7ccaaa2d..6cbdee773 100644 --- a/crates/runx-cli/src/skill/inputs.rs +++ b/crates/runx-cli/src/skill/inputs.rs @@ -44,6 +44,28 @@ pub(super) fn parse_input_arg( Ok(index) } +pub(super) fn parse_json_input_arg( + args: &[OsString], + mut index: usize, + inline_value: Option<&str>, + inputs: &mut BTreeMap, +) -> Result { + if let Some(value) = inline_value { + parse_json_input_assignment(value, None, inputs)?; + return Ok(index); + } + + index += 1; + let key_or_assignment = string_arg(args, index)?; + if key_or_assignment.contains('=') { + parse_json_input_assignment(&key_or_assignment, None, inputs)?; + } else { + index += 1; + parse_json_input_assignment(&key_or_assignment, Some(string_arg(args, index)?), inputs)?; + } + Ok(index) +} + fn parse_input_assignment( key_or_assignment: &str, explicit_value: Option, @@ -60,6 +82,22 @@ fn parse_input_assignment( } } +fn parse_json_input_assignment( + key_or_assignment: &str, + explicit_value: Option, + inputs: &mut BTreeMap, +) -> Result<(), String> { + match explicit_value { + Some(value) => insert_json_input(inputs, key_or_assignment, &value), + None => { + let (key, value) = key_or_assignment.split_once('=').ok_or_else(|| { + "runx skill --input-json requires key= or key ".to_owned() + })?; + insert_json_input(inputs, key, value) + } + } +} + fn insert_input( inputs: &mut BTreeMap, raw_key: &str, @@ -73,6 +111,21 @@ fn insert_input( Ok(()) } +fn insert_json_input( + inputs: &mut BTreeMap, + raw_key: &str, + raw_value: &str, +) -> Result<(), String> { + let key = normalize_input_key(raw_key); + if key.is_empty() { + return Err("runx skill input key must be non-empty".to_owned()); + } + let value = serde_json::from_str(raw_value) + .map_err(|error| format!("runx skill --input-json {key} is invalid JSON: {error}"))?; + inputs.insert(key, value); + Ok(()) +} + fn normalize_input_key(raw: &str) -> String { raw.trim() .trim_start_matches("--") diff --git a/crates/runx-cli/src/skill/output.rs b/crates/runx-cli/src/skill/output.rs index 9da4729a0..718086a79 100644 --- a/crates/runx-cli/src/skill/output.rs +++ b/crates/runx-cli/src/skill/output.rs @@ -111,6 +111,10 @@ fn write_skill_text( writeln!(writer, "- {kind}: {id}")?; } } + if let Some(template) = answers_template(requests) { + writeln!(writer, "answers_template:")?; + write_indented_json(writer, &template)?; + } if let Some(run_id) = object_string(object, "run_id") { let command = crate::resume::render_skill_resume_command(crate::resume::SkillResumeCommand { @@ -128,6 +132,34 @@ fn write_skill_text( Ok(()) } +fn answers_template(requests: &[JsonValue]) -> Option { + let mut answers = JsonObject::new(); + for request in requests { + let Some(request) = request.as_object() else { + continue; + }; + let Some(id) = object_string(request, "id") else { + continue; + }; + answers.insert(id.to_owned(), JsonValue::Object(JsonObject::new())); + } + if answers.is_empty() { + return None; + } + Some(JsonValue::Object(JsonObject::from([( + "answers".to_owned(), + JsonValue::Object(answers), + )]))) +} + +fn write_indented_json(writer: &mut dyn Write, value: &JsonValue) -> io::Result<()> { + let json = serde_json::to_string_pretty(value).unwrap_or_else(|_| "{}".to_owned()); + for line in json.lines() { + writeln!(writer, " {line}")?; + } + Ok(()) +} + fn write_registry_provenance(writer: &mut dyn Write, object: &JsonObject) -> io::Result<()> { for key in [ "skill_id", @@ -253,8 +285,10 @@ mod tests { ); assert!(output.contains( - "runx skill registry/weather --runner 'operator runner' --receipt-dir 'custom receipts' --run-id run_weather --answers 'operator answers.json'" + "runx resume run_weather 'operator answers.json' --receipt-dir 'custom receipts'" )); + assert!(output.contains("answers_template:")); + assert!(output.contains(r#""request_1": {}"#)); } fn base_result() -> JsonObject { diff --git a/crates/runx-cli/src/skill/parser.rs b/crates/runx-cli/src/skill/parser.rs index 903e4cac3..8858a2f3e 100644 --- a/crates/runx-cli/src/skill/parser.rs +++ b/crates/runx-cli/src/skill/parser.rs @@ -11,8 +11,8 @@ use runx_runtime::orchestrator::LocalCredentialDescriptor; use runx_runtime::{resolve_path_from_user_input, resolve_runx_home_dir}; use serde::Deserialize; -use super::SkillPlan; -use super::inputs::{parse_direct_input_arg, parse_input_arg}; +use super::inputs::{parse_direct_input_arg, parse_input_arg, parse_json_input_arg}; +use super::{SkillAction, SkillPlan}; pub fn parse_skill_plan(args: &[OsString]) -> Result { let mut state = SkillParseState::default(); @@ -39,7 +39,18 @@ pub fn parse_skill_plan(args: &[OsString]) -> Result { return Err("runx skill --run-id requires --answers".to_owned()); } + let action = if state.force_run + || state.run_id.is_some() + || state.answers.is_some() + || !state.inputs.is_empty() + { + SkillAction::Run + } else { + SkillAction::Inspect + }; + Ok(SkillPlan { + action, skill_path, runner: state.runner, receipt_dir: state.receipt_dir, @@ -63,6 +74,7 @@ struct SkillParseState { registry: Option, expected_digest: Option, json: bool, + force_run: bool, inputs: BTreeMap, credential: Option, credential_profile: Option, @@ -397,6 +409,14 @@ fn parse_skill_arg( &mut state.inputs, )?; } + value if value.starts_with("--input-json=") => { + index = parse_json_input_arg( + args, + index, + Some(value.trim_start_matches("--input-json=")), + &mut state.inputs, + )?; + } value if value.starts_with("-i=") => { index = parse_input_arg( args, @@ -406,7 +426,9 @@ fn parse_skill_arg( )?; } "--input" => index = parse_input_arg(args, index, None, &mut state.inputs)?, + "--input-json" => index = parse_json_input_arg(args, index, None, &mut state.inputs)?, "-i" => index = parse_input_arg(args, index, None, &mut state.inputs)?, + "--run" => state.force_run = true, value if value.starts_with("--credential=") => { state.credential = Some(parse_credential_binding( value.trim_start_matches("--credential="), @@ -455,10 +477,13 @@ fn parse_skill_arg( index = parse_direct_input_arg(args, index, value, &mut state.inputs)?; } value => { - if state.skill_path.is_some() { + if state.skill_path.is_none() { + state.skill_path = Some(PathBuf::from(value)); + } else if state.runner.is_none() { + state.runner = Some(value.to_owned()); + } else { return Err(format!("unexpected runx skill argument {value}")); } - state.skill_path = Some(PathBuf::from(value)); } } Ok(index) @@ -499,7 +524,7 @@ mod tests { use std::fs; use std::time::{SystemTime, UNIX_EPOCH}; - use super::{SkillParseState, finalize_local_credential}; + use super::{SkillAction, SkillParseState, finalize_local_credential}; #[test] fn credential_profile_resolves_project_descriptor_and_env_secret() -> Result<(), String> { @@ -595,6 +620,128 @@ mod tests { Ok(()) } + #[test] + fn input_json_parses_strict_json_values() -> Result<(), String> { + let args = [ + "skill", + "skills/data-store", + "--input-json", + "event", + r#"{"type":"posting.claimed","payload":{"actor":"agent-9"}}"#, + "--input-json=limits={\"rows\":10}", + ] + .into_iter() + .map(std::ffi::OsString::from) + .collect::>(); + let plan = super::parse_skill_plan(&args)?; + assert_eq!(plan.action, SkillAction::Run); + + assert_eq!( + plan.inputs + .get("event") + .and_then(runx_contracts::JsonValue::as_object) + .and_then(|event| event.get("type")) + .and_then(runx_contracts::JsonValue::as_str), + Some("posting.claimed") + ); + let rows = plan + .inputs + .get("limits") + .and_then(runx_contracts::JsonValue::as_object) + .and_then(|limits| limits.get("rows")) + .and_then(|rows| match rows { + runx_contracts::JsonValue::Number(number) => number.as_f64(), + _ => None, + }); + assert_eq!(rows, Some(10.0)); + Ok(()) + } + + #[test] + fn skill_without_inputs_inspects_skill_card() -> Result<(), String> { + let args = ["skill", "skills/messageboard"] + .into_iter() + .map(std::ffi::OsString::from) + .collect::>(); + let plan = super::parse_skill_plan(&args)?; + + assert_eq!(plan.action, SkillAction::Inspect); + assert_eq!( + plan.skill_path, + std::path::PathBuf::from("skills/messageboard") + ); + assert_eq!(plan.runner, None); + Ok(()) + } + + #[test] + fn positional_runner_without_inputs_inspects_runner_card() -> Result<(), String> { + let args = ["skill", "skills/messageboard", "post_and_append"] + .into_iter() + .map(std::ffi::OsString::from) + .collect::>(); + let plan = super::parse_skill_plan(&args)?; + + assert_eq!(plan.action, SkillAction::Inspect); + assert_eq!(plan.runner.as_deref(), Some("post_and_append")); + Ok(()) + } + + #[test] + fn positional_runner_with_inputs_executes_runner() -> Result<(), String> { + let args = [ + "skill", + "skills/messageboard", + "post_and_append", + "-i", + "title=hello", + ] + .into_iter() + .map(std::ffi::OsString::from) + .collect::>(); + let plan = super::parse_skill_plan(&args)?; + + assert_eq!(plan.action, SkillAction::Run); + assert_eq!(plan.runner.as_deref(), Some("post_and_append")); + assert_eq!( + plan.inputs.get("title"), + Some(&runx_contracts::JsonValue::String("hello".to_owned())) + ); + Ok(()) + } + + #[test] + fn run_flag_executes_zero_input_runner() -> Result<(), String> { + let args = ["skill", "skills/ops-desk", "refresh", "--run"] + .into_iter() + .map(std::ffi::OsString::from) + .collect::>(); + let plan = super::parse_skill_plan(&args)?; + + assert_eq!(plan.action, SkillAction::Run); + assert_eq!(plan.runner.as_deref(), Some("refresh")); + Ok(()) + } + + #[test] + fn input_json_rejects_non_json_values() { + let args = [ + "skill", + "skills/data-store", + "--input-json", + "event", + "plain text", + ] + .into_iter() + .map(std::ffi::OsString::from) + .collect::>(); + let error = super::parse_skill_plan(&args) + .err() + .expect("invalid json input should fail"); + + assert!(error.contains("--input-json event is invalid JSON")); + } + #[test] fn credential_parser_keeps_uri_material_ref_intact() -> Result<(), String> { let binding = super::parse_credential_binding( diff --git a/crates/runx-cli/tests/export.rs b/crates/runx-cli/tests/export.rs index 634d3f9a1..e38a4c192 100644 --- a/crates/runx-cli/tests/export.rs +++ b/crates/runx-cli/tests/export.rs @@ -133,8 +133,7 @@ fn codex_global_writes_shim_and_idempotent_permission_block() assert!(shim.contains("request.invocation.envelope")); assert!(shim.contains("allowed_tools")); assert!(shim.contains("\"answers\"")); - assert!(shim.contains("--run-id \"\"")); - assert!(shim.contains("--answers \"\"")); + assert!(shim.contains("resume \"\" \"\"")); assert!(shim.contains("runx-export:codex")); let rules = fixture.read_home_file(".codex/rules/default.rules")?; assert!(rules.contains("# existing approval")); @@ -145,12 +144,24 @@ fn codex_global_writes_shim_and_idempotent_permission_block() .count(), 1 ); + assert_eq!( + rules + .matches("prefix_rule(pattern = [\"runx\", \"resume\"]") + .count(), + 1 + ); assert_eq!( rules .matches("prefix_rule(pattern = [\"/opt/runx/bin/runx\", \"skill\"]") .count(), 1 ); + assert_eq!( + rules + .matches("prefix_rule(pattern = [\"/opt/runx/bin/runx\", \"resume\"]") + .count(), + 1 + ); Ok(()) } @@ -176,7 +187,9 @@ fn codex_global_initializes_missing_codex_home() -> Result<(), Box [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] [--run-id id --answers file]", + "runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [--run] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir]", + ); + assert_help_line( + &help, + "runx resume [-R dir] [-j|--json]", ); assert_help_line( &help, @@ -99,7 +104,7 @@ fn nested_skill_history_verify_and_publish_help_are_native() { assert_help_line( &skill_help_text(), - "runx skill [-p profile] [-i key=value] [-j] [--runner name] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] [--run-id id --answers file]", + "runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [--run] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir]", ); assert_help_line( &skill_help_text(), @@ -335,6 +340,7 @@ fn routes_canonical_skill_run_to_native_plan() { "Docs bug", ]), LauncherAction::RunSkill(SkillPlan { + action: SkillAction::Run, skill_path: PathBuf::from("skills/issue-intake"), runner: Some("intake".to_owned()), receipt_dir: Some(PathBuf::from(".runx/receipts")), @@ -553,6 +559,15 @@ fn routes_doctor_history_list_new_and_init_to_native_plans() { args: vec!["history".into(), "sourcey".into(), "--json".into()], }) ); + assert_eq!( + plan(&["resume", "run_123", "answers.json", "-R", "receipts", "-j",]), + LauncherAction::RunResume(ResumePlan { + run_id: "run_123".to_owned(), + answers_path: PathBuf::from("answers.json"), + receipt_dir: Some(PathBuf::from("receipts")), + json: true, + }) + ); assert_eq!( plan(&["list", "packets", "--ok-only", "--json"]), LauncherAction::RunList(ListPlan { diff --git a/crates/runx-cli/tests/skill.rs b/crates/runx-cli/tests/skill.rs index 899b4b62b..764b583af 100644 --- a/crates/runx-cli/tests/skill.rs +++ b/crates/runx-cli/tests/skill.rs @@ -451,8 +451,7 @@ fn native_skill_text_output_is_concise_for_pending_agent_request() assert!(stdout.contains("status: needs_agent")); assert!(stdout.contains("pending_requests: 1")); assert!(stdout.contains("agent_task.issue-intake.output")); - assert!(stdout.contains(skill_dir.to_str().ok_or("non-utf8 skill dir")?)); - assert!(stdout.contains("--run-id run_agent_task-issue-intake-output --answers answers.json")); + assert!(stdout.contains("runx resume run_agent_task-issue-intake-output answers.json")); assert!(!stdout.contains("")); assert!(!stdout.trim_start().starts_with('{')); @@ -555,7 +554,7 @@ fn native_skill_rejects_retired_receipt_options() -> Result<(), Box Command { - crate::support::signed_runx_command("skill-test-key") + crate::support::isolated_runx_command_with_inherited_cwd("skill-test-key") } fn trusted_registry_runx_command(root: &Path) -> Result> { diff --git a/crates/runx-runtime/src/adapter.rs b/crates/runx-runtime/src/adapter.rs index f06b2fd08..4b5c2da52 100644 --- a/crates/runx-runtime/src/adapter.rs +++ b/crates/runx-runtime/src/adapter.rs @@ -67,6 +67,43 @@ pub trait SkillAdapter { } } +pub(crate) struct BorrowedSkillAdapter<'a, A> +where + A: SkillAdapter + ?Sized, +{ + adapter: &'a A, +} + +impl<'a, A> BorrowedSkillAdapter<'a, A> +where + A: SkillAdapter + ?Sized, +{ + pub(crate) fn new(adapter: &'a A) -> Self { + Self { adapter } + } +} + +impl SkillAdapter for BorrowedSkillAdapter<'_, A> +where + A: SkillAdapter + ?Sized, +{ + fn adapter_type(&self) -> &'static str { + self.adapter.adapter_type() + } + + fn invoke(&self, request: SkillInvocation) -> Result { + self.adapter.invoke(request) + } + + fn fanout_execution_mode(&self, source: &SkillSource) -> FanoutExecutionMode { + self.adapter.fanout_execution_mode(source) + } + + fn clone_for_fanout(&self) -> Option> { + self.adapter.clone_for_fanout() + } +} + impl SkillAdapter for Box where A: SkillAdapter + ?Sized, diff --git a/crates/runx-runtime/src/adapters/catalog.rs b/crates/runx-runtime/src/adapters/catalog.rs index 6824cac91..5dc49877f 100644 --- a/crates/runx-runtime/src/adapters/catalog.rs +++ b/crates/runx-runtime/src/adapters/catalog.rs @@ -3,6 +3,7 @@ // cohesive unit; splitting them would fracture how a skill is resolved and run. use std::collections::BTreeMap; +use std::fs; use std::path::{Path, PathBuf}; use std::time::Instant; @@ -21,6 +22,15 @@ use crate::tool_catalogs::search::{FixtureTool, fixture_tool}; use crate::tool_catalogs::{ToolCatalogError, ToolInspectOptions, resolve_local_tool}; const MISSING_CATALOG_REF: &str = "Catalog source requires source.catalog_ref metadata."; +const DATA_SOURCE_ROUTER_TOOL_REF: &str = "data.source"; +const RUNX_DATA_SOURCES_ENV: &str = "RUNX_DATA_SOURCES"; +const PROJECT_DATA_SOURCES_PATH: &str = ".runx/data-sources.json"; + +#[derive(Clone, Debug)] +struct DataSourceConfigSource { + value: String, + required: bool, +} #[derive(Clone, Debug, Default)] pub struct CatalogAdapter { @@ -48,22 +58,28 @@ impl SkillAdapter for CatalogAdapter { adapter_type: request.source.source_type.as_str().to_owned(), }); } - let Some(catalog_ref) = request.source.catalog_ref.as_deref() else { + let Some(catalog_ref) = request.source.catalog_ref.clone() else { return Ok(failure(MISSING_CATALOG_REF, started)); }; - let catalog_ref = catalog_ref.trim(); + let catalog_ref = catalog_ref.trim().to_owned(); if catalog_ref.is_empty() { return Ok(failure(MISSING_CATALOG_REF, started)); } - if let Some(output) = invoke_local_tool(catalog_ref, &request, started)? { + let mut request = request; + let catalog_ref = match resolve_data_source_router(&catalog_ref, &mut request) { + Ok(resolved) => resolved.unwrap_or_else(|| catalog_ref.to_owned()), + Err(message) => return Ok(failure(message, started)), + }; + + if let Some(output) = invoke_local_tool(&catalog_ref, &request, started)? { return Ok(output); } if !self.fixture_catalog_enabled { - return Ok(missing_imported_tool(catalog_ref, started)); + return Ok(missing_imported_tool(&catalog_ref, started)); } - let Some(tool) = fixture_tool(catalog_ref) else { - return Ok(missing_imported_tool(catalog_ref, started)); + let Some(tool) = fixture_tool(&catalog_ref) else { + return Ok(missing_imported_tool(&catalog_ref, started)); }; Ok(invoke_fixture_tool( @@ -87,6 +103,234 @@ impl SkillAdapter for CatalogAdapter { } } +fn resolve_data_source_router( + catalog_ref: &str, + request: &mut SkillInvocation, +) -> Result, String> { + if catalog_ref != DATA_SOURCE_ROUTER_TOOL_REF { + return Ok(None); + } + + let data_source_ref = string_input(&request.inputs, "data_source_ref") + .ok_or_else(|| "data.source requires input data_source_ref.".to_owned())? + .to_owned(); + let binding = match data_source_binding( + &data_source_ref, + &request.env, + &request.skill_directory, + )? { + Some(binding) => binding, + None if data_source_ref.starts_with("local://") => { + default_local_data_source_binding(&data_source_ref, &request.inputs) + } + None => { + return Err(format!( + "Data source '{data_source_ref}' is not bound to a data adapter. Add it to {PROJECT_DATA_SOURCES_PATH} or set {RUNX_DATA_SOURCES_ENV}." + )); + } + }; + + let adapter = string_input(&binding, "adapter") + .ok_or_else(|| format!("Data source '{data_source_ref}' binding is missing adapter."))?; + if adapter == DATA_SOURCE_ROUTER_TOOL_REF { + return Err(format!( + "Data source '{data_source_ref}' cannot bind to {DATA_SOURCE_ROUTER_TOOL_REF}; choose a concrete adapter." + )); + } + if !adapter.contains('.') { + return Err(format!( + "Data source '{data_source_ref}' adapter '{adapter}' must be a namespaced tool ref such as data.local." + )); + } + let adapter = adapter.to_owned(); + + request.inputs.insert( + "data_source_binding".to_owned(), + JsonValue::Object(binding.clone()), + ); + request + .resolved_inputs + .insert("data_source_binding".to_owned(), JsonValue::Object(binding)); + Ok(Some(adapter)) +} + +fn default_local_data_source_binding(data_source_ref: &str, inputs: &JsonObject) -> JsonObject { + let mut object = JsonObject::new(); + object.insert( + "data_source_ref".to_owned(), + JsonValue::String(data_source_ref.to_owned()), + ); + if string_input(inputs, "store_id").is_some() { + object.insert( + "adapter".to_owned(), + JsonValue::String("data.local".to_owned()), + ); + object.insert( + "profile".to_owned(), + JsonValue::String("local-fixture".to_owned()), + ); + object.insert( + "storage_class".to_owned(), + JsonValue::String("local-json-fixture".to_owned()), + ); + } else { + let source_digest = sha256_hex(data_source_ref.as_bytes()); + let source_id = &source_digest[..16]; + object.insert( + "adapter".to_owned(), + JsonValue::String("data.sqlite".to_owned()), + ); + object.insert( + "profile".to_owned(), + JsonValue::String("local-durable".to_owned()), + ); + object.insert( + "database_path".to_owned(), + JsonValue::String(format!( + ".runx/data/local-sources/source-{source_id}.sqlite" + )), + ); + object.insert( + "storage_class".to_owned(), + JsonValue::String("sqlite".to_owned()), + ); + } + object.insert("resources".to_owned(), JsonValue::Object(JsonObject::new())); + object +} + +fn data_source_binding( + data_source_ref: &str, + env: &BTreeMap, + skill_directory: &Path, +) -> Result, String> { + for source in data_source_config_sources(env, skill_directory) { + let Some(document) = read_data_source_config_source(&source)? else { + continue; + }; + let parsed: JsonValue = serde_json::from_str(&document).map_err(|error| { + format!( + "Data source config {} is not valid JSON: {error}", + source.value + ) + })?; + let Some(binding) = binding_from_config(&parsed, data_source_ref) else { + continue; + }; + reject_secret_material(&binding, data_source_ref)?; + return Ok(Some(binding)); + } + Ok(None) +} + +fn data_source_config_sources( + env: &BTreeMap, + skill_directory: &Path, +) -> Vec { + let mut sources = Vec::new(); + let root = workspace_root(env, skill_directory); + if let Some(config) = env.get(RUNX_DATA_SOURCES_ENV) { + let trimmed = config.trim(); + if !trimmed.is_empty() { + let value = if trimmed.starts_with('{') || Path::new(trimmed).is_absolute() { + trimmed.to_owned() + } else { + root.join(trimmed).to_string_lossy().into_owned() + }; + sources.push(DataSourceConfigSource { + value, + required: true, + }); + } + } + sources.push(DataSourceConfigSource { + value: root + .join(PROJECT_DATA_SOURCES_PATH) + .to_string_lossy() + .into_owned(), + required: false, + }); + sources +} + +fn read_data_source_config_source( + source: &DataSourceConfigSource, +) -> Result, String> { + let trimmed = source.value.trim(); + if trimmed.is_empty() { + return Ok(None); + } + if trimmed.starts_with('{') { + return Ok(Some(trimmed.to_owned())); + } + match fs::read_to_string(trimmed) { + Ok(document) => Ok(Some(document)), + Err(error) if error.kind() == std::io::ErrorKind::NotFound && !source.required => Ok(None), + Err(error) => Err(format!( + "Failed to read data source config {trimmed}: {error}" + )), + } +} + +fn binding_from_config(config: &JsonValue, data_source_ref: &str) -> Option { + let JsonValue::Object(root) = config else { + return None; + }; + let JsonValue::Object(sources) = root.get("data_sources")? else { + return None; + }; + let JsonValue::Object(binding) = sources.get(data_source_ref)? else { + return None; + }; + let mut normalized = binding.clone(); + normalized.insert( + "data_source_ref".to_owned(), + JsonValue::String(data_source_ref.to_owned()), + ); + Some(normalized) +} + +fn reject_secret_material(binding: &JsonObject, data_source_ref: &str) -> Result<(), String> { + let Some(key) = first_secret_material_key(&JsonValue::Object(binding.clone())) else { + return Ok(()); + }; + Err(format!( + "Data source '{data_source_ref}' binding contains secret-like field '{key}'. Put provider credentials behind a runx credential profile or hosted grant instead." + )) +} + +fn first_secret_material_key(value: &JsonValue) -> Option { + match value { + JsonValue::Object(object) => object.iter().find_map(|(key, value)| { + if secret_material_key(key) { + return Some(key.clone()); + } + first_secret_material_key(value) + }), + JsonValue::Array(values) => values.iter().find_map(first_secret_material_key), + JsonValue::Null | JsonValue::Bool(_) | JsonValue::Number(_) | JsonValue::String(_) => None, + } +} + +fn secret_material_key(key: &str) -> bool { + let normalized = key + .chars() + .filter(|character| character.is_ascii_alphanumeric()) + .flat_map(char::to_lowercase) + .collect::(); + matches!( + normalized.as_str(), + "apikey" + | "accesstoken" + | "refreshtoken" + | "clientsecret" + | "secretkey" + | "privatekey" + | "password" + | "bearertoken" + ) +} + /// The context needed to resolve a local tool by reference and invoke it. Borrowed /// so both the catalog adapter (from its `SkillInvocation`) and the managed-agent /// tool executor (from its run context) can share one resolve-and-invoke path. @@ -352,6 +596,13 @@ fn missing_imported_tool(catalog_ref: &str, started: Instant) -> SkillOutput { ) } +fn string_input<'a>(object: &'a JsonObject, key: &str) -> Option<&'a str> { + match object.get(key) { + Some(JsonValue::String(value)) if !value.trim().is_empty() => Some(value.trim()), + _ => None, + } +} + fn json_string(value: Option<&JsonValue>) -> Option { match value { Some(JsonValue::String(value)) => Some(value.clone()), diff --git a/crates/runx-runtime/src/adapters/mcp/server.rs b/crates/runx-runtime/src/adapters/mcp/server.rs index 8dfa12728..730d6569e 100644 --- a/crates/runx-runtime/src/adapters/mcp/server.rs +++ b/crates/runx-runtime/src/adapters/mcp/server.rs @@ -88,7 +88,7 @@ fn needs_agent_mcp_tool_result( ) -> McpToolResult { mcp_host_tool_result( format!( - "{skill_name} needs agent input at {run_id}. Continue by rerunning the same skill with --run-id {run_id} --answers answers.json after resolving {request_count} request(s)." + "{skill_name} needs agent input at {run_id}. Resolve {request_count} request(s), write answers.json, then run: runx resume {run_id} answers.json." ), runx, false, diff --git a/crates/runx-runtime/src/execution/runner/steps.rs b/crates/runx-runtime/src/execution/runner/steps.rs index 13e160d5b..4505812c1 100644 --- a/crates/runx-runtime/src/execution/runner/steps.rs +++ b/crates/runx-runtime/src/execution/runner/steps.rs @@ -29,7 +29,9 @@ use super::host_resolution::resolve_step_approval; use super::inputs::{optional_input_string, required_input_string, string_value, string_value_ref}; use super::{GraphRun, Runtime, StepRun}; use crate::RuntimeError; -use crate::adapter::{InvocationStatus, SkillAdapter, SkillInvocation, SkillOutput}; +use crate::adapter::{ + BorrowedSkillAdapter, InvocationStatus, SkillAdapter, SkillInvocation, SkillOutput, +}; #[cfg(feature = "catalog")] use crate::adapters::catalog::CatalogAdapter; use crate::agent_invocation::{ @@ -41,6 +43,7 @@ use crate::execution::disposition::agent_answer_disposition_or_closed; use crate::execution::output_projection::{StepOutputProjection, project_step_output}; use crate::host::Host; use crate::receipts::{StepSeal, StepSealClosure, seal_step}; +use crate::services::merge_inferred_tool_roots; const EXTERNAL_ADAPTER_HOST_RESOLUTION_REQUEST_METADATA: &str = "external_adapter_host_resolution_request"; @@ -334,10 +337,14 @@ where source_kind: "graph runner without source.graph".to_owned(), })?; let graph = materialize_graph_inputs(graph, &invocation.inputs); + let mut child_options = request.runtime.options.clone(); + child_options.env = invocation.env.clone(); + child_options.credential_delivery = invocation.credential_delivery.clone(); + let child_adapter: Box = + Box::new(BorrowedSkillAdapter::new(&request.runtime.adapter)); + let child_runtime = Runtime::new(child_adapter, child_options); let run = - request - .runtime - .run_graph_with_host(&invocation.skill_directory, graph, request.host)?; + child_runtime.run_graph_with_host(&invocation.skill_directory, graph, request.host)?; let payload = nested_graph_payload(&run)?; let mut output = nested_graph_skill_output(&payload, &run)?; let projection = step_output_projection(request.step, &output)?; @@ -440,6 +447,8 @@ fn loaded_skill_invocation( credential_delivery: &crate::credentials::CredentialDelivery, ) -> Result<(String, SkillInvocation), RuntimeError> { let skill_name = skill.name.clone(); + let mut invocation_env = env.clone(); + merge_inferred_tool_roots(&mut invocation_env, &skill.directory); let invocation = SkillInvocation { skill_name: skill.name, source: skill.source, @@ -453,7 +462,7 @@ fn loaded_skill_invocation( created_at, )?, skill_directory: skill.directory, - env: env.clone(), + env: invocation_env, credential_delivery: credential_delivery.clone(), }; Ok((skill_name, invocation)) diff --git a/crates/runx-runtime/src/registry/trust_anchor.rs b/crates/runx-runtime/src/registry/trust_anchor.rs index fec1663ce..2458654f4 100644 --- a/crates/runx-runtime/src/registry/trust_anchor.rs +++ b/crates/runx-runtime/src/registry/trust_anchor.rs @@ -177,6 +177,15 @@ pub fn trusted_registry_manifest_keys_from_env_with_source( .get(RUNX_REGISTRY_MANIFEST_TRUST_KEY_ID_ENV) .cloned() .ok_or(RegistryManifestTrustEnvError::MissingKeyId)?; + if matches!( + source_authority, + Some(RegistryManifestSourceAuthority::OfficialRunx) + ) { + let key = TrustedRegistryManifestKey::official_from_base64(key_id, public_key) + .map_err(|_| RegistryManifestTrustEnvError::InvalidKey)?; + trusted_keys.push(key); + return Ok(trusted_keys); + } let allowed_owner = env .get(RUNX_REGISTRY_MANIFEST_TRUST_OWNER_ENV) .cloned() @@ -330,3 +339,48 @@ fn decode_base64(value: &str) -> Result, base64::DecodeError> { .decode(value) .or_else(|_| STANDARD.decode(value)) } + +#[cfg(test)] +mod tests { + use super::*; + + fn trust_env() -> BTreeMap { + BTreeMap::from([ + ( + RUNX_REGISTRY_MANIFEST_TRUST_KEY_ID_ENV.to_owned(), + "test-key".to_owned(), + ), + ( + RUNX_REGISTRY_MANIFEST_TRUST_KEY_ENV.to_owned(), + "QkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkJCQkI=".to_owned(), + ), + ]) + } + + #[test] + fn official_source_trust_key_is_official_scoped_without_owner() { + let keys = trusted_registry_manifest_keys_from_env_with_source( + &trust_env(), + Some(RegistryManifestSourceAuthority::OfficialRunx), + ) + .expect("official source trust key should be accepted"); + + assert_eq!( + keys.last().map(|key| &key.scope), + Some(&RegistryManifestTrustScope::OfficialRunx) + ); + } + + #[test] + fn third_party_source_trust_key_still_requires_owner() { + let error = trusted_registry_manifest_keys_from_env_with_source( + &trust_env(), + Some(RegistryManifestSourceAuthority::RegistrySource( + "local:/tmp/runx-registry".to_owned(), + )), + ) + .expect_err("third-party trust key must be owner-scoped"); + + assert_eq!(error, RegistryManifestTrustEnvError::MissingOwner); + } +} diff --git a/crates/runx-runtime/src/services.rs b/crates/runx-runtime/src/services.rs index 9e799eb8c..af9d9aac7 100644 --- a/crates/runx-runtime/src/services.rs +++ b/crates/runx-runtime/src/services.rs @@ -6,7 +6,7 @@ mod tool_roots; #[cfg(any(feature = "mcp", feature = "agent"))] pub(crate) use env::process_env_snapshot; -pub(crate) use env::{WorkspaceEnv, process_env_value}; +pub(crate) use env::{WorkspaceEnv, merge_inferred_tool_roots, process_env_value}; pub(crate) use receipts::ReceiptServices; #[cfg(any(feature = "cli-tool", feature = "mcp"))] pub(crate) use sandbox::SandboxServices; diff --git a/crates/runx-runtime/src/services/env.rs b/crates/runx-runtime/src/services/env.rs index 9580cb19a..349daaac0 100644 --- a/crates/runx-runtime/src/services/env.rs +++ b/crates/runx-runtime/src/services/env.rs @@ -38,14 +38,42 @@ impl WorkspaceEnv { env.entry(RUNX_CWD_ENV.to_owned()) .or_insert_with(|| cwd.clone()); env.entry(RUNX_PROJECT_DIR_ENV.to_owned()).or_insert(cwd); - if let Some(joined) = inferred_tool_roots(skill_dir) { - env.entry(crate::services::tool_roots::RUNX_TOOL_ROOTS_ENV.to_owned()) - .or_insert(joined); - } + merge_inferred_tool_roots(&mut env, skill_dir); env } } +pub(crate) fn merge_inferred_tool_roots(env: &mut BTreeMap, skill_dir: &Path) { + if let Some(joined) = inferred_tool_roots(skill_dir) { + let key = crate::services::tool_roots::RUNX_TOOL_ROOTS_ENV.to_owned(); + env.entry(key) + .and_modify(|existing| *existing = merge_path_env(existing, &joined)) + .or_insert(joined); + } +} + +fn merge_path_env(existing: &str, addition: &str) -> String { + let mut paths: Vec = std::env::split_paths(existing).collect(); + for path in std::env::split_paths(addition) { + if !paths.iter().any(|existing_path| existing_path == &path) { + paths.push(path); + } + } + std::env::join_paths(paths) + .ok() + .map(|value| value.to_string_lossy().into_owned()) + .unwrap_or_else(|| { + if existing.is_empty() { + addition.to_owned() + } else if addition.is_empty() { + existing.to_owned() + } else { + let separator = if cfg!(windows) { ';' } else { ':' }; + format!("{existing}{separator}{addition}") + } + }) +} + pub(crate) fn process_env_value(key: &str) -> Option { std::env::var(key).ok() } @@ -54,3 +82,29 @@ pub(crate) fn process_env_value(key: &str) -> Option { pub(crate) fn process_env_snapshot() -> BTreeMap { std::env::vars().collect() } + +#[cfg(test)] +mod tests { + use std::path::PathBuf; + + use super::merge_path_env; + + #[test] + fn merge_path_env_appends_new_paths_and_deduplicates_existing_paths() { + let first = PathBuf::from("/runx/tools"); + let second = PathBuf::from("/runx/skills/data-store/tools"); + let existing = std::env::join_paths([first.as_path()]) + .unwrap() + .to_string_lossy() + .into_owned(); + let addition = std::env::join_paths([second.as_path(), first.as_path()]) + .unwrap() + .to_string_lossy() + .into_owned(); + + let merged = merge_path_env(&existing, &addition); + let paths = std::env::split_paths(&merged).collect::>(); + + assert_eq!(paths, vec![first, second]); + } +} diff --git a/crates/runx-runtime/tests/catalog_adapter.rs b/crates/runx-runtime/tests/catalog_adapter.rs index 0454d463c..33432c364 100644 --- a/crates/runx-runtime/tests/catalog_adapter.rs +++ b/crates/runx-runtime/tests/catalog_adapter.rs @@ -297,6 +297,499 @@ fn catalog_adapter_routes_http_tools_to_the_governed_http_adapter() Ok(()) } +#[test] +fn catalog_adapter_resolves_unbound_local_data_source_to_durable_sqlite_adapter() +-> Result<(), Box> { + let temp = tempdir()?; + write_catalog_tool( + &temp.path().join("tools/data/sqlite"), + r#"{ + "schema": "runx.tool.manifest.v1", + "name": "data.sqlite", + "source": { + "type": "cli-tool", + "command": "/bin/sh", + "args": ["./run.sh"], + "input_mode": "stdin" + }, + "inputs": { + "data_source_ref": { "type": "string", "required": true }, + "data_source_binding": { "type": "json", "required": true } + }, + "scopes": ["runx:data:read"] +} +"#, + r#"raw="$(cat)" +case "$raw" in + *'"adapter":"data.sqlite"'*|*'"adapter": "data.sqlite"'*) + case "$raw" in + *'"database_path":".runx/data/local-sources/source-'*|*'"database_path": ".runx/data/local-sources/source-'*) printf '%s\n' '{"adapter":"data.sqlite"}' ;; + *) printf 'missing sqlite database path: %s\n' "$raw" >&2; exit 9 ;; + esac + ;; + *) printf 'missing sqlite binding: %s\n' "$raw" >&2; exit 8 ;; +esac +"#, + )?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String("local://runx-data-store/test".to_owned()), + ); + + let output = CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + tool_root_env(temp.path()), + ))?; + + assert_eq!(output.status, InvocationStatus::Success); + assert_eq!(output.stdout.trim(), r#"{"adapter":"data.sqlite"}"#); + Ok(()) +} + +#[test] +fn catalog_adapter_preserves_store_id_local_data_source_fixture_mode() +-> Result<(), Box> { + let temp = tempdir()?; + write_catalog_tool( + &temp.path().join("tools/data/local"), + r#"{ + "schema": "runx.tool.manifest.v1", + "name": "data.local", + "source": { + "type": "cli-tool", + "command": "/bin/sh", + "args": ["./run.sh"], + "input_mode": "stdin" + }, + "inputs": { + "data_source_ref": { "type": "string", "required": true }, + "data_source_binding": { "type": "json", "required": true } + }, + "scopes": ["runx:data:read"] +} +"#, + r#"raw="$(cat)" +case "$raw" in + *'"adapter":"data.local"'*|*'"adapter": "data.local"'*) printf '%s\n' '{"adapter":"data.local"}' ;; + *) printf 'missing local fixture binding: %s\n' "$raw" >&2; exit 9 ;; +esac +"#, + )?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String("local://runx-data-store/test".to_owned()), + ); + inputs.insert( + "store_id".to_owned(), + JsonValue::String("catalog-fixture-store".to_owned()), + ); + + let output = CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + tool_root_env(temp.path()), + ))?; + + assert_eq!(output.status, InvocationStatus::Success); + assert_eq!(output.stdout.trim(), r#"{"adapter":"data.local"}"#); + Ok(()) +} + +#[test] +fn catalog_adapter_resolves_configured_data_source_binding() +-> Result<(), Box> { + let temp = tempdir()?; + fs::create_dir_all(temp.path().join(".runx"))?; + fs::write( + temp.path().join(".runx/data-sources.json"), + r#"{ + "data_sources": { + "tenant://acme/board": { + "adapter": "test.bound", + "profile": "prod-board", + "resources": { + "board_events": { "kind": "event_stream" } + } + } + } +} +"#, + )?; + write_catalog_tool( + &temp.path().join("tools/test/bound"), + r#"{ + "schema": "runx.tool.manifest.v1", + "name": "test.bound", + "source": { + "type": "cli-tool", + "command": "/bin/sh", + "args": ["./run.sh"], + "input_mode": "stdin" + }, + "inputs": { + "data_source_ref": { "type": "string", "required": true }, + "data_source_binding": { "type": "json", "required": true } + }, + "scopes": ["runx:data:read"] +} +"#, + r#"raw="$(cat)" +case "$raw" in + *'"adapter":"test.bound"'*|*'"adapter": "test.bound"'*) + case "$raw" in + *'"profile":"prod-board"'*|*'"profile": "prod-board"'*) printf '%s\n' '{"adapter":"test.bound","profile":"prod-board"}' ;; + *) printf 'missing profile: %s\n' "$raw" >&2; exit 9 ;; + esac + ;; + *) printf 'missing configured binding: %s\n' "$raw" >&2; exit 8 ;; +esac +"#, + )?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String("tenant://acme/board".to_owned()), + ); + let mut env = tool_root_env(temp.path()); + env.insert( + "RUNX_CWD".to_owned(), + temp.path().to_string_lossy().into_owned(), + ); + + let output = CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + env, + ))?; + + assert_eq!(output.status, InvocationStatus::Success); + assert_eq!( + output.stdout.trim(), + r#"{"adapter":"test.bound","profile":"prod-board"}"# + ); + Ok(()) +} + +#[test] +fn catalog_adapter_prefers_configured_local_data_source_over_default() +-> Result<(), Box> { + let temp = tempdir()?; + fs::create_dir_all(temp.path().join(".runx"))?; + fs::write( + temp.path().join(".runx/data-sources.json"), + r#"{ + "data_sources": { + "local://runx-data-store/configured": { + "adapter": "test.local-bound", + "profile": "configured-local" + } + } +} +"#, + )?; + write_catalog_tool( + &temp.path().join("tools/test/local-bound"), + r#"{ + "schema": "runx.tool.manifest.v1", + "name": "test.local-bound", + "source": { + "type": "cli-tool", + "command": "/bin/sh", + "args": ["./run.sh"], + "input_mode": "stdin" + }, + "inputs": { + "data_source_ref": { "type": "string", "required": true }, + "data_source_binding": { "type": "json", "required": true } + }, + "scopes": ["runx:data:read"] +} +"#, + r#"raw="$(cat)" +case "$raw" in + *'"adapter":"test.local-bound"'*|*'"adapter": "test.local-bound"'*) printf '%s\n' '{"adapter":"test.local-bound"}' ;; + *) printf 'missing configured local binding: %s\n' "$raw" >&2; exit 8 ;; +esac +"#, + )?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String("local://runx-data-store/configured".to_owned()), + ); + let mut env = tool_root_env(temp.path()); + env.insert( + "RUNX_CWD".to_owned(), + temp.path().to_string_lossy().into_owned(), + ); + + let output = CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + env, + ))?; + + assert_eq!(output.status, InvocationStatus::Success); + assert_eq!(output.stdout.trim(), r#"{"adapter":"test.local-bound"}"#); + Ok(()) +} + +#[test] +fn catalog_adapter_resolves_relative_data_sources_env_from_workspace_root() +-> Result<(), Box> { + let temp = tempdir()?; + fs::create_dir_all(temp.path().join("config"))?; + fs::write( + temp.path().join("config/data-sources.json"), + r#"{ + "data_sources": { + "tenant://acme/ledger": { + "adapter": "test.env-bound", + "profile": "ledger-prod" + } + } +} +"#, + )?; + write_catalog_tool( + &temp.path().join("tools/test/env-bound"), + r#"{ + "schema": "runx.tool.manifest.v1", + "name": "test.env-bound", + "source": { + "type": "cli-tool", + "command": "/bin/sh", + "args": ["./run.sh"], + "input_mode": "stdin" + }, + "inputs": { + "data_source_ref": { "type": "string", "required": true }, + "data_source_binding": { "type": "json", "required": true } + }, + "scopes": ["runx:data:read"] +} +"#, + r#"raw="$(cat)" +case "$raw" in + *'"adapter":"test.env-bound"'*|*'"adapter": "test.env-bound"'*) printf '%s\n' '{"adapter":"test.env-bound"}' ;; + *) printf 'missing env binding: %s\n' "$raw" >&2; exit 8 ;; +esac +"#, + )?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String("tenant://acme/ledger".to_owned()), + ); + let mut env = tool_root_env(temp.path()); + env.insert( + "RUNX_CWD".to_owned(), + temp.path().to_string_lossy().into_owned(), + ); + env.insert( + "RUNX_DATA_SOURCES".to_owned(), + "config/data-sources.json".to_owned(), + ); + + let output = CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + env, + ))?; + + assert_eq!(output.status, InvocationStatus::Success); + assert_eq!(output.stdout.trim(), r#"{"adapter":"test.env-bound"}"#); + Ok(()) +} + +#[test] +fn catalog_adapter_fails_closed_for_invalid_data_sources_env_json() +-> Result<(), Box> { + let temp = tempdir()?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String("tenant://acme/board".to_owned()), + ); + let mut env = tool_root_env(temp.path()); + env.insert("RUNX_DATA_SOURCES".to_owned(), "{not-json".to_owned()); + + let output = CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + env, + ))?; + + assert_eq!(output.status, InvocationStatus::Failure); + assert!(output.stderr.contains("not valid JSON")); + Ok(()) +} + +#[test] +fn catalog_adapter_fails_closed_for_missing_required_data_sources_file() +-> Result<(), Box> { + let temp = tempdir()?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String("tenant://acme/board".to_owned()), + ); + let mut env = tool_root_env(temp.path()); + env.insert( + "RUNX_CWD".to_owned(), + temp.path().to_string_lossy().into_owned(), + ); + env.insert( + "RUNX_DATA_SOURCES".to_owned(), + "missing/data-sources.json".to_owned(), + ); + + let output = CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + env, + ))?; + + assert_eq!(output.status, InvocationStatus::Failure); + assert!(output.stderr.contains("Failed to read data source config")); + assert!(output.stderr.contains("missing/data-sources.json")); + Ok(()) +} + +#[test] +fn catalog_adapter_fails_closed_for_unbound_non_local_data_source() +-> Result<(), Box> { + let temp = tempdir()?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String("tenant://missing/board".to_owned()), + ); + + let output = CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + tool_root_env(temp.path()), + ))?; + + assert_eq!(output.status, InvocationStatus::Failure); + assert!(output.stderr.contains("tenant://missing/board")); + assert!(output.stderr.contains(".runx/data-sources.json")); + Ok(()) +} + +#[test] +fn catalog_adapter_fails_closed_for_data_source_binding_without_adapter() +-> Result<(), Box> { + let output = invoke_data_source_with_inline_binding( + "tenant://acme/board", + r#"{"data_sources":{"tenant://acme/board":{"profile":"missing-adapter"}}}"#, + )?; + + assert_eq!(output.status, InvocationStatus::Failure); + assert!(output.stderr.contains("missing adapter")); + Ok(()) +} + +#[test] +fn catalog_adapter_fails_closed_for_recursive_data_source_adapter() +-> Result<(), Box> { + let output = invoke_data_source_with_inline_binding( + "tenant://acme/board", + r#"{"data_sources":{"tenant://acme/board":{"adapter":"data.source"}}}"#, + )?; + + assert_eq!(output.status, InvocationStatus::Failure); + assert!(output.stderr.contains("cannot bind to data.source")); + Ok(()) +} + +#[test] +fn catalog_adapter_fails_closed_for_non_namespaced_data_source_adapter() +-> Result<(), Box> { + let output = invoke_data_source_with_inline_binding( + "tenant://acme/board", + r#"{"data_sources":{"tenant://acme/board":{"adapter":"postgres"}}}"#, + )?; + + assert_eq!(output.status, InvocationStatus::Failure); + assert!(output.stderr.contains("must be a namespaced tool ref")); + Ok(()) +} + +#[test] +fn catalog_adapter_rejects_secret_material_in_data_source_binding() +-> Result<(), Box> { + let temp = tempdir()?; + fs::create_dir_all(temp.path().join(".runx"))?; + fs::write( + temp.path().join(".runx/data-sources.json"), + r#"{ + "data_sources": { + "tenant://acme/board": { + "adapter": "test.bound", + "api_key": "raw-secret-value" + } + } +} +"#, + )?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String("tenant://acme/board".to_owned()), + ); + let mut env = tool_root_env(temp.path()); + env.insert( + "RUNX_CWD".to_owned(), + temp.path().to_string_lossy().into_owned(), + ); + + let output = CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + env, + ))?; + + assert_eq!(output.status, InvocationStatus::Failure); + assert!(output.stderr.contains("api_key")); + assert!(output.stderr.contains("credential profile")); + Ok(()) +} + +fn invoke_data_source_with_inline_binding( + data_source_ref: &str, + config: &str, +) -> Result> { + let temp = tempdir()?; + let mut inputs = JsonObject::new(); + inputs.insert( + "data_source_ref".to_owned(), + JsonValue::String(data_source_ref.to_owned()), + ); + let mut env = tool_root_env(temp.path()); + env.insert("RUNX_DATA_SOURCES".to_owned(), config.to_owned()); + + Ok(CatalogAdapter::default().invoke(invocation_in_directory( + Some("data.source"), + inputs, + temp.path().to_path_buf(), + env, + ))?) +} + fn invocation(catalog_ref: Option<&str>, inputs: JsonObject) -> SkillInvocation { invocation_in_directory(catalog_ref, inputs, PathBuf::from("."), BTreeMap::new()) } diff --git a/crates/runx-runtime/tests/skill_run.rs b/crates/runx-runtime/tests/skill_run.rs index a0b2dc177..ce7624efd 100644 --- a/crates/runx-runtime/tests/skill_run.rs +++ b/crates/runx-runtime/tests/skill_run.rs @@ -1731,6 +1731,48 @@ fn native_graph_skill_run_uses_canonical_tool_root() -> Result<(), Box Result<(), Box> { + let temp = tempdir()?; + let skill_dir = write_graph_importing_graph_with_bundled_tool(temp.path())?; + let receipt_dir = temp.path().join("receipts"); + let inputs = [( + "thread_title".to_owned(), + JsonValue::String("Graph tool bug".to_owned()), + )] + .into_iter() + .collect::>(); + + let result = run_skill(SkillRunRequest { + skill_path: skill_dir, + receipt_dir: Some(receipt_dir), + run_id: None, + answers_path: None, + inputs, + env: BTreeMap::new(), + cwd: temp.path().to_path_buf(), + local_credential: None, + })?; + + let output = object(&result.output, "nested graph tool root result")?; + assert_eq!(string_field(output, "status"), Some("sealed")); + let payload = object_field(output, "payload").ok_or("missing payload")?; + let nested_claim = step_claim(payload, "nested").ok_or("missing nested skill claim")?; + let child_steps = object_field(nested_claim, "step_outputs").ok_or("missing child steps")?; + let child_echo_step = object_field(child_steps, "echo").ok_or("missing child echo step")?; + let child_echo_claim = + object_field(child_echo_step, "skill_claim").ok_or("missing child echo claim")?; + let echo = object_field(child_echo_claim, "echo").ok_or("missing nested echo output")?; + assert_eq!( + string_field(echo, "message"), + Some("Nested graph tool root bug") + ); + + Ok(()) +} + #[cfg(feature = "cli-tool")] #[test] fn native_graph_skill_run_executes_nested_cli_tool_skill() -> Result<(), Box> @@ -2439,6 +2481,64 @@ fn write_graph_tool_skill_under_skills(root: &Path) -> Result Result> { + let parent_dir = root.join("skills/parent-board"); + let child_dir = root.join("skills/child-data"); + fs::create_dir_all(&parent_dir)?; + fs::create_dir_all(&child_dir)?; + fs::write( + parent_dir.join("SKILL.md"), + "---\nname: parent-board\n---\n# Parent Board\n", + )?; + fs::write( + parent_dir.join("X.yaml"), + r#" +skill: parent-board +runners: + graph: + default: true + type: graph + graph: + name: parent-board + steps: + - id: nested + skill: ../child-data + inputs: + message: $input.thread_title +"#, + )?; + + fs::write( + child_dir.join("SKILL.md"), + "---\nname: child-data\n---\n# Child Data\n", + )?; + fs::write( + child_dir.join("X.yaml"), + r#" +skill: child-data +runners: + graph: + default: true + type: graph + graph: + name: child-data + steps: + - id: echo + tool: test.echo + inputs: + message: $input.message +"#, + )?; + write_echo_tool_at( + &child_dir.join("tools/test/echo"), + "Nested graph tool root bug", + )?; + Ok(parent_dir) +} + #[cfg(feature = "catalog")] fn write_graph_tool_skill_at(skill_dir: &Path) -> Result> { fs::create_dir_all(skill_dir)?; diff --git a/docs/cli-exit-codes.md b/docs/cli-exit-codes.md index ccc10033d..ed742c718 100644 --- a/docs/cli-exit-codes.md +++ b/docs/cli-exit-codes.md @@ -37,7 +37,7 @@ can distinguish it from ordinary command failure. Common fixes: ```bash -runx skill --run-id --answers answers.json +runx resume answers.json ``` For required input, pass the missing `--input` value or the corresponding diff --git a/docs/demo-inventory.json b/docs/demo-inventory.json index ed6ed4b26..ac973d499 100644 --- a/docs/demo-inventory.json +++ b/docs/demo-inventory.json @@ -8,8 +8,13 @@ }, { "path": "skills/business-ops", - "proof": "One business signal fans out through governed ops lanes and seals a graph receipt.", - "command": "runx harness skills/business-ops/fixtures/business-ops-smoke.yaml" + "proof": "One business signal is classified, persisted through the governed data plane, read back, and sealed.", + "command": "runx harness skills/business-ops/fixtures/route-and-append-sqlite.yaml" + }, + { + "path": "skills/data-store", + "proof": "Provider-agnostic data operation appends and reads durable SQLite state through a governed adapter envelope.", + "command": "runx harness skills/data-store/fixtures/append-read-sqlite-event.yaml" }, { "path": "examples/github-mcp-hero", diff --git a/docs/demos.md b/docs/demos.md index bbffb5773..e545db386 100644 --- a/docs/demos.md +++ b/docs/demos.md @@ -18,7 +18,8 @@ export RUNX_RECEIPT_SIGN_ISSUER_TYPE=hosted | Demo | Proof | Run | Gate | | --- | --- | --- | --- | | `examples/hello-world` | Native CLI top-level skill and harness baseline. | `runx harness examples/hello-world` | harness | -| `skills/business-ops` | One business signal fans out through governed ops lanes and seals a graph receipt. | `runx harness skills/business-ops/fixtures/business-ops-smoke.yaml` | harness | +| `skills/business-ops` | One business signal is classified, persisted through the governed data plane, read back, and sealed. | `runx harness skills/business-ops/fixtures/route-and-append-sqlite.yaml` | harness | +| `skills/data-store` | A provider-agnostic data operation appends and reads durable SQLite state through a governed adapter envelope. | `runx harness skills/data-store/fixtures/append-read-sqlite-event.yaml` | harness | | `examples/github-mcp-hero` | GitHub MCP repo read succeeds, out-of-scope write is refused, and the denial receipt verifies offline. | `sh examples/github-mcp-hero/run.sh` | harness | | `examples/http-graph` | A graph step uses the governed HTTP front against a local fixture and seals a receipt tree. | `sh examples/http-graph/run.sh` | harness | | `examples/openapi-graph` | An OpenAPI-described operation is executed through the governed external-adapter lane and sealed. | `sh examples/openapi-graph/run.sh` | harness | diff --git a/docs/governed-data-plane.md b/docs/governed-data-plane.md new file mode 100644 index 000000000..5f201a37a --- /dev/null +++ b/docs/governed-data-plane.md @@ -0,0 +1,406 @@ +# Governed Data Plane + +runx should support stateful work without becoming a database. The data plane is +the boundary between domain skills and storage providers. + +This is intentionally a skill capability, not a separate database-admin CLI. +The `runx skill` command remains the execution surface; sources and providers +are selected by bindings. + +## Shape + +- A **domain skill** owns product meaning: messageboard transitions, review + states, CRM records, approval inboxes, support tickets, ledgers, and so on. +- A **data source** declares resources and operations: named reads, append + events, read events, read projections, compare-and-set, or provider-specific + bounded commands. +- A **data adapter** executes those operations against one provider: Postgres, + SQLite, D1, Redis, DynamoDB, S3, Supabase, Turso, product HTTP APIs, or local + JSON fixtures. +- A **data operation result** is provider-neutral receipt evidence: + `runx.data.operation_result.v1`. + +The model never authors arbitrary SQL, Redis commands, or migrations. It selects +declared operations with typed params. + +## Adapter Selection + +Users choose a **data source**, not a raw provider command. A data source is a +stable logical ref such as `local://runx-data-store/dev-board`, +`tenant://acme/board`, or `runx:data-source:acme-board`. The project or hosted +operator binds that source to a concrete adapter: + +```json +{ + "data_sources": { + "tenant://acme/board": { + "adapter": "data.postgres", + "profile": "prod-board", + "resources": { + "board_events": { + "kind": "event_stream", + "partition_key": "aggregate_id" + } + } + } + } +} +``` + +The skill run still passes only the logical source and operation inputs: + +```bash +runx skill data-store append_event \ + -i data_source_ref=tenant://acme/board \ + -i resource=board_events \ + -i aggregate_id=posting-123 \ + --input-json expected_version=2 \ + -i idempotency_key=posting-123:claim:agent-9 \ + --input-json event='{"type":"posting.claimed","payload":{"actor":"agent-9"}}' \ + --json +``` + +For local dogfood, the bundled `data-store` proof uses the checked-in +`data.source` resolver. Unbound `local://...` refs default to the durable +`data.sqlite` adapter under `.runx/data/local-sources/`, with the file name +derived from the logical source ref, so stateful skills work without a separate +database setup and independent sources do not collide. Pass `store_id` only +when a fixture intentionally wants the checked-in `data.local` JSON store. For +production, install or configure a provider adapter such as `data.postgres`, +`data.d1`, `data.redis`, or `data.object`, then bind the same logical +`data_source_ref` to that adapter. Domain skills should not branch on provider +type. If a graph needs a different storage backend, change the binding or pass +a different `data_source_ref`; do not edit messageboard, CRM, or operator +semantics into runx core. + +Adapter binding is authority-bearing configuration. It may name a credential +profile or hosted grant, but it must not contain raw secrets. Provider secrets +are delivered through the normal runx credential boundary. + +Adapter preference is explicit and local to the operator. Use `.runx/data-sources.json` +for a project default, or `RUNX_DATA_SOURCES` for a one-run override. The graph +still passes only `data_source_ref`; it does not get to choose Redis over SQLite +unless the operator binds that source to Redis. + +## Provider Adapter Contract + +A provider adapter is a normal runx tool manifest. It should declare inputs for +the generic operation envelope and may optionally declare `data_source_binding` +if it needs non-secret profile/resource metadata from the resolver: + +```json +{ + "schema": "runx.tool.manifest.v1", + "name": "data.postgres", + "source": { + "type": "cli-tool", + "command": "node", + "args": ["./run.mjs"], + "input_mode": "stdin" + }, + "inputs": { + "operation": { "type": "string", "required": true }, + "data_source_ref": { "type": "string", "required": true }, + "data_source_binding": { "type": "json", "required": false }, + "resource": { "type": "string", "required": true }, + "aggregate_id": { "type": "string", "required": true }, + "expected_version": { "type": "number", "required": false }, + "idempotency_key": { "type": "string", "required": false }, + "event": { "type": "json", "required": false }, + "limit": { "type": "number", "required": false } + }, + "scopes": ["runx:data:read", "runx:data:append"], + "output": { + "packet": "runx.data.operation_result.v1", + "wrap_as": "data_operation_result" + } +} +``` + +Adapter implementations are responsible for translating the declared operation +into provider-specific calls. A Postgres adapter may execute SQL internally; a +Redis adapter may call Redis commands internally; a D1 adapter may use +Cloudflare APIs internally. The model and domain skill still see only the +operation envelope and the sealed `runx.data.operation_result.v1` result. + +Provider adapters must fail closed when a write's commit state is ambiguous. +They should return `provider_unavailable` only when no commit can be proven, and +must include enough provider evidence to diagnose the failure without exposing +credentials or private payloads. + +## Operation Envelope + +Every provider adapter should accept the same conceptual envelope: + +```json +{ + "operation": "append_event", + "data_source_ref": "tenant://example/board", + "resource": "board_events", + "aggregate_id": "posting-123", + "expected_version": 2, + "idempotency_key": "posting-123:claim:agent-9", + "event": { + "type": "posting.claimed", + "payload": {} + } +} +``` + +And return: + +```json +{ + "schema": "runx.data.operation_result.v1", + "data_source_ref": "tenant://example/board", + "provider": "postgres", + "operation": "append_event", + "resource": "board_events", + "aggregate_id": "posting-123", + "status": "committed", + "before_version": 2, + "after_version": 3, + "idempotency_key": "posting-123:claim:agent-9", + "event_ref": "board_events:posting-123:3", + "result_digest": "sha256:...", + "projection_digest": "sha256:...", + "redactions": [] +} +``` + +Adapters may include provider evidence, but not credentials or raw secrets. +When an event carries an explicit `type`, adapters use it as `event_type`. +When a domain skill emits the generic runx effect packet shape instead, adapters +derive `event_type` from `effect_family.operation`, for example +`messageboard.accept`. If neither field exists, the event remains +`data.event`. + +## Provider Rules + +SQL providers should expose named query templates and append/update routines, +not free-form model SQL. Redis providers should expose declared commands by +purpose, not arbitrary command strings. Object stores should expose keyed read +or append operations with content digests and size caps. Product APIs should +declare the same resources and operation names even if they are backed by HTTP. + +All writes need an idempotency key. Versioned resources should require +`expected_version`; append-only streams still return the before and after +versions so replay can prove order. + +## Messageboard Example + +The messageboard skill decides whether `posting.claimed` is allowed and emits a +domain transition packet. A graph then calls `data-store.append_event` with the +packet. The data adapter appends it to `board_events` only if the current stream +version matches `expected_version`. A later turn reads events or a projection to +resume. + +No messageboard enum belongs in runx core. The data plane stores and proves the +transition. The messageboard skill and its app-specific reducer own the meaning. + +### Dogfood A Stateful Messageboard + +This is the current end-to-end local proof. It uses the public `messageboard` +skill, the public `data-store` skill, and a logical source binding. The +messageboard graph does not know whether the storage backend is SQLite or Redis. + +For SQLite, bind the source to a local database: + +```json +{ + "data_sources": { + "tenant://dogfood/sqlite/board-1": { + "adapter": "data.sqlite", + "database_path": ".runx/data/board-1.sqlite", + "resources": { + "board_events": { + "kind": "event_stream", + "partition_key": "aggregate_id" + } + } + } + } +} +``` + +For Redis, keep the same logical resource and change only the binding: + +```json +{ + "data_sources": { + "tenant://dogfood/redis/board-1": { + "adapter": "data.redis", + "endpoint": "redis://127.0.0.1:6379/0", + "key_prefix": "runx:dogfood:board-1", + "resources": { + "board_events": { + "kind": "event_stream", + "partition_key": "aggregate_id" + } + } + } + } +} +``` + +Run the posting transition: + +```bash +RUNX_DATA_SOURCES=.runx/data-sources.json \ +runx skill skills/messageboard post_and_append \ + -R .runx/receipts \ + -i data_source_ref=tenant://dogfood/sqlite/board-1 \ + -i resource=board_events \ + -i aggregate_id=board-1 \ + --input-json expected_version=0 \ + -i idempotency_key=board-1:post:v1 \ + -i actor_kid=vendor-demo \ + -i title='prove persistent messageboard storage' \ + -i deliverable='append, claim, deliver, and accept one posting across separate runx runs' \ + --input-json amount_minor=2500 \ + -i currency=USD \ + --input-json funding_evidence='{"hold_ref":"mock:hold:board-1"}' \ + -j +``` + +With no managed-agent provider configured, the command returns `needs_agent` +with a `run_id` and request id such as `agent_task.messageboard-post.output`. +Answer it by resuming the same run: + +```bash +RUNX_DATA_SOURCES=.runx/data-sources.json \ +runx resume answers.json \ + -R .runx/receipts \ + -j +``` + +Repeat the same start/resume shape for: + +- `claim_and_append` with `expected_version=1` +- `deliver_and_append` with `expected_version=2` +- `accept_and_append` with `expected_version=3` + +For a single posting stream, only these inputs change between transitions: + +```bash +# claim the posting that was appended at version 1 +RUNX_DATA_SOURCES=.runx/data-sources.json \ +runx skill skills/messageboard claim_and_append \ + -R .runx/receipts \ + -i data_source_ref=tenant://dogfood/sqlite/board-1 \ + -i resource=board_events \ + -i aggregate_id=board-1 \ + --input-json expected_version=1 \ + -i idempotency_key=board-1:claim:worker-demo:v1 \ + -i actor_kid=worker-demo \ + --input-json posting='{"id":"board-1","status":"approved","title":"prove persistent messageboard storage","amount_minor":2500,"currency":"USD"}' \ + -i idempotency_seed=worker-demo-board-1 \ + -j + +# deliver against the active claim at version 2 +RUNX_DATA_SOURCES=.runx/data-sources.json \ +runx skill skills/messageboard deliver_and_append \ + -R .runx/receipts \ + -i data_source_ref=tenant://dogfood/sqlite/board-1 \ + -i resource=board_events \ + -i aggregate_id=board-1 \ + --input-json expected_version=2 \ + -i idempotency_key=board-1:deliver:worker-demo:v1 \ + -i actor_kid=worker-demo \ + --input-json claim='{"posting_id":"board-1","claimant_kid":"worker-demo","status":"active","delivery_due_at":"2026-06-13T00:00:00Z"}' \ + --input-json delivery_evidence='{"artifact_ref":"git:commit:abc123","verifier_command":"./verify.sh"}' \ + -j + +# accept the delivered work at version 3 +RUNX_DATA_SOURCES=.runx/data-sources.json \ +runx skill skills/messageboard accept_and_append \ + -R .runx/receipts \ + -i data_source_ref=tenant://dogfood/sqlite/board-1 \ + -i resource=board_events \ + -i aggregate_id=board-1 \ + --input-json expected_version=3 \ + -i idempotency_key=board-1:accept:vendor-demo:v1 \ + -i actor_kid=vendor-demo \ + --input-json delivery='{"posting_id":"board-1","claimant_kid":"worker-demo","delivery_ref":"delivery:board-1","artifact_ref":"git:commit:abc123"}' \ + --input-json acceptance_evidence='{"verifier_result":"passed"}' \ + -j +``` + +If a managed-agent provider is configured, those commands can seal directly. +Without one, each command returns `needs_agent`; resume it with the matching +answer packet for `agent_task.messageboard-claim.output`, +`agent_task.messageboard-deliver.output`, or +`agent_task.messageboard-accept.output`. The checked-in +`skills/messageboard/fixtures/*-and-append-sqlite.yaml` files show the exact +answer shapes. + +Then read the stream: + +```bash +RUNX_DATA_SOURCES=.runx/data-sources.json \ +runx skill skills/data-store read_events \ + -R .runx/receipts \ + -i data_source_ref=tenant://dogfood/sqlite/board-1 \ + -i resource=board_events \ + -i aggregate_id=board-1 \ + --input-json limit=10 \ + -j +``` + +The dogfood pass should return four ordered events: +`messageboard.post`, `messageboard.claim`, `messageboard.deliver`, and +`messageboard.accept`. Switching the `data_source_ref` from the SQLite binding +to the Redis binding exercises the same skill graph against Redis. No graph +edit, provider branch, or messageboard-specific storage code is required. + +## Security Gates + +- require explicit resource, tenant, stream, or partition keys; +- cap rows, event count, object size, and response bytes; +- redact fields declared secret or private; +- reject broad exports and schema-free reads; +- separate read scopes from append/update scopes; +- make retries idempotent; +- fail closed on ambiguous commit state; +- seal result digests and provider evidence, not credentials. + +## Current OSS Proof + +`skills/data-store` ships three adapters: + +- `data.sqlite`: a durable local adapter that uses SQLite transactions, + optimistic concurrency, idempotency keys, and readback projections. It is the + first real provider-shaped proof and the default for unbound `local://...` + refs. Streams are keyed by `data_source_ref`, resource, and aggregate id. +- `data.local`: a local JSON fixture adapter for deterministic harnesses and + contract tests. It is selected by passing `store_id`, not by normal local + dogfood. +- `data.redis`: a Redis adapter that uses a Redis list for the event stream, a + Redis hash for idempotency keys, and one Lua script for atomic append, + optimistic-concurrency, and idempotency checks. It is selected by binding a + logical source to `adapter: "data.redis"` with a non-secret endpoint and key + prefix. + +Postgres, D1, object-store, hosted, and product API providers should implement +the same operation result shape behind their own adapters. + +The public catalog entry is still `data-store`. Bundled provider tools such as +`data.sqlite` and `data.redis` are surfaced as adapters behind that canonical +skill, not as duplicate domain skills. + +## Durable Composition Examples + +The public skills intentionally compose the data plane instead of embedding +storage semantics: + +- `messageboard.post_and_append`, `claim_and_append`, `deliver_and_append`, and + `accept_and_append` decide a board transition, append the packet through + `data-store`, and read back the projection. +- `ops-desk.operate_from_projection` reads a projection before asking the + operator agent to propose next actions. +- `business-ops.route_and_append` classifies one business signal and persists + the routed packet for replay. + +These examples all run against `data.sqlite` fixtures today. The same graph +shape can run against Redis, Postgres, D1, or a product API once the logical +source ref is rebound to that adapter. diff --git a/docs/loop-orchestration.md b/docs/loop-orchestration.md index 2719c61c3..0c70900eb 100644 --- a/docs/loop-orchestration.md +++ b/docs/loop-orchestration.md @@ -96,6 +96,7 @@ Use runx for: - governed skill/graph turns; - authority attenuation and approval gates; - bounded model/tool execution; +- governed data operations through declared data-source adapters; - digest-bound skill context; - receipt sealing and verification. @@ -110,6 +111,10 @@ Use the outer loop host for: The loop host can be a local script, hosted runx service, product app, Temporal workflow, LangGraph app, n8n/Make/Zapier workflow, or another orchestrator. +When the loop host stores state through runx, use the provider-agnostic data +plane in [docs/governed-data-plane.md](governed-data-plane.md): the host owns +scheduling and stop policy, while runx seals each bounded read, append, or +projection operation. ## Do Not Build diff --git a/docs/orchestrator-integrations.md b/docs/orchestrator-integrations.md index 24cdad075..29d7859f8 100644 --- a/docs/orchestrator-integrations.md +++ b/docs/orchestrator-integrations.md @@ -28,11 +28,10 @@ operator dogfood. It should feel direct, literal, and governed: ```bash runx skill weather-forecast \ --input location="Sydney, AU" \ - --input forecast_evidence='{"provider":"example","periods":[]}' \ + --input-json forecast_evidence='{"provider":"example","periods":[]}' \ --json -runx skill nws-weather-forecast \ - --runner forecast \ +runx skill nws-weather-forecast forecast \ --office LWX \ --grid-x 97 \ --grid-y 71 @@ -44,7 +43,7 @@ Operator rules: directory. - `--input key=value` is the documented portable form; direct flags such as `--office LWX` remain the ergonomic shorthand. -- `--runner ` selects a non-default runner without changing the skill +- `runx skill ` selects a non-default runner without changing the skill package. - `--json` prints the full machine contract. Without `--json`, the CLI prints a concise status view with run id, receipt id, and pending request ids rather diff --git a/docs/reference.md b/docs/reference.md index 00bc8769f..6a156c572 100644 --- a/docs/reference.md +++ b/docs/reference.md @@ -104,7 +104,7 @@ runx registry search sourcey --json runx skill sourcey/sourcey@1.0.0 --registry https://runx.example.test --project . --json runx add sourcey/sourcey@1.0.0 --registry https://runx.example.test --to ./skills --json runx skill issue-to-pr --fixture /path/to/repo --task-id task-123 -runx skill /path/to/skill --run-id --answers answers.json +runx resume answers.json runx history --json runx history runx mcp serve ./fixtures/skills/echo @@ -174,10 +174,23 @@ Command-surface ownership: | `runx harness ` | Rust harness replay | tests and wrapper views | | receipts and history | Rust receipt store and journal | display/client views | | policy, authority, payment, x402 | Rust core/runtime policy | published type mirrors and product UX | +| governed data operations | skill graphs plus provider adapters | generated types, helper SDKs, provider glue | | external execution-adapter protocol | `runx-runtime` supervisor | generated types, helper SDKs, host/client wrappers | | non-execution extension protocols | lane-specific Rust/cloud owners | generated types, helper SDKs, provider glue | | marketplace and docs tooling | TypeScript/scafld until separately cut over | canonical for authoring UX | +Stateful product work should use the governed data-plane shape in +[docs/governed-data-plane.md](docs/governed-data-plane.md): domain skills own +meaning, while provider adapters execute bounded reads, append-only event +writes, and projection reads. + +The generic graph tool ref for provider choice is `data.source`. It reads the +step's `data_source_ref`, resolves it through `RUNX_DATA_SOURCES` or +`.runx/data-sources.json`, injects the non-secret binding metadata into the +adapter input, and invokes the configured adapter. Unbound `local://...` refs +default to bundled durable SQLite; `store_id` opts into the bundled JSON fixture +adapter for deterministic harnesses. + ### Local Sandbox Posture `cli-tool` skills declare sandbox intent in `SKILL.md`: profile, cwd policy, @@ -209,7 +222,7 @@ The intended extension model is: execution envelope, while the thread stays the review/control object Sourcey is the reference shape for this model: from inside the Sourcey repo, -`runx skill ./skills/outreach --runner status --issue ...` resolves the local +`runx skill ./skills/outreach status --issue ...` resolves the local `skills/outreach` capability pack. `outreach` is not a privileged engine command, and there is no privileged `runx docs ...` path inside the engine. @@ -259,6 +272,14 @@ custom tags, multi-document markers, duplicate mapping keys, or unknown profile fields. Keep capability and receipt mappings explicit in the runner that uses them. +Public catalog packages must keep examples in standalone fixtures, not inline +manifest harness blocks. The package should contain only the files the skill +uses at execution time: `SKILL.md`, `X.yaml`, deterministic runner files, +schemas, fixtures, and narrowly scoped `context/` or `references/`. Do not add +README/changelog/setup docs, generated state, logs, screenshots, private +provider config, or broad project plans inside a public skill. The public docs +for the package belong in `SKILL.md`; external guides belong under `docs/`. + See `../docs/skill-profile-model.md` for resolution rules, publication modes, trust tiers, MCP export, and composite skill behavior. See `../docs/evolution-model.md` for the evolve lane, the skill/tool boundary, diff --git a/docs/skill-quality-standard.md b/docs/skill-quality-standard.md index e71f71974..545fff9cb 100644 --- a/docs/skill-quality-standard.md +++ b/docs/skill-quality-standard.md @@ -71,6 +71,19 @@ The public catalog test enforces the required sections for every skill with stages at `skills//graph//X.yaml`; they are not hidden catalog skills and should not carry public-skill documentation requirements. +Public skills must also keep their executable proof outside the manifest. A +public `X.yaml` describes runners and authority. Concrete scenarios live in +standalone `fixtures/*.yaml` files with `kind: skill`, `target: ..`, and one +fixture covering every public runner. Inline `harness.cases` are reserved for +internal evaluator/showcase packages, not public catalog packages. + +Public skill packages are not dumping grounds. Keep only files the skill +actually consumes or emits: `SKILL.md`, `X.yaml`, small deterministic runners, +schemas, fixtures, and narrowly scoped `context/` or `references/` files. +Avoid `README.md`, changelogs, generated state, screenshots, logs, hidden +provider config, private examples, and broad strategy docs. If a user-facing +guide is needed, publish it as docs outside the skill package. + ## Execution Profile Discipline Use the term **execution profile** for `X.yaml`. The filename stays `X.yaml` for @@ -85,7 +98,7 @@ the letter as the concept. - tool, adapter, context-skill, and graph wiring; - authority, approval, and receipt-act mappings; - side-effect posture: read, draft, plan, mutate, send, pay, or manual-gated; -- inline `harness.cases`. +- inline `harness.cases` only for internal evaluator packages. Author `X.yaml` in the strict profile YAML subset: no anchors, aliases, merge keys, custom tags, multi-document markers, duplicate mapping keys, or unknown diff --git a/docs/skill-to-graph.md b/docs/skill-to-graph.md index 0d091480a..a15f13c37 100644 --- a/docs/skill-to-graph.md +++ b/docs/skill-to-graph.md @@ -234,6 +234,51 @@ Then run with `-p operator` (or `--profile operator`). If it checks the project `.runx/credentials.json` and then the global runx home. The profile file never contains the secret value. +## Governed Data Steps + +Use the data plane when a graph needs durable state, not when it needs a model +to invent database commands. The canonical shape is a domain skill followed by +a declared data operation: + +```yaml +steps: + - id: decide + skill: ./messageboard + runner: claim + - id: append + skill: ./data-store + runner: append_event + inputs: + data_source_ref: "$input.data_source_ref" + resource: board_events + aggregate_id: "$input.posting_id" + expected_version: "$input.expected_version" + idempotency_key: "$input.idempotency_key" + context: + event: decide.messageboard_claim_packet.data +``` + +The storage provider can be SQL, Redis, D1, DynamoDB, object storage, or a +product API. Provider details live behind an adapter. The graph sees a declared +operation and receives `runx.data.operation_result.v1` with version movement, +digests, redaction notes, and provider evidence. + +Adapter choice is not product logic. A graph passes `data_source_ref` such as +`local://runx-data-store/dev-board` or `tenant://acme/board`; project or hosted +configuration binds that source to `data.sqlite`, `data.postgres`, `data.d1`, +`data.redis`, or another provider adapter. For the bundled OSS proof, the +`data-store` runners call the generic `data.source` resolver. Unbound +`local://...` refs default to the durable `data.sqlite` adapter at +`.runx/data/local-sources/source-.sqlite`; passing `store_id` opts into +the `data.local` fixture adapter for deterministic harnesses. Production +capability packs should keep the same operation inputs and move provider choice +into the data-source binding rather than forking the domain skill. + +Do not put messageboard, CRM, billing, or support-specific state machines into +the data adapter. Domain skills own meaning; data adapters own bounded reads, +idempotent writes, and projection evidence. See +[the governed data plane](./governed-data-plane.md). + Use `inputs` for literals, `$input.*` values, and static configuration. Use `context` when a step needs an earlier step's output: diff --git a/package.json b/package.json index c3eb94b32..83d9c2d98 100644 --- a/package.json +++ b/package.json @@ -33,6 +33,7 @@ "docs:api": "tsx scripts/gen-api-index.ts", "docs:exit-codes": "tsx scripts/check-cli-exit-codes.ts", "authoring:check-package-contract": "node scripts/check-authoring-package-contract.mjs", + "bindings:check": "node scripts/check-upstream-skill-bindings.mjs", "release:version:check": "tsx scripts/set-release-version.ts --check", "release:smoke-live": "node scripts/smoke-released-cli-live.mjs", "typecheck": "tsc -p tsconfig.typecheck.json --noEmit", diff --git a/packages/cli/src/args.ts b/packages/cli/src/args.ts index 89225b643..9d5be71db 100644 --- a/packages/cli/src/args.ts +++ b/packages/cli/src/args.ts @@ -57,6 +57,7 @@ export interface ParsedArgs { readonly answersPath?: string; readonly receiptDir?: string; readonly runner?: string; + readonly forceRun: boolean; readonly knowledgeProject?: string; readonly sourceFilter?: string; readonly addVersion?: string; @@ -93,6 +94,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { let receiptDir: string | undefined; let runId: string | undefined; let runner: string | undefined; + let forceRun = false; for (let index = 0; index < rest.length; index += 1) { const token = rest[index]; @@ -120,6 +122,11 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { continue; } + if (knownKey === "run") { + forceRun = inlineValue === undefined ? true : truthyFlag(parseInputValue(inlineValue)); + continue; + } + const next = nextValue(rest, index); const value = parseInputValue(inlineValue ?? next); if (inlineValue === undefined && next !== "true") { @@ -197,6 +204,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { isReceiptPublish && truthyFlag(inputs.allowLocalApi ?? inputs["allow-local-api"]); const registryUrl = (isSkillSearch || isTopLevelAdd || isSkillPublish || isSkillRun) && typeof inputs.registry === "string" ? inputs.registry : undefined; const expectedDigest = (isTopLevelAdd || isSkillRun) && typeof inputs.digest === "string" ? normalizeDigest(inputs.digest) : undefined; + const selectedRunner = runner ?? (isSkillRun ? positionals[1] : undefined); const newDirectory = isNew && typeof inputs.directory === "string" ? inputs.directory : isNew && typeof inputs.dir === "string" @@ -305,7 +313,8 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { answersPath, receiptDir, runId, - runner, + runner: selectedRunner, + forceRun, knowledgeProject, sourceFilter, addVersion, diff --git a/packages/cli/src/commands/history.ts b/packages/cli/src/commands/history.ts index 3875d881f..165eb6173 100644 --- a/packages/cli/src/commands/history.ts +++ b/packages/cli/src/commands/history.ts @@ -198,7 +198,7 @@ export function renderHistory( } lines.push(""); if (pendingRuns.length > 0) { - lines.push(` ${t.dim}next${t.reset} runx skill --run-id --answers answers.json ${t.dim}or${t.reset} runx history --json`); + lines.push(` ${t.dim}next${t.reset} runx resume answers.json ${t.dim}or${t.reset} runx history --json`); } else { lines.push(` ${t.dim}next${t.reset} runx history --json`); } diff --git a/packages/cli/src/dispatch.ts b/packages/cli/src/dispatch.ts index 14cfb2e27..82108ad1d 100644 --- a/packages/cli/src/dispatch.ts +++ b/packages/cli/src/dispatch.ts @@ -407,6 +407,9 @@ async function executeLocalSkillCommand(options: { pushOptionalFlag(args, "--registry", options.parsed.registryUrl); pushOptionalFlag(args, "--digest", options.parsed.expectedDigest); pushOptionalFlag(args, "--runner", options.parsed.runner); + if (options.parsed.forceRun) { + args.push("--run"); + } pushOptionalFlag(args, "--receipt-dir", resolvedReceiptDir); pushOptionalFlag(args, "--run-id", options.parsed.runId); pushOptionalFlag( diff --git a/packages/cli/src/index.test.ts b/packages/cli/src/index.test.ts index c04d0a871..67c35c181 100644 --- a/packages/cli/src/index.test.ts +++ b/packages/cli/src/index.test.ts @@ -145,7 +145,7 @@ Return the provided task id. const firstExitCode = await runCli( ["skill", skillDir, "--task-id", "abc-123", "--receipt-dir", receiptDir, "--non-interactive", "--json"], { stdin: process.stdin, stdout: firstStdout, stderr: firstStderr }, - { ...process.env, RUNX_CWD: process.cwd() }, + hostDrivenAgentEnv(tempDir), ); expect(firstExitCode).toBe(2); @@ -172,7 +172,7 @@ Return the provided task id. const secondExitCode = await runCli( ["skill", skillDir, "--task-id", "abc-123", "--run-id", firstJson.run_id, "--answers", answersPath, "--receipt-dir", receiptDir, "--non-interactive", "--json"], { stdin: process.stdin, stdout: secondStdout, stderr: secondStderr }, - { ...process.env, RUNX_CWD: process.cwd() }, + hostDrivenAgentEnv(tempDir), ); expect(secondExitCode).toBe(0); @@ -340,7 +340,7 @@ Return the provided task id. const exitCode = await runCli( ["skill", skillDir, "--prompt", "review this", "--non-interactive"], { stdin: process.stdin, stdout, stderr }, - { ...process.env, RUNX_CWD: process.cwd(), PATH: fakeBinDir }, + hostDrivenAgentEnv(tempDir, { PATH: fakeBinDir }), ); expect(exitCode).toBe(2); @@ -348,7 +348,7 @@ Return the provided task id. expect(stdout.contents()).toContain("waiting for verdict"); expect(stdout.contents()).toContain("task review"); expect(stdout.contents()).toContain("Detected here: Claude Code, Codex"); - expect(stdout.contents()).toContain(`runx skill ${skillDir} --run-id run_agent_task-review-output --answers answers.json`); + expect(stdout.contents()).toContain("runx resume run_agent_task-review-output answers.json"); expect(stdout.contents()).not.toContain("Resolution requested"); expect(stdout.contents()).not.toContain("request agent_task"); }); @@ -378,7 +378,7 @@ Return the provided task id. const stderr = createMemoryStream(); const exitCode = await runCli( - ["skill", "skills/sourcey", "--json"], + ["skill", "skills/sourcey", "--run", "--json"], { stdin: process.stdin, stdout, stderr }, { ...process.env, RUNX_CWD: process.cwd(), RUNX_RECEIPT_DIR: tempDir }, ); @@ -419,7 +419,7 @@ Return the provided task id. const exitCode = await runCli( ["skill", skillDir, "--prompt", "review this", "--non-interactive", "--json"], { stdin: process.stdin, stdout, stderr }, - { ...process.env, RUNX_CWD: process.cwd() }, + hostDrivenAgentEnv(tempDir), ); expect(exitCode).toBe(2); @@ -1299,7 +1299,7 @@ Answer the prompt directly. const stderr = createMemoryStream(); const firstExit = await runCli( - ["skill", "sourcey", "--json"], + ["skill", "sourcey", "--run", "--json"], { stdin: process.stdin, stdout, stderr }, { ...process.env, RUNX_CWD: process.cwd(), RUNX_RECEIPT_DIR: tempDir }, ); @@ -2426,6 +2426,21 @@ async function createFakeAgentBin(commands: readonly string[]): Promise return directory; } +function hostDrivenAgentEnv(tempDir: string, overrides: NodeJS.ProcessEnv = {}): NodeJS.ProcessEnv { + const env: NodeJS.ProcessEnv = { + ...process.env, + RUNX_HOME: path.join(tempDir, ".runx"), + RUNX_CWD: process.cwd(), + ...overrides, + }; + delete env.RUNX_AGENT_PROVIDER; + delete env.RUNX_AGENT_MODEL; + delete env.RUNX_AGENT_API_KEY; + delete env.ANTHROPIC_API_KEY; + delete env.OPENAI_API_KEY; + return env; +} + async function configureOpenAiAgent(env: NodeJS.ProcessEnv, model: string): Promise { const stdout = createMemoryStream(); const stderr = createMemoryStream(); diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index cd35da07f..5ce7c23e9 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -8,8 +8,8 @@ }, { "skill_id": "runx/business-ops", - "version": "sha-542469f72fa2", - "digest": "f319e45b875aab442ead32ecddd194c715bfd585f1504d9e9c3d7bcbb914e342", + "version": "sha-fd875c18ba3d", + "digest": "7801492f5b8fa34f0f6e91f9f2729396744c35fe517ae275885e07204bc52b6f", "catalog_visibility": "public", "catalog_role": "canonical" }, @@ -27,6 +27,13 @@ "catalog_visibility": "public", "catalog_role": "context" }, + { + "skill_id": "runx/data-store", + "version": "sha-1b3887a55009", + "digest": "05ed91ab2873f7ccf1a898166f79c1ebae2542924e5444fa8b504a9aa2f22f76", + "catalog_visibility": "public", + "catalog_role": "canonical" + }, { "skill_id": "runx/deep-research-brief", "version": "sha-c2d071df7f50", @@ -36,9 +43,9 @@ }, { "skill_id": "runx/dependency-cve-audit", - "version": "sha-016cc407efa2", - "digest": "c19ec9fdeb088daab950b7c2e1f3757880de9702e31e40b57e2f65c0c4033348", - "catalog_visibility": "internal", + "version": "sha-6db720882ba0", + "digest": "427c964bccd3f5f41c71a90905dd74225547e8b7af11015978e4550db3c27249", + "catalog_visibility": "public", "catalog_role": "canonical" }, { @@ -85,8 +92,8 @@ }, { "skill_id": "runx/github-sync", - "version": "sha-703346713bf3", - "digest": "83b0f4cd98cf23ff81ec71727543e6d811e75aa970cf957bec4267575a16efcc", + "version": "sha-1a2573539bb7", + "digest": "6981adc877736f05a41d764b3e42d479d87de3bc2d69a65992dff457b635bd9a", "catalog_visibility": "public", "catalog_role": "branded" }, @@ -169,8 +176,8 @@ }, { "skill_id": "runx/messageboard", - "version": "sha-a694b4c2d459", - "digest": "0f65121f1cfe18d13f6da323cf1bc6edcf492e521360888e2bb21920cb1b8967", + "version": "sha-7b9930ac9727", + "digest": "7fb6092161a234fbea28681ec5e72afd9c2d380e547cf4ef97683f28bb9a6427", "catalog_visibility": "public", "catalog_role": "canonical" }, @@ -253,8 +260,8 @@ }, { "skill_id": "runx/ops-desk", - "version": "sha-57c1b0df97f6", - "digest": "d468d7984b8a7736cb760373c5348007eed1f387567814f39ac82eb39e58150a", + "version": "sha-5e1d3dc7c252", + "digest": "386e43482f0bb6eaacd50fd836cd0dc112ad70eca8625bcaf50d8a86e6226f07", "catalog_visibility": "public", "catalog_role": "canonical" }, @@ -442,16 +449,16 @@ }, { "skill_id": "runx/structured-extraction", - "version": "sha-a826aca27a7a", - "digest": "ebe37921d3b9cb63aa1ca5232a8075607d3b4ad541af4c1bc901ace749ea404f", - "catalog_visibility": "internal", + "version": "sha-22eeb86d17f4", + "digest": "2c83db0c1f170af2e84ca0237e0850108254415bdcffdc57d2a6e66197cef133", + "catalog_visibility": "public", "catalog_role": "canonical" }, { "skill_id": "runx/support-triage-reply", - "version": "sha-a605f6b30db4", - "digest": "e945d181db20fbb0f2432ad7fd5b5fbc438deb1cdbe4eacad169641e24670416", - "catalog_visibility": "internal", + "version": "sha-93233458fd14", + "digest": "5c6fc18bf3013a1845de83641147f8421ceb1599269e4b3ed111d25e75053fda", + "catalog_visibility": "public", "catalog_role": "canonical" }, { diff --git a/packages/cli/src/presentation/needs-agent.ts b/packages/cli/src/presentation/needs-agent.ts index 1688c7d5b..f06b27ed5 100644 --- a/packages/cli/src/presentation/needs-agent.ts +++ b/packages/cli/src/presentation/needs-agent.ts @@ -110,7 +110,8 @@ export function renderNeedsAgent( } function formatContinueCommand(skillPath: string, runId: string): string { - return `runx skill ${shellQuote(skillPath)} --run-id ${shellQuote(runId)} --answers answers.json`; + void skillPath; + return `runx resume ${shellQuote(runId)} answers.json`; } function shellQuote(value: string): string { diff --git a/packages/cli/src/skill-refs.test.ts b/packages/cli/src/skill-refs.test.ts index 5dd7dbef5..841e50744 100644 --- a/packages/cli/src/skill-refs.test.ts +++ b/packages/cli/src/skill-refs.test.ts @@ -9,70 +9,6 @@ import { parseRunnerManifestYaml, validateRunnerManifest } from "./cli-parser/in import { officialSkillVisibleForCatalog } from "./skill-refs.js"; const repoRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../../.."); -const publicOfficialCatalogSkills = [ - "brand-voice", - "business-ops", - "charge", - "content-pipeline", - "deep-research-brief", - "design-skill", - "dispute-respond", - "draft-content", - "ecosystem-brief", - "ecosystem-vuln-scan", - "evolve", - "github-sync", - "governed-outbound", - "improve-skill", - "inbox-and-calendar-exec", - "issue-intake", - "issue-to-pr", - "issue-triage", - "knowledge-router", - "lead-enrichment", - "lead-router", - "ledger", - "least-privilege-auditor", - "messageboard", - "moltbook", - "n8n-handoff", - "nitrosend", - "nws-weather-forecast", - "overlay-generator", - "policy-author", - "pr-review-note", - "prior-art", - "receipt-auditor", - "redact-pii", - "reflect-digest", - "refund", - "release", - "research", - "review-receipt", - "review-skill", - "run-history-analyst", - "ops-desk", - "sandbox-harden", - "send-as", - "settle-invoice", - "sign-receipt", - "skill-lab", - "skill-testing", - "slack-notify", - "sourcey", - "spend", - "sql-analyst", - "stripe-pay", - "taste-profile", - "vault-unseal", - "vuln-scan", - "weather-forecast", - "web-fetch", - "work-plan", - "write-harness", - "x402-pay", - "zapier-handoff", -]; const paymentGraphStageOwners: Readonly> = { "charge-challenge": "charge", "charge-price": "charge", @@ -117,7 +53,7 @@ describe("official skill catalog exposure", () => { }); it("keeps implemented catalog skills visible", () => { - for (const skill of publicOfficialCatalogSkills) { + for (const skill of publicOfficialCatalogSkills()) { expect(officialSkillVisibleForCatalog(`runx/${skill}`, {}), skill).toBe(true); } }); @@ -125,16 +61,17 @@ describe("official skill catalog exposure", () => { it("keeps catalog visibility explicit in first-party runner manifests", () => { const allSkills = readdirSync(path.join(repoRoot, "skills"), { withFileTypes: true }) .filter((entry) => entry.isDirectory()) + .filter((entry) => !entry.name.startsWith(".")) .filter((entry) => { const skillDir = path.join(repoRoot, "skills", entry.name); return existsSync(path.join(skillDir, "SKILL.md")) && existsSync(path.join(skillDir, "X.yaml")); }) .map((entry) => entry.name) .sort(); - const expectedPublic = new Set(publicOfficialCatalogSkills); + const expectedPublic = new Set(publicOfficialCatalogSkills()); const actualPublic = allSkills.filter((skill) => catalogVisibility(skill) === "public"); - expect(actualPublic).toEqual([...publicOfficialCatalogSkills].sort()); + expect(actualPublic).toEqual([...expectedPublic].sort()); for (const skill of allSkills) { expect(catalogVisibility(skill), skill).toBe(expectedPublic.has(skill) ? "public" : "internal"); expect(catalogRole(skill), skill).toBeTruthy(); @@ -161,6 +98,19 @@ describe("official skill catalog exposure", () => { }); }); +function publicOfficialCatalogSkills(): readonly string[] { + return readdirSync(path.join(repoRoot, "skills"), { withFileTypes: true }) + .filter((entry) => entry.isDirectory()) + .filter((entry) => !entry.name.startsWith(".")) + .filter((entry) => { + const skillDir = path.join(repoRoot, "skills", entry.name); + return existsSync(path.join(skillDir, "SKILL.md")) && existsSync(path.join(skillDir, "X.yaml")); + }) + .map((entry) => entry.name) + .filter((skill) => catalogVisibility(skill) === "public") + .sort(); +} + function catalogVisibility(skill: string): string | undefined { const manifestPath = path.join(repoRoot, "skills", skill, "X.yaml"); const manifest = validateRunnerManifest(parseRunnerManifestYaml(readFileSync(manifestPath, "utf8"))); diff --git a/packages/contracts/src/index.test.ts b/packages/contracts/src/index.test.ts index 9a66d8d00..8869250c1 100644 --- a/packages/contracts/src/index.test.ts +++ b/packages/contracts/src/index.test.ts @@ -15,6 +15,7 @@ import { credentialDeliveryObservationV1Schema, credentialDeliveryProfileV1Schema, credentialDeliveryRequestV1Schema, + dataOperationResultV1Schema, devV1Schema, doctorV1Schema, effectFinalityReceiptV1Schema, @@ -57,6 +58,7 @@ import { validateOutputContract, validateResolutionRequestContract, validateCredentialEnvelopeContract, + validateDataOperationResultContract, validateActAssignmentContract, validateDevReportContract, validateDoctorReportContract, @@ -84,6 +86,7 @@ describe("@runxhq/contracts", () => { expect(RUNX_LOGICAL_SCHEMAS.receipt).toBe("runx.receipt.v1"); expect(RUNX_LOGICAL_SCHEMAS.effectFinalityReceipt).toBe("runx.effect_finality_receipt.v1"); expect(RUNX_LOGICAL_SCHEMAS.operationalProposal).toBe("runx.operational_proposal.v1"); + expect(RUNX_LOGICAL_SCHEMAS.dataOperationResult).toBe("runx.data.operation_result.v1"); }); it("uses durable schema URI ids", () => { @@ -93,6 +96,9 @@ describe("@runxhq/contracts", () => { expect(RUNX_CONTRACT_IDS.effectFinalityReceipt) .toBe("https://schemas.runx.dev/runx/effect-finality-receipt/v1.json"); expect(runxContractSchemas.effectFinalityReceipt.$id).toBe(RUNX_CONTRACT_IDS.effectFinalityReceipt); + expect(RUNX_CONTRACT_IDS.dataOperationResult) + .toBe("https://schemas.runx.dev/runx/data/operation-result/v1.json"); + expect(runxContractSchemas.dataOperationResult.$id).toBe(RUNX_CONTRACT_IDS.dataOperationResult); expect((toolManifestV1Schema.properties as Record).source).toBeDefined(); expect((toolManifestV1Schema.required as readonly string[])).not.toContain("version"); const devProperties = runxContractSchemas.dev.properties as Record | undefined; @@ -119,6 +125,7 @@ describe("@runxhq/contracts", () => { expect(threadOutboxProviderPushV1Schema).toBe(runxContractSchemas.threadOutboxProviderPush); expect(threadOutboxProviderFetchV1Schema).toBe(runxContractSchemas.threadOutboxProviderFetch); expect(threadOutboxProviderObservationV1Schema).toBe(runxContractSchemas.threadOutboxProviderObservation); + expect(dataOperationResultV1Schema).toBe(runxContractSchemas.dataOperationResult); expect(externalAdapterManifestV1Schema).toBe(runxContractSchemas.externalAdapterManifest); expect(externalAdapterCredentialRequestV1Schema).toBe(runxContractSchemas.externalAdapterCredentialRequest); expect(externalAdapterInvocationV1Schema).toBe(runxContractSchemas.externalAdapterInvocation); @@ -150,6 +157,64 @@ describe("@runxhq/contracts", () => { ]); }); + it("validates governed data operation result packets", () => { + const committed = validateDataOperationResultContract({ + schema: RUNX_LOGICAL_SCHEMAS.dataOperationResult, + data_source_ref: "tenant://acme/board", + provider: "postgres", + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-123", + status: "committed", + before_version: 2, + after_version: 3, + idempotency_key: "posting-123:claim:agent-9", + event_ref: "board_events:posting-123:3", + event_digest: "sha256:event", + result_digest: "sha256:result", + projection_digest: "sha256:projection", + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: { + adapter: "data.postgres", + profile: "prod-board", + }, + }); + + expect(committed.status).toBe("committed"); + expect(committed.provider_evidence?.adapter).toBe("data.postgres"); + + const conflict = validateDataOperationResultContract({ + schema: RUNX_LOGICAL_SCHEMAS.dataOperationResult, + data_source_ref: "tenant://acme/board", + provider: "postgres", + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-123", + status: "conflict", + before_version: 4, + after_version: 4, + idempotency_key: "posting-123:claim:agent-9", + event_ref: null, + event_digest: "sha256:event", + result_digest: "sha256:conflict", + projection_digest: "sha256:projection", + events: [], + rows: [], + redactions: [], + stop_conditions: [ + { + code: "conflict", + message: "expected version 2, got 4", + }, + ], + }); + + expect(conflict.stop_conditions[0]?.code).toBe("conflict"); + }); + it("accepts typed proof kinds on references", () => { expect(proofKinds).toEqual(["effect_evidence", "effect_finality", "credential_resolution"]); expect(proofKindSchema).toMatchObject({ diff --git a/packages/contracts/src/index.ts b/packages/contracts/src/index.ts index 64e86e37b..f9f7ee3dc 100644 --- a/packages/contracts/src/index.ts +++ b/packages/contracts/src/index.ts @@ -109,6 +109,16 @@ export { type ThreadOutboxProviderObservationContract, } from "./schemas/thread-outbox-provider.js"; +export { + dataOperationResultStatuses, + dataOperationResultStatusSchema, + dataOperationStopConditionSchema, + dataOperationResultV1Schema, + validateDataOperationResultContract, + type DataOperationStopConditionContract, + type DataOperationResultContract, +} from "./schemas/data-operation.js"; + export { outputScalarSchema, outputObjectEntrySchema, @@ -564,6 +574,7 @@ import { ledgerRecordSchema } from "./schemas/ledger.js"; import { handoffSignalV1Schema, handoffStateV1Schema, suppressionRecordV1Schema } from "./schemas/handoff.js"; import { operationalPolicySchema } from "./schemas/operational-policy.js"; import { operationalProposalSchema } from "./schemas/operational-proposal.js"; +import { dataOperationResultV1Schema } from "./schemas/data-operation.js"; import { runxSchemaArtifacts } from "./schema-artifacts.js"; export const runxContractSchemas = { @@ -586,6 +597,7 @@ export const runxContractSchemas = { threadOutboxProviderPush: runxSchemaArtifacts["thread-outbox-provider-push.schema.json"], threadOutboxProviderFetch: runxSchemaArtifacts["thread-outbox-provider-fetch.schema.json"], threadOutboxProviderObservation: runxSchemaArtifacts["thread-outbox-provider-observation.schema.json"], + dataOperationResult: dataOperationResultV1Schema, doctor: runxSchemaArtifacts["doctor.schema.json"], dev: runxSchemaArtifacts["dev.schema.json"], list: runxSchemaArtifacts["list.schema.json"], diff --git a/packages/contracts/src/internal.ts b/packages/contracts/src/internal.ts index f1797226a..49050c3b4 100644 --- a/packages/contracts/src/internal.ts +++ b/packages/contracts/src/internal.ts @@ -33,6 +33,7 @@ export const RUNX_CONTRACT_IDS = { threadOutboxProviderPush: `${RUNX_SCHEMA_BASE_URL}/runx/thread-outbox-provider/push/v1.json`, threadOutboxProviderFetch: `${RUNX_SCHEMA_BASE_URL}/runx/thread-outbox-provider/fetch/v1.json`, threadOutboxProviderObservation: `${RUNX_SCHEMA_BASE_URL}/runx/thread-outbox-provider/observation/v1.json`, + dataOperationResult: `${RUNX_SCHEMA_BASE_URL}/runx/data/operation-result/v1.json`, reference: `${RUNX_SCHEMA_BASE_URL}/runx/reference/v1.json`, authority: `${RUNX_SCHEMA_BASE_URL}/runx/authority/v1.json`, authoritySubsetProof: `${RUNX_SCHEMA_BASE_URL}/runx/authority/subset-proof/v1.json`, @@ -75,6 +76,7 @@ export const RUNX_LOGICAL_SCHEMAS = { threadOutboxProviderPush: "runx.thread_outbox_provider.push.v1", threadOutboxProviderFetch: "runx.thread_outbox_provider.fetch.v1", threadOutboxProviderObservation: "runx.thread_outbox_provider.observation.v1", + dataOperationResult: "runx.data.operation_result.v1", reference: "runx.reference.v1", authority: "runx.authority.v1", authoritySubsetProof: "runx.authority_subset_proof.v1", diff --git a/packages/contracts/src/schemas/data-operation.ts b/packages/contracts/src/schemas/data-operation.ts new file mode 100644 index 000000000..649a2dd54 --- /dev/null +++ b/packages/contracts/src/schemas/data-operation.ts @@ -0,0 +1,72 @@ +import { Type, type Static } from "../internal.js"; +import { + JSON_SCHEMA_DRAFT_2020_12, + RUNX_CONTRACT_IDS, + RUNX_LOGICAL_SCHEMAS, + type DeepReadonly, + stringEnum, + unknownRecordSchema, + validateContractSchema, +} from "../internal.js"; + +export const dataOperationResultStatuses = [ + "committed", + "idempotent_replay", + "read", + "conflict", + "provider_unavailable", +] as const; + +export const dataOperationResultStatusSchema = stringEnum(dataOperationResultStatuses); + +export const dataOperationStopConditionSchema = Type.Object( + { + code: Type.String({ minLength: 1 }), + message: Type.String({ minLength: 1 }), + }, + { additionalProperties: false }, +); + +export type DataOperationStopConditionContract = + DeepReadonly>; + +export const dataOperationResultV1Schema = Type.Object( + { + schema: Type.Literal(RUNX_LOGICAL_SCHEMAS.dataOperationResult), + data_source_ref: Type.String({ minLength: 1 }), + provider: Type.String({ minLength: 1 }), + operation: Type.String({ minLength: 1 }), + resource: Type.String({ minLength: 1 }), + aggregate_id: Type.String({ minLength: 1 }), + status: dataOperationResultStatusSchema, + before_version: Type.Integer({ minimum: 0 }), + after_version: Type.Integer({ minimum: 0 }), + idempotency_key: Type.Union([Type.String({ minLength: 1 }), Type.Null()]), + event_ref: Type.Union([Type.String({ minLength: 1 }), Type.Null()]), + event_digest: Type.Union([Type.String({ minLength: 1 }), Type.Null()]), + result_digest: Type.String({ minLength: 1 }), + projection_digest: Type.String({ minLength: 1 }), + projection: Type.Optional(unknownRecordSchema()), + events: Type.Array(Type.Unknown()), + rows: Type.Array(Type.Unknown()), + redactions: Type.Array(Type.Unknown()), + stop_conditions: Type.Array(dataOperationStopConditionSchema), + provider_evidence: Type.Optional(unknownRecordSchema()), + }, + { + $schema: JSON_SCHEMA_DRAFT_2020_12, + $id: RUNX_CONTRACT_IDS.dataOperationResult, + "x-runx-schema": RUNX_LOGICAL_SCHEMAS.dataOperationResult, + additionalProperties: false, + }, +); + +export type DataOperationResultContract = + DeepReadonly>; + +export function validateDataOperationResultContract( + value: unknown, + label = "data operation result", +): DataOperationResultContract { + return validateContractSchema(dataOperationResultV1Schema, value, label) as DataOperationResultContract; +} diff --git a/packages/langchain/src/index.test.ts b/packages/langchain/src/index.test.ts index e8a47edf5..d7f213bf0 100644 --- a/packages/langchain/src/index.test.ts +++ b/packages/langchain/src/index.test.ts @@ -52,11 +52,6 @@ describe("@runxhq/langchain", () => { receiptDir: "/tmp/receipts", runId: "run_123", answersPath: "/tmp/answers.json", - inputs: { - repo_url: "acme/docs", - count: 3, - nested: { ok: true }, - }, }); expect(result).toEqual({ @@ -71,21 +66,12 @@ describe("@runxhq/langchain", () => { expect(calls[0]?.command).toBe("fake-runx"); expect(calls[0]?.env.RUNX_LANGCHAIN_CAPTURE_PATH).toBe("/tmp/runx-langchain-argv.txt"); expect(calls[0]?.args).toEqual([ - "skill", - "/tmp/skills/docs-pr", + "resume", + "run_123", + "/tmp/answers.json", "--json", "--receipt-dir", "/tmp/receipts", - "--run-id", - "run_123", - "--answers", - "/tmp/answers.json", - "--repo-url", - "acme/docs", - "--count", - "3", - "--nested", - "{\"ok\":true}", ]); }); diff --git a/packages/langchain/src/index.ts b/packages/langchain/src/index.ts index 71a7b1f8c..906730dee 100644 --- a/packages/langchain/src/index.ts +++ b/packages/langchain/src/index.ts @@ -187,16 +187,23 @@ export function createRunxLangChainTool( } function runxSkillArgs(options: RunxSkillCliRunOptions): readonly string[] { + if (options.runId || options.answersPath) { + if (!options.runId || !options.answersPath) { + throw new Error("runx resume requires both runId and answersPath."); + } + if (Object.keys(options.inputs ?? {}).length > 0) { + throw new Error("runx resume reads answers from the answers file; pass fresh inputs only on a new skill run."); + } + const args = ["resume", options.runId, options.answersPath, "--json"]; + if (options.receiptDir) { + args.push("--receipt-dir", options.receiptDir); + } + return args; + } const args = ["skill", options.skillPath, "--json"]; if (options.receiptDir) { args.push("--receipt-dir", options.receiptDir); } - if (options.runId) { - args.push("--run-id", options.runId); - } - if (options.answersPath) { - args.push("--answers", options.answersPath); - } for (const [name, value] of Object.entries(options.inputs ?? {})) { args.push(inputFlag(name), cliInputValue(value)); } diff --git a/packages/sdk-python/runx/__init__.py b/packages/sdk-python/runx/__init__.py index 90aff2360..1b36f5ddc 100644 --- a/packages/sdk-python/runx/__init__.py +++ b/packages/sdk-python/runx/__init__.py @@ -114,10 +114,10 @@ def continue_run( inputs: Mapping[str, Any] | None = None, non_interactive: bool = True, ) -> dict[str, Any]: - args = ["skill", skill_path] - for key, value in (inputs or {}).items(): - args.extend([f"--{key}", str(value)]) - args.extend(["--run-id", run_id, "--answers", answers_file]) + del skill_path + if inputs: + raise ValueError("runx resume reads answers from the answers file; pass fresh inputs only on a new skill run.") + args = ["resume", run_id, answers_file] if non_interactive: args.append("--non-interactive") return self.run_json(args) diff --git a/packages/sdk-python/tests/test_runx.py b/packages/sdk-python/tests/test_runx.py index 544f98356..1538559d5 100644 --- a/packages/sdk-python/tests/test_runx.py +++ b/packages/sdk-python/tests/test_runx.py @@ -102,11 +102,8 @@ def test_continue_run_invokes_skill_with_run_id_and_answers_file(self) -> None: self.assertEqual( report["args"], [ - "skill", - "skills/example", - "--run-id", + "resume", "run-123", - "--answers", str(answers_path), "--non-interactive", "--json", diff --git a/scripts/check-upstream-skill-bindings.mjs b/scripts/check-upstream-skill-bindings.mjs new file mode 100644 index 000000000..b687e0950 --- /dev/null +++ b/scripts/check-upstream-skill-bindings.mjs @@ -0,0 +1,180 @@ +#!/usr/bin/env node +import { readFileSync, readdirSync, statSync } from "node:fs"; +import path from "node:path"; + +const workspaceRoot = process.cwd(); +const bindingRoot = path.join(workspaceRoot, "bindings"); +const allowedBindingFiles = new Set(["binding.json", "X.yaml"]); +const validStates = new Set([ + "draft", + "harness_verified", + "published", + "retired", +]); + +const findings = []; +const bindings = collectBindings(bindingRoot); + +if (bindings.length === 0) { + findings.push("bindings/ must contain at least one upstream binding or be removed entirely."); +} + +for (const bindingPath of bindings) { + validateBinding(bindingPath); +} + +if (findings.length > 0) { + for (const finding of findings) { + console.error(`binding check: ${finding}`); + } + process.exit(1); +} + +console.log(`upstream binding check ok (${bindings.length} binding${bindings.length === 1 ? "" : "s"})`); + +function collectBindings(root) { + const result = []; + for (const owner of readDirectoryNames(root)) { + const ownerDir = path.join(root, owner); + for (const skill of readDirectoryNames(ownerDir)) { + result.push(path.join(ownerDir, skill, "binding.json")); + } + } + return result.sort(); +} + +function readDirectoryNames(dir) { + return readdirSync(dir) + .filter((entry) => statSync(path.join(dir, entry)).isDirectory()) + .sort(); +} + +function validateBinding(bindingPath) { + const bindingDir = path.dirname(bindingPath); + const relativeDir = path.relative(workspaceRoot, bindingDir); + const [root, owner, skillName] = relativeDir.split(path.sep); + if (root !== "bindings" || !owner || !skillName) { + findings.push(`${relativeDir}: expected bindings///binding.json`); + return; + } + + for (const entry of readdirSync(bindingDir).sort()) { + if (!allowedBindingFiles.has(entry)) { + findings.push(`${relativeDir}: unexpected file ${entry}; bindings contain only binding.json and X.yaml`); + } + } + + const binding = readJson(bindingPath); + const profilePath = path.join(bindingDir, "X.yaml"); + const profile = readText(profilePath); + const expectedId = `${owner}/${skillName}`; + const expectedProfilePath = `bindings/${owner}/${skillName}/X.yaml`; + + requireEqual(binding.schema, "runx.registry_binding.v1", `${relativeDir}: schema`); + requireSetValue(binding.state, validStates, `${relativeDir}: state`); + requireEqual(binding.skill?.id, expectedId, `${relativeDir}: skill.id`); + requireEqual(binding.skill?.name, skillName, `${relativeDir}: skill.name`); + requireString(binding.skill?.description, `${relativeDir}: skill.description`); + + requireEqual(binding.upstream?.host, "github.com", `${relativeDir}: upstream.host`); + requireString(binding.upstream?.owner, `${relativeDir}: upstream.owner`); + requireString(binding.upstream?.repo, `${relativeDir}: upstream.repo`); + requireEqual(binding.upstream?.path, "SKILL.md", `${relativeDir}: upstream.path`); + requireHex(binding.upstream?.commit, 40, `${relativeDir}: upstream.commit`); + requireHex(binding.upstream?.blob_sha, 40, `${relativeDir}: upstream.blob_sha`); + requireEqual(binding.upstream?.source_of_truth, true, `${relativeDir}: upstream.source_of_truth`); + requirePinnedUrl(binding.upstream?.html_url, binding.upstream, `${relativeDir}: upstream.html_url`); + requirePinnedUrl(binding.upstream?.raw_url, binding.upstream, `${relativeDir}: upstream.raw_url`); + + requireEqual(binding.registry?.owner, owner, `${relativeDir}: registry.owner`); + requireString(binding.registry?.trust_tier, `${relativeDir}: registry.trust_tier`); + requireString(binding.registry?.version, `${relativeDir}: registry.version`); + requireEqual(binding.registry?.profile_path, expectedProfilePath, `${relativeDir}: registry.profile_path`); + requireEqual( + binding.registry?.materialized_package_is_registry_artifact, + true, + `${relativeDir}: registry.materialized_package_is_registry_artifact`, + ); + + requireString(binding.harness?.status, `${relativeDir}: harness.status`); + requirePositiveInteger(binding.harness?.case_count, `${relativeDir}: harness.case_count`); + requirePositiveInteger(binding.harness?.assertion_count, `${relativeDir}: harness.assertion_count`); + if (!Array.isArray(binding.harness?.case_names) || binding.harness.case_names.length === 0) { + findings.push(`${relativeDir}: harness.case_names must list at least one case`); + } + + requireString(binding.publication?.status, `${relativeDir}: publication.status`); + if (!Array.isArray(binding.tags) || binding.tags.length === 0) { + findings.push(`${relativeDir}: tags must list at least one catalog tag`); + } + + const profileSkill = profile.match(/^skill:\s*([A-Za-z0-9_.-]+)\s*$/m)?.[1]; + requireEqual(profileSkill, skillName, `${relativeDir}: X.yaml skill`); + if (!/^runners:\s*$/m.test(profile)) { + findings.push(`${relativeDir}: X.yaml must declare runners`); + } +} + +function readJson(file) { + try { + return JSON.parse(readText(file)); + } catch (error) { + findings.push(`${path.relative(workspaceRoot, file)}: invalid JSON (${error.message})`); + return {}; + } +} + +function readText(file) { + try { + return readFileSync(file, "utf8"); + } catch (error) { + findings.push(`${path.relative(workspaceRoot, file)}: cannot read file (${error.message})`); + return ""; + } +} + +function requireEqual(actual, expected, label) { + if (actual !== expected) { + findings.push(`${label} must be ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`); + } +} + +function requireSetValue(actual, allowed, label) { + if (!allowed.has(actual)) { + findings.push(`${label} must be one of ${Array.from(allowed).join(", ")}, got ${JSON.stringify(actual)}`); + } +} + +function requireString(value, label) { + if (typeof value !== "string" || value.trim().length === 0) { + findings.push(`${label} must be a non-empty string`); + } +} + +function requirePositiveInteger(value, label) { + if (!Number.isInteger(value) || value <= 0) { + findings.push(`${label} must be a positive integer`); + } +} + +function requireHex(value, length, label) { + if (typeof value !== "string" || !new RegExp(`^[a-f0-9]{${length}}$`, "i").test(value)) { + findings.push(`${label} must be a ${length}-character hex digest`); + } +} + +function requirePinnedUrl(value, upstream, label) { + requireString(value, label); + if (typeof value !== "string") return; + const expectedParts = [ + upstream?.owner, + upstream?.repo, + upstream?.commit, + upstream?.path, + ].filter(Boolean); + for (const part of expectedParts) { + if (!value.includes(part)) { + findings.push(`${label} must include pinned upstream component ${part}`); + } + } +} diff --git a/scripts/verify-fast.mjs b/scripts/verify-fast.mjs index fb2405e41..997558b9a 100644 --- a/scripts/verify-fast.mjs +++ b/scripts/verify-fast.mjs @@ -45,6 +45,7 @@ await runParallelGroup("source checks", [ step("boundary:check", "pnpm", ["boundary:check"]), step("test:boundary", "pnpm", ["test:boundary"]), step("typecheck", "pnpm", ["typecheck"]), + step("bindings:check", "pnpm", ["bindings:check"]), step("release version sync", "pnpm", ["release:version:check"]), step("integration module guard", "node", ["scripts/check-integration-test-modules.mjs"]), ]); diff --git a/skills/business-ops/SKILL.md b/skills/business-ops/SKILL.md index f8269412f..89a5b58e5 100644 --- a/skills/business-ops/SKILL.md +++ b/skills/business-ops/SKILL.md @@ -20,6 +20,12 @@ This is not a provider integration and not an operator dashboard. It is the small core shape that teams copy when they want one objective to fan out into a chain of skills, then replay that chain with receipts. +When the route itself should become durable, use `route_and_append`. That runner +classifies the signal, appends the classification packet through `data-store`, +and reads back the projection. The same graph can use local JSON, SQLite, +Postgres, D1, Redis, or a product adapter by changing the `data_source_ref` +binding. + ## What this skill does - Classifies one business signal before doing work. @@ -31,6 +37,7 @@ chain of skills, then replay that chain with receipts. drafts and plans can be produced, but sends, spend, merges, publishes, and deploys require a separate approval and execution lane. - Gives downstream agents a clear handoff target instead of vague prose. +- Optionally persists the classified route for replay through `data-store`. ## What this skill deliberately does not do @@ -110,6 +117,8 @@ skill runner or provider tool. 6. Name the exact downstream handoff that should replace the fixture in a real workflow. 7. Seal the graph so the route itself is replayable. +8. If using `route_and_append`, append the classification packet with an + idempotency key and expected version, then read back the projection. ## Edge cases and stop conditions diff --git a/skills/business-ops/X.yaml b/skills/business-ops/X.yaml index 7a47a05ef..21c08db4b 100644 --- a/skills/business-ops/X.yaml +++ b/skills/business-ops/X.yaml @@ -1,5 +1,5 @@ skill: business-ops -version: "0.1.1" +version: "0.1.2" catalog: kind: graph @@ -65,3 +65,62 @@ runners: lane: receipt-audit signal: "$input.signal" operator_context: "$input.operator_context" + + route_and_append: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Logical data source used to persist the routed signal packet. + resource: + type: string + required: true + description: Declared event resource for business operations route events. + aggregate_id: + type: string + required: true + description: Business operation stream key. + expected_version: + type: number + required: true + description: Current stream version required before append. + idempotency_key: + type: string + required: true + description: Stable retry key for this routed signal. + signal: + type: string + required: true + description: Business signal to triage. + operator_context: + type: string + required: false + description: Optional product policy, topology, audience constraints, or provider state. Context only, not authority. + graph: + name: business-ops-route-and-append + steps: + - id: classify + skill: ./graph/ops-lane + inputs: + lane: classify + signal: "$input.signal" + operator_context: "$input.operator_context" + - id: persist-route + skill: ../data-store + runner: append_event + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + expected_version: "$input.expected_version" + idempotency_key: "$input.idempotency_key" + context: + event: classify.lane_packet + - id: readback + skill: ../data-store + runner: read_projection + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" diff --git a/skills/business-ops/fixtures/route-and-append-sqlite.yaml b/skills/business-ops/fixtures/route-and-append-sqlite.yaml new file mode 100644 index 000000000..4ce92db1c --- /dev/null +++ b/skills/business-ops/fixtures/route-and-append-sqlite.yaml @@ -0,0 +1,28 @@ +name: business-ops-route-and-append-sqlite +kind: skill +target: .. +runner: route_and_append +env: + RUNX_DATA_SOURCES: '{"data_sources":{"tenant://business-ops/sqlite-routes":{"adapter":"data.sqlite","database_path":".runx/data/business-ops-routes.sqlite","resources":{"ops_routes":{"kind":"event_stream","partition_key":"aggregate_id"}}}}}' +inputs: + data_source_ref: tenant://business-ops/sqlite-routes + resource: ops_routes + aggregate_id: launch-readiness + expected_version: 0 + idempotency_key: launch-readiness:classify:v1 + signal: Launch readiness for API v2 with docs, release, customer comms, and spend checks. + operator_context: Live sends route through send-as; payment movement requires a spend gate and provider readback. +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - classify + - persist-route + - readback +metadata: + public_skill: business-ops + source_case: route-and-append-sqlite + source: skills-fixture + runner_kind: graph + graph_shape: route_and_append diff --git a/skills/data-store/SKILL.md b/skills/data-store/SKILL.md new file mode 100644 index 000000000..4619a1da2 --- /dev/null +++ b/skills/data-store/SKILL.md @@ -0,0 +1,272 @@ +--- +name: data-store +description: Govern provider-agnostic data reads and state transitions through declared data-source operations, not model-authored raw queries. +runx: + category: data +--- + +# Data Store + +Operate a data source through a governed adapter contract. This skill gives an +agent enough context to read, append, or project state without learning provider +secrets, inventing SQL, or depending on one storage backend. + +The storage backend can be Postgres, SQLite, D1, Redis, DynamoDB, S3, a ledger, +or a product API. The runx boundary is the same: a declared data source exposes +typed operations; the graph supplies bounded params; the adapter executes the +operation; the receipt records the resource, authority, idempotency, version, +digest, and redaction evidence. + +## Adapter selection + +The operator chooses a data source at run time. The skill receives +`data_source_ref` and operation inputs; project or hosted configuration binds +that ref to the concrete adapter. A local development ref might be +`local://runx-data-store/dev-board`. A production ref might be +`tenant://acme/board` bound to `data.postgres`, `data.d1`, `data.redis`, or a +product-owned HTTP adapter. + +Do not put provider logic in the domain skill. Messageboard, CRM, support, and +business-ops skills should ask for durable facts to be read or written; the data +source binding decides whether those facts live in local JSON, SQL, Redis, D1, +object storage, or a product API. Switching providers is a binding change, not a +rewrite of the skill. + +The bundled OSS profile calls `data.source`. Unbound `local://...` refs default +to durable local SQLite under `.runx/data/local-sources/`, with one source-scoped +database file per logical ref, so stateful skills can be dogfooded without +standing up hosted infrastructure. Pass `store_id` only when a fixture +intentionally wants the deterministic `data.local` JSON store. The graph inputs +stay the same when a project later binds the source to Postgres, Redis, D1, +object storage, or a product API. + +Adapter preference is operator configuration, not model choice. To choose Redis, +SQLite, or a hosted provider, bind the same `data_source_ref` through +`RUNX_DATA_SOURCES` or `.runx/data-sources.json`; do not add provider branches to +the domain skill. + +## What this skill does + +- Reads data through named queries or read operations declared by a data-source + adapter. +- Appends state transitions with idempotency keys and expected versions. +- Reads projections or event streams so loops can resume from explicit state. +- Produces receipt-bound evidence for data source, resource, operation, params, + row/event limits, versions, and output digests. +- Keeps product semantics outside the data layer. Messageboards, CRMs, billing + ledgers, and support desks define their own events and reducers. +- Ships a fixture adapter (`data.local`), durable local SQLite adapter + (`data.sqlite`), and Redis adapter (`data.redis`) behind the same operation + envelope. + +## When to use this skill + +- A graph needs durable state between turns, such as queue position, board + state, sync cursor, review status, or approval inbox state. +- A skill must query a bounded slice of product data before deciding the next + action. +- A workflow needs to append an auditable event or effect transition with + optimistic concurrency. +- An operator wants one provider-agnostic shape that can later move from local + JSON or SQLite to Postgres, Redis, D1, Supabase, Turso, DynamoDB, or another + store. + +## When not to use this skill + +- To let a model write arbitrary SQL, Redis commands, or database migrations. +- To export broad data sets, secrets, raw PII, or unrestricted tables. +- To hide product decisions in storage code. Domain skills still own state + machines, acceptance criteria, and business rules. +- To treat a projection as independent truth when the event stream or receipt + chain is available and required for review. +- To bypass payment, send, deploy, moderation, or human approval gates. + +## Procedure + +1. Identify the domain skill and transition first. The data store is a carrier, + not the policy owner. +2. Select the logical data source. Use `data_source_ref` to name the project or + tenant source; let the project binding choose the adapter. Do not put raw + database URLs, provider credentials, or SQL in the skill input. +3. Select a declared operation: named read query, append event, read events, or + read projection. Do not synthesize raw provider commands. +4. Check authority. Reads need the narrow resource/query scope; writes need the + transition scope, idempotency key, and expected version unless the operation + is explicitly append-only without concurrency. +5. Bind typed params. Enforce row/event limits, tenant/partition keys, and + redaction rules before the adapter runs. +6. For writes, use optimistic concurrency and idempotency. A retry with the same + idempotency key and same payload returns the existing effect; a different + payload under the same key is a conflict. +7. Return the operation result with resource refs, version movement, digests, + redaction notes, and stop conditions. Receipts should link this data effect + to the domain transition that caused it. + +## Edge cases and stop conditions + +- `needs_source`: the data source, resource, query name, tenant key, or schema + summary is missing. +- `needs_input`: required operation params are incomplete, malformed, or not + specific enough to bind a declared data-source operation. +- `needs_authority`: the caller lacks the declared read/write scope or provider + grant. +- `needs_version`: a mutating operation lacks `expected_version` where the data + source requires optimistic concurrency. +- `conflict`: the current version differs from `expected_version`, or an + idempotency key is reused with different content. +- `too_broad`: the requested read lacks partition filters, exceeds limits, or + asks for raw export. +- `redaction_required`: the operation would return secrets, private PII, or + fields outside the declared projection. +- `provider_unavailable`: the adapter cannot reach the data source, times out, + or cannot prove whether a write committed. + +## Output schema + +All runners return `runx.data.operation_result.v1`: + +```json +{ + "schema": "runx.data.operation_result.v1", + "data_source_ref": "local://example", + "provider": "local-json-event-store", + "operation": "append_event", + "resource": "board_events", + "aggregate_id": "posting-123", + "status": "committed", + "before_version": 0, + "after_version": 1, + "idempotency_key": "posting-123:create", + "event_ref": "board_events:posting-123:1", + "result_digest": "sha256:...", + "projection_digest": "sha256:...", + "rows": [], + "events": [], + "redactions": [], + "stop_conditions": [] +} +``` + +Provider adapters may add provider evidence under `provider_evidence`, but they +must not expose credentials or raw secret material. + +## Worked example + +A messageboard skill decides that `posting.claimed` is allowed. It emits a +domain transition packet. The graph then calls `data-store.append_event` with +resource `board_events`, aggregate id `posting-123`, expected version `2`, and +idempotency key `posting-123:claim:agent-9`. The data adapter appends the event +only if the stream is still at version `2`. The receipt proves the decision, +the data operation, and the new version. A later loop turn calls +`data-store.read_events` or `read_projection` to resume from the explicit board +state. + +## Inputs + +- `data_source_ref` (required): stable logical ref for the data source. The + project or hosted binding maps this ref to the concrete adapter and provider + profile. +- `resource` (required): declared resource, stream, table, keyspace, or + projection name. +- `operation` (required for tool-level use): `append_event`, `read_events`, or + `read_projection`. +- `aggregate_id` (required for event operations): stream or partition key. +- `event` (required for `append_event`): domain event or transition packet. +- `idempotency_key` (required for writes): stable retry key. +- `expected_version` (required when the source enforces concurrency): current + stream/resource version expected by the caller. +- `limit` (optional): maximum rows or events to return. +- `store_id` (local fixture adapter only): deterministic local store id that + opts into the bundled `data.local` proof adapter. Omit it for durable local + SQLite. Production adapters should ignore it. + +## Invocation examples + +Durable local dogfood with the bundled default: + +```bash +runx skill data-store append_event \ + -i data_source_ref=local://runx-data-store/dev-board \ + -i resource=board_events \ + -i aggregate_id=posting-123 \ + --input-json expected_version=0 \ + -i idempotency_key=posting-123:create:v1 \ + --input-json event='{"type":"posting.created","payload":{"title":"verify a receipt link"}}' \ + --json +``` + +Fixture-only dogfood can still use `store_id` to select the JSON fixture store: + +```bash +runx skill data-store append_event \ + -i data_source_ref=local://runx-data-store/dev-board \ + -i store_id=dev-board \ + -i resource=board_events \ + -i aggregate_id=posting-123 \ + --input-json expected_version=0 \ + -i idempotency_key=posting-123:create:v1 \ + --input-json event='{"type":"posting.created","payload":{"title":"fixture proof"}}' \ + --json +``` + +Production graph shape is the same at the skill boundary: + +```bash +runx skill data-store append_event \ + -i data_source_ref=tenant://acme/board \ + -i resource=board_events \ + -i aggregate_id=posting-123 \ + --input-json expected_version=2 \ + -i idempotency_key=posting-123:claim:agent-9 \ + --input-json event='{"type":"posting.claimed","payload":{"actor":"agent-9"}}' \ + --json +``` + +The second command only works once `tenant://acme/board` is bound to an +installed provider adapter. That binding is operator configuration and may name a +credential profile or hosted grant; it must not carry raw secrets. + +Project-specific SQLite uses the same command shape after binding the source: + +```json +{ + "data_sources": { + "tenant://acme/board": { + "adapter": "data.sqlite", + "database_path": ".runx/data/acme-board.sqlite", + "resources": { + "board_events": { + "kind": "event_stream", + "partition_key": "aggregate_id" + } + } + } + } +} +``` + +Pass that document through `RUNX_DATA_SOURCES` or `.runx/data-sources.json`. + +Redis uses the same skill and graph inputs. Only the binding changes: + +```json +{ + "data_sources": { + "tenant://acme/board": { + "adapter": "data.redis", + "endpoint": "redis://127.0.0.1:6379/0", + "key_prefix": "runx:acme:board", + "resources": { + "board_events": { + "kind": "event_stream", + "partition_key": "aggregate_id" + } + } + } + } +} +``` + +The Redis endpoint must not embed credentials. Use local unauthenticated Redis +for OSS dogfood, or put production secrets behind a runx credential profile or +hosted grant. diff --git a/skills/data-store/X.yaml b/skills/data-store/X.yaml new file mode 100644 index 000000000..be06c1bbd --- /dev/null +++ b/skills/data-store/X.yaml @@ -0,0 +1,207 @@ +skill: data-store +version: "0.1.1" + +catalog: + kind: skill + audience: public + visibility: public + role: canonical + runtime_path: data-adapter + +policy: + allow: + - provider: data-source + method: READ + scope: runx:data:read + - provider: data-source + method: APPEND + scope: runx:data:append + deny: + - raw_sql_from_model + - unrestricted_export + - secret_material + - pii_without_projection + +emits: + - name: data_operation_result + packet: runx.data.operation_result.v1 + +runners: + append_event: + default: true + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Stable logical ref bound by the project or hosted operator to a provider adapter. + store_id: + type: string + required: false + description: Opt into the bundled data.local fixture store with this deterministic store id; omit for durable local SQLite. + resource: + type: string + required: true + description: Declared event resource or stream family. + aggregate_id: + type: string + required: true + description: Event stream or partition key. + expected_version: + type: number + required: true + description: Current stream version required before append. + idempotency_key: + type: string + required: true + description: Stable retry key for this data effect. + event: + type: json + required: true + description: Domain event or transition packet to append. + graph: + name: data-store-append-event + steps: + - id: append + tool: data.source + scopes: + - runx:data:append + inputs: + operation: append_event + data_source_ref: "$input.data_source_ref" + store_id: "$input.store_id" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + expected_version: "$input.expected_version" + idempotency_key: "$input.idempotency_key" + event: "$input.event" + + read_events: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Stable logical ref bound by the project or hosted operator to a provider adapter. + store_id: + type: string + required: false + description: Opt into the bundled data.local fixture store with this deterministic store id; omit for durable local SQLite. + resource: + type: string + required: true + description: Declared event resource or stream family. + aggregate_id: + type: string + required: true + description: Event stream or partition key. + limit: + type: number + required: false + default: 50 + description: Maximum events to return. + graph: + name: data-store-read-events + steps: + - id: read + tool: data.source + scopes: + - runx:data:read + inputs: + operation: read_events + data_source_ref: "$input.data_source_ref" + store_id: "$input.store_id" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + limit: "$input.limit" + + read_projection: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Stable logical ref bound by the project or hosted operator to a provider adapter. + store_id: + type: string + required: false + description: Opt into the bundled data.local fixture store with this deterministic store id; omit for durable local SQLite. + resource: + type: string + required: true + description: Declared event resource or projection family. + aggregate_id: + type: string + required: true + description: Event stream or partition key. + graph: + name: data-store-read-projection + steps: + - id: read + tool: data.source + scopes: + - runx:data:read + inputs: + operation: read_projection + data_source_ref: "$input.data_source_ref" + store_id: "$input.store_id" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + + append_and_readback: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Stable logical ref bound by the project or hosted operator to a provider adapter. + store_id: + type: string + required: false + description: Opt into the bundled data.local fixture store with this deterministic store id; omit for durable local SQLite. + resource: + type: string + required: true + description: Declared event resource or stream family. + aggregate_id: + type: string + required: true + description: Event stream or partition key. + expected_version: + type: number + required: true + description: Current stream version required before append. + idempotency_key: + type: string + required: true + description: Stable retry key for this data effect. + event: + type: json + required: true + description: Domain event or transition packet to append. + graph: + name: data-store-append-and-readback + steps: + - id: append + tool: data.source + scopes: + - runx:data:append + inputs: + operation: append_event + data_source_ref: "$input.data_source_ref" + store_id: "$input.store_id" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + expected_version: "$input.expected_version" + idempotency_key: "$input.idempotency_key" + event: "$input.event" + - id: readback + tool: data.source + scopes: + - runx:data:read + inputs: + operation: read_projection + data_source_ref: "$input.data_source_ref" + store_id: "$input.store_id" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" diff --git a/skills/data-store/fixtures/append-local-event.yaml b/skills/data-store/fixtures/append-local-event.yaml new file mode 100644 index 000000000..ebfff50cb --- /dev/null +++ b/skills/data-store/fixtures/append-local-event.yaml @@ -0,0 +1,27 @@ +name: append-local-event +kind: skill +target: .. +runner: append_event +inputs: + data_source_ref: local://runx-data-store/append-fixture + store_id: data-store-append-local-event-v1 + resource: generic_events + aggregate_id: item-1 + expected_version: 0 + idempotency_key: item-1:create:v1 + event: + type: item.created + payload: + label: first item +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - append +metadata: + public_skill: data-store + source_case: append-local-event + source: skills-fixture + runner_kind: graph + graph_shape: append_event diff --git a/skills/data-store/fixtures/append-read-default-sqlite-event.yaml b/skills/data-store/fixtures/append-read-default-sqlite-event.yaml new file mode 100644 index 000000000..9d2e71843 --- /dev/null +++ b/skills/data-store/fixtures/append-read-default-sqlite-event.yaml @@ -0,0 +1,30 @@ +name: append-read-default-sqlite-event +kind: skill +target: .. +runner: append_and_readback +inputs: + data_source_ref: local://runx-data-store/default-sqlite-fixture + resource: board_events + aggregate_id: default-sqlite-posting-123 + expected_version: 0 + idempotency_key: default-sqlite-posting-123:create:v1 + event: + type: posting.created + payload: + title: verify default sqlite-backed local data source + actor: runx:principal:example + amount_minor: 500 + currency: usd +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - append + - readback +metadata: + public_skill: data-store + source_case: append-read-default-sqlite-event + source: skills-fixture + runner_kind: graph + graph_shape: append_and_readback_default_sqlite diff --git a/skills/data-store/fixtures/append-read-local-event.yaml b/skills/data-store/fixtures/append-read-local-event.yaml new file mode 100644 index 000000000..2007c3128 --- /dev/null +++ b/skills/data-store/fixtures/append-read-local-event.yaml @@ -0,0 +1,31 @@ +name: append-read-local-event +kind: skill +target: .. +runner: append_and_readback +inputs: + data_source_ref: local://runx-data-store/fixture + store_id: data-store-append-read-local-event-v1 + resource: board_events + aggregate_id: posting-123 + expected_version: 0 + idempotency_key: posting-123:create:v1 + event: + type: posting.created + payload: + title: verify a receipt link + actor: runx:principal:example + amount_minor: 500 + currency: usd +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - append + - readback +metadata: + public_skill: data-store + source_case: append-read-local-event + source: skills-fixture + runner_kind: graph + graph_shape: append_and_readback diff --git a/skills/data-store/fixtures/append-read-sqlite-event.yaml b/skills/data-store/fixtures/append-read-sqlite-event.yaml new file mode 100644 index 000000000..675769281 --- /dev/null +++ b/skills/data-store/fixtures/append-read-sqlite-event.yaml @@ -0,0 +1,32 @@ +name: append-read-sqlite-event +kind: skill +target: .. +runner: append_and_readback +env: + RUNX_DATA_SOURCES: '{"data_sources":{"tenant://runx-data-store/sqlite-fixture":{"adapter":"data.sqlite","database_path":".runx/data/data-store-sqlite-fixture.sqlite","resources":{"board_events":{"kind":"event_stream","partition_key":"aggregate_id"}}}}}' +inputs: + data_source_ref: tenant://runx-data-store/sqlite-fixture + resource: board_events + aggregate_id: sqlite-posting-123 + expected_version: 0 + idempotency_key: sqlite-posting-123:create:v1 + event: + type: posting.created + payload: + title: verify sqlite-backed data-source resolution + actor: runx:principal:example + amount_minor: 500 + currency: usd +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - append + - readback +metadata: + public_skill: data-store + source_case: append-read-sqlite-event + source: skills-fixture + runner_kind: graph + graph_shape: append_and_readback_sqlite diff --git a/skills/data-store/fixtures/append-version-conflict.yaml b/skills/data-store/fixtures/append-version-conflict.yaml new file mode 100644 index 000000000..e0b826b7f --- /dev/null +++ b/skills/data-store/fixtures/append-version-conflict.yaml @@ -0,0 +1,27 @@ +name: append-version-conflict +kind: skill +target: .. +runner: append_event +inputs: + data_source_ref: local://runx-data-store/version-conflict + store_id: data-store-version-conflict-v1 + resource: generic_events + aggregate_id: item-1 + expected_version: 1 + idempotency_key: item-1:create-conflict:v1 + event: + type: item.created + payload: + label: conflict item +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - append +metadata: + public_skill: data-store + source_case: append-version-conflict + source: skills-fixture + runner_kind: graph + graph_shape: append_event_conflict diff --git a/skills/data-store/fixtures/read-local-events.yaml b/skills/data-store/fixtures/read-local-events.yaml new file mode 100644 index 000000000..64fe16f24 --- /dev/null +++ b/skills/data-store/fixtures/read-local-events.yaml @@ -0,0 +1,22 @@ +name: read-local-events +kind: skill +target: .. +runner: read_events +inputs: + data_source_ref: local://runx-data-store/read-events-fixture + store_id: data-store-read-local-events-v1 + resource: generic_events + aggregate_id: item-1 + limit: 10 +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - read +metadata: + public_skill: data-store + source_case: read-local-events + source: skills-fixture + runner_kind: graph + graph_shape: read_events diff --git a/skills/data-store/fixtures/read-local-projection.yaml b/skills/data-store/fixtures/read-local-projection.yaml new file mode 100644 index 000000000..b3662e3b5 --- /dev/null +++ b/skills/data-store/fixtures/read-local-projection.yaml @@ -0,0 +1,21 @@ +name: read-local-projection +kind: skill +target: .. +runner: read_projection +inputs: + data_source_ref: local://runx-data-store/read-projection-fixture + store_id: data-store-read-local-projection-v1 + resource: generic_events + aggregate_id: item-1 +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - read +metadata: + public_skill: data-store + source_case: read-local-projection + source: skills-fixture + runner_kind: graph + graph_shape: read_projection diff --git a/skills/data-store/tools/data/local/manifest.json b/skills/data-store/tools/data/local/manifest.json new file mode 100644 index 000000000..ebf37ea0f --- /dev/null +++ b/skills/data-store/tools/data/local/manifest.json @@ -0,0 +1,77 @@ +{ + "schema": "runx.tool.manifest.v1", + "name": "data.local", + "version": "0.1.0", + "description": "Local JSON event-store adapter for the provider-agnostic runx data operation envelope.", + "source": { + "type": "cli-tool", + "command": "node", + "args": ["./run.mjs"] + }, + "inputs": { + "operation": { + "type": "string", + "required": true, + "description": "append_event, read_events, or read_projection." + }, + "data_source_ref": { + "type": "string", + "required": true, + "description": "Stable logical data-source reference." + }, + "store_id": { + "type": "string", + "required": false, + "description": "Local fixture store id. Provider adapters may ignore this." + }, + "resource": { + "type": "string", + "required": true, + "description": "Declared resource, stream, table, keyspace, or projection name." + }, + "aggregate_id": { + "type": "string", + "required": true, + "description": "Stream or partition key." + }, + "expected_version": { + "type": "number", + "required": false, + "description": "Required current stream version for append_event." + }, + "idempotency_key": { + "type": "string", + "required": false, + "description": "Stable retry key for append_event." + }, + "event": { + "type": "json", + "required": false, + "description": "Domain event or transition packet for append_event." + }, + "limit": { + "type": "number", + "required": false, + "default": 50, + "description": "Maximum events returned by read_events." + } + }, + "scopes": ["runx:data:read", "runx:data:append"], + "runx": { + "artifacts": { + "named_emits": { + "data_operation_result": "runx.data.operation_result.v1" + }, + "wrap_as": "data_operation_result" + } + }, + "runtime": { + "command": "node", + "args": ["./run.mjs"] + }, + "output": { + "packet": "runx.data.operation_result.v1", + "wrap_as": "data_operation_result" + }, + "toolkit_version": "0.1.4" +} diff --git a/skills/data-store/tools/data/local/run.mjs b/skills/data-store/tools/data/local/run.mjs new file mode 100644 index 000000000..659c9702b --- /dev/null +++ b/skills/data-store/tools/data/local/run.mjs @@ -0,0 +1,335 @@ +import crypto from "node:crypto"; +import fs from "node:fs"; +import os from "node:os"; +import path from "node:path"; + +const SCHEMA = "runx.data.operation_result.v1"; +const PROVIDER = "local-json-event-store"; + +const inputs = readInputs(); +const operation = stringInput("operation"); + +let result; +if (operation === "append_event") { + result = appendEvent(inputs); +} else if (operation === "read_events") { + result = readEvents(inputs); +} else if (operation === "read_projection") { + result = readProjection(inputs); +} else { + throw new Error("operation must be append_event, read_events, or read_projection"); +} + +process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + +function readInputs() { + const raw = process.env.RUNX_INPUTS_PATH + ? fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8") + : process.env.RUNX_INPUTS_JSON || "{}"; + return JSON.parse(raw); +} + +function appendEvent(rawInputs) { + const envelope = baseEnvelope(rawInputs, "append_event"); + const expectedVersion = numberInput("expected_version"); + const idempotencyKey = stringInput("idempotency_key"); + const event = objectInput("event"); + const store = readStore(rawInputs); + const stream = streamFor(store, envelope.resource, envelope.aggregate_id); + const eventDigest = sha256Json(event); + const existing = stream.events.find((entry) => entry.idempotency_key === idempotencyKey); + + if (existing) { + if (existing.event_digest !== eventDigest) { + return conflictResult(envelope, stream, { + idempotency_key: idempotencyKey, + event_digest: eventDigest, + reason: "idempotency key was reused with different event content", + provider_evidence: providerEvidence(store, envelope), + }); + } + return { + ...envelope, + status: "idempotent_replay", + before_version: stream.version, + after_version: stream.version, + idempotency_key: idempotencyKey, + event_ref: existing.event_ref, + event_digest: existing.event_digest, + result_digest: sha256Json(existing), + projection_digest: projectionDigest(stream), + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(store, envelope), + }; + } + + if (stream.version !== expectedVersion) { + return conflictResult(envelope, stream, { + idempotency_key: idempotencyKey, + event_digest: eventDigest, + reason: `expected version ${expectedVersion}, got ${stream.version}`, + provider_evidence: providerEvidence(store, envelope), + }); + } + + const nextVersion = stream.version + 1; + const eventRef = `${envelope.resource}:${envelope.aggregate_id}:${nextVersion}`; + const record = { + event_ref: eventRef, + version: nextVersion, + event_type: eventType(event), + event, + event_digest: eventDigest, + idempotency_key: idempotencyKey, + committed_at: typeof rawInputs.observed_at === "string" ? rawInputs.observed_at : "1970-01-01T00:00:00.000Z", + }; + stream.events.push(record); + stream.version = nextVersion; + writeStore(rawInputs, store); + + return { + ...envelope, + status: "committed", + before_version: expectedVersion, + after_version: nextVersion, + idempotency_key: idempotencyKey, + event_ref: eventRef, + event_digest: eventDigest, + result_digest: sha256Json(record), + projection_digest: projectionDigest(stream), + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(store, envelope), + }; +} + +function conflictResult(envelope, stream, { idempotency_key, event_digest, reason, provider_evidence }) { + const stop = { + code: "conflict", + message: reason, + }; + return { + ...envelope, + status: "conflict", + before_version: stream.version, + after_version: stream.version, + idempotency_key, + event_ref: null, + event_digest, + result_digest: sha256Json(stop), + projection_digest: projectionDigest(stream), + events: [], + rows: [], + redactions: [], + stop_conditions: [stop], + provider_evidence, + }; +} + +function readEvents(rawInputs) { + const envelope = baseEnvelope(rawInputs, "read_events"); + const limit = boundedLimit(rawInputs.limit); + const store = readStore(rawInputs); + const stream = streamFor(store, envelope.resource, envelope.aggregate_id); + const events = stream.events.slice(Math.max(0, stream.events.length - limit)); + return { + ...envelope, + status: "read", + before_version: stream.version, + after_version: stream.version, + idempotency_key: null, + event_ref: null, + event_digest: null, + result_digest: sha256Json(events), + projection_digest: projectionDigest(stream), + events, + rows: events, + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(store, envelope), + }; +} + +function readProjection(rawInputs) { + const envelope = baseEnvelope(rawInputs, "read_projection"); + const store = readStore(rawInputs); + const stream = streamFor(store, envelope.resource, envelope.aggregate_id); + const projection = { + aggregate_id: envelope.aggregate_id, + resource: envelope.resource, + version: stream.version, + event_count: stream.events.length, + last_event_ref: stream.events.at(-1)?.event_ref ?? null, + last_event_type: stream.events.at(-1)?.event_type ?? null, + event_digests: stream.events.map((entry) => entry.event_digest), + }; + return { + ...envelope, + status: "read", + before_version: stream.version, + after_version: stream.version, + idempotency_key: null, + event_ref: null, + event_digest: null, + result_digest: sha256Json(projection), + projection_digest: sha256Json(projection), + projection, + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(store, envelope), + }; +} + +function baseEnvelope(rawInputs, operation) { + return { + schema: SCHEMA, + data_source_ref: stringInput("data_source_ref"), + provider: PROVIDER, + operation, + resource: safeName(stringInput("resource"), "resource"), + aggregate_id: safeName(stringInput("aggregate_id"), "aggregate_id"), + }; +} + +function streamFor(store, resource, aggregateId) { + store.resources[resource] ??= { streams: {} }; + store.resources[resource].streams[aggregateId] ??= { version: 0, events: [] }; + return store.resources[resource].streams[aggregateId]; +} + +function readStore(rawInputs) { + const file = storePath(rawInputs); + if (!fs.existsSync(file)) { + return { + schema: "runx.local_data_store.v1", + store_id: localStoreId(rawInputs), + resources: {}, + }; + } + const parsed = JSON.parse(fs.readFileSync(file, "utf8")); + if (!parsed || typeof parsed !== "object" || parsed.schema !== "runx.local_data_store.v1") { + throw new Error("local data store file has an invalid schema"); + } + parsed.resources ??= {}; + return parsed; +} + +function writeStore(rawInputs, store) { + const file = storePath(rawInputs); + fs.mkdirSync(path.dirname(file), { recursive: true }); + const tmp = `${file}.${process.pid}.tmp`; + fs.writeFileSync(tmp, `${JSON.stringify(store, null, 2)}\n`); + fs.renameSync(tmp, file); +} + +function storePath(rawInputs) { + const storeId = localStoreId(rawInputs); + return path.join(os.tmpdir(), "runx-data-store", `${storeId}.json`); +} + +function localStoreId(rawInputs) { + if (typeof rawInputs.store_id === "string" && rawInputs.store_id.trim().length > 0) { + return safeName(rawInputs.store_id, "store_id"); + } + const ref = typeof rawInputs.data_source_ref === "string" && rawInputs.data_source_ref.length > 0 + ? rawInputs.data_source_ref + : "default"; + return `source-${crypto.createHash("sha256").update(ref).digest("hex").slice(0, 24)}`; +} + +function providerEvidence(store, envelope) { + return { + provider: PROVIDER, + store_id: store.store_id, + resource: envelope.resource, + aggregate_id: envelope.aggregate_id, + storage_class: "local-fixture", + }; +} + +function projectionDigest(stream) { + return sha256Json({ + version: stream.version, + event_digests: stream.events.map((entry) => entry.event_digest), + }); +} + +function readValue(name) { + return inputs[name]; +} + +function stringInput(name) { + const value = readValue(name); + if (typeof value !== "string" || value.trim().length === 0) { + throw new Error(`${name} is required`); + } + return value.trim(); +} + +function numberInput(name) { + const value = readValue(name); + if (!Number.isInteger(value) || value < 0) { + throw new Error(`${name} must be a non-negative integer`); + } + return value; +} + +function objectInput(name) { + const value = readValue(name); + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new Error(`${name} must be an object`); + } + return value; +} + +function eventType(event) { + const explicit = safeEventToken(event.type) ?? safeEventToken(event.event_type); + if (explicit) return explicit; + const family = safeEventToken(event.effect_family); + const operation = safeEventToken(event.operation); + if (family && operation) return `${family}.${operation}`; + if (operation) return operation; + return "data.event"; +} + +function safeEventToken(value) { + if (typeof value !== "string") return undefined; + const text = value.trim(); + return /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(text) ? text : undefined; +} + +function boundedLimit(value) { + if (value === undefined || value === null) return 50; + if (!Number.isInteger(value) || value < 1 || value > 500) { + throw new Error("limit must be an integer from 1 to 500"); + } + return value; +} + +function safeName(value, field) { + const text = String(value || "").trim(); + const pattern = field === "aggregate_id" + ? /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,191}$/ + : /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; + if (!pattern.test(text)) { + throw new Error(`${field} must be a safe identifier`); + } + return text; +} + +function sha256Json(value) { + return `sha256:${crypto.createHash("sha256").update(canonicalJson(value)).digest("hex")}`; +} + +function canonicalJson(value) { + if (value === null || typeof value !== "object") return JSON.stringify(value); + if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`; + return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`; +} diff --git a/skills/data-store/tools/data/redis/README.md b/skills/data-store/tools/data/redis/README.md new file mode 100644 index 000000000..ecce9844f --- /dev/null +++ b/skills/data-store/tools/data/redis/README.md @@ -0,0 +1,42 @@ +# data.redis + +`data.redis` is the Redis provider adapter for the `data-store` operation +envelope. It is intentionally not a separate domain skill: messageboards, +operator desks, sync cursors, and business workflows keep their semantics in +their own skills, while this adapter supplies the storage backend. + +## Binding + +Bind a logical source to Redis with non-secret project configuration: + +```json +{ + "data_sources": { + "tenant://acme/board": { + "adapter": "data.redis", + "endpoint": "redis://127.0.0.1:6379/0", + "key_prefix": "runx:acme:board", + "resources": { + "board_events": { + "kind": "event_stream", + "partition_key": "aggregate_id" + } + } + } + } +} +``` + +Pass the document through `RUNX_DATA_SOURCES` or write it to +`.runx/data-sources.json`. The endpoint must not embed credentials. Use a local +unauthenticated Redis for OSS dogfood, or put provider credentials behind the +normal runx credential boundary when a hosted/production adapter supplies secret +delivery. + +## Requirements + +- `redis-cli` on `PATH`, or set `RUNX_REDIS_CLI_BIN`. +- A reachable `redis://` or `rediss://` endpoint. + +Live conformance tests run only when `RUNX_REDIS_URL` is set and responds to +`PING`, so normal CI does not require Redis. diff --git a/skills/data-store/tools/data/redis/manifest.json b/skills/data-store/tools/data/redis/manifest.json new file mode 100644 index 000000000..aae2c85f6 --- /dev/null +++ b/skills/data-store/tools/data/redis/manifest.json @@ -0,0 +1,87 @@ +{ + "schema": "runx.tool.manifest.v1", + "name": "data.redis", + "version": "0.1.0", + "description": "Redis event-store adapter for the provider-agnostic runx data operation envelope.", + "source": { + "type": "cli-tool", + "command": "node", + "args": ["./run.mjs"] + }, + "inputs": { + "operation": { + "type": "string", + "required": true, + "description": "append_event, read_events, or read_projection." + }, + "data_source_ref": { + "type": "string", + "required": true, + "description": "Stable logical data-source reference." + }, + "data_source_binding": { + "type": "json", + "required": false, + "description": "Non-secret data-source binding injected by data.source." + }, + "redis_url": { + "type": "string", + "required": false, + "description": "Redis URL for direct harness use. Prefer data_source_binding.endpoint." + }, + "key_prefix": { + "type": "string", + "required": false, + "description": "Redis key prefix for direct harness use. Prefer data_source_binding.key_prefix." + }, + "resource": { + "type": "string", + "required": true, + "description": "Declared event resource or stream family." + }, + "aggregate_id": { + "type": "string", + "required": true, + "description": "Stream or partition key." + }, + "expected_version": { + "type": "number", + "required": false, + "description": "Required current stream version for append_event." + }, + "idempotency_key": { + "type": "string", + "required": false, + "description": "Stable retry key for append_event." + }, + "event": { + "type": "json", + "required": false, + "description": "Domain event or transition packet for append_event." + }, + "limit": { + "type": "number", + "required": false, + "default": 50, + "description": "Maximum events returned by read_events." + } + }, + "scopes": ["runx:data:read", "runx:data:append"], + "runx": { + "artifacts": { + "named_emits": { + "data_operation_result": "runx.data.operation_result.v1" + }, + "wrap_as": "data_operation_result" + } + }, + "runtime": { + "command": "node", + "args": ["./run.mjs"] + }, + "output": { + "packet": "runx.data.operation_result.v1", + "wrap_as": "data_operation_result" + }, + "toolkit_version": "0.1.4" +} diff --git a/skills/data-store/tools/data/redis/run.mjs b/skills/data-store/tools/data/redis/run.mjs new file mode 100644 index 000000000..4e3f1e931 --- /dev/null +++ b/skills/data-store/tools/data/redis/run.mjs @@ -0,0 +1,426 @@ +import crypto from "node:crypto"; +import fs from "node:fs"; +import { spawnSync } from "node:child_process"; + +const SCHEMA = "runx.data.operation_result.v1"; +const PROVIDER = "redis-event-store"; +const REDIS_CLI_BIN = process.env.RUNX_REDIS_CLI_BIN || "redis-cli"; + +const inputs = readInputs(); +const operation = stringInput("operation"); + +let result; +if (operation === "append_event") { + result = appendEvent(inputs); +} else if (operation === "read_events") { + result = readEvents(inputs); +} else if (operation === "read_projection") { + result = readProjection(inputs); +} else { + throw new Error("operation must be append_event, read_events, or read_projection"); +} + +process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + +function readInputs() { + const raw = process.env.RUNX_INPUTS_PATH + ? fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8") + : process.env.RUNX_INPUTS_JSON || "{}"; + return JSON.parse(raw); +} + +function appendEvent(rawInputs) { + const envelope = baseEnvelope(rawInputs, "append_event"); + const expectedVersion = numberInput("expected_version"); + const idempotencyKey = stringInput("idempotency_key"); + const event = objectInput("event"); + const eventDigest = sha256Json(event); + const keys = redisKeys(rawInputs, envelope); + const nextVersion = expectedVersion + 1; + const eventRef = `${envelope.resource}:${envelope.aggregate_id}:${nextVersion}`; + const record = { + event_ref: eventRef, + version: nextVersion, + event_type: eventType(event), + event, + event_digest: eventDigest, + idempotency_key: idempotencyKey, + committed_at: typeof rawInputs.observed_at === "string" ? rawInputs.observed_at : "1970-01-01T00:00:00.000Z", + }; + const recordDigest = sha256Json(record); + const response = redisEval(rawInputs, appendScript(), [keys.stream, keys.idempotency], [ + String(expectedVersion), + idempotencyKey, + eventDigest, + eventRef, + String(nextVersion), + JSON.stringify(record), + recordDigest, + ]); + const [status, ...fields] = response.split("|"); + + if (status === "committed") { + const [before, after, ref, digest, resultDigest] = fields; + return { + ...envelope, + status: "committed", + before_version: Number(before), + after_version: Number(after), + idempotency_key: idempotencyKey, + event_ref: ref, + event_digest: digest, + result_digest: resultDigest, + projection_digest: projectionDigest(rawInputs, envelope), + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(rawInputs, envelope), + }; + } + + if (status === "idempotent_replay") { + const [current, digest, ref, version, resultDigest] = fields; + return { + ...envelope, + status: "idempotent_replay", + before_version: Number(current), + after_version: Number(current), + idempotency_key: idempotencyKey, + event_ref: ref, + event_digest: digest, + result_digest: resultDigest, + projection_digest: projectionDigest(rawInputs, envelope), + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: { + ...providerEvidence(rawInputs, envelope), + committed_version: Number(version), + }, + }; + } + + if (status === "idempotency_conflict") { + return conflictResult(envelope, Number(fields[0]), { + idempotency_key: idempotencyKey, + event_digest: eventDigest, + reason: "idempotency key was reused with different event content", + projection_digest: projectionDigest(rawInputs, envelope), + provider_evidence: providerEvidence(rawInputs, envelope), + }); + } + + if (status === "version_conflict") { + const current = Number(fields[0]); + return conflictResult(envelope, current, { + idempotency_key: idempotencyKey, + event_digest: eventDigest, + reason: `expected version ${expectedVersion}, got ${current}`, + projection_digest: projectionDigest(rawInputs, envelope), + provider_evidence: providerEvidence(rawInputs, envelope), + }); + } + + throw new Error(`unexpected redis append response: ${response}`); +} + +function readEvents(rawInputs) { + const envelope = baseEnvelope(rawInputs, "read_events"); + const limit = boundedLimit(rawInputs.limit); + const keys = redisKeys(rawInputs, envelope); + const rows = redis(rawInputs, ["LRANGE", keys.stream, String(-limit), "-1"]); + const events = parseJsonLines(rows); + const current = redisInteger(rawInputs, ["LLEN", keys.stream]); + return { + ...envelope, + status: "read", + before_version: current, + after_version: current, + idempotency_key: null, + event_ref: null, + event_digest: null, + result_digest: sha256Json(events), + projection_digest: projectionDigest(rawInputs, envelope), + events, + rows: events, + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(rawInputs, envelope), + }; +} + +function readProjection(rawInputs) { + const envelope = baseEnvelope(rawInputs, "read_projection"); + const projection = buildProjection(rawInputs, envelope); + return { + ...envelope, + status: "read", + before_version: projection.version, + after_version: projection.version, + idempotency_key: null, + event_ref: null, + event_digest: null, + result_digest: sha256Json(projection), + projection_digest: sha256Json(projection), + projection, + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(rawInputs, envelope), + }; +} + +function appendScript() { + return ` +local current = redis.call('LLEN', KEYS[1]) +local existing = redis.call('HGET', KEYS[2], ARGV[2]) +if existing then + local digest, ref, version, result_digest = string.match(existing, '^([^|]+)|([^|]+)|([^|]+)|([^|]+)$') + if digest ~= ARGV[3] then + return 'idempotency_conflict|' .. current + end + return 'idempotent_replay|' .. current .. '|' .. digest .. '|' .. ref .. '|' .. version .. '|' .. result_digest +end +local expected = tonumber(ARGV[1]) +if current ~= expected then + return 'version_conflict|' .. current +end +redis.call('RPUSH', KEYS[1], ARGV[6]) +redis.call('HSET', KEYS[2], ARGV[2], ARGV[3] .. '|' .. ARGV[4] .. '|' .. ARGV[5] .. '|' .. ARGV[7]) +return 'committed|' .. current .. '|' .. (current + 1) .. '|' .. ARGV[4] .. '|' .. ARGV[3] .. '|' .. ARGV[7] +`; +} + +function conflictResult(envelope, currentVersionValue, { idempotency_key, event_digest, reason, projection_digest, provider_evidence }) { + const stop = { + code: "conflict", + message: reason, + }; + return { + ...envelope, + status: "conflict", + before_version: currentVersionValue, + after_version: currentVersionValue, + idempotency_key, + event_ref: null, + event_digest, + result_digest: sha256Json(stop), + projection_digest, + events: [], + rows: [], + redactions: [], + stop_conditions: [stop], + provider_evidence, + }; +} + +function baseEnvelope(rawInputs, operation) { + return { + schema: SCHEMA, + data_source_ref: stringInput("data_source_ref"), + provider: PROVIDER, + operation, + resource: safeName(stringInput("resource"), "resource"), + aggregate_id: safeName(stringInput("aggregate_id"), "aggregate_id"), + }; +} + +function buildProjection(rawInputs, envelope) { + const keys = redisKeys(rawInputs, envelope); + const events = parseJsonLines(redis(rawInputs, ["LRANGE", keys.stream, "0", "-1"])); + return { + aggregate_id: envelope.aggregate_id, + resource: envelope.resource, + version: events.length, + event_count: events.length, + last_event_ref: events.at(-1)?.event_ref ?? null, + last_event_type: events.at(-1)?.event_type ?? null, + event_digests: events.map((entry) => entry.event_digest), + }; +} + +function projectionDigest(rawInputs, envelope) { + return sha256Json(buildProjection(rawInputs, envelope)); +} + +function providerEvidence(rawInputs, envelope) { + const keys = redisKeys(rawInputs, envelope); + return { + provider: PROVIDER, + adapter: "data.redis", + data_source_ref_digest: sha256Json(envelope.data_source_ref), + resource: envelope.resource, + aggregate_id: envelope.aggregate_id, + storage_class: "redis", + key_prefix_digest: sha256Json(keyPrefix(rawInputs)), + stream_digest: keys.digest, + }; +} + +function redisKeys(rawInputs, envelope) { + const digest = sha256Hex({ + data_source_ref: envelope.data_source_ref, + resource: envelope.resource, + aggregate_id: envelope.aggregate_id, + }); + const prefix = keyPrefix(rawInputs); + return { + digest, + stream: `${prefix}:stream:${digest}`, + idempotency: `${prefix}:idempotency:${digest}`, + }; +} + +function redisEval(rawInputs, script, keys, argv) { + return redis(rawInputs, ["EVAL", script, String(keys.length), ...keys, ...argv]).trim(); +} + +function redisInteger(rawInputs, args) { + const text = redis(rawInputs, args).trim(); + const value = Number(text || "0"); + if (!Number.isInteger(value) || value < 0) { + throw new Error(`redis returned invalid integer for ${args[0]}`); + } + return value; +} + +function redis(rawInputs, args) { + const result = spawnSync(REDIS_CLI_BIN, ["-u", redisUrl(rawInputs), "--raw", ...args], { + encoding: "utf8", + maxBuffer: 1024 * 1024, + }); + if (result.error) { + throw result.error; + } + if (result.status !== 0) { + throw new Error((result.stderr || result.stdout || `redis-cli exited ${result.status}`).trim()); + } + return result.stdout; +} + +function redisUrl(rawInputs) { + const sourceBinding = dataSourceBinding(rawInputs); + const raw = textValue(sourceBinding.endpoint) ?? textValue(sourceBinding.redis_url) ?? textValue(rawInputs.redis_url) ?? "redis://127.0.0.1:6379/0"; + let parsed; + try { + parsed = new URL(raw); + } catch { + throw new Error("data.redis endpoint must be a valid redis:// or rediss:// URL"); + } + if (parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") { + throw new Error("data.redis endpoint must use redis:// or rediss://"); + } + if (parsed.username || parsed.password) { + throw new Error("data.redis endpoint must not embed credentials; use a runx credential profile or hosted grant"); + } + if (parsed.search || parsed.hash) { + throw new Error("data.redis endpoint must not include query or fragment parameters"); + } + return parsed.toString(); +} + +function keyPrefix(rawInputs) { + const bindingObject = dataSourceBinding(rawInputs); + const raw = textValue(bindingObject.key_prefix) ?? textValue(rawInputs.key_prefix) ?? "runx:data-store"; + const pattern = /^[A-Za-z0-9][A-Za-z0-9._:/-]{0,191}$/; + if (!pattern.test(raw)) { + throw new Error("data.redis key_prefix must be a safe Redis key prefix"); + } + return raw; +} + +function dataSourceBinding(rawInputs) { + return rawInputs.data_source_binding && typeof rawInputs.data_source_binding === "object" && !Array.isArray(rawInputs.data_source_binding) + ? rawInputs.data_source_binding + : {}; +} + +function parseJsonLines(stdout) { + const text = stdout.trim(); + if (!text) return []; + return text.split(/\r?\n/).map((line) => JSON.parse(line)); +} + +function readValue(name) { + return inputs[name]; +} + +function stringInput(name) { + const value = readValue(name); + if (typeof value !== "string" || value.trim().length === 0) { + throw new Error(`${name} is required`); + } + return value.trim(); +} + +function numberInput(name) { + const value = readValue(name); + if (!Number.isInteger(value) || value < 0) { + throw new Error(`${name} must be a non-negative integer`); + } + return value; +} + +function objectInput(name) { + const value = readValue(name); + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new Error(`${name} must be an object`); + } + return value; +} + +function eventType(event) { + const explicit = safeEventToken(event.type) ?? safeEventToken(event.event_type); + if (explicit) return explicit; + const family = safeEventToken(event.effect_family); + const operation = safeEventToken(event.operation); + if (family && operation) return `${family}.${operation}`; + if (operation) return operation; + return "data.event"; +} + +function safeEventToken(value) { + if (typeof value !== "string") return undefined; + const text = value.trim(); + return /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(text) ? text : undefined; +} + +function boundedLimit(value) { + if (value === undefined || value === null) return 50; + if (!Number.isInteger(value) || value < 1 || value > 500) { + throw new Error("limit must be an integer from 1 to 500"); + } + return value; +} + +function safeName(value, field) { + const text = String(value || "").trim(); + const pattern = field === "aggregate_id" + ? /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,191}$/ + : /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; + if (!pattern.test(text)) { + throw new Error(`${field} must be a safe identifier`); + } + return text; +} + +function textValue(value) { + return typeof value === "string" && value.trim().length > 0 ? value.trim() : undefined; +} + +function sha256Json(value) { + return `sha256:${sha256Hex(value)}`; +} + +function sha256Hex(value) { + return crypto.createHash("sha256").update(canonicalJson(value)).digest("hex"); +} + +function canonicalJson(value) { + if (value === null || typeof value !== "object") return JSON.stringify(value); + if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`; + return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`; +} diff --git a/skills/data-store/tools/data/sqlite/README.md b/skills/data-store/tools/data/sqlite/README.md new file mode 100644 index 000000000..aa4645e75 --- /dev/null +++ b/skills/data-store/tools/data/sqlite/README.md @@ -0,0 +1,63 @@ +# data.sqlite + +`data.sqlite` is the durable local adapter for the provider-agnostic runx data +operation envelope. It is useful for dogfooding real stateful graphs without +standing up hosted infrastructure. Unbound `local://...` data sources resolve to +this adapter by default; pass `store_id` only when a fixture intentionally wants +the JSON `data.local` adapter instead. + +The adapter shells out to `sqlite3`. Set `RUNX_SQLITE_BIN` when the binary is not +on `PATH`. + +The adapter is selected through a data-source binding: + +```json +{ + "data_sources": { + "tenant://example/board": { + "adapter": "data.sqlite", + "database_path": ".runx/data/example-board.sqlite", + "resources": { + "board_events": { + "kind": "event_stream", + "partition_key": "aggregate_id" + } + } + } + } +} +``` + +Graphs still pass only `data_source_ref`, `resource`, `aggregate_id`, +`expected_version`, `idempotency_key`, and operation-specific inputs. The +binding chooses SQLite. + +For unbound `local://...` refs, runx derives a source-scoped database path under +`.runx/data/local-sources/`. When several sources intentionally share one +configured `database_path`, `data.sqlite` still isolates streams by +`data_source_ref`, `resource`, and `aggregate_id`. + +## Operations + +- `append_event` +- `read_events` +- `read_projection` + +Writes require `expected_version` and `idempotency_key`. A retry with the same +idempotency key and same event digest returns `idempotent_replay`. A retry with +the same idempotency key and different event digest returns `conflict`. + +## Path rules + +Relative `database_path` values resolve from `RUNX_CWD`, `INIT_CWD`, or the +current working directory. Absolute paths are rejected unless the binding sets +`allow_absolute_path: true`. + +Provider evidence never includes the absolute database path. + +## Resetting local state + +Delete the relevant file under `.runx/data/local-sources/` for default local +dogfood, or delete the configured `database_path` for a project-specific +binding. Do not reset by changing domain skill inputs; that hides replay +problems instead of clearing local storage. diff --git a/skills/data-store/tools/data/sqlite/manifest.json b/skills/data-store/tools/data/sqlite/manifest.json new file mode 100644 index 000000000..b6926bbe8 --- /dev/null +++ b/skills/data-store/tools/data/sqlite/manifest.json @@ -0,0 +1,82 @@ +{ + "schema": "runx.tool.manifest.v1", + "name": "data.sqlite", + "version": "0.1.0", + "description": "SQLite event-store adapter for the provider-agnostic runx data operation envelope.", + "source": { + "type": "cli-tool", + "command": "node", + "args": ["./run.mjs"] + }, + "inputs": { + "operation": { + "type": "string", + "required": true, + "description": "append_event, read_events, or read_projection." + }, + "data_source_ref": { + "type": "string", + "required": true, + "description": "Stable logical data-source reference." + }, + "data_source_binding": { + "type": "json", + "required": false, + "description": "Non-secret data-source binding injected by data.source." + }, + "database_path": { + "type": "string", + "required": false, + "description": "Local SQLite database path for direct harness use. Prefer data_source_binding.database_path." + }, + "resource": { + "type": "string", + "required": true, + "description": "Declared event resource or stream family." + }, + "aggregate_id": { + "type": "string", + "required": true, + "description": "Stream or partition key." + }, + "expected_version": { + "type": "number", + "required": false, + "description": "Required current stream version for append_event." + }, + "idempotency_key": { + "type": "string", + "required": false, + "description": "Stable retry key for append_event." + }, + "event": { + "type": "json", + "required": false, + "description": "Domain event or transition packet for append_event." + }, + "limit": { + "type": "number", + "required": false, + "default": 50, + "description": "Maximum events returned by read_events." + } + }, + "scopes": ["runx:data:read", "runx:data:append"], + "runx": { + "artifacts": { + "named_emits": { + "data_operation_result": "runx.data.operation_result.v1" + }, + "wrap_as": "data_operation_result" + } + }, + "runtime": { + "command": "node", + "args": ["./run.mjs"] + }, + "output": { + "packet": "runx.data.operation_result.v1", + "wrap_as": "data_operation_result" + }, + "toolkit_version": "0.1.4" +} diff --git a/skills/data-store/tools/data/sqlite/run.mjs b/skills/data-store/tools/data/sqlite/run.mjs new file mode 100644 index 000000000..dfaf4d1b9 --- /dev/null +++ b/skills/data-store/tools/data/sqlite/run.mjs @@ -0,0 +1,546 @@ +import crypto from "node:crypto"; +import fs from "node:fs"; +import path from "node:path"; +import { spawnSync } from "node:child_process"; + +const SCHEMA = "runx.data.operation_result.v1"; +const PROVIDER = "sqlite-event-store"; +const SQLITE_BIN = process.env.RUNX_SQLITE_BIN || "sqlite3"; + +const inputs = readInputs(); +const operation = stringInput("operation"); + +let result; +if (operation === "append_event") { + result = appendEvent(inputs); +} else if (operation === "read_events") { + result = readEvents(inputs); +} else if (operation === "read_projection") { + result = readProjection(inputs); +} else { + throw new Error("operation must be append_event, read_events, or read_projection"); +} + +process.stdout.write(`${JSON.stringify(result, null, 2)}\n`); + +function readInputs() { + const raw = process.env.RUNX_INPUTS_PATH + ? fs.readFileSync(process.env.RUNX_INPUTS_PATH, "utf8") + : process.env.RUNX_INPUTS_JSON || "{}"; + return JSON.parse(raw); +} + +function appendEvent(rawInputs) { + const database = databasePath(rawInputs); + ensureSchema(database); + + const envelope = baseEnvelope(rawInputs, "append_event"); + const expectedVersion = numberInput("expected_version"); + const idempotencyKey = stringInput("idempotency_key"); + const event = objectInput("event"); + const eventDigest = sha256Json(event); + const current = currentVersion(database, envelope); + const existing = existingEvent(database, envelope, idempotencyKey); + + if (existing) { + if (existing.event_digest !== eventDigest) { + return conflictResult(envelope, current, { + idempotency_key: idempotencyKey, + event_digest: eventDigest, + reason: "idempotency key was reused with different event content", + provider_evidence: providerEvidence(envelope), + }); + } + return { + ...envelope, + status: "idempotent_replay", + before_version: current, + after_version: current, + idempotency_key: idempotencyKey, + event_ref: existing.event_ref, + event_digest: existing.event_digest, + result_digest: sha256Json(existing), + projection_digest: projectionDigest(database, envelope), + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(envelope), + }; + } + + if (current !== expectedVersion) { + return conflictResult(envelope, current, { + idempotency_key: idempotencyKey, + event_digest: eventDigest, + reason: `expected version ${expectedVersion}, got ${current}`, + provider_evidence: providerEvidence(envelope), + }); + } + + const nextVersion = current + 1; + const eventRef = `${envelope.resource}:${envelope.aggregate_id}:${nextVersion}`; + const record = { + event_ref: eventRef, + version: nextVersion, + event_type: eventType(event), + event, + event_digest: eventDigest, + idempotency_key: idempotencyKey, + committed_at: typeof rawInputs.observed_at === "string" ? rawInputs.observed_at : "1970-01-01T00:00:00.000Z", + }; + + try { + execSql(database, ` +BEGIN IMMEDIATE; +INSERT INTO runx_events ( + data_source_ref, + resource, + aggregate_id, + version, + idempotency_key, + event_ref, + event_type, + event_digest, + event_json, + committed_at +) VALUES ( + ${sqlString(envelope.data_source_ref)}, + ${sqlString(envelope.resource)}, + ${sqlString(envelope.aggregate_id)}, + ${nextVersion}, + ${sqlString(idempotencyKey)}, + ${sqlString(eventRef)}, + ${sqlString(record.event_type)}, + ${sqlString(eventDigest)}, + ${sqlString(JSON.stringify(event))}, + ${sqlString(record.committed_at)} +); +COMMIT; +`); + } catch (error) { + const latest = currentVersion(database, envelope); + return conflictResult(envelope, latest, { + idempotency_key: idempotencyKey, + event_digest: eventDigest, + reason: `sqlite append failed after version check: ${error.message}`, + provider_evidence: providerEvidence(envelope), + }); + } + + return { + ...envelope, + status: "committed", + before_version: expectedVersion, + after_version: nextVersion, + idempotency_key: idempotencyKey, + event_ref: eventRef, + event_digest: eventDigest, + result_digest: sha256Json(record), + projection_digest: projectionDigest(database, envelope), + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(envelope), + }; +} + +function readEvents(rawInputs) { + const database = databasePath(rawInputs); + ensureSchema(database); + + const envelope = baseEnvelope(rawInputs, "read_events"); + const limit = boundedLimit(rawInputs.limit); + const current = currentVersion(database, envelope); + const rows = queryJson(database, ` +SELECT event_ref, version, event_type, event_digest, idempotency_key, committed_at, event_json +FROM runx_events +WHERE data_source_ref = ${sqlString(envelope.data_source_ref)} + AND resource = ${sqlString(envelope.resource)} + AND aggregate_id = ${sqlString(envelope.aggregate_id)} +ORDER BY version DESC +LIMIT ${limit}; +`); + const events = rows + .reverse() + .map((row) => ({ + event_ref: row.event_ref, + version: Number(row.version), + event_type: row.event_type, + event: JSON.parse(row.event_json), + event_digest: row.event_digest, + idempotency_key: row.idempotency_key, + committed_at: row.committed_at, + })); + + return { + ...envelope, + status: "read", + before_version: current, + after_version: current, + idempotency_key: null, + event_ref: null, + event_digest: null, + result_digest: sha256Json(events), + projection_digest: projectionDigest(database, envelope), + events, + rows: events, + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(envelope), + }; +} + +function readProjection(rawInputs) { + const database = databasePath(rawInputs); + ensureSchema(database); + + const envelope = baseEnvelope(rawInputs, "read_projection"); + const eventRows = queryJson(database, ` +SELECT event_ref, event_type, event_digest +FROM runx_events +WHERE data_source_ref = ${sqlString(envelope.data_source_ref)} + AND resource = ${sqlString(envelope.resource)} + AND aggregate_id = ${sqlString(envelope.aggregate_id)} +ORDER BY version ASC; +`); + const projection = { + aggregate_id: envelope.aggregate_id, + resource: envelope.resource, + version: eventRows.length, + event_count: eventRows.length, + last_event_ref: eventRows.at(-1)?.event_ref ?? null, + last_event_type: eventRows.at(-1)?.event_type ?? null, + event_digests: eventRows.map((entry) => entry.event_digest), + }; + return { + ...envelope, + status: "read", + before_version: projection.version, + after_version: projection.version, + idempotency_key: null, + event_ref: null, + event_digest: null, + result_digest: sha256Json(projection), + projection_digest: sha256Json(projection), + projection, + events: [], + rows: [], + redactions: [], + stop_conditions: [], + provider_evidence: providerEvidence(envelope), + }; +} + +function conflictResult(envelope, currentVersionValue, { idempotency_key, event_digest, reason, provider_evidence }) { + const stop = { + code: "conflict", + message: reason, + }; + return { + ...envelope, + status: "conflict", + before_version: currentVersionValue, + after_version: currentVersionValue, + idempotency_key, + event_ref: null, + event_digest, + result_digest: sha256Json(stop), + projection_digest: `sha256:${"0".repeat(64)}`, + events: [], + rows: [], + redactions: [], + stop_conditions: [stop], + provider_evidence, + }; +} + +function baseEnvelope(rawInputs, operation) { + return { + schema: SCHEMA, + data_source_ref: stringInput("data_source_ref"), + provider: PROVIDER, + operation, + resource: safeName(stringInput("resource"), "resource"), + aggregate_id: safeName(stringInput("aggregate_id"), "aggregate_id"), + }; +} + +function ensureSchema(database) { + fs.mkdirSync(path.dirname(database), { recursive: true }); + execSql(database, ` +PRAGMA journal_mode = WAL; +CREATE TABLE IF NOT EXISTS runx_events ( + data_source_ref TEXT NOT NULL DEFAULT '', + resource TEXT NOT NULL, + aggregate_id TEXT NOT NULL, + version INTEGER NOT NULL, + idempotency_key TEXT NOT NULL, + event_ref TEXT NOT NULL, + event_type TEXT NOT NULL, + event_digest TEXT NOT NULL, + event_json TEXT NOT NULL, + committed_at TEXT NOT NULL, + PRIMARY KEY (data_source_ref, resource, aggregate_id, version), + UNIQUE (data_source_ref, resource, aggregate_id, idempotency_key) +); +`); + migrateLegacySchema(database); + execSql(database, ` +CREATE UNIQUE INDEX IF NOT EXISTS runx_events_stream_version_v1 + ON runx_events (data_source_ref, resource, aggregate_id, version); +CREATE UNIQUE INDEX IF NOT EXISTS runx_events_stream_idempotency_v1 + ON runx_events (data_source_ref, resource, aggregate_id, idempotency_key); +`); +} + +function migrateLegacySchema(database) { + const columns = queryJson(database, "PRAGMA table_info(runx_events);").map((column) => column.name); + if (columns.includes("data_source_ref")) return; + + execSql(database, ` +BEGIN IMMEDIATE; +ALTER TABLE runx_events RENAME TO runx_events_legacy_unscoped; +CREATE TABLE runx_events ( + data_source_ref TEXT NOT NULL, + resource TEXT NOT NULL, + aggregate_id TEXT NOT NULL, + version INTEGER NOT NULL, + idempotency_key TEXT NOT NULL, + event_ref TEXT NOT NULL, + event_type TEXT NOT NULL, + event_digest TEXT NOT NULL, + event_json TEXT NOT NULL, + committed_at TEXT NOT NULL, + PRIMARY KEY (data_source_ref, resource, aggregate_id, version), + UNIQUE (data_source_ref, resource, aggregate_id, idempotency_key) +); +INSERT INTO runx_events ( + data_source_ref, + resource, + aggregate_id, + version, + idempotency_key, + event_ref, + event_type, + event_digest, + event_json, + committed_at +) +SELECT + '', + resource, + aggregate_id, + version, + idempotency_key, + event_ref, + event_type, + event_digest, + event_json, + committed_at +FROM runx_events_legacy_unscoped; +DROP TABLE runx_events_legacy_unscoped; +CREATE UNIQUE INDEX IF NOT EXISTS runx_events_stream_version_v1 + ON runx_events (data_source_ref, resource, aggregate_id, version); +CREATE UNIQUE INDEX IF NOT EXISTS runx_events_stream_idempotency_v1 + ON runx_events (data_source_ref, resource, aggregate_id, idempotency_key); +COMMIT; +`); +} + +function currentVersion(database, envelope) { + const rows = queryJson(database, ` +SELECT COALESCE(MAX(version), 0) AS version +FROM runx_events +WHERE data_source_ref = ${sqlString(envelope.data_source_ref)} + AND resource = ${sqlString(envelope.resource)} + AND aggregate_id = ${sqlString(envelope.aggregate_id)}; +`); + return Number(rows[0]?.version ?? 0); +} + +function existingEvent(database, envelope, idempotencyKey) { + const rows = queryJson(database, ` +SELECT event_ref, version, event_type, event_digest, idempotency_key, committed_at, event_json +FROM runx_events +WHERE data_source_ref = ${sqlString(envelope.data_source_ref)} + AND resource = ${sqlString(envelope.resource)} + AND aggregate_id = ${sqlString(envelope.aggregate_id)} + AND idempotency_key = ${sqlString(idempotencyKey)} +LIMIT 1; +`); + const row = rows[0]; + if (!row) return null; + return { + event_ref: row.event_ref, + version: Number(row.version), + event_type: row.event_type, + event: JSON.parse(row.event_json), + event_digest: row.event_digest, + idempotency_key: row.idempotency_key, + committed_at: row.committed_at, + }; +} + +function projectionDigest(database, envelope) { + const rows = queryJson(database, ` +SELECT version, event_digest +FROM runx_events +WHERE data_source_ref = ${sqlString(envelope.data_source_ref)} + AND resource = ${sqlString(envelope.resource)} + AND aggregate_id = ${sqlString(envelope.aggregate_id)} +ORDER BY version ASC; +`); + return sha256Json({ + version: rows.length, + event_digests: rows.map((entry) => entry.event_digest), + }); +} + +function providerEvidence(envelope) { + return { + provider: PROVIDER, + adapter: "data.sqlite", + data_source_ref_digest: sha256Json(envelope.data_source_ref), + resource: envelope.resource, + aggregate_id: envelope.aggregate_id, + storage_class: "sqlite", + }; +} + +function databasePath(rawInputs) { + const binding = rawInputs.data_source_binding && typeof rawInputs.data_source_binding === "object" && !Array.isArray(rawInputs.data_source_binding) + ? rawInputs.data_source_binding + : {}; + const rawPath = typeof binding.database_path === "string" && binding.database_path.trim().length > 0 + ? binding.database_path.trim() + : typeof rawInputs.database_path === "string" && rawInputs.database_path.trim().length > 0 + ? rawInputs.database_path.trim() + : null; + if (!rawPath) { + throw new Error("data.sqlite requires data_source_binding.database_path or database_path"); + } + const root = path.resolve(process.env.RUNX_CWD || process.env.INIT_CWD || process.cwd()); + const allowAbsolute = binding.allow_absolute_path === true || rawInputs.allow_absolute_path === true; + const resolved = path.isAbsolute(rawPath) ? path.resolve(rawPath) : path.resolve(root, rawPath); + if (path.isAbsolute(rawPath) && !allowAbsolute) { + throw new Error("data.sqlite absolute database_path requires allow_absolute_path=true in the operator-owned binding"); + } + if (!allowAbsolute && !isInside(root, resolved)) { + throw new Error("data.sqlite database_path must stay inside RUNX_CWD unless allow_absolute_path=true"); + } + return resolved; +} + +function execSql(database, sql) { + const result = spawnSync(SQLITE_BIN, [database], { + input: sql, + encoding: "utf8", + maxBuffer: 1024 * 1024, + }); + if (result.error) { + throw result.error; + } + if (result.status !== 0) { + throw new Error((result.stderr || result.stdout || `sqlite3 exited ${result.status}`).trim()); + } +} + +function queryJson(database, sql) { + const result = spawnSync(SQLITE_BIN, ["-json", database], { + input: sql, + encoding: "utf8", + maxBuffer: 1024 * 1024, + }); + if (result.error) { + throw result.error; + } + if (result.status !== 0) { + throw new Error((result.stderr || result.stdout || `sqlite3 exited ${result.status}`).trim()); + } + const text = result.stdout.trim(); + return text ? JSON.parse(text) : []; +} + +function sqlString(value) { + return `'${String(value).replaceAll("'", "''")}'`; +} + +function readValue(name) { + return inputs[name]; +} + +function stringInput(name) { + const value = readValue(name); + if (typeof value !== "string" || value.trim().length === 0) { + throw new Error(`${name} is required`); + } + return value.trim(); +} + +function numberInput(name) { + const value = readValue(name); + if (!Number.isInteger(value) || value < 0) { + throw new Error(`${name} must be a non-negative integer`); + } + return value; +} + +function objectInput(name) { + const value = readValue(name); + if (!value || typeof value !== "object" || Array.isArray(value)) { + throw new Error(`${name} must be an object`); + } + return value; +} + +function eventType(event) { + const explicit = safeEventToken(event.type) ?? safeEventToken(event.event_type); + if (explicit) return explicit; + const family = safeEventToken(event.effect_family); + const operation = safeEventToken(event.operation); + if (family && operation) return `${family}.${operation}`; + if (operation) return operation; + return "data.event"; +} + +function safeEventToken(value) { + if (typeof value !== "string") return undefined; + const text = value.trim(); + return /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(text) ? text : undefined; +} + +function boundedLimit(value) { + if (value === undefined || value === null) return 50; + if (!Number.isInteger(value) || value < 1 || value > 500) { + throw new Error("limit must be an integer from 1 to 500"); + } + return value; +} + +function safeName(value, field) { + const text = String(value || "").trim(); + const pattern = field === "aggregate_id" + ? /^[A-Za-z0-9][A-Za-z0-9._:@/-]{0,191}$/ + : /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/; + if (!pattern.test(text)) { + throw new Error(`${field} must be a safe identifier`); + } + return text; +} + +function sha256Json(value) { + return `sha256:${crypto.createHash("sha256").update(canonicalJson(value)).digest("hex")}`; +} + +function canonicalJson(value) { + if (value === null || typeof value !== "object") return JSON.stringify(value); + if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`; + return `{${Object.keys(value).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(",")}}`; +} + +function isInside(root, candidate) { + const relative = path.relative(root, candidate); + return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative)); +} diff --git a/skills/dependency-cve-audit/SKILL.md b/skills/dependency-cve-audit/SKILL.md index 1b2d634b6..4f9b43c36 100644 --- a/skills/dependency-cve-audit/SKILL.md +++ b/skills/dependency-cve-audit/SKILL.md @@ -67,9 +67,16 @@ contents of the supplied lockfile. ## Edge cases and stop conditions -Stop with an error when neither `package_lock_path` nor `package_lock_url` is -provided, when the lockfile cannot be read, when the URL is not HTTPS, when the -lockfile is not valid JSON, or when it does not contain a `packages` object. +Return `needs_input` when neither `package_lock_path` nor `package_lock_url` is +provided. Return `needs_more_evidence` when the target repository or immutable +reference is missing and the audit is intended for publication. Return +`refused` when the caller asks the skill to install packages, execute target +code, read private repository contents without an explicit grant, publish an +advisory, or mutate the target repository. + +Stop with an error when the lockfile cannot be read, when the URL is not HTTPS, +when the lockfile is not valid JSON, or when it does not contain a `packages` +object. For local paths and output paths, the resolved path must stay inside the skill directory. This prevents the runner from reading or writing unrelated workspace @@ -81,7 +88,7 @@ is missing from `packages`; do not invent versions from semver declarations. The output is evidence for dependency triage, not an authorization to publish a security advisory or mutate a repository. Any later issue filing, advisory -publication, or remediation PR needs its own gate. +publication, or remediation PR needs its own authority gate and receipt. ## Output schema diff --git a/skills/dependency-cve-audit/X.yaml b/skills/dependency-cve-audit/X.yaml index 5eb7d1cb5..42afc205c 100644 --- a/skills/dependency-cve-audit/X.yaml +++ b/skills/dependency-cve-audit/X.yaml @@ -4,7 +4,7 @@ version: "0.1.1" catalog: kind: skill audience: public - visibility: internal + visibility: public role: canonical runx: @@ -34,21 +34,6 @@ runx: - report_md wrap_as: dependency_cve_audit_packet -harness: - cases: - - name: nodegoat-direct-production - runner: default - inputs: - target_name: OWASP NodeGoat - target_repo: https://github.com/OWASP/NodeGoat - target_ref: c5cb68a7084e4ae7dcc60e6a98768720a81841e8 - package_lock_url: https://raw.githubusercontent.com/OWASP/NodeGoat/c5cb68a7084e4ae7dcc60e6a98768720a81841e8/package-lock.json - scan_scope: direct - include_dev: false - output_dir: artifacts/nodegoat - expect: - status: sealed - runners: default: default: true diff --git a/skills/dependency-cve-audit/fixtures/nodegoat-direct-production.yaml b/skills/dependency-cve-audit/fixtures/nodegoat-direct-production.yaml new file mode 100644 index 000000000..7177018b8 --- /dev/null +++ b/skills/dependency-cve-audit/fixtures/nodegoat-direct-production.yaml @@ -0,0 +1,19 @@ +name: nodegoat-direct-production +kind: skill +target: .. +runner: default +inputs: + target_name: OWASP NodeGoat + target_repo: https://github.com/OWASP/NodeGoat + target_ref: c5cb68a7084e4ae7dcc60e6a98768720a81841e8 + package_lock_url: https://raw.githubusercontent.com/OWASP/NodeGoat/c5cb68a7084e4ae7dcc60e6a98768720a81841e8/package-lock.json + scan_scope: direct + include_dev: false +expect: + status: sealed + receipt: + schema: runx.receipt.v1 +metadata: + public_skill: dependency-cve-audit + source_case: nodegoat-direct-production + source: skills-fixture diff --git a/skills/github-sync/SKILL.md b/skills/github-sync/SKILL.md index 36dbbad22..a9dc1beb5 100644 --- a/skills/github-sync/SKILL.md +++ b/skills/github-sync/SKILL.md @@ -36,6 +36,11 @@ plan is the artifact a downstream adapter executes after the approval gate clears. Planning and mutation stay on opposite sides of the gate so a review can read intent before anything changes on the remote. +When a sync loop needs a durable cursor, use `plan_and_append_cursor`. That +runner reads the cursor projection through `data-store`, plans the bounded sync, +appends the plan as a cursor event, and reads back the projection. The storage +provider is selected by `data_source_ref`, not by GitHub-specific code. + ## When to use this skill - An agent needs to fetch a bounded set of issues, threads, or PRs into the @@ -79,6 +84,9 @@ one comment. 7. Record `scope_used` as the narrowest scope the plan actually needs. 8. Emit the smallest `sync_plan` an adapter can execute without widening authority, and stop at the approval gate for any write. +9. For cursor-backed loops, read the cursor projection first, append one sync + plan event with an idempotency key and expected version, and read back the + projection before the next turn. ## Edge cases and stop conditions @@ -138,6 +146,15 @@ No write grant is exercised and no approval gate is opened, because a pull is pure observation. Had the same request asked to `push` labels without a `repo:write` grant, the run would refuse instead of reading. +Cursor-backed loop: + +```text +read cursor -> plan bounded pull/push -> append sync plan event -> read cursor +``` + +The cursor event stores refs, filters, digests, and gate status. It does not +store raw issue bodies, OAuth tokens, or write payload secrets. + ## Inputs - `repo` (required): target repository as `owner/name`. diff --git a/skills/github-sync/X.yaml b/skills/github-sync/X.yaml index a270db39f..0a845ea6a 100644 --- a/skills/github-sync/X.yaml +++ b/skills/github-sync/X.yaml @@ -1,5 +1,5 @@ skill: github-sync -version: "0.1.1" +version: "0.1.2" catalog: kind: skill @@ -40,3 +40,84 @@ runners: type: string required: true description: "read or write. A push needs write backed by a repo:write grant." + + plan_and_append_cursor: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Logical data source used to persist sync cursor events. + resource: + type: string + required: true + description: Declared event resource for GitHub sync cursor events. + aggregate_id: + type: string + required: true + description: Cursor stream key, usually owner/repo or owner/repo:selector. + expected_version: + type: number + required: true + description: Current cursor stream version required before append. + idempotency_key: + type: string + required: true + description: Stable retry key for this sync plan. + repo: + type: string + required: true + description: "Target repository as owner/name." + direction: + type: string + required: true + description: "Sync direction: pull (read-only) or push (mutation)." + resources: + type: json + required: true + description: "Selector for issues, prs, or threads plus filters (state, label, author, range, refs)." + scope: + type: string + required: true + description: "read or write. A push needs write backed by a repo:write grant." + graph: + name: github-sync-plan-and-append-cursor + steps: + - id: read-cursor + skill: ../data-store + runner: read_projection + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + - id: plan + skill: . + runner: github-sync + inputs: + repo: "$input.repo" + direction: "$input.direction" + resources: "$input.resources" + scope: "$input.scope" + context: + cursor_projection: read-cursor.step_outputs.read.data_operation_result.data.projection + artifacts: + wrap_as: sync_plan_packet + packet: runx.github_sync.v1 + - id: append-cursor-event + skill: ../data-store + runner: append_event + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + expected_version: "$input.expected_version" + idempotency_key: "$input.idempotency_key" + context: + event: plan.sync_plan_packet.data + - id: readback + skill: ../data-store + runner: read_projection + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" diff --git a/skills/github-sync/fixtures/plan-and-append-cursor-sqlite.yaml b/skills/github-sync/fixtures/plan-and-append-cursor-sqlite.yaml new file mode 100644 index 000000000..459e3872c --- /dev/null +++ b/skills/github-sync/fixtures/plan-and-append-cursor-sqlite.yaml @@ -0,0 +1,53 @@ +name: github-sync-plan-and-append-cursor-sqlite +kind: skill +target: .. +runner: plan_and_append_cursor +env: + RUNX_DATA_SOURCES: '{"data_sources":{"tenant://github-sync/sqlite-cursors":{"adapter":"data.sqlite","database_path":".runx/data/github-sync-cursors.sqlite","resources":{"github_sync_events":{"kind":"event_stream","partition_key":"aggregate_id"}}}}}' +inputs: + data_source_ref: tenant://github-sync/sqlite-cursors + resource: github_sync_events + aggregate_id: runxhq/runx:triage-open + expected_version: 0 + idempotency_key: runxhq/runx:triage-open:pull:v1 + repo: runxhq/runx + direction: pull + resources: + kind: issues + filters: + state: open + label: triage + limit: 25 + scope: read +caller: + answers: + agent_task.github-sync.output: + sync_plan: + decision: ready + repo: runxhq/runx + direction: pull + resources_touched: + - kind: issue + ref: issue:triage-filter + selected_by: state:open label:triage limit:25 + diff_summary: [] + scope_used: repo:read + gates: + approval_required: false + approval_ref: null + blockers: [] +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - read-cursor + - plan + - append-cursor-event + - readback +metadata: + public_skill: github-sync + source_case: plan-and-append-cursor-sqlite + source: skills-fixture + runner_kind: graph + graph_shape: sync_cursor diff --git a/skills/issue-to-pr/graph/scafld/fixtures/issue-to-pr-harness-scafld.mjs b/skills/issue-to-pr/graph/scafld/fixtures/issue-to-pr-harness-scafld.mjs index 724c60020..1145b9428 100755 --- a/skills/issue-to-pr/graph/scafld/fixtures/issue-to-pr-harness-scafld.mjs +++ b/skills/issue-to-pr/graph/scafld/fixtures/issue-to-pr-harness-scafld.mjs @@ -8,6 +8,11 @@ const taskId = argv[1] || ""; const cwd = process.cwd(); const specPath = path.join(cwd, ".scafld", "specs", "drafts", `${taskId}.md`); +if (command === "--version" || command === "version") { + process.stdout.write("scafld 2.4.0\n"); + process.exit(0); +} + switch (command) { case "init": mkdirSync(path.join(cwd, ".scafld", "specs", "drafts"), { recursive: true }); diff --git a/skills/issue-to-pr/graph/scafld/fixtures/scafld-v2-harness.mjs b/skills/issue-to-pr/graph/scafld/fixtures/scafld-v2-harness.mjs index 2e4a930d6..51714349c 100755 --- a/skills/issue-to-pr/graph/scafld/fixtures/scafld-v2-harness.mjs +++ b/skills/issue-to-pr/graph/scafld/fixtures/scafld-v2-harness.mjs @@ -8,6 +8,11 @@ const taskId = argv[1] || ""; const cwd = process.cwd(); const draftPath = path.join(cwd, ".scafld", "specs", "drafts", `${taskId}.md`); +if (command === "--version" || command === "version") { + process.stdout.write("scafld 2.4.0\n"); + process.exit(0); +} + switch (command) { case "plan": requireTask(); diff --git a/skills/messageboard/SKILL.md b/skills/messageboard/SKILL.md index ef6d8bc3f..d5790d815 100644 --- a/skills/messageboard/SKILL.md +++ b/skills/messageboard/SKILL.md @@ -15,8 +15,10 @@ messageboard ledger transition or a denial. Use this skill as the agent-facing context for board work. Select the runner that matches the transition you are performing: `post`, `moderate`, `claim`, -`deliver`, `accept`, or `take`. Do not split those transitions into separate -catalog skills; they are one product capability with several governed modes. +`deliver`, `accept`, or `take`. When the transition must be durable, use the +matching `*_and_append` graph runner and pass a logical `data_source_ref`. +Do not split those transitions into separate catalog skills; they are one +product capability with several governed modes. ## What this skill does @@ -29,6 +31,8 @@ catalog skills; they are one product capability with several governed modes. - Authorizes payout ledger rows only after accepted delivery. - Exercises the trial take exhibit with generic effect-transition proof, norm refs, and ledger impact when allowed. +- Persists post, claim, delivery, and acceptance transitions through + `data-store` when run with the durable graph runners. ## When to use this skill @@ -65,6 +69,11 @@ catalog skills; they are one product capability with several governed modes. clocks, acceptance criteria, or artifacts are unclear. 6. Return the transition packet named by the runner. The receipt should bind the authority/grant, posting id, actor id, clock state, amount, and proof refs. +7. For durable board state, call the matching `*_and_append` runner. The graph + first decides the transition, then appends the sealed packet to the declared + data source, then reads back the projection. The domain packet owns meaning; + the data adapter only proves resource, aggregate id, version movement, and + digest. ## Edge cases and stop conditions @@ -102,6 +111,22 @@ folds; runx seals the generic transition envelope with the relevant grant/scope, prior receipt refs, and ledger impact when a transition changes value or visibility. +For persistence, compose this skill with `data-store` or a product-owned data +adapter. Do not add messageboard-specific database semantics to runx core. + +Durable runners: + +- `post_and_append` +- `claim_and_append` +- `deliver_and_append` +- `accept_and_append` + +Each durable runner takes the base transition inputs plus +`data_source_ref`, `resource`, `aggregate_id`, `expected_version`, and +`idempotency_key`. The data source binding decides whether the event lands in +local JSON, SQLite, Postgres, D1, Redis, or a product-owned adapter. The +messageboard graph does not branch on provider type. + ## Worked example A vendor posts `Verify receipt link` with a mock funded hold. The `post` runner diff --git a/skills/messageboard/X.yaml b/skills/messageboard/X.yaml index bd4e41504..bc33b7658 100644 --- a/skills/messageboard/X.yaml +++ b/skills/messageboard/X.yaml @@ -1,5 +1,5 @@ skill: messageboard -version: "0.1.0" +version: "0.2.0" catalog: kind: skill audience: public @@ -212,3 +212,291 @@ runners: type: string required: true description: Receipt reference for the sealed/denied take. + + post_and_append: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Logical data source used to persist the transition. + resource: + type: string + required: true + description: Declared event resource for messageboard transitions. + aggregate_id: + type: string + required: true + description: Posting stream key. + expected_version: + type: number + required: true + description: Current stream version required before append. + idempotency_key: + type: string + required: true + description: Stable retry key for this posting transition. + actor_kid: + type: string + required: true + description: Registered kid placing the bounty. + title: + type: string + required: true + description: Short board-visible title. + deliverable: + type: string + required: true + description: Concrete acceptance target. + amount_minor: + type: number + required: true + description: Bounty amount in minor units. + currency: + type: string + required: true + description: Currency code. + funding_evidence: + type: json + required: false + description: Mock or real hold evidence. + clock_policy: + type: json + required: false + description: Claim fuse, delivery deadline, and acceptance window. + graph: + name: messageboard-post-and-append + steps: + - id: decide + skill: . + runner: post + inputs: + actor_kid: "$input.actor_kid" + title: "$input.title" + deliverable: "$input.deliverable" + amount_minor: "$input.amount_minor" + currency: "$input.currency" + funding_evidence: "$input.funding_evidence" + clock_policy: "$input.clock_policy" + artifacts: + wrap_as: messageboard_post_packet + packet: runx.effect.transition.v1 + - id: persist + skill: ../data-store + runner: append_event + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + expected_version: "$input.expected_version" + idempotency_key: "$input.idempotency_key" + context: + event: decide.messageboard_post_packet.data + - id: readback + skill: ../data-store + runner: read_projection + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + + claim_and_append: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Logical data source used to persist the transition. + resource: + type: string + required: true + description: Declared event resource for messageboard transitions. + aggregate_id: + type: string + required: true + description: Posting stream key. + expected_version: + type: number + required: true + description: Current stream version required before append. + idempotency_key: + type: string + required: true + description: Stable retry key for this claim transition. + actor_kid: + type: string + required: true + description: Registered claimant kid. + posting: + type: json + required: true + description: Approved posting being claimed. + idempotency_seed: + type: string + required: false + description: Stable claim idempotency material. + graph: + name: messageboard-claim-and-append + steps: + - id: decide + skill: . + runner: claim + inputs: + actor_kid: "$input.actor_kid" + posting: "$input.posting" + idempotency_seed: "$input.idempotency_seed" + artifacts: + wrap_as: messageboard_claim_packet + packet: runx.effect.transition.v1 + - id: persist + skill: ../data-store + runner: append_event + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + expected_version: "$input.expected_version" + idempotency_key: "$input.idempotency_key" + context: + event: decide.messageboard_claim_packet.data + - id: readback + skill: ../data-store + runner: read_projection + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + + deliver_and_append: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Logical data source used to persist the transition. + resource: + type: string + required: true + description: Declared event resource for messageboard transitions. + aggregate_id: + type: string + required: true + description: Posting stream key. + expected_version: + type: number + required: true + description: Current stream version required before append. + idempotency_key: + type: string + required: true + description: Stable retry key for this delivery transition. + actor_kid: + type: string + required: true + description: Claim owner submitting delivery. + claim: + type: json + required: true + description: Active board claim. + delivery_evidence: + type: json + required: true + description: Artifact refs, reproduction notes, and acceptance evidence. + graph: + name: messageboard-deliver-and-append + steps: + - id: decide + skill: . + runner: deliver + inputs: + actor_kid: "$input.actor_kid" + claim: "$input.claim" + delivery_evidence: "$input.delivery_evidence" + artifacts: + wrap_as: messageboard_delivery_packet + packet: runx.effect.transition.v1 + - id: persist + skill: ../data-store + runner: append_event + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + expected_version: "$input.expected_version" + idempotency_key: "$input.idempotency_key" + context: + event: decide.messageboard_delivery_packet.data + - id: readback + skill: ../data-store + runner: read_projection + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + + accept_and_append: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Logical data source used to persist the transition. + resource: + type: string + required: true + description: Declared event resource for messageboard transitions. + aggregate_id: + type: string + required: true + description: Posting stream key. + expected_version: + type: number + required: true + description: Current stream version required before append. + idempotency_key: + type: string + required: true + description: Stable retry key for this acceptance transition. + actor_kid: + type: string + required: true + description: Posting actor or authorized moderator accepting delivery. + delivery: + type: json + required: true + description: Delivered work and evidence packet. + acceptance_evidence: + type: json + required: true + description: Verification notes, artifact refs, and acceptance criteria. + graph: + name: messageboard-accept-and-append + steps: + - id: decide + skill: . + runner: accept + inputs: + actor_kid: "$input.actor_kid" + delivery: "$input.delivery" + acceptance_evidence: "$input.acceptance_evidence" + artifacts: + wrap_as: messageboard_acceptance_packet + packet: runx.effect.transition.v1 + - id: persist + skill: ../data-store + runner: append_event + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + expected_version: "$input.expected_version" + idempotency_key: "$input.idempotency_key" + context: + event: decide.messageboard_acceptance_packet.data + - id: readback + skill: ../data-store + runner: read_projection + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" diff --git a/skills/messageboard/fixtures/accept-and-append-sqlite.yaml b/skills/messageboard/fixtures/accept-and-append-sqlite.yaml new file mode 100644 index 000000000..3642f103f --- /dev/null +++ b/skills/messageboard/fixtures/accept-and-append-sqlite.yaml @@ -0,0 +1,48 @@ +name: accept-and-append-sqlite +kind: skill +target: .. +runner: accept_and_append +env: + RUNX_DATA_SOURCES: '{"data_sources":{"tenant://messageboard/sqlite-accept":{"adapter":"data.sqlite","database_path":".runx/data/messageboard-accept.sqlite","resources":{"board_events":{"kind":"event_stream","partition_key":"aggregate_id"}}}}}' +inputs: + data_source_ref: tenant://messageboard/sqlite-accept + resource: board_events + aggregate_id: post_sqlite_4 + expected_version: 0 + idempotency_key: post_sqlite_4:accept:vendor:v1 + actor_kid: vendor + delivery: + posting_id: post_sqlite_4 + claimant_kid: worker + delivery_ref: delivery:post_sqlite_4 + artifact_ref: git:commit:abc123 + acceptance_evidence: + verifier_result: passed +caller: + answers: + agent_task.messageboard-accept.output: + actor_kid: vendor + posting_id: post_sqlite_4 + acceptance: + accepted: true + acceptance_ref: acceptance:post_sqlite_4 + payout_authorization: + debit: board:escrow + credit: kid:worker + amount_minor: 5000 + currency: USD + stop_conditions: [] +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - decide + - persist + - readback +metadata: + public_skill: messageboard + source_case: accept-and-append-sqlite + source: skills-fixture + runner_kind: graph + graph_shape: durable_accept diff --git a/skills/messageboard/fixtures/claim-and-append-conflict.yaml b/skills/messageboard/fixtures/claim-and-append-conflict.yaml new file mode 100644 index 000000000..43b9fabf5 --- /dev/null +++ b/skills/messageboard/fixtures/claim-and-append-conflict.yaml @@ -0,0 +1,45 @@ +name: claim-and-append-conflict +kind: skill +target: .. +runner: claim_and_append +env: + RUNX_DATA_SOURCES: '{"data_sources":{"tenant://messageboard/sqlite-conflict":{"adapter":"data.sqlite","database_path":".runx/data/messageboard-conflict.sqlite","resources":{"board_events":{"kind":"event_stream","partition_key":"aggregate_id"}}}}}' +inputs: + data_source_ref: tenant://messageboard/sqlite-conflict + resource: board_events + aggregate_id: post_sqlite_conflict + expected_version: 1 + idempotency_key: post_sqlite_conflict:claim:worker:v1 + actor_kid: worker + posting: + id: post_sqlite_conflict + status: approved + title: Verify receipt link + amount_minor: 5000 + currency: USD + idempotency_seed: worker-post-sqlite-conflict +caller: + answers: + agent_task.messageboard-claim.output: + actor_kid: worker + posting_id: post_sqlite_conflict + claim: + status: active + idempotency_key: messageboard-claim:worker-post-sqlite-conflict + claim_fuse_at: 2026-06-12T00:30:00Z + delivery_due_at: 2026-06-13T00:00:00Z + stop_conditions: [] +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - decide + - persist + - readback +metadata: + public_skill: messageboard + source_case: claim-and-append-conflict + source: skills-fixture + runner_kind: graph + graph_shape: durable_claim_conflict diff --git a/skills/messageboard/fixtures/claim-and-append-sqlite.yaml b/skills/messageboard/fixtures/claim-and-append-sqlite.yaml new file mode 100644 index 000000000..155b97851 --- /dev/null +++ b/skills/messageboard/fixtures/claim-and-append-sqlite.yaml @@ -0,0 +1,45 @@ +name: claim-and-append-sqlite +kind: skill +target: .. +runner: claim_and_append +env: + RUNX_DATA_SOURCES: '{"data_sources":{"tenant://messageboard/sqlite-claim":{"adapter":"data.sqlite","database_path":".runx/data/messageboard-claim.sqlite","resources":{"board_events":{"kind":"event_stream","partition_key":"aggregate_id"}}}}}' +inputs: + data_source_ref: tenant://messageboard/sqlite-claim + resource: board_events + aggregate_id: post_sqlite_2 + expected_version: 0 + idempotency_key: post_sqlite_2:claim:worker:v1 + actor_kid: worker + posting: + id: post_sqlite_2 + status: approved + title: Verify receipt link + amount_minor: 5000 + currency: USD + idempotency_seed: worker-post-sqlite-2 +caller: + answers: + agent_task.messageboard-claim.output: + actor_kid: worker + posting_id: post_sqlite_2 + claim: + status: active + idempotency_key: messageboard-claim:worker-post-sqlite-2 + claim_fuse_at: 2026-06-12T00:30:00Z + delivery_due_at: 2026-06-13T00:00:00Z + stop_conditions: [] +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - decide + - persist + - readback +metadata: + public_skill: messageboard + source_case: claim-and-append-sqlite + source: skills-fixture + runner_kind: graph + graph_shape: durable_claim diff --git a/skills/messageboard/fixtures/deliver-and-append-sqlite.yaml b/skills/messageboard/fixtures/deliver-and-append-sqlite.yaml new file mode 100644 index 000000000..8a9ae51e9 --- /dev/null +++ b/skills/messageboard/fixtures/deliver-and-append-sqlite.yaml @@ -0,0 +1,47 @@ +name: deliver-and-append-sqlite +kind: skill +target: .. +runner: deliver_and_append +env: + RUNX_DATA_SOURCES: '{"data_sources":{"tenant://messageboard/sqlite-deliver":{"adapter":"data.sqlite","database_path":".runx/data/messageboard-deliver.sqlite","resources":{"board_events":{"kind":"event_stream","partition_key":"aggregate_id"}}}}}' +inputs: + data_source_ref: tenant://messageboard/sqlite-deliver + resource: board_events + aggregate_id: post_sqlite_3 + expected_version: 0 + idempotency_key: post_sqlite_3:deliver:worker:v1 + actor_kid: worker + claim: + posting_id: post_sqlite_3 + claimant_kid: worker + status: active + delivery_due_at: 2026-06-13T00:00:00Z + delivery_evidence: + artifact_ref: git:commit:abc123 + verifier_command: ./verify.sh +caller: + answers: + agent_task.messageboard-deliver.output: + actor_kid: worker + posting_id: post_sqlite_3 + delivery: + delivery_ref: delivery:post_sqlite_3 + artifact_ref: git:commit:abc123 + verifier_command: ./verify.sh + acceptance_window: + acceptance_due_at: 2026-06-13T12:00:00Z + stop_conditions: [] +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - decide + - persist + - readback +metadata: + public_skill: messageboard + source_case: deliver-and-append-sqlite + source: skills-fixture + runner_kind: graph + graph_shape: durable_deliver diff --git a/skills/messageboard/fixtures/post-and-append-sqlite.yaml b/skills/messageboard/fixtures/post-and-append-sqlite.yaml new file mode 100644 index 000000000..9ff41359d --- /dev/null +++ b/skills/messageboard/fixtures/post-and-append-sqlite.yaml @@ -0,0 +1,58 @@ +name: post-and-append-sqlite +kind: skill +target: .. +runner: post_and_append +env: + RUNX_DATA_SOURCES: '{"data_sources":{"tenant://messageboard/sqlite-post":{"adapter":"data.sqlite","database_path":".runx/data/messageboard-post.sqlite","resources":{"board_events":{"kind":"event_stream","partition_key":"aggregate_id"}}}}}' +inputs: + data_source_ref: tenant://messageboard/sqlite-post + resource: board_events + aggregate_id: post_sqlite_1 + expected_version: 0 + idempotency_key: post_sqlite_1:post:v1 + actor_kid: vendor + title: Verify receipt link + deliverable: Run the published verifier from a clean checkout and report the result. + amount_minor: 5000 + currency: USD + funding_evidence: + hold_ref: mock:hold:post-sqlite-1 + clock_policy: + claim_fuse_ms: 1800000 + delivery_deadline_ms: 86400000 + acceptance_window_ms: 43200000 +caller: + answers: + agent_task.messageboard-post.output: + actor_kid: vendor + posting: + id: post_sqlite_1 + title: Verify receipt link + deliverable: Run the published verifier from a clean checkout and report the result. + amount_minor: 5000 + currency: USD + status: screening + funding: + funded_badge: true + evidence_ref: mock:hold:post-sqlite-1 + clocks: + claim_fuse_ms: 1800000 + delivery_deadline_ms: 86400000 + acceptance_window_ms: 43200000 + screening_notes: + - Verify funding hold before approval. + stop_conditions: [] +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - decide + - persist + - readback +metadata: + public_skill: messageboard + source_case: post-and-append-sqlite + source: skills-fixture + runner_kind: graph + graph_shape: durable_post diff --git a/skills/ops-desk/SKILL.md b/skills/ops-desk/SKILL.md index 7e4060292..19a7e9c10 100644 --- a/skills/ops-desk/SKILL.md +++ b/skills/ops-desk/SKILL.md @@ -39,6 +39,12 @@ The model may diagnose and write the operator rationale. The mutation itself must be a deterministic handoff to an existing skill runner, CLI command, hosted API route, workflow, or provider tool. +When the desk should start from durable state, use `operate_from_projection`. +That runner reads a projection through `data-store` first, then passes the +projection as the dashboard snapshot. The storage provider is still selected by +the logical `data_source_ref`; ops desk does not know whether state came from +SQLite, Postgres, D1, Redis, or a product API. + ## When to use this skill - An operator asks an agent to manage a project, workspace, product, account, @@ -112,6 +118,9 @@ product gap. Do not invent a private workaround. whether the artifact is real, useful, complete, and valuable. A reachable artifact with no credible user, maintainer, operator, public proof, or marketing value is not ready. + - If using `operate_from_projection`, treat the read projection as the + dashboard snapshot. An empty projection is not an error, but it should + usually produce `needs_input` rather than fake readiness. 3. Route to governed lanes. - Release questions route to `release` plus the project release profile and diff --git a/skills/ops-desk/X.yaml b/skills/ops-desk/X.yaml index 456a40be5..27bf8e7df 100644 --- a/skills/ops-desk/X.yaml +++ b/skills/ops-desk/X.yaml @@ -1,5 +1,5 @@ skill: ops-desk -version: "0.1.2" +version: "0.1.3" catalog: kind: skill @@ -125,3 +125,78 @@ runners: type: string required: false description: Project topology and expected execution surfaces. + + operate_from_projection: + type: graph + inputs: + data_source_ref: + type: string + required: true + description: Logical data source that stores the operating projection. + resource: + type: string + required: true + description: Declared projection or event resource. + aggregate_id: + type: string + required: true + description: Operating scope partition to read before planning. + objective: + type: string + required: true + description: The bounded operator objective. + scope_ref: + type: string + required: true + description: Project, workspace, account, product, or bounded operating surface being operated. + receipt_summary: + type: json + required: false + description: Receipt and effect evidence available to the run. + provider_status: + type: json + required: false + description: Provider health, account, webhook, credential, or deploy state. + approval_context: + type: json + required: false + description: Existing approvals, denials, or policy gates. + operator_policy: + type: string + required: false + description: Tenant-specific guardrails and lane names. + project_profile: + type: string + required: false + description: Project topology, existing commands/workflows, and verification expectations. Context only, not authority. + requested_action: + type: string + required: false + description: Optional action id or lane selected by the dashboard. + graph: + name: ops-desk-operate-from-projection + steps: + - id: read-state + skill: ../data-store + runner: read_projection + inputs: + data_source_ref: "$input.data_source_ref" + resource: "$input.resource" + aggregate_id: "$input.aggregate_id" + - id: operate + skill: . + runner: operate + inputs: + objective: "$input.objective" + scope_ref: "$input.scope_ref" + receipt_summary: "$input.receipt_summary" + provider_status: "$input.provider_status" + approval_context: "$input.approval_context" + operator_policy: "$input.operator_policy" + project_profile: "$input.project_profile" + requested_action: "$input.requested_action" + context: + dashboard_snapshot: read-state.step_outputs.read.data_operation_result.data.projection + artifacts: + wrap_as: ops_desk_packet + packet: runx.ops_desk.packet.v1 diff --git a/skills/ops-desk/fixtures/operate-from-sqlite-projection.yaml b/skills/ops-desk/fixtures/operate-from-sqlite-projection.yaml new file mode 100644 index 000000000..f81b5f1e6 --- /dev/null +++ b/skills/ops-desk/fixtures/operate-from-sqlite-projection.yaml @@ -0,0 +1,63 @@ +name: ops-desk-operate-from-sqlite-projection +kind: skill +target: .. +runner: operate_from_projection +env: + RUNX_DATA_SOURCES: '{"data_sources":{"tenant://ops-desk/sqlite-state":{"adapter":"data.sqlite","database_path":".runx/data/ops-desk-state.sqlite","resources":{"ops_projection":{"kind":"event_stream","partition_key":"aggregate_id"}}}}}' +inputs: + data_source_ref: tenant://ops-desk/sqlite-state + resource: ops_projection + aggregate_id: workspace-example + objective: Check the workspace and tell me the next safe action. + scope_ref: workspace:example + receipt_summary: + receipts: [] + provider_status: + runx_api: ok + approval_context: + approvals: [] + operator_policy: Route live sends through send-as and money movement through spend or refund. +caller: + answers: + agent_task.ops-desk.output: + ops_desk_packet: + decision: needs_input + scope_ref: workspace:example + objective: Check the workspace and tell me the next safe action. + mode: read_only + dashboard: + health: unknown + money: unknown + communications: unknown + providers: ok + receipts: unknown + findings: + - severity: warning + area: receipts + summary: The projection is empty, so there is no receipt-backed operating state yet. + evidence_refs: + - data-store.read_projection + proposals: [] + ordered_next_steps: + - step: Append a governed state event or provide a receipt summary before proposing live actions. + lane: data-store + requires_confirmation: false + refused_reasons: [] + needs_input: + - receipt-backed operating state + success_checkpoint: + milestone: state loaded + description: A projection read was attempted before operator planning. +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + steps: + - read-state + - operate +metadata: + public_skill: ops-desk + source_case: operate-from-sqlite-projection + source: skills-fixture + runner_kind: graph + graph_shape: operate_from_projection diff --git a/skills/structured-extraction/README.md b/skills/structured-extraction/README.md deleted file mode 100644 index 8e6dc7c9d..000000000 --- a/skills/structured-extraction/README.md +++ /dev/null @@ -1,21 +0,0 @@ -# Structured Extraction Skill - -This skill extracts schema-validated JSON from messy HTML or text fixtures. The -default harness uses the real RFC 9110 HTML document as a deterministic input. - -It emits `runx.structured_extraction.result.v1` and includes artifact -references for: - -- input fixture SHA-256 -- JSON Schema SHA-256 -- validated output payload SHA-256 - -Reproduce: - -```powershell -runx harness . --receipt-dir .\receipts --json -``` - -The Frantic #22 delivery evidence was generated from -`fixtures/rfc9110-http-semantics.html` with source URL -`https://www.rfc-editor.org/rfc/rfc9110.html`. diff --git a/skills/structured-extraction/SKILL.md b/skills/structured-extraction/SKILL.md index b2dc81b51..5b3d19875 100644 --- a/skills/structured-extraction/SKILL.md +++ b/skills/structured-extraction/SKILL.md @@ -13,22 +13,148 @@ runx: - provenance --- -# Structured Extraction +## What this skill does -Use this skill to turn messy HTML or text into schema-validated JSON with -reproducible input and output digests. +Extract structured JSON from a bounded HTML or plain-text source inside the +skill package, validate the result against a declared JSON Schema, and emit a +digest-bound provenance packet. The runner is deterministic: it reads local +fixture bytes, extracts headings, useful paragraphs, and HTTP/API terms, checks +the packet against `schemas/extraction.schema.json`, and returns +`runx.structured_extraction.result.v1`. -The default harness extracts a compact API-reference summary from the RFC 9110 -HTML document. It records the source URL, fixture byte count, input digest, -schema digest, extracted items, validation status, and artifact ids that the -runx receipt can bind as references. +This is not a scraper or crawler. Network fetch belongs in a separate governed +web-fetch step. This skill starts after the bytes are already available as an +approved package fixture, so the runx receipt can bind the input digest, schema +digest, and validated output digest without depending on a live website. -Inputs: +## When to use this skill + +Use this skill when an agent needs a reproducible extraction packet from messy +reference material, docs snapshots, benchmark fixtures, or captured public web +content. It is appropriate when the source bytes have already been fetched, +approved for local use, and pinned inside the skill package. + +Use it as the extraction stage in a larger chain: fetch or curate bytes first, +run structured extraction second, then pass the validated packet to a downstream +agent, reviewer, search index, or evidence bundle. + +## When not to use this skill + +Do not use this skill to fetch URLs, bypass network policy, process private +customer data, parse credentials, or summarize a source without a schema. Do +not use it when the desired output is free-form prose; this runner exists to +produce typed, schema-checked JSON. + +If the source bytes are not already present, stop with `needs_input` and use a +web-fetch or repository-read skill with its own authority grant and receipt. If +the schema is missing or unknown, stop with `needs_more_evidence` instead of +inventing a packet shape. + +## Procedure + +1. Resolve `input_path` and `schema_path` relative to the skill package. +2. Reject any path that escapes the package root. +3. Read the source bytes and JSON Schema bytes. +4. Record SHA-256 digests for both inputs. +5. Extract a bounded set of headings, paragraphs, and HTTP/API terms. +6. Build `runx.structured_extraction.result.v1`. +7. Validate the packet against the schema and deterministic internal checks. +8. Return the packet only when validation passes; otherwise fail closed. + +## Edge cases and stop conditions + +Return `needs_input` when `source_url`, `input_path`, or `schema_path` is +missing. Return `needs_more_evidence` when the source URL does not identify the +origin of the fixture bytes. Return `refused` if the caller asks the skill to +fetch live network content, read outside the package root, process secrets, or +extract private user data. + +Fail the run if the input file or schema file cannot be read, the schema is not +valid JSON, the content type is unsupported, the extracted packet has too few +items to be useful, or JSON Schema validation fails. Do not emit a partial +success packet. + +The authority scope is local fixture read plus local schema read. The proof +surface is the sealed receipt containing input digest, schema digest, output +digest, validation checks, and source URL. + +## Output schema + +The runner emits `structured_extraction_result` with packet schema +`runx.structured_extraction.result.v1`: + +```json +{ + "schema": "runx.structured_extraction.result.v1", + "source": { + "url": "https://example.test/source.html", + "content_type": "text/html", + "input_path": "fixtures/source.html", + "input_sha256": "sha256:", + "input_bytes": 0 + }, + "extraction": { + "title": "Document title", + "summary": { + "item_count": 0, + "heading_count": 0, + "term_count": 0, + "paragraph_count": 0, + "text_chars": 0 + }, + "items": [] + }, + "validation": { + "schema_id": "runx.structured_extraction.result.v1", + "schema_sha256": "sha256:", + "valid": true, + "engine": "native-json-schema-subset-v1", + "checks": [] + }, + "provenance": { + "mode": "fixture", + "tool_version": "0.1.0", + "source_kind": "real_public_document", + "output_payload_sha256": "sha256:" + } +} +``` + +The packet also includes artifact and signal records that let a downstream +receipt reference the input fixture, schema, and validated output. + +## Worked example + +Extract a compact evidence packet from the packaged RFC 9110 fixture: + +```bash +runx skill "$PWD" \ + --runner extract \ + --input input_path=fixtures/rfc9110-http-semantics.html \ + --input schema_path=schemas/extraction.schema.json \ + --input source_url=https://www.rfc-editor.org/rfc/rfc9110.html \ + --input content_type=text/html \ + --input max_items=18 \ + --json +``` + +Expected behavior: + +- The run stays local and does not fetch the RFC URL. +- `source.input_sha256` identifies the exact fixture bytes. +- `validation.valid` is true only if the packet satisfies the schema and + internal extraction checks. +- The sealed receipt links the source digest, schema digest, and output digest. + +## Inputs - `input_path`: package-relative path to an HTML or text fixture. - `schema_path`: package-relative JSON Schema path. -- `source_url`: canonical public source URL for the fixture. -- `content_type`: `text/html` or `text/plain`. -- `max_items`: maximum extracted items to include. +- `source_url`: canonical public source URL for the fixture bytes. +- `content_type`: `text/html` or `text/plain`; defaults to `text/html`. +- `max_items`: maximum extracted items to include; clamped by the runner. + +## Outputs -The output packet is `runx.structured_extraction.result.v1`. +- `structured_extraction_result`: validated packet with source, extraction, + validation, provenance, artifacts, and signal metadata. diff --git a/skills/structured-extraction/X.yaml b/skills/structured-extraction/X.yaml index 5344a009c..c6e54e2dd 100644 --- a/skills/structured-extraction/X.yaml +++ b/skills/structured-extraction/X.yaml @@ -4,7 +4,7 @@ version: "0.1.0" catalog: kind: skill audience: public - visibility: internal + visibility: public role: canonical runtime_path: local @@ -25,24 +25,6 @@ emits: - name: structured_extraction_result packet: runx.structured_extraction.result.v1 -harness: - cases: - - name: rfc9110-http-semantics - runner: extract - inputs: - input_path: "fixtures/rfc9110-http-semantics.html" - schema_path: "schemas/extraction.schema.json" - source_url: "https://www.rfc-editor.org/rfc/rfc9110.html" - content_type: "text/html" - max_items: 18 - expect: - status: sealed - outputs: - structured_extraction_result: - matches_packet: runx.structured_extraction.result.v1 - receipt: - schema: runx.receipt.v1 - runners: extract: default: true diff --git a/skills/structured-extraction/fixtures/rfc9110-http-semantics.yaml b/skills/structured-extraction/fixtures/rfc9110-http-semantics.yaml index 040ab424b..d90fbbd29 100644 --- a/skills/structured-extraction/fixtures/rfc9110-http-semantics.yaml +++ b/skills/structured-extraction/fixtures/rfc9110-http-semantics.yaml @@ -1,8 +1,6 @@ name: rfc9110-http-semantics -lane: deterministic -target: - kind: skill - ref: . +kind: skill +target: .. runner: extract inputs: input_path: "fixtures/rfc9110-http-semantics.html" @@ -11,10 +9,9 @@ inputs: content_type: "text/html" max_items: 18 expect: - status: success - outputs: - structured_extraction_result: - matches_packet: runx.structured_extraction.result.v1 + status: sealed + receipt: + schema: runx.receipt.v1 metadata: public_skill: structured-extraction source_case: rfc9110-http-semantics diff --git a/skills/support-triage-reply/SKILL.md b/skills/support-triage-reply/SKILL.md index dfddaa3a1..8955bbe86 100644 --- a/skills/support-triage-reply/SKILL.md +++ b/skills/support-triage-reply/SKILL.md @@ -16,16 +16,119 @@ runx: - support_request --- -# Support Triage Reply +## What this skill does -Classify one bounded support request and return a support-safe decision packet. -The skill is designed for day-to-day operator work where support, product, and -engineering signals arrive together, but a customer send must remain a separate -human-approved action. +Classify one bounded support request, choose the safest next path, and draft a +customer reply only when the supplied context supports one. The runner emits a +support triage packet with classification, severity, confidence, evidence, +draft email, and a send gate. -This skill never sends email, posts to Slack, creates issues, mutates accounts, -or touches billing. It returns a draft and a gated send proposal only when the -request is safe to answer from the supplied context. +This skill never sends email, posts to Slack, opens issues, mutates accounts, or +touches billing. It prepares the decision packet that a separate governed send +skill can review, approve, and deliver with its own authority grant and receipt. + +## When to use this skill + +Use this skill when an agent has a single support request and needs a safe first +decision: answer, ask for more information, route to engineering, route to +billing, route to account review, or route to abuse review. + +It is useful in business-ops graphs where support triage fans out from inbox +intake, then hands off only safe drafts to `send-as` or another provider-backed +send lane. It also works for dry-run review of support queues because it has no +external side effects. + +## When not to use this skill + +Do not use this skill as a helpdesk transport, account access workflow, +billing authority, customer identity verifier, or automatic sender. Do not use +it to answer from private account state unless that state has already been +summarized into an approved `support_request` packet. + +If the request asks for account recovery, billing changes, abuse handling, or +anything that needs private records, the skill must not draft a definitive +answer. It should return a review route and let a stronger authority gate handle +the consequence. + +## Procedure + +1. Require `support_request` to contain at least `subject` or `body`. +2. Normalize the request text and classify it as `how_to`, `billing`, + `account_access`, `bug`, `abuse`, or `unknown`. +3. Estimate severity and confidence from matched signals. +4. Choose the recommended path. +5. Draft a customer reply only for safe `how_to` requests. +6. Record missing context and matched signals. +7. Emit `send_gate.status = requires_human_approval` for every result. +8. Let downstream send or operator lanes decide whether a draft may be sent. + +## Edge cases and stop conditions + +Return `needs_input` when `support_request` is missing or lacks both subject and +body. Return `needs_more_evidence` when the request is too vague to route. Mark +private-state paths as gated review, not as ready-to-send drafts. If a caller +asks the skill to send, mutate an account, bypass an approval gate, or provide +credential recovery instructions, return `refused`. + +The authority scope is classification and draft preparation only. The proof +surface is the sealed receipt containing the request summary, matched signals, +recommended path, draft proposal if any, and send gate. Any live customer send +requires a separate `send-as` receipt. + +## Output schema + +The runner emits `runx.support.triage_reply.v1`: + +```json +{ + "classification": "how_to | billing | account_access | bug | abuse | unknown", + "severity": "low | medium | high | critical", + "confidence": 0.78, + "recommended_path": "reply_draft | request_info | engineering_intake | billing_review | account_review | abuse_review | manual_review", + "evidence": { + "source": "fixture:safe-how-to", + "source_summary": "How do I verify my sending domain?", + "matched_signals": ["verify", "dns", "domain"], + "missing_context": [], + "taxonomy_coverage": ["how_to", "billing", "account_access", "bug", "abuse", "unknown"], + "private_data_required": false, + "send_side_effects": "none" + }, + "draft_email": { + "proposed": true, + "subject": "Re: How do I verify my sending domain?", + "body": "..." + }, + "send_gate": { + "status": "requires_human_approval", + "action": "send_customer_email", + "rationale": "..." + } +} +``` + +## Worked example + +```bash +runx skill "$PWD" \ + --runner triage \ + --input-json support_request='{ + "customer_name": "Mira", + "customer_email": "mira@example.test", + "subject": "How do I verify my sending domain?", + "body": "I added the DNS records. What should I check next?", + "source": "fixture:safe-how-to" + }' \ + --input-json policy='{ + "product_name": "ExampleDesk", + "support_signature": "ExampleDesk Support" + }' \ + --json +``` + +Expected result: `classification = how_to`, `recommended_path = reply_draft`, +`draft_email.proposed = true`, and `send_gate.status = +requires_human_approval`. The run does not send the email. ## Inputs @@ -34,50 +137,13 @@ request is safe to answer from the supplied context. - `policy`: optional object with `product_name`, `support_signature`, `safe_reply_topics`, and `escalation_contacts`. -## Output - -The runner emits these top-level fields: +## Outputs -- `classification`: `how_to`, `billing`, `account_access`, `bug`, `abuse`, or - `unknown`. -- `severity`: `low`, `medium`, `high`, or `critical`. +- `classification`: request class. +- `severity`: operational severity. - `confidence`: number from 0 to 1. -- `recommended_path`: one of `reply_draft`, `request_info`, - `engineering_intake`, `billing_review`, `account_review`, `abuse_review`, or - `manual_review`. -- `evidence`: object with matched signals, missing context, source summary, and - taxonomy coverage. -- `draft_email`: object with `proposed`, `subject`, and `body`. When a reply is - not safe from the supplied packet, `proposed` is `false` and `reason` explains - the blocker. -- `send_gate`: object whose `status` is always `requires_human_approval`. - -## Decision Rules - -Prefer safety over completeness: - -- `how_to`: draft a clear support email when the request is answerable from the - supplied text or common product-safe instructions. -- `billing`: route to billing review unless the supplied context already names - a public, non-account-specific policy. -- `account_access`: route to account review. Do not ask for passwords, recovery - secrets, or private tokens. -- `bug`: route to engineering intake when the report includes a failure mode, - product surface, or reproduction clue. -- `abuse`: route to abuse review and do not draft a customer-facing answer. -- `unknown`: request more information or manual review. Do not invent a fix. - -Customer-facing copy must be specific, calm, and sendable. It should include a -greeting, acknowledge the actual request, state the answer or next step, and end -with the configured support signature. Avoid filler, unsupported promises, and -fake certainty. - -## Safety Bar - -- No customer send occurs inside this skill. -- No private credentials, billing records, account identifiers, or inbox state - are required. -- A draft is a proposal, not permission. The caller must use a separate - governed send lane to deliver any message. -- When confidence is low or private account state is needed, return - `manual_review` or a review-specific route. +- `recommended_path`: next safe handling path. +- `evidence`: matched signals, missing context, source summary, and taxonomy + coverage. +- `draft_email`: proposed customer reply or blocker reason. +- `send_gate`: always requires human approval before delivery. diff --git a/skills/support-triage-reply/X.yaml b/skills/support-triage-reply/X.yaml index b8332cd81..2071509ab 100644 --- a/skills/support-triage-reply/X.yaml +++ b/skills/support-triage-reply/X.yaml @@ -3,64 +3,10 @@ version: "0.1.1" catalog: kind: skill - audience: operator - visibility: internal + audience: public + visibility: public role: canonical -harness: - cases: - - name: safe-how-to-reply-draft - runner: triage - inputs: - support_request: - customer_name: Mira - customer_email: mira@example.test - subject: How do I verify my sending domain? - body: I added the DNS records for my domain. What should I check next so emails can send safely? - source: fixture:safe-how-to - policy: - product_name: ExampleDesk - support_signature: ExampleDesk Support - expect: - status: sealed - receipt: - schema: runx.receipt.v1 - state: sealed - disposition: closed - reason_code: process_closed - - - name: account-access-escalates-without-draft - runner: triage - inputs: - support_request: - customer_name: Theo - customer_email: theo@example.test - subject: I cannot access my account - body: My login is blocked and I need someone to reset access for the team owner. - source: fixture:account-access - policy: - product_name: ExampleDesk - support_signature: ExampleDesk Support - expect: - status: sealed - receipt: - schema: runx.receipt.v1 - state: sealed - disposition: closed - reason_code: process_closed - - - name: missing-request-fails - runner: triage - inputs: - support_request: {} - expect: - status: failure - receipt: - schema: runx.receipt.v1 - state: sealed - disposition: closed - reason_code: process_failed - runners: triage: default: true diff --git a/skills/support-triage-reply/fixtures/account-access-escalates-without-draft.yaml b/skills/support-triage-reply/fixtures/account-access-escalates-without-draft.yaml new file mode 100644 index 000000000..63021abae --- /dev/null +++ b/skills/support-triage-reply/fixtures/account-access-escalates-without-draft.yaml @@ -0,0 +1,25 @@ +name: account-access-escalates-without-draft +kind: skill +target: .. +runner: triage +inputs: + support_request: + customer_name: Theo + customer_email: theo@example.test + subject: I cannot access my account + body: My login is blocked and I need someone to reset access for the team owner. + source: fixture:account-access + policy: + product_name: ExampleDesk + support_signature: ExampleDesk Support +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_closed +metadata: + public_skill: support-triage-reply + source_case: account-access-escalates-without-draft + source: skills-fixture diff --git a/skills/support-triage-reply/fixtures/missing-request-fails.yaml b/skills/support-triage-reply/fixtures/missing-request-fails.yaml new file mode 100644 index 000000000..164386a9f --- /dev/null +++ b/skills/support-triage-reply/fixtures/missing-request-fails.yaml @@ -0,0 +1,17 @@ +name: missing-request-fails +kind: skill +target: .. +runner: triage +inputs: + support_request: {} +expect: + status: failure + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: failed + reason_code: process_failed +metadata: + public_skill: support-triage-reply + source_case: missing-request-fails + source: skills-fixture diff --git a/skills/support-triage-reply/fixtures/safe-how-to-reply-draft.yaml b/skills/support-triage-reply/fixtures/safe-how-to-reply-draft.yaml new file mode 100644 index 000000000..c49f8cad9 --- /dev/null +++ b/skills/support-triage-reply/fixtures/safe-how-to-reply-draft.yaml @@ -0,0 +1,25 @@ +name: safe-how-to-reply-draft +kind: skill +target: .. +runner: triage +inputs: + support_request: + customer_name: Mira + customer_email: mira@example.test + subject: How do I verify my sending domain? + body: I added the DNS records for my domain. What should I check next so emails can send safely? + source: fixture:safe-how-to + policy: + product_name: ExampleDesk + support_signature: ExampleDesk Support +expect: + status: sealed + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_closed +metadata: + public_skill: support-triage-reply + source_case: safe-how-to-reply-draft + source: skills-fixture diff --git a/tests/cli-skill-registry-profile.test.ts b/tests/cli-skill-registry-profile.test.ts index e74e40bb3..4bd6515f1 100644 --- a/tests/cli-skill-registry-profile.test.ts +++ b/tests/cli-skill-registry-profile.test.ts @@ -1,5 +1,5 @@ import { generateKeyPairSync, sign } from "node:crypto"; -import { readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"; +import { existsSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs"; import { mkdtemp, readFile, rm } from "node:fs/promises"; import os from "node:os"; import path from "node:path"; @@ -23,7 +23,7 @@ describe("CLI skill registry execution profile", () => { runCli( ["skill", "publish", "skills/sourcey", "--owner", "acme", "--version", "1.0.0", "--registry", registryDir, "--json"], { stdin: process.stdin, stdout: publishOut, stderr: publishErr }, - { ...process.env, RUNX_CWD: process.cwd(), ...trustEnv }, + { ...process.env, RUNX_CWD: process.cwd(), RUNX_DEV_RUST_CLI_BIN: nativeRunxBinaryForTest(), ...trustEnv }, ), ).resolves.toBe(0); expect(publishErr.contents()).toBe(""); @@ -44,7 +44,13 @@ describe("CLI skill registry execution profile", () => { runCli( ["skill", "search", "sourcey", "--json"], { stdin: process.stdin, stdout: searchOut, stderr: searchErr }, - { ...process.env, RUNX_CWD: process.cwd(), RUNX_REGISTRY_DIR: registryDir, ...trustEnv }, + { + ...process.env, + RUNX_CWD: process.cwd(), + RUNX_DEV_RUST_CLI_BIN: nativeRunxBinaryForTest(), + RUNX_REGISTRY_DIR: registryDir, + ...trustEnv, + }, ), ).resolves.toBe(0); expect(searchErr.contents()).toBe(""); @@ -65,7 +71,13 @@ describe("CLI skill registry execution profile", () => { runCli( ["add", "acme/sourcey@1.0.0", "--to", skillsDir, "--json"], { stdin: process.stdin, stdout: addOut, stderr: addErr }, - { ...process.env, RUNX_CWD: process.cwd(), RUNX_REGISTRY_DIR: registryDir, ...trustEnv }, + { + ...process.env, + RUNX_CWD: process.cwd(), + RUNX_DEV_RUST_CLI_BIN: nativeRunxBinaryForTest(), + RUNX_REGISTRY_DIR: registryDir, + ...trustEnv, + }, ), ).resolves.toBe(0); expect(addErr.contents()).toBe(""); @@ -131,6 +143,15 @@ function registryTrustEnv(owner: string, signingKey: TestManifestSigningKey): No }; } +function nativeRunxBinaryForTest(): string { + const existing = process.env.RUNX_DEV_RUST_CLI_BIN; + if (existing) { + return existing; + } + const candidate = path.resolve("crates/target/debug/runx"); + return existsSync(candidate) ? candidate : "runx"; +} + function signPublishedRegistryEntry(registryDir: string, signingKey: TestManifestSigningKey): void { const entryPath = findSingleRegistryEntry(registryDir); const entry = JSON.parse(readFileSync(entryPath, "utf8")) as { @@ -138,6 +159,7 @@ function signPublishedRegistryEntry(registryDir: string, signingKey: TestManifes version: string; digest: string; profile_digest?: string; + package_digest?: string; signed_manifest?: unknown; }; const payload = @@ -146,6 +168,7 @@ function signPublishedRegistryEntry(registryDir: string, signingKey: TestManifes `version=${entry.version}\n` + `digest=${entry.digest}\n` + `profile_digest=${entry.profile_digest ?? ""}\n` + + `package_digest=${entry.package_digest ?? ""}\n` + `signer_id=${signingKey.signerId}\n` + `key_id=${signingKey.keyId}\n`; entry.signed_manifest = { @@ -154,6 +177,7 @@ function signPublishedRegistryEntry(registryDir: string, signingKey: TestManifes version: entry.version, digest: entry.digest, ...(entry.profile_digest ? { profile_digest: entry.profile_digest } : {}), + ...(entry.package_digest ? { package_digest: entry.package_digest } : {}), signer: { id: signingKey.signerId, key_id: signingKey.keyId, diff --git a/tests/data-adapter-conformance.test.ts b/tests/data-adapter-conformance.test.ts new file mode 100644 index 000000000..092a8b96a --- /dev/null +++ b/tests/data-adapter-conformance.test.ts @@ -0,0 +1,574 @@ +import { existsSync, mkdtempSync, rmSync } from "node:fs"; +import os from "node:os"; +import path from "node:path"; +import { spawnSync } from "node:child_process"; + +import { describe, expect, it } from "vitest"; + +import { validateDataOperationResultContract } from "../packages/contracts/src/index.js"; + +type AdapterCase = { + readonly name: string; + readonly path: string; + readonly makeBaseInputs: (workspace: string, caseId: string) => Record; + readonly skip?: string; +}; + +const adapters: readonly AdapterCase[] = [ + { + name: "data.local", + path: "skills/data-store/tools/data/local/run.mjs", + makeBaseInputs: (_workspace, caseId) => ({ + data_source_ref: `local://runx-data-store/conformance/${caseId}`, + store_id: `data-adapter-conformance-${caseId}`, + }), + }, + { + name: "data.sqlite", + path: "skills/data-store/tools/data/sqlite/run.mjs", + makeBaseInputs: (_workspace, caseId) => ({ + data_source_ref: `local://runx-data-store/conformance/${caseId}`, + data_source_binding: { + adapter: "data.sqlite", + database_path: `.runx/data/conformance-${caseId}.sqlite`, + resources: { + board_events: { + kind: "event_stream", + partition_key: "aggregate_id", + }, + }, + }, + }), + skip: existsSync("skills/data-store/tools/data/sqlite/run.mjs") ? undefined : "sqlite adapter not present", + }, + ...redisAdapterCase(), +]; + +describe.each(adapters)("data adapter conformance: $name", (adapter) => { + it("appends, replays, reads events, and reads projection", () => { + const workspace = tempWorkspace(adapter.name); + try { + const base = adapter.makeBaseInputs(workspace, uniqueId("happy")); + const append = runAdapter(adapter, workspace, { + ...base, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-123", + expected_version: 0, + idempotency_key: "posting-123:create:v1", + event: { + type: "posting.created", + payload: { + title: "verify a receipt link", + }, + }, + }); + + expectPacket(append, { + status: "committed", + operation: "append_event", + before_version: 0, + after_version: 1, + provider: expectedProvider(adapter.name), + }); + + const replay = runAdapter(adapter, workspace, { + ...base, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-123", + expected_version: 0, + idempotency_key: "posting-123:create:v1", + event: { + type: "posting.created", + payload: { + title: "verify a receipt link", + }, + }, + }); + + expectPacket(replay, { + status: "idempotent_replay", + operation: "append_event", + before_version: 1, + after_version: 1, + }); + + const events = runAdapter(adapter, workspace, { + ...base, + operation: "read_events", + resource: "board_events", + aggregate_id: "posting-123", + limit: 10, + }); + + const eventsPacket = expectPacket(events, { + status: "read", + operation: "read_events", + before_version: 1, + after_version: 1, + }); + expect(eventsPacket.events).toHaveLength(1); + expect(eventsPacket.rows).toHaveLength(1); + + const projection = runAdapter(adapter, workspace, { + ...base, + operation: "read_projection", + resource: "board_events", + aggregate_id: "posting-123", + }); + + const projectionPacket = expectPacket(projection, { + status: "read", + operation: "read_projection", + before_version: 1, + after_version: 1, + }); + expect(projectionPacket.projection).toMatchObject({ + aggregate_id: "posting-123", + resource: "board_events", + version: 1, + event_count: 1, + }); + } finally { + rmSync(workspace, { recursive: true, force: true }); + } + }); + + it("derives event_type from generic effect transition packets", () => { + const workspace = tempWorkspace(adapter.name); + try { + const base = adapter.makeBaseInputs(workspace, uniqueId("effect-type")); + runAdapter(adapter, workspace, { + ...base, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-effect", + expected_version: 0, + idempotency_key: "posting-effect:accept:v1", + event: { + effect_family: "messageboard", + operation: "accept", + payload: { + accepted: true, + }, + }, + }); + + const events = runAdapter(adapter, workspace, { + ...base, + operation: "read_events", + resource: "board_events", + aggregate_id: "posting-effect", + limit: 10, + }); + const packet = expectPacket(events, { + status: "read", + operation: "read_events", + before_version: 1, + after_version: 1, + }); + expect(packet.events[0]?.event_type).toBe("messageboard.accept"); + + const projection = runAdapter(adapter, workspace, { + ...base, + operation: "read_projection", + resource: "board_events", + aggregate_id: "posting-effect", + }); + const projectionPacket = expectPacket(projection, { + status: "read", + operation: "read_projection", + before_version: 1, + after_version: 1, + }); + expect(projectionPacket.projection.last_event_type).toBe("messageboard.accept"); + } finally { + rmSync(workspace, { recursive: true, force: true }); + } + }); + + it("rejects idempotency conflicts and stale expected versions without committing", () => { + const workspace = tempWorkspace(adapter.name); + try { + const base = adapter.makeBaseInputs(workspace, uniqueId("conflict")); + runAdapter(adapter, workspace, { + ...base, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-456", + expected_version: 0, + idempotency_key: "posting-456:create:v1", + event: { + type: "posting.created", + payload: { + title: "first", + }, + }, + }); + + const idempotencyConflict = runAdapter(adapter, workspace, { + ...base, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-456", + expected_version: 1, + idempotency_key: "posting-456:create:v1", + event: { + type: "posting.created", + payload: { + title: "different", + }, + }, + }); + + const conflictPacket = expectPacket(idempotencyConflict, { + status: "conflict", + operation: "append_event", + before_version: 1, + after_version: 1, + }); + expect(conflictPacket.stop_conditions[0]?.code).toBe("conflict"); + + const versionConflict = runAdapter(adapter, workspace, { + ...base, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-456", + expected_version: 0, + idempotency_key: "posting-456:claim:v1", + event: { + type: "posting.claimed", + payload: { + actor: "agent-9", + }, + }, + }); + + const versionPacket = expectPacket(versionConflict, { + status: "conflict", + operation: "append_event", + before_version: 1, + after_version: 1, + }); + expect(versionPacket.stop_conditions[0]?.message).toContain("expected version 0"); + } finally { + rmSync(workspace, { recursive: true, force: true }); + } + }); + + it("fails closed on missing write keys and broad invalid reads", () => { + const workspace = tempWorkspace(adapter.name); + try { + const base = adapter.makeBaseInputs(workspace, uniqueId("failure")); + + const missingIdempotency = runAdapterRaw(adapter, workspace, { + ...base, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-789", + expected_version: 0, + event: { + type: "posting.created", + }, + }); + expect(missingIdempotency.status).not.toBe(0); + expect(missingIdempotency.stderr).toContain("idempotency_key"); + + const invalidLimit = runAdapterRaw(adapter, workspace, { + ...base, + operation: "read_events", + resource: "board_events", + aggregate_id: "posting-789", + limit: 10_000, + }); + expect(invalidLimit.status).not.toBe(0); + expect(invalidLimit.stderr).toContain("limit"); + } finally { + rmSync(workspace, { recursive: true, force: true }); + } + }); + + it("accepts safe slash-style aggregate ids for repo and cursor streams", () => { + const workspace = tempWorkspace(adapter.name); + try { + const base = adapter.makeBaseInputs(workspace, uniqueId("slash-aggregate")); + const append = runAdapter(adapter, workspace, { + ...base, + operation: "append_event", + resource: "github_sync_events", + aggregate_id: "runxhq/runx:triage-open", + expected_version: 0, + idempotency_key: "runxhq/runx:triage-open:pull:v1", + event: { + type: "github.sync.planned", + payload: { + repo: "runxhq/runx", + }, + }, + }); + + const packet = expectPacket(append, { + status: "committed", + operation: "append_event", + before_version: 0, + after_version: 1, + }); + expect(packet.aggregate_id).toBe("runxhq/runx:triage-open"); + } finally { + rmSync(workspace, { recursive: true, force: true }); + } + }); +}); + +it("isolates SQLite streams by data_source_ref when sources share one database", () => { + const adapter = adapters.find((candidate) => candidate.name === "data.sqlite"); + expect(adapter?.skip).toBeUndefined(); + if (!adapter || adapter.skip) return; + + const workspace = tempWorkspace(adapter.name); + try { + const databasePath = ".runx/data/shared-source-isolation.sqlite"; + const binding = { + adapter: "data.sqlite", + database_path: databasePath, + resources: { + board_events: { + kind: "event_stream", + partition_key: "aggregate_id", + }, + }, + }; + const appendA = runAdapter(adapter, workspace, { + data_source_ref: "tenant://source-a/board", + data_source_binding: binding, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-123", + expected_version: 0, + idempotency_key: "posting-123:create:v1", + event: { + type: "posting.created", + payload: { + source: "a", + }, + }, + }); + + expectPacket(appendA, { + status: "committed", + operation: "append_event", + before_version: 0, + after_version: 1, + }); + + const appendB = runAdapter(adapter, workspace, { + data_source_ref: "tenant://source-b/board", + data_source_binding: binding, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-123", + expected_version: 0, + idempotency_key: "posting-123:create:v1", + event: { + type: "posting.created", + payload: { + source: "b", + }, + }, + }); + + expectPacket(appendB, { + status: "committed", + operation: "append_event", + before_version: 0, + after_version: 1, + }); + } finally { + rmSync(workspace, { recursive: true, force: true }); + } +}); + +it("isolates Redis streams by data_source_ref when sources share one key prefix", () => { + const adapter = adapters.find((candidate) => candidate.name === "data.redis"); + if (!adapter) return; + + const workspace = tempWorkspace(adapter.name); + try { + const keyPrefix = `runx:data-store:source-isolation:${uniqueId("redis")}`; + const binding = { + adapter: "data.redis", + endpoint: process.env.RUNX_REDIS_URL, + key_prefix: keyPrefix, + resources: { + board_events: { + kind: "event_stream", + partition_key: "aggregate_id", + }, + }, + }; + const appendA = runAdapter(adapter, workspace, { + data_source_ref: "tenant://source-a/board", + data_source_binding: binding, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-123", + expected_version: 0, + idempotency_key: "posting-123:create:v1", + event: { + type: "posting.created", + payload: { + source: "a", + }, + }, + }); + + expectPacket(appendA, { + status: "committed", + operation: "append_event", + before_version: 0, + after_version: 1, + }); + + const appendB = runAdapter(adapter, workspace, { + data_source_ref: "tenant://source-b/board", + data_source_binding: binding, + operation: "append_event", + resource: "board_events", + aggregate_id: "posting-123", + expected_version: 0, + idempotency_key: "posting-123:create:v1", + event: { + type: "posting.created", + payload: { + source: "b", + }, + }, + }); + + expectPacket(appendB, { + status: "committed", + operation: "append_event", + before_version: 0, + after_version: 1, + }); + } finally { + rmSync(workspace, { recursive: true, force: true }); + } +}); + +function runAdapter(adapter: AdapterCase, workspace: string, inputs: unknown): unknown { + const result = runAdapterRaw(adapter, workspace, inputs); + expect(result.status, result.stderr).toBe(0); + expect(result.stderr).toBe(""); + expect(result.stdout.trim()).not.toBe(""); + return JSON.parse(result.stdout); +} + +function runAdapterRaw(adapter: AdapterCase, workspace: string, inputs: unknown) { + return spawnSync(process.execPath, [path.resolve(adapter.path)], { + cwd: workspace, + encoding: "utf8", + env: { + ...process.env, + RUNX_CWD: workspace, + RUNX_INPUTS_JSON: JSON.stringify(inputs), + }, + }); +} + +function expectPacket( + value: unknown, + expected: { + readonly status: string; + readonly operation: string; + readonly before_version: number; + readonly after_version: number; + readonly provider?: string; + }, +) { + const packet = validateDataOperationResultContract(value); + expect(packet.status).toBe(expected.status); + expect(packet.operation).toBe(expected.operation); + expect(packet.before_version).toBe(expected.before_version); + expect(packet.after_version).toBe(expected.after_version); + if (expected.provider) { + expect(packet.provider).toBe(expected.provider); + } + expect(packet.result_digest).toMatch(/^sha256:[a-f0-9]{64}$/); + expect(packet.projection_digest).toMatch(/^sha256:[a-f0-9]{64}$/); + assertNoSecretMaterial(packet); + return packet; +} + +function assertNoSecretMaterial(value: unknown, pathParts: readonly string[] = []): void { + if (!value || typeof value !== "object") return; + if (Array.isArray(value)) { + value.forEach((entry, index) => assertNoSecretMaterial(entry, [...pathParts, String(index)])); + return; + } + for (const [key, child] of Object.entries(value)) { + const lowered = key.toLowerCase(); + expect( + /(?:secret|token|api[_-]?key|password|private[_-]?key|connection[_-]?string)/.test(lowered), + [...pathParts, key].join("."), + ).toBe(false); + assertNoSecretMaterial(child, [...pathParts, key]); + } +} + +function tempWorkspace(adapterName: string): string { + return mkdtempSync(path.join(os.tmpdir(), `runx-${adapterName.replaceAll(".", "-")}-`)); +} + +function uniqueId(label: string): string { + return `${label}-${process.pid}-${Date.now()}-${Math.random().toString(16).slice(2)}`; +} + +function expectedProvider(adapterName: string): string { + if (adapterName === "data.local") return "local-json-event-store"; + if (adapterName === "data.sqlite") return "sqlite-event-store"; + if (adapterName === "data.redis") return "redis-event-store"; + throw new Error(`unexpected adapter ${adapterName}`); +} + +function redisAdapterCase(): readonly AdapterCase[] { + const redisUrl = process.env.RUNX_REDIS_URL; + if (!redisUrl || !redisReady(redisUrl)) return []; + return [ + { + name: "data.redis", + path: "skills/data-store/tools/data/redis/run.mjs", + makeBaseInputs: (_workspace, caseId) => ({ + data_source_ref: `local://runx-data-store/conformance/${caseId}`, + data_source_binding: { + adapter: "data.redis", + endpoint: redisUrl, + key_prefix: `runx:data-store:conformance:${caseId}`, + resources: { + board_events: { + kind: "event_stream", + partition_key: "aggregate_id", + }, + }, + }, + }), + }, + ]; +} + +function redisReady(redisUrl: string): boolean { + try { + const parsed = new URL(redisUrl); + if ((parsed.protocol !== "redis:" && parsed.protocol !== "rediss:") || parsed.username || parsed.password) { + return false; + } + } catch { + return false; + } + const result = spawnSync(process.env.RUNX_REDIS_CLI_BIN || "redis-cli", ["-u", redisUrl, "PING"], { + encoding: "utf8", + maxBuffer: 1024 * 32, + }); + return result.status === 0 && result.stdout.trim().toUpperCase() === "PONG"; +} diff --git a/tests/data-store-skill.test.ts b/tests/data-store-skill.test.ts new file mode 100644 index 000000000..bc30f2168 --- /dev/null +++ b/tests/data-store-skill.test.ts @@ -0,0 +1,50 @@ +import { spawnSync } from "node:child_process"; +import path from "node:path"; + +import { describe, expect, it } from "vitest"; + +import { validateDataOperationResultContract } from "../packages/contracts/src/index.js"; + +const adapterPath = path.resolve("skills/data-store/tools/data/local/run.mjs"); + +describe("data-store local adapter", () => { + it("emits the governed data operation result contract", () => { + const storeId = `contract-test-${process.pid}-${Date.now()}`; + const result = runLocalDataAdapter({ + operation: "append_event", + data_source_ref: "local://runx-data-store/contract-test", + store_id: storeId, + resource: "board_events", + aggregate_id: "posting-123", + expected_version: 0, + idempotency_key: "posting-123:create:v1", + event: { + type: "posting.created", + payload: { + title: "verify a receipt link", + }, + }, + }); + + const packet = validateDataOperationResultContract(JSON.parse(result.stdout)); + expect(packet.status).toBe("committed"); + expect(packet.operation).toBe("append_event"); + expect(packet.provider).toBe("local-json-event-store"); + }); +}); + +function runLocalDataAdapter(inputs: unknown): { readonly stdout: string } { + const result = spawnSync(process.execPath, [adapterPath], { + cwd: path.resolve("."), + encoding: "utf8", + env: { + ...process.env, + RUNX_INPUTS_JSON: JSON.stringify(inputs), + }, + }); + + expect(result.status).toBe(0); + expect(result.stderr).toBe(""); + expect(result.stdout.trim()).not.toBe(""); + return { stdout: result.stdout }; +} diff --git a/tests/official-skill-catalog.test.ts b/tests/official-skill-catalog.test.ts index 7b82b5172..1b588b3be 100644 --- a/tests/official-skill-catalog.test.ts +++ b/tests/official-skill-catalog.test.ts @@ -15,71 +15,6 @@ import { import { validateSkillMarkdown } from "./parser-eval.js"; import { resolveRunxBinary } from "./runx-binary.js"; -const publicCatalogPackages = [ - "brand-voice", - "business-ops", - "charge", - "content-pipeline", - "deep-research-brief", - "design-skill", - "dispute-respond", - "draft-content", - "ecosystem-brief", - "ecosystem-vuln-scan", - "evolve", - "github-sync", - "governed-outbound", - "improve-skill", - "inbox-and-calendar-exec", - "issue-intake", - "issue-to-pr", - "issue-triage", - "knowledge-router", - "lead-enrichment", - "lead-router", - "least-privilege-auditor", - "ledger", - "messageboard", - "moltbook", - "n8n-handoff", - "nitrosend", - "nws-weather-forecast", - "overlay-generator", - "policy-author", - "pr-review-note", - "prior-art", - "receipt-auditor", - "redact-pii", - "reflect-digest", - "refund", - "release", - "research", - "review-receipt", - "review-skill", - "run-history-analyst", - "ops-desk", - "sandbox-harden", - "send-as", - "settle-invoice", - "sign-receipt", - "skill-lab", - "skill-testing", - "slack-notify", - "sourcey", - "spend", - "sql-analyst", - "stripe-pay", - "taste-profile", - "vault-unseal", - "vuln-scan", - "web-fetch", - "weather-forecast", - "work-plan", - "write-harness", - "x402-pay", - "zapier-handoff", -] as const; - const publicSkillRequiredHeadings = [ "What this skill does", "When to use this skill", @@ -221,8 +156,15 @@ describe("official skill catalog", () => { it("keeps the public official catalog limited to implemented catalog skills", async () => { const publicSkills = officialSkillPackages().filter((skillName) => catalogVisibility(skillName) === "public"); + const entries = JSON.parse( + await readFile(path.resolve("packages", "cli", "src", "official-skills.lock.json"), "utf8"), + ) as ReadonlyArray<{ readonly skill_id: string; readonly catalog_visibility?: string }>; + const publicLockSkills = entries + .filter((entry) => entry.catalog_visibility === "public") + .map((entry) => entry.skill_id.slice("runx/".length)) + .sort(); - expect(publicSkills).toEqual([...publicCatalogPackages].sort()); + expect(publicLockSkills).toEqual(publicSkills); }); it("keeps public official skills at the execution-context documentation bar", () => { @@ -399,6 +341,7 @@ describe("official skill catalog", () => { function officialSkillPackages(): readonly string[] { return readdirSync(path.resolve("skills"), { withFileTypes: true }) .filter((entry) => entry.isDirectory()) + .filter((entry) => !entry.name.startsWith(".")) .filter((entry) => existsSync(path.resolve("skills", entry.name, "SKILL.md"))) .filter((entry) => existsSync(path.resolve("skills", entry.name, "X.yaml"))) .map((entry) => entry.name) diff --git a/tests/official-skill-fetch.test.ts b/tests/official-skill-fetch.test.ts index 1f74b3f89..02a88b9d1 100644 --- a/tests/official-skill-fetch.test.ts +++ b/tests/official-skill-fetch.test.ts @@ -35,9 +35,8 @@ describe("official skill native fetch", () => { "--non-interactive", ]); const firstJson = parseJsonOutput(first, 2); - const firstPath = skillDirectoryFromNeedsAgent(firstJson); - expect(firstPath).toContain(path.join(globalHomeDir, "official-skills")); - expect(firstPath).toContain(path.join("runx", "sourcey")); + expect((firstJson as { status?: string }).status).toBe("needs_agent"); + const firstPath = findOfficialSkillCachePath(globalHomeDir, "runx/sourcey"); expect((await stat(path.join(firstPath, "SKILL.md"))).isFile()).toBe(true); expect((await stat(path.join(firstPath, "X.yaml"))).isFile()).toBe(true); @@ -49,7 +48,7 @@ describe("official skill native fetch", () => { "--non-interactive", ]); const secondJson = parseJsonOutput(second, 2); - expect(skillDirectoryFromNeedsAgent(secondJson)).toBe(firstPath); + expect((secondJson as { status?: string }).status).toBe("needs_agent"); expect((await stat(path.join(firstPath, "SKILL.md"))).isFile()).toBe(true); } finally { await rm(tempDir, { recursive: true, force: true }); @@ -103,8 +102,8 @@ describe("official skill native fetch", () => { } }); - it("copies packaged stage helpers beside cached official graph skills", async () => { - const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-official-fetch-runtime-")); + it("copies graph stages beside cached official graph skills", async () => { + const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-official-fetch-stages-")); const projectDir = path.join(tempDir, "project"); const globalHomeDir = path.join(tempDir, "home"); const env = testEnv(projectDir, globalHomeDir); @@ -112,36 +111,31 @@ describe("official skill native fetch", () => { try { await mkdir(projectDir, { recursive: true }); const registryDir = path.join(tempDir, "registry"); - const lockEntry = await officialSkillLock("runx/issue-to-pr"); + const lockEntry = await officialSkillLock("runx/spend"); publishLocalRegistrySkill({ registryDir, - subject: path.resolve("skills/issue-to-pr/SKILL.md"), - profile: path.resolve("skills/issue-to-pr/X.yaml"), + subject: path.resolve("skills/spend/SKILL.md"), + profile: path.resolve("skills/spend/X.yaml"), owner: "runx", version: lockEntry.version, env, }); - const result = runNativeSkill(env, [ - "issue-to-pr", - "--registry", - registryDir, - "--input", - "task_id=issue-to-pr-native-fetch", - "--input", - "thread_title=Fixture smoke test", - "--input", - "thread_body=Minimal thread body for the official cache test.", - "--input", - "thread_locator=local://fixtures/official-cache", - "--json", - "--non-interactive", - ]); + const result = runNativeSkill(env, ["spend", "--registry", registryDir, "--json", "--non-interactive"]); const output = parseJsonOutput(result, 2); - const skillPath = skillDirectoryFromNeedsAgent(output); + expect((output as { status?: string }).status).toBe("needs_agent"); + const skillPath = findOfficialSkillCachePath(globalHomeDir, "runx/spend"); + for (const stage of ["pay-quote", "pay-reserve", "pay-fulfill-rail"]) { + expect( + (await stat( + path.join(skillPath, "graph", stage, "X.yaml"), + )).isFile(), + stage, + ).toBe(true); + } expect( (await stat( - path.join(skillPath, "graph", "scafld", "run.mjs"), + path.join(skillPath, "graph", "pay-fulfill-rail", "stripe-spt-fulfill-adapter.mjs"), )).isFile(), ).toBe(true); } finally { @@ -149,8 +143,8 @@ describe("official skill native fetch", () => { } }); - it("copies graph stages beside cached official graph skills", async () => { - const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-official-fetch-stages-")); + it("copies local tool adapters beside cached official graph skills", async () => { + const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-official-fetch-data-store-")); const projectDir = path.join(tempDir, "project"); const globalHomeDir = path.join(tempDir, "home"); const env = testEnv(projectDir, globalHomeDir); @@ -158,27 +152,46 @@ describe("official skill native fetch", () => { try { await mkdir(projectDir, { recursive: true }); const registryDir = path.join(tempDir, "registry"); - const lockEntry = await officialSkillLock("runx/spend"); + const lockEntry = await officialSkillLock("runx/data-store"); publishLocalRegistrySkill({ registryDir, - subject: path.resolve("skills/spend/SKILL.md"), - profile: path.resolve("skills/spend/X.yaml"), + subject: path.resolve("skills/data-store/SKILL.md"), + profile: path.resolve("skills/data-store/X.yaml"), owner: "runx", version: lockEntry.version, env, }); - const result = runNativeSkill(env, ["spend", "--registry", registryDir, "--json", "--non-interactive"]); - const output = parseJsonOutput(result, 2); - const skillPath = officialPackageRootFromSkillDirectory(skillDirectoryFromNeedsAgent(output)); - for (const stage of ["pay-quote", "pay-reserve", "pay-fulfill-rail"]) { - expect( - (await stat( - path.join(skillPath, "graph", stage, "X.yaml"), - )).isFile(), - stage, - ).toBe(true); - } + const result = runNativeSkill(env, [ + "data-store", + "--registry", + registryDir, + "--runner", + "append_event", + "--input", + "data_source_ref=local://runx-data-store/official-cache", + "--input", + "store_id=official-cache-data-store", + "--input", + "resource=board_events", + "--input", + "aggregate_id=posting-123", + "--input", + "expected_version=0", + "--input", + "idempotency_key=posting-123:create:v1", + "--input", + "event", + "{\"type\":\"posting.created\",\"payload\":{\"title\":\"cached data-store smoke\"}}", + "--json", + "--non-interactive", + ]); + const output = parseJsonOutput(result, 0) as { status?: string }; + + expect(output.status).toBe("sealed"); + const cachedSkillPath = findOfficialSkillCachePath(globalHomeDir, "runx/data-store"); + expect((await stat(path.join(cachedSkillPath, "tools", "data", "local", "manifest.json"))).isFile()).toBe(true); + expect((await stat(path.join(cachedSkillPath, "tools", "data", "local", "run.mjs"))).isFile()).toBe(true); } finally { await rm(tempDir, { recursive: true, force: true }); } @@ -244,29 +257,38 @@ function parseJsonOutput(result: { return JSON.parse(result.stdout); } -function skillDirectoryFromNeedsAgent(value: unknown): string { - const record = value as { - requests?: Array<{ - invocation?: { - envelope?: { - execution_location?: { - skill_directory?: string; - }; - }; - }; - }>; +function findOfficialSkillCachePath(globalHomeDir: string, skillId: string): string { + const [owner, name] = skillId.split("/"); + if (!owner || !name) { + throw new Error(`Invalid skill id ${skillId}.`); + } + const base = globalHomeDir; + const matches: string[] = []; + const walk = (directory: string): void => { + if (!existsSync(directory)) { + return; + } + for (const entry of readdirSync(directory)) { + const entryPath = path.join(directory, entry); + const stats = statSync(entryPath); + if (!stats.isDirectory()) { + continue; + } + if ( + existsSync(path.join(entryPath, "SKILL.md")) && + existsSync(path.join(entryPath, ".runx", "profile.json")) && + entryPath.includes(`${path.sep}${owner}${path.sep}${name}${path.sep}`) + ) { + matches.push(entryPath); + } + walk(entryPath); + } }; - const skillDirectory = record.requests?.[0]?.invocation?.envelope?.execution_location?.skill_directory; - if (!skillDirectory) { - throw new Error("Missing needs_agent skill directory."); + walk(base); + if (matches.length !== 1) { + throw new Error(`expected one cached official package for ${skillId}, found ${matches.length}`); } - return skillDirectory; -} - -function officialPackageRootFromSkillDirectory(skillDirectory: string): string { - const graphMarker = `${path.sep}graph${path.sep}`; - const index = skillDirectory.indexOf(graphMarker); - return index === -1 ? skillDirectory : skillDirectory.slice(0, index); + return matches[0]; } function publishLocalRegistrySkill(input: { @@ -361,6 +383,7 @@ function signPublishedRegistryEntry(registryDir: string, signingKey: TestManifes version: string; digest: string; profile_digest?: string; + package_digest?: string; signed_manifest?: unknown; }; const payload = @@ -369,6 +392,7 @@ function signPublishedRegistryEntry(registryDir: string, signingKey: TestManifes `version=${entry.version}\n` + `digest=${entry.digest}\n` + `profile_digest=${entry.profile_digest ?? ""}\n` + + `package_digest=${entry.package_digest ?? ""}\n` + `signer_id=${signingKey.signerId}\n` + `key_id=${signingKey.keyId}\n`; entry.signed_manifest = { @@ -377,6 +401,7 @@ function signPublishedRegistryEntry(registryDir: string, signingKey: TestManifes version: entry.version, digest: entry.digest, ...(entry.profile_digest ? { profile_digest: entry.profile_digest } : {}), + ...(entry.package_digest ? { package_digest: entry.package_digest } : {}), signer: { id: signingKey.signerId, key_id: signingKey.keyId, From 8924314db9042bac55dd617b07642146f13afa8d Mon Sep 17 00:00:00 2001 From: kam Date: Mon, 22 Jun 2026 02:27:14 +1000 Subject: [PATCH 60/64] fix(cli): restore resume and doctor ci --- crates/runx-cli/src/registry/package.rs | 1 + crates/runx-cli/src/skill.rs | 19 +++-- crates/runx-cli/src/skill/output.rs | 58 +++++++++------ crates/runx-cli/src/skill/parser.rs | 60 ++++++--------- crates/runx-cli/tests/launcher.rs | 32 +++++--- crates/runx-cli/tests/skill.rs | 32 ++++---- crates/runx-runtime/src/adapters/catalog.rs | 2 + .../src/execution/skill_front/agent.rs | 55 +++++++++++++- .../src/execution/skill_front/graph.rs | 8 +- .../execution/skill_front/runner_manifest.rs | 2 +- crates/runx-runtime/src/journal.rs | 47 ++++++++++-- .../runx-runtime/src/registry/trust_anchor.rs | 17 +++-- crates/runx-runtime/src/services/env.rs | 20 ++--- crates/runx-runtime/tests/mcp_server.rs | 2 +- crates/runx-runtime/tests/skill_run.rs | 4 +- crates/runx-sdk/src/client.rs | 8 +- crates/runx-sdk/tests/client_cli.rs | 6 +- dist/packets/effect.transition.v1.schema.json | 40 ++++++++++ dist/packets/github-sync.v1.schema.json | 26 +++++++ docs/issue-to-pr.md | 2 +- fixtures/cli-parity/cases/oracle.json | 11 +++ fixtures/cli-parity/commands.json | 40 +++++++++- packages/cli/src/args.ts | 19 ++++- packages/cli/src/callers.ts | 10 +-- packages/cli/src/dispatch.ts | 29 ++++++-- packages/cli/src/index.test.ts | 26 ++++--- packages/cli/src/presentation/run-result.ts | 2 +- scripts/dogfood-github-issue-to-pr.mjs | 69 +++++++----------- scripts/generate-cli-feature-parity.ts | 3 +- skills/business-ops/graph/ops-lane/run.mjs | 2 +- tests/data-adapter-conformance.test.ts | 9 ++- tests/recognizable-work-lanes.test.ts | 73 ++++++++----------- 32 files changed, 479 insertions(+), 255 deletions(-) create mode 100644 dist/packets/effect.transition.v1.schema.json create mode 100644 dist/packets/github-sync.v1.schema.json diff --git a/crates/runx-cli/src/registry/package.rs b/crates/runx-cli/src/registry/package.rs index 92e03729c..9a7881d1f 100644 --- a/crates/runx-cli/src/registry/package.rs +++ b/crates/runx-cli/src/registry/package.rs @@ -358,6 +358,7 @@ fn resolve_publish_harness_dependency_paths( Ok(vec![declared_relative.to_owned()]) } +// rust-style-allow: long-function - publish packaging keeps file safety, byte limits, and canonical path checks in one audit-friendly collector. fn copy_publish_harness_dependency( package_dir: &Path, relative: &str, diff --git a/crates/runx-cli/src/skill.rs b/crates/runx-cli/src/skill.rs index 84ecfdc16..64239e610 100644 --- a/crates/runx-cli/src/skill.rs +++ b/crates/runx-cli/src/skill.rs @@ -1,3 +1,4 @@ +// rust-style-allow: large-file - skill command keeps parse, inspect, registry provenance, and execution wiring together until the native skill UX settles. use std::collections::BTreeMap; use std::env; use std::fs; @@ -44,6 +45,7 @@ pub enum SkillAction { Run, } +// rust-style-allow: long-function - the top-level command path owns resolve/inspect/run/failure presentation in one explicit dispatch. pub fn run_native_skill(plan: SkillPlan) -> ExitCode { let cwd = env::current_dir().unwrap_or_else(|_| PathBuf::from(".")); let env = env::vars().collect(); @@ -127,6 +129,7 @@ fn write_skill_inspection( } } +// rust-style-allow: long-function - inspection assembles one public JSON contract from SKILL.md, X.yaml, fixtures, and selected runner metadata. fn inspect_skill( skill_path: &Path, selected_runner: Option<&str>, @@ -210,6 +213,7 @@ fn inspect_skill( Ok(JsonValue::Object(output)) } +// rust-style-allow: long-function - text rendering mirrors the inspect JSON shape and is kept adjacent to avoid presentation drift. fn write_inspection_text(value: &JsonValue) -> ExitCode { let Some(object) = value.as_object() else { return crate::cli_io::write_stdout_code("{}\n", 0); @@ -300,9 +304,9 @@ fn parse_skill_frontmatter(markdown: &str) -> Result { }; serde_norway::from_str::(frontmatter) .map_err(|error| format!("skill frontmatter is invalid YAML: {error}")) - .and_then(|value| match value { - JsonValue::Object(object) => Ok(object), - _ => Ok(JsonObject::new()), + .map(|value| match value { + JsonValue::Object(object) => object, + _ => JsonObject::new(), }) } @@ -409,11 +413,10 @@ fn fixture_targets_runner(path: &Path, runner: &str) -> bool { } fn runner_may_pause(runner: &JsonObject) -> bool { - match object_string(runner, "type") { - Some("agent") | Some("agent-task") => true, - Some("graph") => true, - _ => false, - } + matches!( + object_string(runner, "type"), + Some("agent") | Some("agent-task") | Some("graph") + ) } fn attach_registry_provenance(output: &mut JsonValue, resolved: &ResolvedSkillRef) { diff --git a/crates/runx-cli/src/skill/output.rs b/crates/runx-cli/src/skill/output.rs index 718086a79..24fdb29cc 100644 --- a/crates/runx-cli/src/skill/output.rs +++ b/crates/runx-cli/src/skill/output.rs @@ -103,32 +103,42 @@ fn write_skill_text( writeln!(writer, "summary: {summary}")?; } if let Some(requests) = object.get("requests").and_then(JsonValue::as_array) { - writeln!(writer, "pending_requests: {}", requests.len())?; - for request in requests { - if let Some(request) = request.as_object() { - let id = object_string(request, "id").unwrap_or(""); - let kind = object_string(request, "kind").unwrap_or(""); - writeln!(writer, "- {kind}: {id}")?; - } - } - if let Some(template) = answers_template(requests) { - writeln!(writer, "answers_template:")?; - write_indented_json(writer, &template)?; - } - if let Some(run_id) = object_string(object, "run_id") { - let command = - crate::resume::render_skill_resume_command(crate::resume::SkillResumeCommand { - skill_ref: resume - .skill_ref - .or_else(|| object_string(object, "skill_name")), - run_id, - selected_runner: resume.selected_runner, - receipt_dir: resume.receipt_dir, - answers_path: resume.answers_path, - }); - writeln!(writer, "next: resolve the request, then rerun: {command}")?; + write_pending_requests(writer, object, requests, resume)?; + } + Ok(()) +} + +fn write_pending_requests( + writer: &mut dyn Write, + object: &JsonObject, + requests: &[JsonValue], + resume: SkillOutputResume<'_>, +) -> io::Result<()> { + writeln!(writer, "pending_requests: {}", requests.len())?; + for request in requests { + if let Some(request) = request.as_object() { + let id = object_string(request, "id").unwrap_or(""); + let kind = object_string(request, "kind").unwrap_or(""); + writeln!(writer, "- {kind}: {id}")?; } } + if let Some(template) = answers_template(requests) { + writeln!(writer, "answers_template:")?; + write_indented_json(writer, &template)?; + } + if let Some(run_id) = object_string(object, "run_id") { + let command = + crate::resume::render_skill_resume_command(crate::resume::SkillResumeCommand { + skill_ref: resume + .skill_ref + .or_else(|| object_string(object, "skill_name")), + run_id, + selected_runner: resume.selected_runner, + receipt_dir: resume.receipt_dir, + answers_path: resume.answers_path, + }); + writeln!(writer, "next: resolve the request, then rerun: {command}")?; + } Ok(()) } diff --git a/crates/runx-cli/src/skill/parser.rs b/crates/runx-cli/src/skill/parser.rs index 8858a2f3e..e5563bd4a 100644 --- a/crates/runx-cli/src/skill/parser.rs +++ b/crates/runx-cli/src/skill/parser.rs @@ -32,18 +32,7 @@ pub fn parse_skill_plan(args: &[OsString]) -> Result { }; reject_resolver_flags_for_skill_management_action(skill_path, &state)?; let skill_path = skill_path.clone(); - if state.answers.is_some() && state.run_id.is_none() { - return Err("runx skill --answers requires --run-id".to_owned()); - } - if state.run_id.is_some() && state.answers.is_none() { - return Err("runx skill --run-id requires --answers".to_owned()); - } - - let action = if state.force_run - || state.run_id.is_some() - || state.answers.is_some() - || !state.inputs.is_empty() - { + let action = if state.force_run || !state.inputs.is_empty() { SkillAction::Run } else { SkillAction::Inspect @@ -318,8 +307,8 @@ fn is_skill_management_action(skill_path: &Path) -> bool { } // rust-style-allow: long-function because this is the single skill-flag dispatch -// match (--receipt-dir/--run-id/--answers/--json/--credential and positionals); -// splitting the arms would scatter the CLI parse contract. +// match (--receipt-dir/--json/--credential and positionals); splitting the +// arms would scatter the CLI parse contract. fn parse_skill_arg( args: &[OsString], mut index: usize, @@ -353,29 +342,17 @@ fn parse_skill_arg( index += 1; state.receipt_dir = Some(PathBuf::from(string_arg(args, index)?)); } - value if value.starts_with("--run-id=") => { - state.run_id = Some(value.trim_start_matches("--run-id=").to_owned()); - } - "--run-id" => { - index += 1; - state.run_id = Some(string_arg(args, index)?); - } - value if value.starts_with("--answers=") => { - state.answers = Some(PathBuf::from(value.trim_start_matches("--answers="))); + value if value.starts_with("--run-id=") || value == "--run-id" => { + return Err(skill_resume_flag_error()); } - "--answers" => { - index += 1; - state.answers = Some(PathBuf::from(string_arg(args, index)?)); - } - value if value.starts_with("--runner=") => { - state.runner = Some(non_empty_flag_value( - "--runner", - value.trim_start_matches("--runner="), - )?); + value if value.starts_with("--answers=") || value == "--answers" => { + return Err(skill_resume_flag_error()); } - "--runner" => { - index += 1; - state.runner = Some(non_empty_flag_value("--runner", &string_arg(args, index)?)?); + value if value.starts_with("--runner=") || value == "--runner" => { + return Err( + "runx skill --runner is no longer supported; use `runx skill `" + .to_owned(), + ); } value if value.starts_with("--registry=") => { state.registry = Some(non_empty_flag_value( @@ -497,6 +474,10 @@ fn non_empty_flag_value(flag: &str, value: &str) -> Result { Ok(value.to_owned()) } +fn skill_resume_flag_error() -> String { + "runx skill continuation flags are no longer supported; use `runx resume `".to_owned() +} + fn is_retired_skill_option(token: &str) -> bool { let Some(flag) = token.strip_prefix("--") else { return false; @@ -724,7 +705,7 @@ mod tests { } #[test] - fn input_json_rejects_non_json_values() { + fn input_json_rejects_non_json_values() -> Result<(), String> { let args = [ "skill", "skills/data-store", @@ -735,11 +716,12 @@ mod tests { .into_iter() .map(std::ffi::OsString::from) .collect::>(); - let error = super::parse_skill_plan(&args) - .err() - .expect("invalid json input should fail"); + let Err(error) = super::parse_skill_plan(&args) else { + return Err("invalid json input should fail".to_owned()); + }; assert!(error.contains("--input-json event is invalid JSON")); + Ok(()) } #[test] diff --git a/crates/runx-cli/tests/launcher.rs b/crates/runx-cli/tests/launcher.rs index 440377b44..c4e6e83d4 100644 --- a/crates/runx-cli/tests/launcher.rs +++ b/crates/runx-cli/tests/launcher.rs @@ -324,14 +324,9 @@ fn routes_canonical_skill_run_to_native_plan() { plan(&[ "skill", "skills/issue-intake", - "--runner", "intake", "--receipt-dir", ".runx/receipts", - "--run-id", - "run_agent_task.issue-intake.output", - "--answers", - "/tmp/answers.json", "--json", "--non-interactive", "--input", @@ -344,8 +339,8 @@ fn routes_canonical_skill_run_to_native_plan() { skill_path: PathBuf::from("skills/issue-intake"), runner: Some("intake".to_owned()), receipt_dir: Some(PathBuf::from(".runx/receipts")), - run_id: Some("run_agent_task.issue-intake.output".to_owned()), - answers: Some(PathBuf::from("/tmp/answers.json")), + run_id: None, + answers: None, registry: None, expected_digest: None, json: true, @@ -367,11 +362,21 @@ fn routes_canonical_skill_run_to_native_plan() { } #[test] -fn skill_rejects_partial_continuation_shape() { +fn skill_rejects_legacy_runner_and_continuation_flags() { assert_eq!( - plan(&["skill", "skills/issue-intake", "--run-id", "run_123"]), - LauncherAction::Error("runx skill --run-id requires --answers".to_owned()) + plan(&["skill", "skills/issue-intake", "--runner", "intake"]), + LauncherAction::Error( + "runx skill --runner is no longer supported; use `runx skill `" + .to_owned() + ) ); + assert_eq!( + plan(&["skill", "skills/issue-intake", "--run-id", "run_123"]), + LauncherAction::Error( + "runx skill continuation flags are no longer supported; use `runx resume `" + .to_owned() + ) + ); assert_eq!( plan(&[ "skill", @@ -379,8 +384,11 @@ fn skill_rejects_partial_continuation_shape() { "--answers", "/tmp/answers.json", ]), - LauncherAction::Error("runx skill --answers requires --run-id".to_owned()) - ); + LauncherAction::Error( + "runx skill continuation flags are no longer supported; use `runx resume `" + .to_owned() + ) + ); } #[test] diff --git a/crates/runx-cli/tests/skill.rs b/crates/runx-cli/tests/skill.rs index 764b583af..ed965e5e1 100644 --- a/crates/runx-cli/tests/skill.rs +++ b/crates/runx-cli/tests/skill.rs @@ -51,16 +51,12 @@ fn native_skill_pauses_and_resumes_with_run_id() -> Result<(), Box Result<(), Box> { - let root = crate::support::temp_root("runx-skill-runner-flag"); +fn native_skill_positional_runner_selects_non_default_runner() +-> Result<(), Box> { + let root = crate::support::temp_root("runx-skill-positional-runner"); let skill_dir = write_multi_runner_skill(&root)?; let receipt_dir = root.join("receipts"); @@ -126,8 +123,8 @@ fn native_skill_runner_flag_selects_non_default_runner() -> Result<(), Box Result<(), Box> { +fn native_skill_rejects_legacy_answers_flag() -> Result<(), Box> { let root = crate::support::temp_root("runx-skill-reject-answers"); let skill_dir = write_agent_task_skill(&root)?; let answers_path = root.join("answers.json"); @@ -480,14 +476,16 @@ fn native_skill_rejects_answers_without_run_id() -> Result<(), Box `") + ); assert_eq!(String::from_utf8(output.stdout)?, ""); Ok(()) } #[test] -fn native_skill_rejects_run_id_without_answers() -> Result<(), Box> { +fn native_skill_rejects_legacy_run_id_flag() -> Result<(), Box> { let root = crate::support::temp_root("runx-skill-reject-run-id"); let skill_dir = write_agent_task_skill(&root)?; let output = runx_command() @@ -500,7 +498,9 @@ fn native_skill_rejects_run_id_without_answers() -> Result<(), Box `") + ); assert_eq!(String::from_utf8(output.stdout)?, ""); Ok(()) diff --git a/crates/runx-runtime/src/adapters/catalog.rs b/crates/runx-runtime/src/adapters/catalog.rs index 5dc49877f..124bb5fd0 100644 --- a/crates/runx-runtime/src/adapters/catalog.rs +++ b/crates/runx-runtime/src/adapters/catalog.rs @@ -223,6 +223,7 @@ fn data_source_binding( Ok(None) } +// rust-style-allow: long-function - the style scanner over-counts this compact source collector because of surrounding let-else control flow. fn data_source_config_sources( env: &BTreeMap, skill_directory: &Path, @@ -253,6 +254,7 @@ fn data_source_config_sources( sources } +// rust-style-allow: long-function - the style scanner over-counts this compact config reader because of surrounding let-else control flow. fn read_data_source_config_source( source: &DataSourceConfigSource, ) -> Result, String> { diff --git a/crates/runx-runtime/src/execution/skill_front/agent.rs b/crates/runx-runtime/src/execution/skill_front/agent.rs index b6a27cb81..e13f5d1a2 100644 --- a/crates/runx-runtime/src/execution/skill_front/agent.rs +++ b/crates/runx-runtime/src/execution/skill_front/agent.rs @@ -6,9 +6,11 @@ use super::{ use runx_contracts::{ClosureDisposition, JsonObject, JsonValue}; +use crate::RuntimeError; use crate::adapter::{InvocationStatus, SkillInvocation, SkillOutput}; use crate::agent_invocation::agent_act_invocation_id; use crate::execution::orchestrator::SkillRunRequest; +use crate::journal::{PausedRunCheckpoint, append_paused_run_checkpoint}; use crate::receipts::{DomainActReceiptRequest, domain_act_receipt}; use crate::services::{ReceiptServices, WorkspaceEnv}; use runx_parser::{SkillRunnerDefinition, SkillRunnerManifest}; @@ -46,6 +48,15 @@ pub(super) fn execute_agent_skill_run( #[cfg(feature = "agent")] InlineAgentOutcome::Resolved { payload, effect } => (payload, effect), InlineAgentOutcome::HostDrives => { + write_paused_agent_checkpoint( + request, + workspace, + receipts, + manifest, + runner, + &run_id, + &request_id, + )?; return Ok(JsonValue::Object(needs_agent_output( &run_id, &request_id, @@ -96,6 +107,42 @@ pub(super) fn execute_agent_skill_run( ))) } +fn write_paused_agent_checkpoint( + request: &SkillRunRequest, + workspace: &WorkspaceEnv, + receipts: &ReceiptServices, + manifest: &SkillRunnerManifest, + runner: &SkillRunnerDefinition, + run_id: &str, + request_id: &str, +) -> Result<(), SkillRunError> { + let receipt_path = receipts.resolve_path(workspace, request.receipt_dir.as_deref(), None); + let checkpoint = PausedRunCheckpoint { + id: run_id.to_owned(), + name: manifest + .skill + .clone() + .unwrap_or_else(|| runner.name.clone()), + kind: "agent".to_owned(), + started_at: Some(crate::time::now_iso8601()), + resume_skill_ref: Some(request.skill_path.to_string_lossy().into_owned()), + selected_runner: Some(runner.name.clone()), + step_ids: vec![request_id.to_owned()], + step_labels: vec![runner.name.clone()], + }; + append_paused_run_checkpoint(&receipt_path.path, &checkpoint).map_err(|source| { + RuntimeError::io( + format!( + "writing paused run checkpoint for {} in {}", + checkpoint.id, + receipt_path.path.display() + ), + source, + ) + })?; + Ok(()) +} + /// Outcome of attempting the optional in-process managed-agent loop. enum InlineAgentOutcome { /// The in-kernel loop ran and produced the agent answer payload, plus the last @@ -178,8 +225,12 @@ fn try_inline_agent_resolution( fn agent_run_id(request: &SkillRunRequest, request_id: &str) -> Result { match (&request.run_id, &request.answers_path) { (Some(run_id), Some(_)) => Ok(run_id.clone()), - (Some(_), None) => Err(invalid("runx skill --run-id requires --answers")), - (None, Some(_)) => Err(invalid("runx skill --answers requires --run-id")), + (Some(_), None) => Err(invalid( + "skill continuation requires both run_id and answers", + )), + (None, Some(_)) => Err(invalid( + "skill continuation requires both run_id and answers", + )), (None, None) => Ok(format!("run_{}", identifier_segment(request_id))), } } diff --git a/crates/runx-runtime/src/execution/skill_front/graph.rs b/crates/runx-runtime/src/execution/skill_front/graph.rs index 8540000d6..04dcb0471 100644 --- a/crates/runx-runtime/src/execution/skill_front/graph.rs +++ b/crates/runx-runtime/src/execution/skill_front/graph.rs @@ -619,8 +619,12 @@ fn graph_run_id( ) -> Result { match (&request.run_id, &request.answers_path) { (Some(run_id), Some(_)) => Ok(run_id.clone()), - (Some(_), None) => Err(invalid("runx skill --run-id requires --answers")), - (None, Some(_)) => Err(invalid("runx skill --answers requires --run-id")), + (Some(_), None) => Err(invalid( + "skill continuation requires both run_id and answers", + )), + (None, Some(_)) => Err(invalid( + "skill continuation requires both run_id and answers", + )), (None, None) => { let input_bytes = serde_json::to_vec(&request.inputs).unwrap_or_default(); let digest = sha256_hex(&input_bytes); diff --git a/crates/runx-runtime/src/execution/skill_front/runner_manifest.rs b/crates/runx-runtime/src/execution/skill_front/runner_manifest.rs index 823742737..776b69697 100644 --- a/crates/runx-runtime/src/execution/skill_front/runner_manifest.rs +++ b/crates/runx-runtime/src/execution/skill_front/runner_manifest.rs @@ -160,7 +160,7 @@ pub(super) fn execute_cli_tool_skill_run( ) -> Result { if request.answers_path.is_some() { return Err(invalid( - "runx skill cli-tool runners do not support --answers", + "cli-tool runners do not support continuation answers", )); } let run_id = request diff --git a/crates/runx-runtime/src/journal.rs b/crates/runx-runtime/src/journal.rs index 012bfbe3c..e2eade60c 100644 --- a/crates/runx-runtime/src/journal.rs +++ b/crates/runx-runtime/src/journal.rs @@ -4,6 +4,7 @@ use std::collections::BTreeSet; use std::fs; use std::io::ErrorKind; +use std::io::Write; use std::path::Path; use runx_contracts::schema::NonEmptyString; @@ -123,6 +124,40 @@ pub struct PausedRunCheckpoint { pub step_labels: Vec, } +pub fn append_paused_run_checkpoint( + receipt_dir: &Path, + checkpoint: &PausedRunCheckpoint, +) -> Result<(), std::io::Error> { + let ledgers_dir = receipt_dir.join("ledgers"); + fs::create_dir_all(&ledgers_dir)?; + let ledger_path = ledgers_dir.join(format!("{}.jsonl", checkpoint.id)); + let mut file = fs::OpenOptions::new() + .create(true) + .append(true) + .open(ledger_path)?; + let entry = LedgerEntry { + entry_type: "run_event".to_owned(), + data: LedgerEventData { + kind: "resolution_requested".to_owned(), + detail: LedgerEventDetail { + resume_skill_ref: checkpoint.resume_skill_ref.clone(), + selected_runner: checkpoint.selected_runner.clone(), + step_ids: checkpoint.step_ids.clone(), + step_labels: checkpoint.step_labels.clone(), + }, + }, + meta: LedgerEventMeta { + created_at: checkpoint.started_at.clone(), + producer: Some(LedgerEventProducer { + skill: Some(checkpoint.name.clone()), + runner: checkpoint.selected_runner.clone(), + }), + }, + }; + serde_json::to_writer(&mut file, &entry)?; + file.write_all(b"\n") +} + #[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)] pub struct JournalProjection { pub schema: String, @@ -729,7 +764,7 @@ fn ledger_run_id(path: &Path) -> Option { return None; } let run_id = path.file_stem()?.to_str()?; - if !(run_id.starts_with("rx_") || run_id.starts_with("gx_")) + if !(run_id.starts_with("rx_") || run_id.starts_with("gx_") || run_id.starts_with("run_")) || !run_id .chars() .all(|character| character.is_ascii_alphanumeric() || matches!(character, '_' | '-')) @@ -774,7 +809,7 @@ enum LedgerLine { Entry(LedgerEntry), } -#[derive(Clone, Debug, Deserialize)] +#[derive(Clone, Debug, Deserialize, Serialize)] struct LedgerEntry { #[serde(rename = "type")] entry_type: String, @@ -782,14 +817,14 @@ struct LedgerEntry { meta: LedgerEventMeta, } -#[derive(Clone, Debug, Deserialize)] +#[derive(Clone, Debug, Deserialize, Serialize)] struct LedgerEventData { kind: String, #[serde(default)] detail: LedgerEventDetail, } -#[derive(Clone, Debug, Default, Deserialize)] +#[derive(Clone, Debug, Default, Deserialize, Serialize)] struct LedgerEventDetail { #[serde(default)] resume_skill_ref: Option, @@ -801,7 +836,7 @@ struct LedgerEventDetail { step_labels: Vec, } -#[derive(Clone, Debug, Deserialize)] +#[derive(Clone, Debug, Deserialize, Serialize)] struct LedgerEventMeta { #[serde(default)] created_at: Option, @@ -809,7 +844,7 @@ struct LedgerEventMeta { producer: Option, } -#[derive(Clone, Debug, Deserialize)] +#[derive(Clone, Debug, Deserialize, Serialize)] struct LedgerEventProducer { #[serde(default)] skill: Option, diff --git a/crates/runx-runtime/src/registry/trust_anchor.rs b/crates/runx-runtime/src/registry/trust_anchor.rs index 2458654f4..4b369de46 100644 --- a/crates/runx-runtime/src/registry/trust_anchor.rs +++ b/crates/runx-runtime/src/registry/trust_anchor.rs @@ -359,11 +359,15 @@ mod tests { #[test] fn official_source_trust_key_is_official_scoped_without_owner() { - let keys = trusted_registry_manifest_keys_from_env_with_source( + let result = trusted_registry_manifest_keys_from_env_with_source( &trust_env(), Some(RegistryManifestSourceAuthority::OfficialRunx), - ) - .expect("official source trust key should be accepted"); + ); + assert!( + result.is_ok(), + "official source trust key should be accepted: {result:?}" + ); + let keys = result.unwrap_or_default(); assert_eq!( keys.last().map(|key| &key.scope), @@ -373,14 +377,13 @@ mod tests { #[test] fn third_party_source_trust_key_still_requires_owner() { - let error = trusted_registry_manifest_keys_from_env_with_source( + let result = trusted_registry_manifest_keys_from_env_with_source( &trust_env(), Some(RegistryManifestSourceAuthority::RegistrySource( "local:/tmp/runx-registry".to_owned(), )), - ) - .expect_err("third-party trust key must be owner-scoped"); + ); - assert_eq!(error, RegistryManifestTrustEnvError::MissingOwner); + assert_eq!(result, Err(RegistryManifestTrustEnvError::MissingOwner)); } } diff --git a/crates/runx-runtime/src/services/env.rs b/crates/runx-runtime/src/services/env.rs index 349daaac0..edca18595 100644 --- a/crates/runx-runtime/src/services/env.rs +++ b/crates/runx-runtime/src/services/env.rs @@ -90,21 +90,23 @@ mod tests { use super::merge_path_env; #[test] - fn merge_path_env_appends_new_paths_and_deduplicates_existing_paths() { + fn merge_path_env_appends_new_paths_and_deduplicates_existing_paths() + -> Result<(), std::env::JoinPathsError> { let first = PathBuf::from("/runx/tools"); let second = PathBuf::from("/runx/skills/data-store/tools"); - let existing = std::env::join_paths([first.as_path()]) - .unwrap() - .to_string_lossy() - .into_owned(); - let addition = std::env::join_paths([second.as_path(), first.as_path()]) - .unwrap() - .to_string_lossy() - .into_owned(); + let existing = path_list_string([first.as_path()])?; + let addition = path_list_string([second.as_path(), first.as_path()])?; let merged = merge_path_env(&existing, &addition); let paths = std::env::split_paths(&merged).collect::>(); assert_eq!(paths, vec![first, second]); + Ok(()) + } + + fn path_list_string<'a>( + paths: impl IntoIterator, + ) -> Result { + std::env::join_paths(paths).map(|value| value.to_string_lossy().into_owned()) } } diff --git a/crates/runx-runtime/tests/mcp_server.rs b/crates/runx-runtime/tests/mcp_server.rs index 739c01ba6..fbd092998 100644 --- a/crates/runx-runtime/tests/mcp_server.rs +++ b/crates/runx-runtime/tests/mcp_server.rs @@ -625,7 +625,7 @@ fn mcp_server_host_result_conversion_covers_terminal_statuses() { }); assert_eq!( needs_agent.content[0].text, - "echo needs agent input at run-1. Continue by rerunning the same skill with --run-id run-1 --answers answers.json after resolving 2 request(s)." + "echo needs agent input at run-1. Resolve 2 request(s), write answers.json, then run: runx resume run-1 answers.json." ); assert!(!needs_agent.is_error); diff --git a/crates/runx-runtime/tests/skill_run.rs b/crates/runx-runtime/tests/skill_run.rs index ce7624efd..f3ba60d44 100644 --- a/crates/runx-runtime/tests/skill_run.rs +++ b/crates/runx-runtime/tests/skill_run.rs @@ -2217,7 +2217,7 @@ fn native_skill_run_rejects_partial_continuation_shape() -> Result<(), Box Result<(), Box RunxResult { let mut args = vec!["skill".to_owned(), skill_ref.to_owned()]; if let Some(runner) = options.runner { - args.push("--runner".to_owned()); args.push(runner); } for (name, value) in options.inputs { @@ -119,18 +118,15 @@ impl RunxClient { pub fn continue_run( &self, - skill_ref: &str, + _skill_ref: &str, run_id: &str, payload: ContinuePayload, ) -> RunxResult { let answers_path = write_continue_payload(payload)?; let result = self.run_json( vec![ - "skill".to_owned(), - skill_ref.to_owned(), - "--run-id".to_owned(), + "resume".to_owned(), run_id.to_owned(), - "--answers".to_owned(), answers_path.to_string_lossy().into_owned(), ], None, diff --git a/crates/runx-sdk/tests/client_cli.rs b/crates/runx-sdk/tests/client_cli.rs index 6b4e614f2..95f808c7a 100644 --- a/crates/runx-sdk/tests/client_cli.rs +++ b/crates/runx-sdk/tests/client_cli.rs @@ -49,7 +49,7 @@ fn continue_run_writes_answers_file_for_canonical_skill_rerun() assert_eq!(report.status(), Some("sealed")); let args = fs::read_to_string(fixture.args_path())?; - assert!(args.starts_with("skill\nskills/example\n--run-id\nrun-123\n--answers\n")); + assert!(args.starts_with("resume\nrun-123\n")); assert!(args.ends_with("\n--json\n")); assert_eq!( fs::read_to_string(fixture.stdin_path())?, @@ -131,8 +131,8 @@ fn fake_runx_script() -> &'static str { printf '%s\n' "$@" > "$RUNX_SDK_ARGS" if [ "$1" = "skill" ] && [ "$2" = "search" ]; then printf '%s\n' '{"status":"success","results":[{"skill_id":"acme/sourcey","name":"sourcey","owner":"acme","source":"runx-registry","source_label":"runx registry","source_type":"cli-tool","trust_tier":"community","required_scopes":["repo:read"],"tags":["docs"],"version":"1.0.0"}]}' -elif [ "$1" = "skill" ] && [ "$3" = "--run-id" ]; then - cat "$6" > "$RUNX_SDK_STDIN" +elif [ "$1" = "resume" ]; then + cat "$3" > "$RUNX_SDK_STDIN" printf '%s\n' '{"status":"sealed","args":["skill"]}' else printf '%s\n' '{"status":"success","args":["skill"]}' diff --git a/dist/packets/effect.transition.v1.schema.json b/dist/packets/effect.transition.v1.schema.json new file mode 100644 index 000000000..18deb9415 --- /dev/null +++ b/dist/packets/effect.transition.v1.schema.json @@ -0,0 +1,40 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.runx.dev/runx/effect/transition/v1.json", + "x-runx-packet-id": "runx.effect.transition.v1", + "type": "object", + "properties": { + "effect_family": { "type": "string", "minLength": 1 }, + "operation": { "type": "string", "minLength": 1 }, + "actor_kid": { "type": "string" }, + "moderator_kid": { "type": "string" }, + "posting_id": { "type": "string" }, + "posting": { + "type": "object", + "additionalProperties": true + }, + "claim": { + "type": "object", + "additionalProperties": true + }, + "delivery": { + "type": "object", + "additionalProperties": true + }, + "judgment": { + "type": "object", + "additionalProperties": true + }, + "funding": { + "type": "object", + "additionalProperties": true + }, + "clocks": { + "type": "object", + "additionalProperties": true + }, + "stop_conditions": { "type": "array" } + }, + "required": ["effect_family", "operation"], + "additionalProperties": true +} diff --git a/dist/packets/github-sync.v1.schema.json b/dist/packets/github-sync.v1.schema.json new file mode 100644 index 000000000..a2e44d5c0 --- /dev/null +++ b/dist/packets/github-sync.v1.schema.json @@ -0,0 +1,26 @@ +{ + "$schema": "https://json-schema.org/draft/2020-12/schema", + "$id": "https://schemas.runx.dev/runx/github-sync/v1.json", + "x-runx-packet-id": "runx.github_sync.v1", + "type": "object", + "properties": { + "repo": { "type": "string", "minLength": 1 }, + "direction": { + "type": "string", + "enum": ["pull", "push"] + }, + "resources": { + "type": "object", + "additionalProperties": true + }, + "scope": { "type": "string" }, + "cursor": { + "type": "object", + "additionalProperties": true + }, + "planned_actions": { "type": "array" }, + "stop_conditions": { "type": "array" } + }, + "required": ["repo", "direction", "resources", "scope"], + "additionalProperties": true +} diff --git a/docs/issue-to-pr.md b/docs/issue-to-pr.md index 6e147814f..d3f35afcf 100644 --- a/docs/issue-to-pr.md +++ b/docs/issue-to-pr.md @@ -229,7 +229,7 @@ continuation command. Resolve that request into an answers file, then resume the same native run: ```bash -pnpm dogfood:github-issue-to-pr -- --mode create --run-id --answers answers.json --allow-repo owner/repo --repo owner/repo --issue 123 --workspace /path/to/repo +runx resume answers.json --receipt-dir /path/to/repo/.runx/receipts --json ``` When the graph seals, provider push runs through the `issue-to-pr-push-outbox` diff --git a/fixtures/cli-parity/cases/oracle.json b/fixtures/cli-parity/cases/oracle.json index fc0825dce..fd11628e4 100644 --- a/fixtures/cli-parity/cases/oracle.json +++ b/fixtures/cli-parity/cases/oracle.json @@ -140,6 +140,17 @@ "official-skills" ] }, + { + "id": "resume.validate", + "commandId": "resume", + "mode": "validate", + "proves": [ + "caller-mediated-resolution", + "graph-runtime", + "receipts", + "cli-presentation" + ] + }, { "id": "verify.validate", "commandId": "verify", diff --git a/fixtures/cli-parity/commands.json b/fixtures/cli-parity/commands.json index c5c7c52e4..a4832bc5d 100644 --- a/fixtures/cli-parity/commands.json +++ b/fixtures/cli-parity/commands.json @@ -134,6 +134,41 @@ "history.execute" ] }, + { + "id": "resume", + "usage": "runx resume ", + "aliases": [], + "requiredPositionals": [ + "", + "" + ], + "flags": [ + "--receipt-dir", + "--non-interactive", + "--json" + ], + "exitCodes": [ + 0, + 1, + 2, + 64 + ], + "parity": { + "humanOutput": "semantic", + "jsonOutput": "schema-exact", + "receipt": "schema-exact", + "sideEffect": "local-runtime", + "surfaces": [ + "caller-mediated-resolution", + "graph-runtime", + "receipts", + "cli-presentation" + ] + }, + "cases": [ + "resume.validate" + ] + }, { "id": "verify", "usage": "runx verify [receipt-id]", @@ -621,7 +656,7 @@ }, { "id": "skill.run", - "usage": "runx skill ", + "usage": "runx skill [runner]", "aliases": [], "requiredPositionals": [ "" @@ -629,11 +664,8 @@ "flags": [ "--registry", "--digest", - "--runner", "--input", "--receipt-dir", - "--run-id", - "--answers", "--credential", "--secret-env", "--non-interactive", diff --git a/packages/cli/src/args.ts b/packages/cli/src/args.ts index 9d5be71db..a285d7c5e 100644 --- a/packages/cli/src/args.ts +++ b/packages/cli/src/args.ts @@ -57,6 +57,8 @@ export interface ParsedArgs { readonly answersPath?: string; readonly receiptDir?: string; readonly runner?: string; + readonly skillRunnerFlagUsed: boolean; + readonly skillContinuationFlagUsed: boolean; readonly forceRun: boolean; readonly knowledgeProject?: string; readonly sourceFilter?: string; @@ -94,6 +96,8 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { let receiptDir: string | undefined; let runId: string | undefined; let runner: string | undefined; + let runnerFlagUsed = false; + let continuationFlagUsed = false; let forceRun = false; for (let index = 0; index < rest.length; index += 1) { @@ -134,6 +138,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { } if (knownKey === "answers") { + continuationFlagUsed = true; answersPath = String(value); continue; } @@ -144,11 +149,13 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { } if (knownKey === "runId") { + continuationFlagUsed = true; runId = String(value); continue; } if (knownKey === "runner") { + runnerFlagUsed = true; runner = String(value); continue; } @@ -171,6 +178,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { const isNew = command === "new"; const isInit = command === "init"; const isReplay = command === "replay"; + const isResume = command === "resume"; const isDiff = command === "diff"; const isDoctor = command === "doctor"; const isTool = command === "tool"; @@ -205,6 +213,8 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { const registryUrl = (isSkillSearch || isTopLevelAdd || isSkillPublish || isSkillRun) && typeof inputs.registry === "string" ? inputs.registry : undefined; const expectedDigest = (isTopLevelAdd || isSkillRun) && typeof inputs.digest === "string" ? normalizeDigest(inputs.digest) : undefined; const selectedRunner = runner ?? (isSkillRun ? positionals[1] : undefined); + const selectedRunId = isResume ? positionals[0] : runId; + const selectedAnswersPath = isResume ? positionals[1] : answersPath; const newDirectory = isNew && typeof inputs.directory === "string" ? inputs.directory : isNew && typeof inputs.dir === "string" @@ -287,6 +297,7 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { receiptPublishToken, receiptPublishAllowLocalApi, receiptId: isSkillInspect ? inspectPositionals[0] : undefined, + runId: selectedRunId, replayRef: isReplay ? positionals[0] : undefined, diffLeft: isDiff ? positionals[0] : undefined, diffRight: isDiff ? positionals[1] : undefined, @@ -310,10 +321,11 @@ export function parseArgs(argv: readonly string[]): ParsedArgs { inputs: effectiveInputs, nonInteractive, json, - answersPath, + answersPath: selectedAnswersPath, receiptDir, - runId, runner: selectedRunner, + skillRunnerFlagUsed: isSkillRun && runnerFlagUsed, + skillContinuationFlagUsed: isSkillRun && continuationFlagUsed, forceRun, knowledgeProject, sourceFilter, @@ -379,6 +391,9 @@ export function isSupportedCommand(parsed: ParsedArgs): boolean { if (parsed.command === "publish" && parsed.receiptPublishPath) { return true; } + if (parsed.command === "resume" && parsed.runId && parsed.answersPath) { + return true; + } if (parsed.skillPath) { return true; } diff --git a/packages/cli/src/callers.ts b/packages/cli/src/callers.ts index 45312ffa8..11bbb313d 100644 --- a/packages/cli/src/callers.ts +++ b/packages/cli/src/callers.ts @@ -66,7 +66,7 @@ export function createAgentRuntimeLoader( export async function readCallerInputFile(answersPath: string): Promise { const parsed = JSON.parse(await readFile(answersPath, "utf8")) as unknown; if (!isRecord(parsed)) { - throw new Error("--answers file must contain a JSON object."); + throw new Error("answers file must contain a JSON object."); } if (parsed.answers === undefined && parsed.approvals === undefined) { return { @@ -78,13 +78,13 @@ export async function readCallerInputFile(answersPath: string): Promise 0) { throw new Error( - `--answers file mixes top-level keys [${extraTopLevelKeys.join(", ")}] with the nested 'answers'/'approvals' shape. ` + + `answers file mixes top-level keys [${extraTopLevelKeys.join(", ")}] with the nested 'answers'/'approvals' shape. ` + "Use either the flat shape (top-level keys = answers, no 'approvals') " + "or the nested shape ({ answers: {...}, approvals: {...} }), not both.", ); } if (parsed.answers !== undefined && !isRecord(parsed.answers)) { - throw new Error("--answers answers field must be an object."); + throw new Error("answers field must be an object."); } return { answers: parsed.answers === undefined ? {} : parsed.answers, @@ -260,12 +260,12 @@ function validateCallerApprovals(value: unknown): boolean | Readonly { if (typeof approval !== "boolean") { - throw new Error(`--answers approvals.${key} must be a boolean.`); + throw new Error(`answers approvals.${key} must be a boolean.`); } return [key, approval]; }), diff --git a/packages/cli/src/dispatch.ts b/packages/cli/src/dispatch.ts index 82108ad1d..a4b845997 100644 --- a/packages/cli/src/dispatch.ts +++ b/packages/cli/src/dispatch.ts @@ -228,6 +228,15 @@ export async function dispatchCli( return await streamNativeRunxToIo(io, args, env); } + if (parsed.command === "resume" && parsed.runId && parsed.answersPath) { + const resumeEnv = await withBundledCliToolRoots(env); + const args = ["resume", parsed.runId, resolvePathFromUserInput(parsed.answersPath, env)]; + pushOptionalFlag(args, "--receipt-dir", parsed.receiptDir ? resolvePathFromUserInput(parsed.receiptDir, env) : undefined); + if (parsed.json) args.push("--json"); + if (parsed.nonInteractive) args.push("--non-interactive"); + return await streamNativeRunxToIo(io, args, resumeEnv); + } + if (parsed.command === "add") { const unknownFlag = firstUnknownAddFlag(parsed.inputs); if (unknownFlag) { @@ -403,20 +412,24 @@ async function executeLocalSkillCommand(options: { const env = await withBundledCliToolRoots(options.env); const resolvedReceiptDir = options.parsed.receiptDir ? resolvePathFromUserInput(options.parsed.receiptDir, env) : undefined; - const args = ["skill", options.skillPath, ...inputArgs(options.inputs), "--json"]; + if (options.parsed.skillRunnerFlagUsed) { + throw new Error("runx skill --runner is no longer supported; use `runx skill `."); + } + if (options.parsed.skillContinuationFlagUsed) { + throw new Error("runx skill continuation flags are no longer supported; use `runx resume `."); + } + + const args = ["skill", options.skillPath]; + if (options.parsed.runner) { + args.push(options.parsed.runner); + } + args.push(...inputArgs(options.inputs), "--json"); pushOptionalFlag(args, "--registry", options.parsed.registryUrl); pushOptionalFlag(args, "--digest", options.parsed.expectedDigest); - pushOptionalFlag(args, "--runner", options.parsed.runner); if (options.parsed.forceRun) { args.push("--run"); } pushOptionalFlag(args, "--receipt-dir", resolvedReceiptDir); - pushOptionalFlag(args, "--run-id", options.parsed.runId); - pushOptionalFlag( - args, - "--answers", - options.parsed.answersPath ? resolvePathFromUserInput(options.parsed.answersPath, env) : undefined, - ); if (options.parsed.nonInteractive) { args.push("--non-interactive"); } diff --git a/packages/cli/src/index.test.ts b/packages/cli/src/index.test.ts index 67c35c181..1eb749aeb 100644 --- a/packages/cli/src/index.test.ts +++ b/packages/cli/src/index.test.ts @@ -170,12 +170,12 @@ Return the provided task id. const secondStdout = createMemoryStream(); const secondStderr = createMemoryStream(); const secondExitCode = await runCli( - ["skill", skillDir, "--task-id", "abc-123", "--run-id", firstJson.run_id, "--answers", answersPath, "--receipt-dir", receiptDir, "--non-interactive", "--json"], + ["resume", firstJson.run_id, answersPath, "--receipt-dir", receiptDir, "--non-interactive", "--json"], { stdin: process.stdin, stdout: secondStdout, stderr: secondStderr }, hostDrivenAgentEnv(tempDir), ); - expect(secondExitCode).toBe(0); + expect(secondExitCode, secondStdout.contents() + secondStderr.contents()).toBe(0); expect(secondStderr.contents()).toBe(""); const secondJson = JSON.parse(secondStdout.contents()) as { execution: { stdout: string }; status: string }; expect(secondJson).toMatchObject({ @@ -205,13 +205,21 @@ Return the provided task id. "--non-interactive", "--receipt-dir", "/tmp/receipts", - "--run-id", - "rx_123", ]); expect(parsed.nonInteractive).toBe(true); expect(parsed.receiptDir).toBe("/tmp/receipts"); + expect(parsed.inputs).toEqual({}); + }); + + it("parses resume as the canonical continuation command", () => { + const parsed = parseArgs(["resume", "rx_123", "answers.json", "--receipt-dir", "/tmp/receipts", "--json"]); + + expect(parsed.command).toBe("resume"); expect(parsed.runId).toBe("rx_123"); + expect(parsed.answersPath).toBe("answers.json"); + expect(parsed.receiptDir).toBe("/tmp/receipts"); + expect(parsed.json).toBe(true); expect(parsed.inputs).toEqual({}); }); @@ -301,7 +309,7 @@ Return the provided task id. expect(parsed.inputs).toEqual({}); }); - it("requires native answer continuation to include a run id", async () => { + it("rejects legacy skill continuation flags with resume guidance", async () => { const stdout = createMemoryStream(); const stderr = createMemoryStream(); const exitCode = await runCli( @@ -312,8 +320,8 @@ Return the provided task id. expect(exitCode).toBe(1); expect(stdout.contents()).toBe(""); - expect(stderr.contents()).toContain("native runx skill"); - expect(stderr.contents()).toContain("runx skill --answers requires --run-id"); + expect(stderr.contents()).toContain("runx skill continuation flags are no longer supported"); + expect(stderr.contents()).toContain("runx resume "); }); it("renders human-friendly needs-agent guidance for native agent-task runs", async () => { @@ -839,12 +847,12 @@ Return the grounded label. const continuedStdout = createMemoryStream(); const continuedStderr = createMemoryStream(); const continuedExit = await runCli( - ["skill", skillDir, "--prompt", "hello", "--run-id", first.run_id, "--answers", answersPath, "--receipt-dir", receiptDir, "--non-interactive", "--json"], + ["resume", first.run_id, answersPath, "--receipt-dir", receiptDir, "--non-interactive", "--json"], { stdin: process.stdin, stdout: continuedStdout, stderr: continuedStderr }, env, ); - expect(continuedExit).toBe(0); + expect(continuedExit, continuedStdout.contents() + continuedStderr.contents()).toBe(0); expect(continuedStderr.contents()).toBe(""); const continued = JSON.parse(continuedStdout.contents()) as { execution: { stdout: string } }; expect(JSON.parse(continued.execution.stdout)).toMatchObject({ summary: "grounded from caller answer" }); diff --git a/packages/cli/src/presentation/run-result.ts b/packages/cli/src/presentation/run-result.ts index ddf5efb45..bca237818 100644 --- a/packages/cli/src/presentation/run-result.ts +++ b/packages/cli/src/presentation/run-result.ts @@ -98,7 +98,7 @@ function writeNeedsAgentResult( const requestIds = result.requests.map((request) => request.id).join(", "); io.stderr.write( `runx: production run ${result.runId} halted with unresolved cognitive-work request(s): ${requestIds}\n` - + " RUNX_PRODUCTION=1 forbids pausing; supply --answers or unset RUNX_PRODUCTION to allow pause semantics.\n", + + " RUNX_PRODUCTION=1 forbids pausing; unset RUNX_PRODUCTION to allow pause/resume semantics.\n", ); } return 2; diff --git a/scripts/dogfood-github-issue-to-pr.mjs b/scripts/dogfood-github-issue-to-pr.mjs index 19ec1059a..791a61285 100644 --- a/scripts/dogfood-github-issue-to-pr.mjs +++ b/scripts/dogfood-github-issue-to-pr.mjs @@ -318,7 +318,7 @@ Mutation gates: Examples: pnpm live:issue-to-pr -- --allow-repo owner/repo --repo owner/repo --issue 123 --workspace /repo pnpm dogfood:github-issue-to-pr -- --mode create --prepare-branch --allow-repo owner/repo --repo owner/repo --issue 123 --workspace /repo - pnpm dogfood:github-issue-to-pr -- --mode create --run-id --answers answers.json --allow-repo owner/repo --repo owner/repo --issue 123 --workspace /repo + runx resume answers.json --receipt-dir /repo/.runx/receipts --json pnpm dogfood:github-issue-to-pr -- --mode observe --allow-repo owner/repo --repo owner/repo --issue 123 --workspace /repo `; } @@ -395,8 +395,6 @@ async function buildDogfoodPreflight({ args: argsRecord, issueRef, workspace, sc argsRecord.scafld_bin ? `--scafld-bin ${shellQuote(argsRecord.scafld_bin)}` : "", argsRecord.runx_bin ? `--runx-bin ${shellQuote(argsRecord.runx_bin)}` : "", argsRecord.skill ? `--skill ${shellQuote(argsRecord.skill)}` : "", - argsRecord.run_id ? `--run-id ${shellQuote(argsRecord.run_id)}` : "", - argsRecord.answers ? `--answers ${shellQuote(argsRecord.answers)}` : "", argsRecord.receipt_dir ? `--receipt-dir ${shellQuote(argsRecord.receipt_dir)}` : "", ].filter(Boolean).join(" "); @@ -570,7 +568,7 @@ function inspectContinuationArgs(argsRecord, taskId, issueRef, workspace) { }, task_id: taskId, workspace: summarizeLocalPath(workspace), - next: "First run create mode without --answers, then rerun with the returned run_id and --answers file.", + next: "First run create mode without an answers file, then continue with the returned run_id and answers file.", }; } if (runId && !answers) { @@ -587,7 +585,7 @@ function inspectContinuationArgs(argsRecord, taskId, issueRef, workspace) { task_id: taskId, run_id: runId, workspace: summarizeLocalPath(workspace), - next: "Pass --answers with --run-id so the native graph can resume the stored run state.", + next: "Provide an answers file with the run_id so the native graph can resume the stored run state.", }; } return undefined; @@ -606,6 +604,22 @@ function buildIssueToPrSkillInvocation({ repoSnapshot, }) { const skillPath = resolveDogfoodSkillPath(argsRecord); + const runId = firstNonEmptyString(argsRecord.run_id); + const answers = firstNonEmptyString(argsRecord.answers); + if (runId && answers) { + return { + skill_path: skillPath, + argv: [ + "resume", + runId, + resolveInputPath(answers), + "--receipt-dir", + receiptDir, + "--json", + ], + }; + } + const threadBody = primaryThreadBody(thread); const argv = [ "skill", @@ -651,12 +665,6 @@ function buildIssueToPrSkillInvocation({ pushOptionalInput(argv, "--provider-binary", argsRecord.provider_binary); pushOptionalInput(argv, "--model", argsRecord.model); - const runId = firstNonEmptyString(argsRecord.run_id); - const answers = firstNonEmptyString(argsRecord.answers); - if (runId && answers) { - argv.push("--run-id", runId, "--answers", resolveInputPath(answers)); - } - return { skill_path: skillPath, argv, @@ -709,14 +717,10 @@ function buildDogfoodCreateResult({ requests: sanitizeDogfoodValue(nativeOutput?.requests, redactions), next_command: buildContinuationCommand({ args: argsRecord, - issueRef, - workspace, - taskId, - branchName, runId, receiptDir, }), - next_human_gate: "Resolve the native graph request and rerun create mode with --run-id and --answers.", + next_human_gate: "Resolve the native graph request, write answers.json, then run the continuation command.", }; } @@ -832,34 +836,15 @@ function summarizeNativeRoute(runxCli, run, nativeOutput, redactions) { }; } -function buildContinuationCommand({ args: argsRecord, issueRef, workspace, taskId, branchName, runId, receiptDir }) { +function buildContinuationCommand({ args: argsRecord, runId, receiptDir }) { + const runx = firstNonEmptyString(argsRecord.runx_bin, "runx"); return [ - "pnpm dogfood:github-issue-to-pr --", - "--mode create", - "--allow-repo", issueRef.repo_slug, - "--repo", issueRef.repo_slug, - "--issue", issueRef.issue_number, - "--workspace", shellQuote(workspace), - "--task-id", shellQuote(taskId), - branchName && branchName !== taskId ? `--branch ${shellQuote(branchName)}` : "", - argsRecord.prepare_branch ? "--prepare-branch" : "", - argsRecord.scafld_bin ? `--scafld-bin ${shellQuote(argsRecord.scafld_bin)}` : "", - argsRecord.runx_bin ? `--runx-bin ${shellQuote(argsRecord.runx_bin)}` : "", - argsRecord.skill ? `--skill ${shellQuote(argsRecord.skill)}` : "", + shellQuote(runx), + "resume", + runId ? shellQuote(runId) : "", + "", receiptDir ? `--receipt-dir ${shellQuote(receiptDir)}` : "", - argsRecord.source_id ? `--source-id ${shellQuote(argsRecord.source_id)}` : "", - argsRecord.runner_id ? `--runner-id ${shellQuote(argsRecord.runner_id)}` : "", - argsRecord.operational_policy ? `--operational-policy ${shellQuote(argsRecord.operational_policy)}` : "", - argsRecord.repo_context ? `--repo-context ${shellQuote(argsRecord.repo_context)}` : "", - argsRecord.size ? `--size ${shellQuote(argsRecord.size)}` : "", - argsRecord.risk ? `--risk ${shellQuote(argsRecord.risk)}` : "", - argsRecord.base ? `--base ${shellQuote(argsRecord.base)}` : "", - argsRecord.provider ? `--provider ${shellQuote(argsRecord.provider)}` : "", - argsRecord.provider_command ? `--provider-command ${shellQuote(argsRecord.provider_command)}` : "", - argsRecord.provider_binary ? `--provider-binary ${shellQuote(argsRecord.provider_binary)}` : "", - argsRecord.model ? `--model ${shellQuote(argsRecord.model)}` : "", - runId ? `--run-id ${shellQuote(runId)}` : "", - "--answers ", + "--json", ].filter(Boolean).join(" "); } diff --git a/scripts/generate-cli-feature-parity.ts b/scripts/generate-cli-feature-parity.ts index e926ba0ef..82fe1c939 100644 --- a/scripts/generate-cli-feature-parity.ts +++ b/scripts/generate-cli-feature-parity.ts @@ -58,6 +58,7 @@ const commands: readonly CommandMatrixEntry[] = [ command("new", "runx new ", [], ["--directory", "--json"], "filesystem", ["scaffold", "cli-presentation"], ["new.validate"]), command("init", "runx init", [], ["-g", "--global", "--prefetch", "--json"], "filesystem", ["scaffold", "official-skills"], ["init.validate"]), command("history", "runx history [query]", [], ["--skill", "--status", "--source", "--actor", "--artifact-type", "--since", "--until", "--receipt-dir", "--json"], "none", ["history", "receipts"], ["history.execute"]), + command("resume", "runx resume ", [], ["--receipt-dir", "--non-interactive", "--json"], "local-runtime", ["caller-mediated-resolution", "graph-runtime", "receipts", "cli-presentation"], ["resume.validate"]), command("verify", "runx verify [receipt-id]", [], ["--receipt-dir", "--receipt", "--json"], "none", ["receipts", "cli-presentation"], ["verify.validate"]), command("list", "runx list [tools|skills|graphs|packets|overlays]", [], ["--ok-only", "--invalid-only", "--json"], "none", ["list", "tool-catalog"], ["list.tools.execute"]), command("config.set", "runx config set ", [], ["--json"], "filesystem", ["config", "cli-presentation"], ["config.set.validate"]), @@ -74,7 +75,7 @@ const commands: readonly CommandMatrixEntry[] = [ command("dev", "runx dev [root]", [], ["--lane", "--json"], "local-runtime", ["dev", "harness", "receipts"], ["dev.validate"]), command("export", "runx export [skill-ref...]", [], ["--project", "--json"], "filesystem", ["skill-export", "cli-presentation"], ["export.validate"]), command("mcp.serve", "runx mcp serve ", [], ["--receipt-dir"], "adapter", ["mcp", "adapter-mcp"], ["mcp.serve.validate"]), - command("skill.run", "runx skill ", [], ["--registry", "--digest", "--runner", "--input", "--receipt-dir", "--run-id", "--answers", "--credential", "--secret-env", "--non-interactive", "--json"], "local-runtime", ["skill-resolution", "graph-runtime", "receipts", "sandbox", "authority", "caller-mediated-resolution", "adapter-cli-tool", "adapter-a2a", "adapter-agent"], ["skill.run.validate"]), + command("skill.run", "runx skill [runner]", [], ["--registry", "--digest", "--input", "--receipt-dir", "--credential", "--secret-env", "--non-interactive", "--json"], "local-runtime", ["skill-resolution", "graph-runtime", "receipts", "sandbox", "authority", "caller-mediated-resolution", "adapter-cli-tool", "adapter-a2a", "adapter-agent"], ["skill.run.validate"]), command("harness", "runx harness ", [], ["--json"], "local-runtime", ["harness", "receipts", "sandbox"], ["harness.execute"]), command("tool.build", "runx tool build |--all", [], ["--all", "--json"], "filesystem", ["tool-catalog", "authoring"], ["tool.build.validate"], { conditionalPositionals: [""] }), command("tool.search", "runx tool search ", [], ["--source", "--json"], "external-stub", ["tool-catalog", "adapter-catalog"], ["tool.search.validate"]), diff --git a/skills/business-ops/graph/ops-lane/run.mjs b/skills/business-ops/graph/ops-lane/run.mjs index e2f1b7d62..5ea24a98f 100644 --- a/skills/business-ops/graph/ops-lane/run.mjs +++ b/skills/business-ops/graph/ops-lane/run.mjs @@ -148,7 +148,7 @@ const laneDetails = { interfaceName: "skill", laneRef: "send-as -> provider.send", runnerRef: "send-as plan, then the selected vendor-specific send runner", - commandHint: "runx skill send-as ...; runx skill --runner ...", + commandHint: "runx skill send-as ...; runx skill ...", }), evidence: evidence( ["principal", "audience", "content digest", "consent basis", "provider status"], diff --git a/tests/data-adapter-conformance.test.ts b/tests/data-adapter-conformance.test.ts index 092a8b96a..0e1277959 100644 --- a/tests/data-adapter-conformance.test.ts +++ b/tests/data-adapter-conformance.test.ts @@ -168,7 +168,7 @@ describe.each(adapters)("data adapter conformance: $name", (adapter) => { before_version: 1, after_version: 1, }); - expect(packet.events[0]?.event_type).toBe("messageboard.accept"); + expect(recordField(packet.events[0], "event_type")).toBe("messageboard.accept"); const projection = runAdapter(adapter, workspace, { ...base, @@ -182,7 +182,7 @@ describe.each(adapters)("data adapter conformance: $name", (adapter) => { before_version: 1, after_version: 1, }); - expect(projectionPacket.projection.last_event_type).toBe("messageboard.accept"); + expect(recordField(projectionPacket.projection, "last_event_type")).toBe("messageboard.accept"); } finally { rmSync(workspace, { recursive: true, force: true }); } @@ -517,6 +517,11 @@ function assertNoSecretMaterial(value: unknown, pathParts: readonly string[] = [ } } +function recordField(value: unknown, key: string): unknown { + expect(value && typeof value === "object" && !Array.isArray(value)).toBe(true); + return (value as Record)[key]; +} + function tempWorkspace(adapterName: string): string { return mkdtempSync(path.join(os.tmpdir(), `runx-${adapterName.replaceAll(".", "-")}-`)); } diff --git a/tests/recognizable-work-lanes.test.ts b/tests/recognizable-work-lanes.test.ts index 4c33b4ccb..291aa9507 100644 --- a/tests/recognizable-work-lanes.test.ts +++ b/tests/recognizable-work-lanes.test.ts @@ -113,21 +113,39 @@ describe("recognizable work lanes", () => { )}\n`, ); + const firstStdout = createMemoryStream(); + const firstStderr = createMemoryStream(); + const startArgs = [ + "skill", + "skills/issue-intake", + "--thread-title", + "README should point users to issue-to-pr", + "--thread-body", + "The public docs should present issue-to-pr as the canonical command.", + "--thread-locator", + "github://example/repo/issues/101", + "--operator-context", + "Prefer the canonical issue-to-pr name in user-facing replies.", + "--receipt-dir", + receiptDir, + "--non-interactive", + "--json", + ]; + const firstExitCode = await runCli( + startArgs, + { stdin: process.stdin, stdout: firstStdout, stderr: firstStderr }, + { ...process.env, ...fixtureSigningEnv, RUNX_CWD: process.cwd() }, + ); + + expect(firstExitCode, firstStderr.contents() || firstStdout.contents()).toBe(2); + expect(firstStderr.contents()).toBe(""); + const firstJson = JSON.parse(firstStdout.contents()) as { run_id: string; status: string }; + expect(firstJson.status).toBe("needs_agent"); + const exitCode = await runCli( [ - "skill", - "skills/issue-intake", - "--thread-title", - "README should point users to issue-to-pr", - "--thread-body", - "The public docs should present issue-to-pr as the canonical command.", - "--thread-locator", - "github://example/repo/issues/101", - "--operator-context", - "Prefer the canonical issue-to-pr name in user-facing replies.", - "--run-id", - "issue-intake-recognizable-work-lane", - "--answers", + "resume", + firstJson.run_id, answersPath, "--receipt-dir", receiptDir, @@ -268,35 +286,8 @@ describe("recognizable work lanes", () => { const exitCode = await runCli( [ - "skill", - "skills/issue-to-pr", - "--fixture", - tempDir, - "--task-id", - taskId, - "--thread-title", - "Fixture thread-driven change", - "--thread-body", - "Apply a bounded fixture docs update.", - "--thread-locator", - threadLocator, - "--thread", - JSON.stringify(thread), - "--target-repo", - "fixtures/repo", - "--size", - "micro", - "--risk", - "low", - "--provider", - "command", - "--provider-command", - passingReviewCommand, - "--scafld-bin", - scafldBin, - "--run-id", + "resume", firstJson.run_id, - "--answers", answersPath, "--receipt-dir", receiptDir, From 35d7adb3209a5524ae6d01e53c51d91c628d8848 Mon Sep 17 00:00:00 2001 From: kam Date: Mon, 22 Jun 2026 02:39:50 +1000 Subject: [PATCH 61/64] fix(cli): restore skill execution and ci --- crates/runx-cli/src/launcher.rs | 7 +-- crates/runx-cli/src/skill.rs | 2 +- crates/runx-cli/src/skill/parser.rs | 34 +++++++++--- crates/runx-cli/tests/doctor.rs | 1 + crates/runx-cli/tests/launcher.rs | 14 +++-- crates/runx-cli/tests/skill.rs | 5 +- .../src/execution/skill_front/graph.rs | 54 +++++++++++++++++++ crates/runx-runtime/src/outbox_provider.rs | 42 +++++++++++++-- .../runx-runtime/src/registry/trust_anchor.rs | 18 ++----- fixtures/cli-parity/cases/oracle.json | 9 ++++ fixtures/cli-parity/commands.json | 32 +++++++++++ scripts/generate-cli-feature-parity.ts | 4 ++ tests/recognizable-work-lanes.test.ts | 37 +++++++++---- 13 files changed, 213 insertions(+), 46 deletions(-) diff --git a/crates/runx-cli/src/launcher.rs b/crates/runx-cli/src/launcher.rs index fe24da58c..d1b973015 100644 --- a/crates/runx-cli/src/launcher.rs +++ b/crates/runx-cli/src/launcher.rs @@ -370,7 +370,8 @@ Commands: runx dev [root] [--lane lane] [--json] runx export [skill-ref...] [--project] [--json] runx mcp serve [--receipt-dir dir] [--http-listen [addr]] [--http-allow-non-loopback] - runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [--run] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] + runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] + runx skill inspect [runner] [-j] [--registry url|path] [--digest sha256] runx add [--registry url|path] [--version version] [--ref git-ref] [--digest sha256] [--to dir] [--api-base-url url] [--json] runx harness [-R dir] [-j|--json] runx tool build |--all [--json] @@ -536,13 +537,13 @@ pub fn skill_help_text() -> String { runx skill Usage: - runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [--run] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] + runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir] + runx skill inspect [runner] [-j] [--registry url|path] [--digest sha256] Options: -p, --profile name Use a local credential profile from .runx/credentials.json -i, --input key=value Set a structured input; repeat for multiple inputs --input-json key=json Set an input that must parse as JSON - --run Execute a zero-input runner instead of inspecting it -R, --receipts dir Write receipts under dir --receipt-dir dir Alias for --receipts -j, --json Print machine-readable output diff --git a/crates/runx-cli/src/skill.rs b/crates/runx-cli/src/skill.rs index 64239e610..9b0267780 100644 --- a/crates/runx-cli/src/skill.rs +++ b/crates/runx-cli/src/skill.rs @@ -275,7 +275,7 @@ fn write_inspection_text(value: &JsonValue) -> ExitCode { object_string(resume, "command").unwrap_or("runx resume answers.json") )); } - out.push_str("run: add inputs, or pass --run for a zero-input runner\n"); + out.push_str("run: runx skill [runner]\n"); } else if let Some(runners) = object.get("runners").and_then(JsonValue::as_array) { out.push_str("runners:\n"); for runner in runners { diff --git a/crates/runx-cli/src/skill/parser.rs b/crates/runx-cli/src/skill/parser.rs index e5563bd4a..343a9085c 100644 --- a/crates/runx-cli/src/skill/parser.rs +++ b/crates/runx-cli/src/skill/parser.rs @@ -32,10 +32,10 @@ pub fn parse_skill_plan(args: &[OsString]) -> Result { }; reject_resolver_flags_for_skill_management_action(skill_path, &state)?; let skill_path = skill_path.clone(); - let action = if state.force_run || !state.inputs.is_empty() { - SkillAction::Run - } else { + let action = if state.inspect { SkillAction::Inspect + } else { + SkillAction::Run }; Ok(SkillPlan { @@ -63,6 +63,7 @@ struct SkillParseState { registry: Option, expected_digest: Option, json: bool, + inspect: bool, force_run: bool, inputs: BTreeMap, credential: Option, @@ -454,7 +455,9 @@ fn parse_skill_arg( index = parse_direct_input_arg(args, index, value, &mut state.inputs)?; } value => { - if state.skill_path.is_none() { + if state.skill_path.is_none() && value == "inspect" { + state.inspect = true; + } else if state.skill_path.is_none() { state.skill_path = Some(PathBuf::from(value)); } else if state.runner.is_none() { state.runner = Some(value.to_owned()); @@ -639,14 +642,14 @@ mod tests { } #[test] - fn skill_without_inputs_inspects_skill_card() -> Result<(), String> { + fn skill_without_inputs_executes_default_runner() -> Result<(), String> { let args = ["skill", "skills/messageboard"] .into_iter() .map(std::ffi::OsString::from) .collect::>(); let plan = super::parse_skill_plan(&args)?; - assert_eq!(plan.action, SkillAction::Inspect); + assert_eq!(plan.action, SkillAction::Run); assert_eq!( plan.skill_path, std::path::PathBuf::from("skills/messageboard") @@ -656,14 +659,31 @@ mod tests { } #[test] - fn positional_runner_without_inputs_inspects_runner_card() -> Result<(), String> { + fn positional_runner_without_inputs_executes_runner() -> Result<(), String> { let args = ["skill", "skills/messageboard", "post_and_append"] .into_iter() .map(std::ffi::OsString::from) .collect::>(); let plan = super::parse_skill_plan(&args)?; + assert_eq!(plan.action, SkillAction::Run); + assert_eq!(plan.runner.as_deref(), Some("post_and_append")); + Ok(()) + } + + #[test] + fn explicit_inspect_returns_skill_card() -> Result<(), String> { + let args = ["skill", "inspect", "skills/messageboard", "post_and_append"] + .into_iter() + .map(std::ffi::OsString::from) + .collect::>(); + let plan = super::parse_skill_plan(&args)?; + assert_eq!(plan.action, SkillAction::Inspect); + assert_eq!( + plan.skill_path, + std::path::PathBuf::from("skills/messageboard") + ); assert_eq!(plan.runner.as_deref(), Some("post_and_append")); Ok(()) } diff --git a/crates/runx-cli/tests/doctor.rs b/crates/runx-cli/tests/doctor.rs index 465aa19d3..3e200064e 100644 --- a/crates/runx-cli/tests/doctor.rs +++ b/crates/runx-cli/tests/doctor.rs @@ -259,6 +259,7 @@ fn diagnostic_has_repair(report: &serde_json::Value, id: &str) -> bool { fn runx_command() -> Command { let mut command = Command::new(env!("CARGO_BIN_EXE_runx")); command.env("NO_COLOR", "1"); + command.env("RUNX_HOME", temp_root("runx-doctor-home")); command } diff --git a/crates/runx-cli/tests/launcher.rs b/crates/runx-cli/tests/launcher.rs index c4e6e83d4..86118dc22 100644 --- a/crates/runx-cli/tests/launcher.rs +++ b/crates/runx-cli/tests/launcher.rs @@ -35,7 +35,11 @@ fn top_level_help_and_version_are_native() { ); assert_help_line( &help, - "runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [--run] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir]", + "runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir]", + ); + assert_help_line( + &help, + "runx skill inspect [runner] [-j] [--registry url|path] [--digest sha256]", ); assert_help_line( &help, @@ -104,7 +108,11 @@ fn nested_skill_history_verify_and_publish_help_are_native() { assert_help_line( &skill_help_text(), - "runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [--run] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir]", + "runx skill [runner] [-p profile] [-i key=value] [--input-json key=json] [-j] [--registry url|path] [--digest sha256] [--flag value] [--credential descriptor --secret-env NAME] [-R dir]", + ); + assert_help_line( + &skill_help_text(), + "runx skill inspect [runner] [-j] [--registry url|path] [--digest sha256]", ); assert_help_line( &skill_help_text(), @@ -393,7 +401,7 @@ fn skill_rejects_legacy_runner_and_continuation_flags() { #[test] fn skill_rejects_resolver_flags_for_management_actions() { - for action in ["inspect", "publish", "search", "validate"] { + for action in ["publish", "search", "validate"] { assert_eq!( plan(&["skill", action, "--registry", "fixtures/registry"]), LauncherAction::Error( diff --git a/crates/runx-cli/tests/skill.rs b/crates/runx-cli/tests/skill.rs index ed965e5e1..66fd4b06b 100644 --- a/crates/runx-cli/tests/skill.rs +++ b/crates/runx-cli/tests/skill.rs @@ -33,6 +33,7 @@ fn native_skill_pauses_and_resumes_with_run_id() -> Result<(), Box Result<(), Box Result<(), Box { + request: &'a SkillRunRequest, + workspace: &'a WorkspaceEnv, + receipts: &'a ReceiptServices, + manifest: &'a SkillRunnerManifest, + runner: &'a SkillRunnerDefinition, + graph: &'a ExecutionGraph, + run_id: &'a str, + request_id: &'a str, +} + +fn write_paused_graph_checkpoint(input: PausedGraphCheckpoint<'_>) -> Result<(), SkillRunError> { + let receipt_path = + input + .receipts + .resolve_path(input.workspace, input.request.receipt_dir.as_deref(), None); + let checkpoint = PausedRunCheckpoint { + id: input.run_id.to_owned(), + name: input + .manifest + .skill + .clone() + .unwrap_or_else(|| input.graph.name.clone()), + kind: "graph".to_owned(), + started_at: Some(crate::time::now_iso8601()), + resume_skill_ref: Some(input.request.skill_path.to_string_lossy().into_owned()), + selected_runner: Some(input.runner.name.clone()), + step_ids: vec![input.request_id.to_owned()], + step_labels: vec![input.request_id.to_owned()], + }; + append_paused_run_checkpoint(&receipt_path.path, &checkpoint).map_err(|source| { + RuntimeError::io( + format!( + "writing paused run checkpoint for {} in {}", + checkpoint.id, + receipt_path.path.display() + ), + source, + ) + })?; + Ok(()) +} + fn missing_required_graph_input_request( runner: &SkillRunnerDefinition, graph_inputs: &JsonObject, diff --git a/crates/runx-runtime/src/outbox_provider.rs b/crates/runx-runtime/src/outbox_provider.rs index 0b1aa0b41..370a6789e 100644 --- a/crates/runx-runtime/src/outbox_provider.rs +++ b/crates/runx-runtime/src/outbox_provider.rs @@ -2,7 +2,7 @@ // validation, secret rejection, and redaction in one module so the provider boundary is reviewed // as a single trust surface. use std::collections::BTreeSet; -use std::path::PathBuf; +use std::path::{Path, PathBuf}; use std::process::{Command, ExitStatus, Stdio}; use std::time::{Duration, Instant}; @@ -303,14 +303,48 @@ fn validate_request_identity( fn process_command( manifest: &ThreadOutboxProviderManifest, -) -> Result<&str, ThreadOutboxProviderSupervisorError> { +) -> Result { let Some(command) = manifest.transport.command.as_deref() else { return Err(ThreadOutboxProviderSupervisorError::MissingProcessCommand); }; - if command.trim().is_empty() { + let command = command.trim(); + if command.is_empty() { return Err(ThreadOutboxProviderSupervisorError::EmptyProcessCommand); } - Ok(command) + Ok(resolve_process_command(command)) +} + +fn resolve_process_command(command: &str) -> PathBuf { + let path = Path::new(command); + if path.is_absolute() || path.components().count() > 1 { + return path.to_path_buf(); + } + + if let Some(paths) = std::env::var_os("PATH") { + for dir in std::env::split_paths(&paths) { + let candidate = dir.join(command); + if candidate.is_file() { + return candidate; + } + #[cfg(windows)] + { + if candidate.extension().is_some() { + continue; + } + if let Some(exts) = std::env::var_os("PATHEXT") { + for ext in std::env::split_paths(&exts) { + let ext = ext.to_string_lossy(); + let candidate = dir.join(format!("{command}{ext}")); + if candidate.is_file() { + return candidate; + } + } + } + } + } + } + + PathBuf::from(command) } fn write_request( diff --git a/crates/runx-runtime/src/registry/trust_anchor.rs b/crates/runx-runtime/src/registry/trust_anchor.rs index 4b369de46..e9d854deb 100644 --- a/crates/runx-runtime/src/registry/trust_anchor.rs +++ b/crates/runx-runtime/src/registry/trust_anchor.rs @@ -181,10 +181,7 @@ pub fn trusted_registry_manifest_keys_from_env_with_source( source_authority, Some(RegistryManifestSourceAuthority::OfficialRunx) ) { - let key = TrustedRegistryManifestKey::official_from_base64(key_id, public_key) - .map_err(|_| RegistryManifestTrustEnvError::InvalidKey)?; - trusted_keys.push(key); - return Ok(trusted_keys); + return Err(RegistryManifestTrustEnvError::InvalidKey); } let allowed_owner = env .get(RUNX_REGISTRY_MANIFEST_TRUST_OWNER_ENV) @@ -358,21 +355,12 @@ mod tests { } #[test] - fn official_source_trust_key_is_official_scoped_without_owner() { + fn env_trust_key_cannot_promote_itself_to_official_source() { let result = trusted_registry_manifest_keys_from_env_with_source( &trust_env(), Some(RegistryManifestSourceAuthority::OfficialRunx), ); - assert!( - result.is_ok(), - "official source trust key should be accepted: {result:?}" - ); - let keys = result.unwrap_or_default(); - - assert_eq!( - keys.last().map(|key| &key.scope), - Some(&RegistryManifestTrustScope::OfficialRunx) - ); + assert_eq!(result, Err(RegistryManifestTrustEnvError::InvalidKey)); } #[test] diff --git a/fixtures/cli-parity/cases/oracle.json b/fixtures/cli-parity/cases/oracle.json index fd11628e4..87802b7e8 100644 --- a/fixtures/cli-parity/cases/oracle.json +++ b/fixtures/cli-parity/cases/oracle.json @@ -294,6 +294,15 @@ "adapter-agent" ] }, + { + "id": "skill.inspect.validate", + "commandId": "skill.inspect", + "mode": "validate", + "proves": [ + "skill-resolution", + "cli-presentation" + ] + }, { "id": "tool.build.validate", "commandId": "tool.build", diff --git a/fixtures/cli-parity/commands.json b/fixtures/cli-parity/commands.json index a4832bc5d..99858314e 100644 --- a/fixtures/cli-parity/commands.json +++ b/fixtures/cli-parity/commands.json @@ -698,6 +698,38 @@ "skill.run.validate" ] }, + { + "id": "skill.inspect", + "usage": "runx skill inspect [runner]", + "aliases": [], + "requiredPositionals": [ + "" + ], + "flags": [ + "--registry", + "--digest", + "--json" + ], + "exitCodes": [ + 0, + 1, + 2, + 64 + ], + "parity": { + "humanOutput": "semantic", + "jsonOutput": "schema-exact", + "receipt": "none", + "sideEffect": "filesystem", + "surfaces": [ + "skill-resolution", + "cli-presentation" + ] + }, + "cases": [ + "skill.inspect.validate" + ] + }, { "id": "harness", "usage": "runx harness ", diff --git a/scripts/generate-cli-feature-parity.ts b/scripts/generate-cli-feature-parity.ts index 82fe1c939..662f662e5 100644 --- a/scripts/generate-cli-feature-parity.ts +++ b/scripts/generate-cli-feature-parity.ts @@ -76,6 +76,7 @@ const commands: readonly CommandMatrixEntry[] = [ command("export", "runx export [skill-ref...]", [], ["--project", "--json"], "filesystem", ["skill-export", "cli-presentation"], ["export.validate"]), command("mcp.serve", "runx mcp serve ", [], ["--receipt-dir"], "adapter", ["mcp", "adapter-mcp"], ["mcp.serve.validate"]), command("skill.run", "runx skill [runner]", [], ["--registry", "--digest", "--input", "--receipt-dir", "--credential", "--secret-env", "--non-interactive", "--json"], "local-runtime", ["skill-resolution", "graph-runtime", "receipts", "sandbox", "authority", "caller-mediated-resolution", "adapter-cli-tool", "adapter-a2a", "adapter-agent"], ["skill.run.validate"]), + command("skill.inspect", "runx skill inspect [runner]", [], ["--registry", "--digest", "--json"], "filesystem", ["skill-resolution", "cli-presentation"], ["skill.inspect.validate"]), command("harness", "runx harness ", [], ["--json"], "local-runtime", ["harness", "receipts", "sandbox"], ["harness.execute"]), command("tool.build", "runx tool build |--all", [], ["--all", "--json"], "filesystem", ["tool-catalog", "authoring"], ["tool.build.validate"], { conditionalPositionals: [""] }), command("tool.search", "runx tool search ", [], ["--source", "--json"], "external-stub", ["tool-catalog", "adapter-catalog"], ["tool.search.validate"]), @@ -314,6 +315,9 @@ function helpUsageCommandIds(usage: string): readonly string[] { if (usage.startsWith("runx skill <")) { return ["skill.run"]; } + if (usage.startsWith("runx skill inspect ")) { + return ["skill.inspect"]; + } if (usage.startsWith("runx config ")) { return ["config.set", "config.get", "config.list"]; } diff --git a/tests/recognizable-work-lanes.test.ts b/tests/recognizable-work-lanes.test.ts index 291aa9507..70878e213 100644 --- a/tests/recognizable-work-lanes.test.ts +++ b/tests/recognizable-work-lanes.test.ts @@ -16,11 +16,26 @@ const fixtureSigningEnv = { RUNX_RECEIPT_SIGN_ISSUER_TYPE: process.env.RUNX_RECEIPT_SIGN_ISSUER_TYPE ?? "hosted", }; +function hostDrivenRunxEnv(overrides: NodeJS.ProcessEnv): NodeJS.ProcessEnv { + const env: NodeJS.ProcessEnv = { + ...process.env, + ...fixtureSigningEnv, + ...overrides, + }; + delete env.RUNX_AGENT_PROVIDER; + delete env.RUNX_AGENT_MODEL; + delete env.RUNX_AGENT_API_KEY; + delete env.ANTHROPIC_API_KEY; + delete env.OPENAI_API_KEY; + return env; +} + describe("recognizable work lanes", () => { it("runs issue-intake through the local CLI with a bounded next-lane packet", async () => { const tempDir = await mkdtemp(path.join(os.tmpdir(), "runx-issue-intake-cli-")); const answersPath = path.join(tempDir, "answers.json"); const receiptDir = path.join(tempDir, "receipts"); + const runxHome = path.join(tempDir, "home"); const stdout = createMemoryStream(); const stderr = createMemoryStream(); @@ -134,7 +149,7 @@ describe("recognizable work lanes", () => { const firstExitCode = await runCli( startArgs, { stdin: process.stdin, stdout: firstStdout, stderr: firstStderr }, - { ...process.env, ...fixtureSigningEnv, RUNX_CWD: process.cwd() }, + hostDrivenRunxEnv({ RUNX_CWD: process.cwd(), RUNX_HOME: runxHome }), ); expect(firstExitCode, firstStderr.contents() || firstStdout.contents()).toBe(2); @@ -153,16 +168,14 @@ describe("recognizable work lanes", () => { "--json", ], { stdin: process.stdin, stdout, stderr }, - { ...process.env, ...fixtureSigningEnv, RUNX_CWD: process.cwd() }, + hostDrivenRunxEnv({ RUNX_CWD: process.cwd(), RUNX_HOME: runxHome }), ); expect(exitCode, stderr.contents() || stdout.contents()).toBe(0); expect(stderr.contents()).toBe(""); expect(JSON.parse(stdout.contents())).toMatchObject({ status: "sealed", - skill: { - name: "issue-intake", - }, + skill_name: "issue-intake", execution: { stdout: expect.stringContaining("\"recommended_lane\":\"issue-to-pr\""), }, @@ -199,7 +212,7 @@ describe("recognizable work lanes", () => { kind: "runx.thread.v1", adapter: { type: "file", - adapter_ref: threadPath, + adapter_ref: threadLocator, }, thread_kind: "signal", thread_locator: threadLocator, @@ -275,7 +288,7 @@ describe("recognizable work lanes", () => { "--json", ], { stdin: process.stdin, stdout: firstStdout, stderr: firstStderr }, - { ...process.env, ...fixtureSigningEnv, RUNX_CWD: tempDir, RUNX_HOME: runxHome }, + hostDrivenRunxEnv({ RUNX_CWD: process.cwd(), RUNX_HOME: runxHome }), ); expect(firstExitCode, firstStderr.contents() || firstStdout.contents()).toBe(2); expect(firstStderr.contents()).toBe(""); @@ -295,15 +308,13 @@ describe("recognizable work lanes", () => { "--json", ], { stdin: process.stdin, stdout, stderr }, - { ...process.env, ...fixtureSigningEnv, RUNX_CWD: tempDir, RUNX_HOME: runxHome }, + hostDrivenRunxEnv({ RUNX_CWD: process.cwd(), RUNX_HOME: runxHome }), ); expect(exitCode, stderr.contents() || stdout.contents()).toBe(0); expect(stderr.contents()).toBe(""); expect(JSON.parse(stdout.contents())).toMatchObject({ status: "sealed", - skill: { - name: "issue-to-pr", - }, + skill_name: "issue-to-pr", execution: { stdout: expect.stringContaining("\"draft_pull_request\""), }, @@ -430,7 +441,11 @@ Profile: standard Definition of done: - [ ] \`dod1\` app.txt contains the fixed output. + - Command: \`grep -q '^fixed$' app.txt\` + - Expected kind: \`exit_code_zero\` - [ ] \`dod2\` notes.md contains the governed output. + - Command: \`grep -q '^governed$' notes.md\` + - Expected kind: \`exit_code_zero\` Validation: - [ ] \`v1\` test - app.txt contains the fixed output. From 79d4731828a2157e04569d63c249283592d78fc7 Mon Sep 17 00:00:00 2001 From: kam Date: Mon, 22 Jun 2026 02:44:02 +1000 Subject: [PATCH 62/64] fix: skip live github for fixture thread adapters --- tests/github-thread.test.ts | 86 +++++++++++++++++++ .../github-provider.mjs | 83 ++++++++++++++++-- 2 files changed, 164 insertions(+), 5 deletions(-) diff --git a/tests/github-thread.test.ts b/tests/github-thread.test.ts index d14d813f3..907e9e3ee 100644 --- a/tests/github-thread.test.ts +++ b/tests/github-thread.test.ts @@ -1,6 +1,7 @@ import { chmod, mkdtemp, readFile, rm, writeFile } from "node:fs/promises"; import os from "node:os"; import path from "node:path"; +import { spawnSync } from "node:child_process"; import { describe, expect, it } from "vitest"; import { @@ -630,6 +631,91 @@ describe("GitHub thread helper", () => { await rm(tempDir, { recursive: true, force: true }); } }); + + it("skips live GitHub mutation for non-GitHub fixture thread adapters", () => { + const request = { + protocol_version: "runx.thread_outbox_provider.v1", + push_id: "thread_push_fixture", + adapter_id: "thread-provider.github", + provider: "github", + thread_locator: { + provider: "github", + locator: "github://example/repo/issues/123", + thread_ref: { + type: "github_issue", + uri: "github://example/repo/issues/123", + provider: "github", + locator: "github://example/repo/issues/123", + }, + }, + outbox_entry_id: "pull_request:fixture", + idempotency: { + key: "thread-outbox:github:fixture", + content_hash: "sha256:fixture", + }, + payload: { + format: "json", + body: JSON.stringify({ + thread: { + kind: "runx.thread.v1", + adapter: { + type: "file", + adapter_ref: "github://example/repo/issues/123", + }, + thread_kind: "signal", + thread_locator: "github://example/repo/issues/123", + entries: [], + decisions: [], + outbox: [], + source_refs: [], + }, + outbox_entry: { + entry_id: "pull_request:fixture", + kind: "pull_request", + status: "proposed", + thread_locator: "github://example/repo/issues/123", + }, + draft_pull_request: { + target: { + repo: "example/repo", + branch: "fixture", + }, + }, + fixture: "/tmp/runx-fixture", + }), + }, + }; + + const result = spawnSync("node", ["tools/thread/thread_outbox_provider/github-provider.mjs"], { + cwd: process.cwd(), + input: `${JSON.stringify(request)}\n`, + encoding: "utf8", + env: { + ...process.env, + RUNX_GH_BIN: "/path/that/should/not/be/called", + }, + }); + + expect(result.status, result.stderr || result.stdout).toBe(0); + const parsed = JSON.parse(result.stdout); + expect(parsed).toMatchObject({ + observation: { + status: "skipped", + idempotency: { + status: "skipped", + }, + }, + output: { + outbox_entry: { + entry_id: "pull_request:fixture", + }, + push: { + status: "skipped", + reason: "thread adapter is not github", + }, + }, + }); + }); }); function fakeGhScript(logPath: string): string { diff --git a/tools/thread/thread_outbox_provider/github-provider.mjs b/tools/thread/thread_outbox_provider/github-provider.mjs index 19738fd5d..292782ab7 100644 --- a/tools/thread/thread_outbox_provider/github-provider.mjs +++ b/tools/thread/thread_outbox_provider/github-provider.mjs @@ -20,12 +20,35 @@ try { const thread = asRecord(payload.thread, "payload.thread"); const outboxEntry = asRecord(payload.outbox_entry, "payload.outbox_entry"); const draftPullRequest = optionalRecord(payload.draft_pull_request); - const workspacePath = firstNonEmptyString(payload.workspace_path); + const workspacePath = firstNonEmptyString(payload.workspace_path, payload.fixture); const nextStatus = firstNonEmptyString(payload.next_status); const kind = firstNonEmptyString(outboxEntry.kind); const env = process.env; - const adapterRef = firstNonEmptyString(optionalRecord(thread.adapter)?.adapter_ref); + const adapter = optionalRecord(thread.adapter); + const adapterRef = firstNonEmptyString(adapter?.adapter_ref); const pendingProviderThread = optionalRecord(thread.metadata)?.pending_provider_thread === true; + const shouldUseLiveProvider = isGitHubThreadAdapter(adapter); + + if (!shouldUseLiveProvider) { + writeJson({ + observation: observationFor({ + request, + locator: undefined, + status: "skipped", + idempotencyStatus: "skipped", + reason: "thread adapter is not github", + }), + output: skippedProviderOutput({ + request, + thread, + outboxEntry, + draftPullRequest, + reason: "thread adapter is not github", + }), + }); + process.exit(0); + } + const pushThread = adapterRef && !pendingProviderThread ? fetchGitHubIssueThread({ adapterRef, env, cwd: workspacePath ?? process.cwd() }) : thread; @@ -111,7 +134,13 @@ function providerPayload(request) { return asRecord(parsed, "payload.body"); } -function observationFor({ request, locator }) { +function observationFor({ + request, + locator, + status = "accepted", + idempotencyStatus = "created", + reason, +}) { const observedAt = new Date().toISOString(); const providerLocator = locator ? { @@ -135,10 +164,10 @@ function observationFor({ request, locator }) { provider: request.provider, operation: "push", request_id: request.push_id, - status: "accepted", + status, idempotency: { key: request.idempotency?.key, - status: "created", + status: idempotencyStatus, }, provider_locator: providerLocator, provider_event_id_hash: locator ? sha256Prefixed(locator) : undefined, @@ -154,10 +183,54 @@ function observationFor({ request, locator }) { uri: "runx:redaction_policy:provider-output", }, ], + errors: reason + ? [ + { + code: "provider_skipped", + message: reason, + retryable: false, + }, + ] + : undefined, observed_at: observedAt, }); } +function skippedProviderOutput({ + request, + thread, + outboxEntry, + draftPullRequest, + reason, +}) { + return prune({ + draft_pull_request: draftPullRequest, + outbox_entry: outboxEntry, + thread, + push: { + status: "skipped", + provider: request.provider, + adapter: optionalRecord(thread.adapter), + reason, + }, + }); +} + +function isGitHubThreadAdapter(adapter) { + if (!adapter) { + return true; + } + const type = firstNonEmptyString(adapter.type); + const provider = firstNonEmptyString(adapter.provider); + if (type && type !== "github") { + return false; + } + if (provider && provider !== "github") { + return false; + } + return true; +} + function asRecord(value, field) { if (!isRecord(value)) { throw new Error(`${field} must be an object.`); From ec8e16af1e69af61f6686cb55e46b47b9b507262 Mon Sep 17 00:00:00 2001 From: kam Date: Mon, 22 Jun 2026 02:48:16 +1000 Subject: [PATCH 63/64] chore: remove local workspace state --- .ai/OPERATORS.md | 129 ---- .ai/README.md | 71 -- .ai/config.local.yaml | 26 - .ai/config.yaml | 307 -------- .ai/prompts/exec.md | 307 -------- .ai/prompts/harden.md | 32 - .ai/prompts/plan.md | 197 ----- .ai/prompts/review.md | 169 ----- .ai/runs/runx-claim-via-nango/session.json | 23 - .ai/scafld/OPERATORS.md | 131 ---- .ai/scafld/README.md | 72 -- .ai/scafld/config.yaml | 315 -------- .ai/scafld/manifest.json | 49 -- .ai/scafld/prompts/exec.md | 307 -------- .ai/scafld/prompts/harden.md | 32 - .ai/scafld/prompts/plan.md | 203 ------ .ai/scafld/prompts/review.md | 169 ----- .ai/scafld/schemas/spec.json | 590 --------------- .ai/scafld/specs/README.md | 99 --- .../specs/examples/add-error-codes.yaml | 365 ---------- .ai/schemas/spec.json | 476 ------------ .ai/specs/README.md | 99 --- .../runx-unified-workspace-topology.yaml | 295 -------- .../2026-04/icey-cli-upstream-binding.yaml | 239 ------ .../runx-capability-execution-envelope.yaml | 205 ------ .../2026-04/runx-claim-via-github-app.yaml | 462 ------------ .../archive/2026-04/runx-claim-via-nango.yaml | 686 ------------------ .../2026-04/runx-cli-command-modules.yaml | 171 ----- .../2026-04/runx-cli-kernel-final-split.yaml | 225 ------ .../2026-04/runx-cloud-api-service-split.yaml | 158 ---- .../runx-contract-typebox-authority.yaml | 140 ---- .../runx-contracts-single-authority.yaml | 281 ------- .../runx-doctor-structure-enforcement.yaml | 140 ---- ...runx-fanout-gate-resolution-semantics.yaml | 101 --- .../runx-handoff-signal-core-model.yaml | 341 --------- .../runx-hosted-api-domain-service-split.yaml | 250 ------- .../2026-04/runx-langchain-adoption-path.yaml | 221 ------ .../runx-local-sandbox-enforcement.yaml | 102 --- .../runx-runner-local-facade-final-split.yaml | 248 ------- .../runx-runner-local-kernel-split.yaml | 175 ----- .../2026-04/runx-runtime-bootstrap.yaml | 151 ---- .../runx-sourcey-capability-pack-cutover.yaml | 325 --------- .../archive/2026-04/runx-url-as-publish.yaml | 482 ------------ ...erification-foundation-and-fast-lanes.yaml | 228 ------ .ai/specs/examples/add-error-codes.yaml | 365 ---------- 45 files changed, 10159 deletions(-) delete mode 100644 .ai/OPERATORS.md delete mode 100644 .ai/README.md delete mode 100644 .ai/config.local.yaml delete mode 100644 .ai/config.yaml delete mode 100644 .ai/prompts/exec.md delete mode 100644 .ai/prompts/harden.md delete mode 100644 .ai/prompts/plan.md delete mode 100644 .ai/prompts/review.md delete mode 100644 .ai/runs/runx-claim-via-nango/session.json delete mode 100644 .ai/scafld/OPERATORS.md delete mode 100644 .ai/scafld/README.md delete mode 100644 .ai/scafld/config.yaml delete mode 100644 .ai/scafld/manifest.json delete mode 100644 .ai/scafld/prompts/exec.md delete mode 100644 .ai/scafld/prompts/harden.md delete mode 100644 .ai/scafld/prompts/plan.md delete mode 100644 .ai/scafld/prompts/review.md delete mode 100644 .ai/scafld/schemas/spec.json delete mode 100644 .ai/scafld/specs/README.md delete mode 100644 .ai/scafld/specs/examples/add-error-codes.yaml delete mode 100644 .ai/schemas/spec.json delete mode 100644 .ai/specs/README.md delete mode 100644 .ai/specs/active/runx-unified-workspace-topology.yaml delete mode 100644 .ai/specs/archive/2026-04/icey-cli-upstream-binding.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-capability-execution-envelope.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-claim-via-github-app.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-claim-via-nango.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-cli-command-modules.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-cli-kernel-final-split.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-cloud-api-service-split.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-contract-typebox-authority.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-contracts-single-authority.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-doctor-structure-enforcement.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-fanout-gate-resolution-semantics.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-handoff-signal-core-model.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-hosted-api-domain-service-split.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-langchain-adoption-path.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-local-sandbox-enforcement.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-runner-local-facade-final-split.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-runner-local-kernel-split.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-runtime-bootstrap.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-sourcey-capability-pack-cutover.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-url-as-publish.yaml delete mode 100644 .ai/specs/archive/2026-04/runx-verification-foundation-and-fast-lanes.yaml delete mode 100644 .ai/specs/examples/add-error-codes.yaml diff --git a/.ai/OPERATORS.md b/.ai/OPERATORS.md deleted file mode 100644 index abd8c2d81..000000000 --- a/.ai/OPERATORS.md +++ /dev/null @@ -1,129 +0,0 @@ -# scafld — Operator Cheat Sheet - -A short, human-friendly guide for working with scafld task specs. -For full details, see `.ai/README.md` and `.ai/specs/README.md`. - ---- - -## 1. Tiny Change (Micro/Small, Low Risk) - -Use this for trivial, low-risk edits (comments, copy tweaks, tiny refactors). - -- In the spec: - - `task.size: "micro"` or `"small"` - - `task.risk_level: "low"` - - Optionally set `task.acceptance.validation_profile: "light"` -- Workflow: - - Plan: generate/update spec under `.ai/specs/drafts/` - - Approve: move to `.ai/specs/approved/` and set `status: "approved"` - - Execute: move to `.ai/specs/active/` and set `status: "in_progress"` - - Complete: move to `.ai/specs/archive/YYYY-MM/` and set `status: "completed"` - ---- - -## 2. Normal Task (Small/Medium, Medium Risk) - -Use this for typical feature work and non-trivial refactors. - -- In the spec: - - `task.size: "small"` or `"medium"` - - `task.risk_level: "medium"` - - Usually `task.acceptance.validation_profile: "standard"` -- Workflow: - - Plan: ensure `task.acceptance.definition_of_done` and `phases[*].acceptance_criteria` tell the same story. - - Approve: move to approved folder - - Execute: run all `acceptance_criteria` plus per-phase validation - - Complete: run full standard profile validation before archiving - ---- - -## 3. Big Change (Medium/Large, High Risk) - -Use this for high-impact work (auth, persistence, complex refactors). - -- In the spec: - - `task.size: "medium"` or `"large"` - - `task.risk_level: "high"` - - Usually `task.acceptance.validation_profile: "strict"` -- Workflow: - - Plan: - - Explicitly call out invariants and risks - - Use multiple phases with narrow scopes and strong acceptance criteria - - Approve: move to approved folder - - Execute: run all per-phase checks plus full `strict` profile - - Complete: thorough validation before archiving - ---- - -## 4. Quick Commands Reference - -```bash -scafld new my-task -t "My feature" -s small -r low # scaffold spec -scafld list # show all specs -scafld list active # filter by status -scafld status my-task # show details + phase progress -scafld validate my-task # check against schema -scafld approve my-task # drafts/ -> approved/ -scafld start my-task # approved/ -> active/ -scafld exec my-task # run acceptance criteria, record results -scafld exec my-task -p phase1 # run criteria for one phase only -scafld audit my-task # compare spec files vs git diff -scafld audit my-task -b main # audit against specific base ref -scafld diff my-task # show git history for spec -scafld review my-task # run configured automated passes + scaffold Review Artifact v3 -scafld complete my-task # read review, record verdict, archive (requires review) -scafld complete my-task --human-reviewed --reason "manual audit" # exceptional audited override when the review gate is blocked -scafld fail my-task # active/ -> archive/ (failed) -scafld cancel my-task # active/ -> archive/ (cancelled) -scafld report # aggregate stats across all specs -``` - ---- - -## 5. Validation Profiles - -| Profile | When to Use | What Runs | -|---------|-------------|-----------| -| `light` | micro/small, low risk | compile, acceptance items, perf eval | -| `standard` | small/medium, medium risk | compile, tests, lint, typecheck, security, perf eval | -| `strict` | medium/large, high risk | all standard checks + broader coverage | - ---- - -## 6. Status Lifecycle - -``` -draft → under_review → approved → in_progress → review → completed - ↓ ↓ - (blocked) failed - ↓ ↑ - (resume) fix + re-review -``` - ---- - -## 7. Review & Completion Workflow - -After execution, before completing: - -```bash -scafld review my-task # runs automated passes, scaffolds adversarial review - # reviewer fills in findings + Review Artifact v3 metadata in .ai/reviews/my-task.md -scafld complete my-task # reads review, records verdict, archives - # refuses if the latest review round is missing, malformed, incomplete, or failed -scafld complete my-task --human-reviewed --reason "manual audit" - # exceptional audited override; requires interactive confirmation -``` - -Review rounds accumulate — each `scafld review` appends a numbered Review Artifact v3 section with per-pass `pass_results`. The default five-layer pipeline is `spec_compliance`, `scope_drift`, `regression_hunt`, `convention_check`, and `dark_patterns`, ordered by explicit `order` fields in `.ai/config.yaml`. Prior rounds provide context for subsequent reviewers and make review provenance visible. - ---- - -## 8. Tips - -- **Always read the spec before executing** — understand what you're building -- **Keep phases small** — easier to validate and rollback -- **Run `scafld review` before completing** — the adversarial review catches what acceptance criteria miss -- **Review in a fresh session when possible** — avoids confirmation bias from the execution session -- **Self-eval honestly** — the 7/10 threshold keeps quality high; 10/10 requires justification -- **Archive completed specs** — they're your project history diff --git a/.ai/README.md b/.ai/README.md deleted file mode 100644 index 31ccc5d2e..000000000 --- a/.ai/README.md +++ /dev/null @@ -1,71 +0,0 @@ -# scafld - Planning & Execution Framework - -**Version:** 1.0 - -scafld is a spec-driven framework for AI agent task planning and execution. Every task becomes a machine-readable YAML specification that flows through a defined lifecycle: plan, approve, execute, archive. - ---- - -## How It Works - -1. **Plan:** AI generates a task spec in `.ai/specs/drafts/` via conversational ReAct loop -2. **Approve:** Developer reviews and moves spec to `.ai/specs/approved/` -3. **Execute:** AI picks up the approved spec, executes phases, validates at each checkpoint -4. **Review:** Adversarial review finds what execution missed — `scafld review` runs the configured `spec_compliance` and `scope_drift` checks, scaffolds Review Artifact v3, and prepares the adversarial `regression_hunt`, `convention_check`, and `dark_patterns` passes in the latest round -5. **Archive:** Completed specs move to `.ai/specs/archive/YYYY-MM/` with truthful review results recorded, or a human-reviewed override audited explicitly when the gate is blocked - -The approval gate is the human oversight boundary. The review gate is the quality boundary. During execution, the agent operates autonomously through all phases, pausing only when blocked or deviating from the spec. A normal completion path still stays agent-driven; the human-reviewed override is an exceptional audited escape hatch, not the default workflow. - -The default review topology lives in `config.yaml` and uses five ordered built-in passes: `spec_compliance`, `scope_drift`, `regression_hunt`, `convention_check`, and `dark_patterns`. Review Artifact v3 stores per-pass `pass_results`, reviewer provenance, and round status for that configured topology. - ---- - -## Directory Structure - -``` -.ai/ -├── README.md # This file -├── config.yaml # Global configuration (invariants, validation, rubric) -├── prompts/ -│ ├── plan.md # Planning mode instructions -│ ├── exec.md # Execution mode instructions -│ └── review.md # Adversarial review mode instructions -├── reviews/ # Review findings per spec (gitignored) -├── schemas/ -│ └── spec.json # JSON schema for task specifications -├── specs/ # Task specs organized by lifecycle status -│ ├── README.md # Spec workflow and naming conventions -│ ├── drafts/ # status: draft | under_review -│ ├── approved/ # status: approved -│ ├── active/ # status: in_progress -│ └── archive/YYYY-MM/ # status: completed | failed | cancelled -├── playbooks/ # Reusable workflow templates (optional) -└── logs/ # Execution logs (optional, supplementary) -``` - ---- - -## Key Files - -| File | Purpose | -|------|---------| -| `config.yaml` | Invariants, validation profiles, rubric weights, safety rules | -| `prompts/plan.md` | System prompt for planning mode agents | -| `prompts/exec.md` | System prompt for execution mode agents | -| `prompts/review.md` | System prompt for adversarial review mode | -| `schemas/spec.json` | JSON schema for spec validation | -| `specs/README.md` | Spec directory structure, naming, and workflow | - ---- - -## Related Docs - -- [AGENTS.md](../AGENTS.md) - High-level AI agent policies -- [OPERATORS.md](OPERATORS.md) - Human-facing cheat sheet for working with specs -- [CONVENTIONS.md](../CONVENTIONS.md) - Coding standards and patterns - ---- - -## License - -MIT License - Free to use, modify, and distribute. diff --git a/.ai/config.local.yaml b/.ai/config.local.yaml deleted file mode 100644 index a6d76cf1d..000000000 --- a/.ai/config.local.yaml +++ /dev/null @@ -1,26 +0,0 @@ -# Project-specific config overlay -# Values here merge on top of .ai/config.yaml. -# Only include sections you want to override - everything else inherits. - -# CUSTOMIZE: Replace with your actual build/test/lint commands -validation: - per_phase: - compile_check: "echo 'Replace: your build command'" - targeted_tests: "echo 'Replace: your test command'" - pre_commit: - full_test_suite: "echo 'Replace: your full test suite'" - linter_suite: "echo 'Replace: your linter'" - typecheck: "echo 'Replace: your typecheck'" - -# CUSTOMIZE: Replace with your actual tech stack -tech_stack: - backend: - language: "Your language (e.g., Python 3.11, Ruby 3.2)" - framework: "Your framework (e.g., Django, Rails, FastAPI)" - frontend: - framework: "Your framework (e.g., React, Vue, Next.js)" - -# CUSTOMIZE: Replace with your actual directory layout -repo_layout: - backend: "backend/" - frontend: "frontend/" diff --git a/.ai/config.yaml b/.ai/config.yaml deleted file mode 100644 index f1e55eb81..000000000 --- a/.ai/config.yaml +++ /dev/null @@ -1,307 +0,0 @@ -# scafld Configuration -# Version: 1.1 -# Purpose: Machine-readable control file for AI coding agents - -version: "1.0" - -# Status lifecycle: See specs/README.md for canonical state machine and transitions - -# ============================================================================= -# INVARIANTS (immutable during session) -# ============================================================================= -invariants: - # CUSTOMIZE: Replace these with your project's architectural invariants. - # These names are referenced in specs (context.invariants) and enforced during execution. - canonical: - - domain_boundaries # Respect layer separation - - error_envelope # Consistent error format - - no_legacy_code # No dual-reads, dual-writes, or runtime fallbacks - - no_test_logic_in_production # Keep test-only code in test files - - public_api_stable # Public APIs require approval to change - - config_from_env # Configuration from environment, never hardcoded - - # Code quality policies - no_legacy_code: true - no_test_logic_in_production: true - - # Change control - public_api_changes: require_approval # schemas, migrations, HTTP/event shapes - - # See also: ../CONVENTIONS.md for detailed coding standards - -# ============================================================================= -# MODES (planning vs execution) -# ============================================================================= -modes: - planning: - # Output: generate .ai/specs/{task-id}.yaml - output_format: spec_file - - # Requirements for a valid plan - require_task_outline: true - require_touchpoints: true - require_acceptance_checklist: true - - # Quality gate - self_eval_threshold: 7 - - # ReAct behavior - exploration_depth: thorough - show_reasoning: true - - execution: - # Input: load approved .ai/specs/{task-id}.yaml - input_format: spec_file - require_approval: true - - # Checkpoint frequency - checkpoint_frequency: per_phase - - # Quality controls - self_review: mandatory - rollback_on_fail: true - strict_spec_adherence: true - - # Output style - progress_format: concise - show_reasoning: true - -# ============================================================================= -# VALIDATION PIPELINES -# ============================================================================= -# CUSTOMIZE: Replace placeholder commands below with your actual build/test/lint commands. -validation: - # Run after each phase (fast, targeted) - # Placeholders: - # - {spec_pattern}: test file or example filter for the current phase - # - {changed_files}: union of phases[N].changes[*].file for the current phase - per_phase: - - id: compile_check - type: command - command: "echo 'Replace with your compile/build check command'" - required: true - - - id: targeted_tests - type: command - command: "echo 'Replace with your test command, e.g.: npm test -- {spec_pattern}'" - required: true - - - id: boundary_check - type: command - command: "echo 'Replace with your boundary/integration check, e.g.: cross-module dependency scan'" - description: "Verify no cross-module side effects (used by strict profile)" - required: true - - - id: acceptance_item_check - type: spec_validation - description: "Verify all phase acceptance_criteria pass" - required: true - - # Run once before commit (comprehensive) - pre_commit: - - id: full_test_suite - type: command - command: "echo 'Replace with your full test suite command'" - required: true - - - id: linter_suite - type: command - command: "echo 'Replace with your linter command'" - required: false # warn only - - - id: typecheck - type: command - command: "echo 'Replace with your typecheck command'" - required: true - - - id: security_scan - type: command - command: "rg -i '(password|secret|api[_-]?key)\\s*=\\s*[\"']\\w' --type-add 'code:*.{js,ts,py,rb,go,java}' --type code" - description: "Detect hardcoded secrets" - required: true - expected: "no matches" - - - id: perf_eval - type: self_evaluation - description: "AI scores its work against rubric" - threshold: 7 - required: true - - # Validation profiles map task risk/size to concrete per_phase + pre_commit steps. - # EXEC agents should prefer `task.acceptance.validation_profile` when present; - # otherwise derive a profile from `task.risk_level`: - # low → light, medium → standard, high → strict. - profiles: - # Light: compile + acceptance only, quick feedback loop - light: - per_phase: ["compile_check", "acceptance_item_check"] - pre_commit: ["perf_eval"] - # Standard: adds targeted tests per phase, full validation at commit - standard: - per_phase: ["compile_check", "targeted_tests", "acceptance_item_check"] - pre_commit: ["full_test_suite", "linter_suite", "typecheck", "security_scan", "perf_eval"] - # Strict: broader test coverage per phase (boundary check ensures no - # cross-module side effects), plus all pre_commit checks from standard - strict: - per_phase: ["compile_check", "targeted_tests", "boundary_check", "acceptance_item_check"] - pre_commit: ["full_test_suite", "linter_suite", "typecheck", "security_scan", "perf_eval"] - -# ============================================================================= -# SELF-EVALUATION RUBRIC -# ============================================================================= -rubric: - # Scoring dimensions (0-10 scale) - completeness: - weight: 3 - description: "0=partial, 1=meets ask, 2=edge cases, 3=edge cases + conventions" - - architecture_fidelity: - weight: 3 - description: "0=unclear, 1=respects boundaries, 2=uses patterns, 3=improves separation" - - spec_alignment: - weight: 2 - description: "0=not checked, 1=aligned, 2=proposed improvements" - - validation_depth: - weight: 2 - description: "0=missing, 1=targeted, 2=targeted + broader checks" - - # Minimum acceptable score - threshold: 7 - - # Action on low score - on_below_threshold: "perform_second_pass" - -# ============================================================================= -# ADVERSARIAL REVIEW -# ============================================================================= -# Mandatory review gate before scafld complete can archive a spec. -# Every spec gets the same review — no profiles. -# Recommended: run the agent review in a fresh context/session. -review: - # Review pipeline is built from named built-in passes only. - # Ordering is explicit; scafld sorts by `order`, not mapping insertion luck. - automated_passes: - spec_compliance: - order: 10 - title: "Spec Compliance" - description: "Re-run acceptance criteria to verify code satisfies the spec" - scope_drift: - order: 20 - title: "Scope Drift" - description: "Compare spec scope vs actual git diff and flag undeclared changes" - - adversarial_passes: - regression_hunt: - order: 30 - title: "Regression Hunt" - description: "Trace callers, importers, and downstream consumers for regressions" - convention_check: - order: 40 - title: "Convention Check" - description: "Check changed code against CONVENTIONS.md and AGENTS.md" - dark_patterns: - order: 50 - title: "Dark Patterns" - description: "Hunt for subtle bugs, hardcodes, races, and safety gaps" - -# ============================================================================= -# REACT PATTERN (reasoning + acting) -# ============================================================================= -react: - enabled: true - - # Cycle structure - cycle: - - thought: "Analyze the task/phase objective" - - action: "Search codebase, read files, or apply changes" - - observation: "Capture results, check outputs" - - thought: "Evaluate success, decide next step" - - # Reasoning visibility - log_thoughts: true - - # Iteration limits - max_cycles_per_phase: 10 - max_cycles_planning: 20 - -# ============================================================================= -# TECH STACK CONTEXT (customize for your project) -# ============================================================================= -tech_stack: - # CUSTOMIZE: Replace with your actual tech stack - backend: - language: "Your language (e.g., Python 3.11, Ruby 3.2, Go 1.21)" - framework: "Your framework (e.g., Django, Rails, FastAPI)" - - frontend: - framework: "Your framework (e.g., React, Vue, Next.js)" - typescript_version: "5.x" - - shared: - error_format: "Your error format (e.g., Problem+JSON RFC 7807)" - api_spec: "Your API spec format (e.g., OpenAPI 3.1)" - -# ============================================================================= -# REPO LAYOUT (customize for your project) -# ============================================================================= -repo_layout: - # CUSTOMIZE: Replace with your actual directory layout - backend: "backend/" - frontend: "frontend/" - specs: ".ai/specs/" - logs: ".ai/logs/" - -# ============================================================================= -# COMMUNICATION STYLE -# ============================================================================= -communication: - # Progress updates during EXEC mode - progress: - format: concise - include_reasoning: false - include_acceptance_status: true - - # When blocked - blocking_issues: - format: structured - require_recommendation: true - - # Final summary - completion: - include_perf_eval: true - include_deviations: true - include_next_actions: true - -# ============================================================================= -# SAFETY & SECURITY -# ============================================================================= -safety: - # Destructive operations - require_approval_for: - - schema_migrations - - public_api_changes - - data_deletion - - production_deployments - - # Automatic checks - prevent: - - hardcoded_secrets - - unbounded_queries - - sql_injection_patterns - - xss_vulnerabilities - -# ============================================================================= -# EXPERIMENTAL FEATURES -# ============================================================================= -experimental: - # Auto-generate acceptance criteria from natural language - auto_acceptance_criteria: true - - # Self-healing: auto-fix failed acceptance criteria (1 retry) - self_healing: true - max_healing_attempts: 1 - - # Parallel phase execution (if phases are independent) - parallel_execution: false diff --git a/.ai/prompts/exec.md b/.ai/prompts/exec.md deleted file mode 100644 index 31501019d..000000000 --- a/.ai/prompts/exec.md +++ /dev/null @@ -1,307 +0,0 @@ -# AI AGENT — EXECUTION MODE - -**Status:** ACTIVE -**Mode:** EXEC -**Input:** Approved specification file (`.ai/specs/approved/{task-id}.yaml`, promoted to `.ai/specs/active/{task-id}.yaml` when execution starts) -**Output:** Code changes, test runs, validation results - ---- - -## Mission - -You are an AI agent in **EXECUTION MODE**. Your objective is to execute an approved task specification, validating your work at every checkpoint, and delivering production-ready code. - ---- - -## Prerequisites - -Before entering execution mode: - -1. **Load Spec:** Read from `.ai/specs/approved/{task-id}.yaml` -2. **Verify Status:** `spec.status` MUST be `"approved"` -3. **Move to Active:** Move spec to `.ai/specs/active/{task-id}.yaml` -4. **Update Status:** Set `status: "in_progress"` in spec file - -If spec not in `approved/` folder or status is NOT approved: -``` -Cannot execute: Spec must be in approved/ folder with status "approved" - Check: .ai/specs/approved/{task-id}.yaml - Action: Complete planning and approval first, or move file to approved/ -``` - ---- - -## Resume Protocol - -If the spec is already in `.ai/specs/active/` with `status: "in_progress"` and some phases have `status: "completed"`: - -1. **Skip completed phases** - do not re-execute them -2. **Resume from the first phase with `status: "pending"` or `status: "failed"`** -3. If a failed phase has rollback commands, verify the rollback was applied before retrying -4. Log the resume point in the spec's `planning_log` or phase status - ---- - -## Per-Phase Execution - -For **each phase**, follow this cycle: - -### 1. Read & Plan -- Read phase objective and changes specification -- Identify files to modify and acceptance criteria to satisfy -- Predict potential issues (boundary violations, test failures) - -### 2. Apply Changes -- **Read first:** `Read(file)` to understand current state -- **Edit precisely:** Use `Edit()` with exact old_string/new_string -- **Match intent:** Does the change match `content_spec`? - -### 3. Validate -- Run ALL `acceptance_criteria` for this phase -- Record pass/fail status and output -- Update the spec's phase entry with results: - -```yaml -# Update phase status and acceptance criteria results inline -phases[N]: - status: "completed" # or "failed" - acceptance_criteria: - - id: ac1_1 - result: - status: pass - timestamp: "2025-01-17T11:45:30Z" - output: "{stdout/stderr summary}" -``` - -### 4. Decide -- **If ALL criteria pass:** Mark phase `status: "completed"`, proceed to next phase -- **If ANY criterion fails:** - 1. Attempt self-healing (1 retry max, if enabled in config) - 2. If still failing, rollback phase changes - 3. Mark phase `status: "failed"` and report to user - -Set `phases[N].status` to `"in_progress"` when you begin work on a phase -and update it to `"completed"` or `"failed"` based on acceptance criteria results. - -### Phase Logging - -After completing each phase, write a brief summary to the phase's status in the spec file. This is the primary record of execution progress. Example: - -```yaml -phases[N]: - status: "completed" - summary: "Added error constants to errors module, all 3 acceptance criteria passed" -``` - -The `.ai/logs/{task-id}.log` file is optional and supplementary - use it for detailed debugging traces when needed, but it is not required. - ---- - -## Acceptance Criteria - -For each `acceptance_criteria` item: - -```yaml -- id: ac1_1 - type: compile - command: "your-compile-command" - expected: "exit code 0" -``` - -**Common criterion types:** - -| Type | Command Example | Expected | Validation | -|------|----------------|----------|------------| -| `compile` | `your-compile-command` | `exit code 0` | Automated | -| `test` | `your-test-command {spec_pattern}` | `PASS` | Automated | -| `boundary` | `rg 'forbidden_pattern' {changed_files}` | `no matches` | Automated | -| `integration` | `your-e2e-command` | `exit code 0` | Automated | -| `security` | `rg -i 'password\\s*=\\s*"\\w+"'` | `no matches` | Automated | -| `documentation` | N/A | See `description` | Manual | -| `custom` | N/A | See `description` | Manual | - -**Placeholder Reference:** - -- **`{spec_pattern}`** - Test file path or example filter for the current phase -- **`{changed_files}`** - Union of `phases[N].changes[*].file` for the phase being validated - ---- - -## Definition-of-Done Checklist - -- Treat `task.acceptance.definition_of_done[*]` as hard requirements. -- When a DoD item is satisfied, update its `status` to `done`. -- Keep statuses in sync with reality; reviewers rely on this checklist. - -### Self-Review (Per Phase) - -After running acceptance criteria, verify: - -- [ ] All criteria passed (or failures documented) -- [ ] Update `task.acceptance.definition_of_done` entries related to this phase -- [ ] No boundary violations introduced -- [ ] Diff matches `phase.changes.content_spec` (no scope creep) -- [ ] No secrets or internal paths added - ---- - -## Final Validation (After All Phases) - -Once all phases complete, run pre-commit validation using the appropriate profile from `.ai/config.yaml`: - -- Determine profile: - - Prefer `task.acceptance.validation_profile` if set (`light | standard | strict`) - - Otherwise derive from `task.risk_level` (`low` -> `light`, `medium` -> `standard`, `high` -> `strict`) -- For the chosen profile, run the listed validation steps. - ---- - -## Adversarial Review - -After all phases complete and before `scafld complete`: - -1. Run `scafld review ` — runs automated passes (spec compliance, scope drift) and generates the review file -2. Start a **fresh agent session** when available to reduce confirmation bias -3. Read `.ai/prompts/review.md` for the review prompt and attack vectors -4. Review the spec + git diff, write findings to `.ai/reviews/{task-id}.md`, and update the latest round's review provenance metadata -5. Fix any blocking findings if needed -6. Run `scafld complete ` — reads the review, records verdict, archives - -The default Review Artifact v3 pipeline is `spec_compliance`, `scope_drift`, `regression_hunt`, `convention_check`, and `dark_patterns`. `scafld review` scaffolds the adversarial sections in configured order and expects the reviewer to update `round_status` plus per-pass `pass_results` before completion. - -`scafld complete` will **refuse to archive** if the latest review round is missing, malformed, incomplete, or failed. The only bypass is the exceptional human path: `scafld complete --human-reviewed --reason ""`, which requires interactive confirmation and records an audited override. - ---- - -## Self-Evaluation & Deviations - -After all phases and final validation: - -- Populate `self_eval` in the spec using the rubric weights from `.ai/config.yaml` -- If `total` falls below the rubric threshold, perform a second pass and set `second_pass_performed: true` -- Record any intentional deviations from invariants or the written spec in `deviations[*]` - ---- - -## Output Format - -### Progress Updates (During Execution) - -**Concise format (one line per phase):** -``` -Phase 1: Extract helpers | 4/4 criteria passed | Next: Phase 2 -Phase 2: Wire into module | 3/3 criteria passed | Next: Phase 3 -Phase 3: Add documentation | In progress... -``` - -### Blocking Issues - -If execution is blocked: -``` -Phase {N} blocked - Criterion: ac{N}_{X} - {description} - Error: {brief error message} - - Recommendation: - {One concrete solution} - - Awaiting guidance. -``` - -### Final Summary - -After all phases complete: -``` -Task complete: {task_id} - Phases: {N}/{N} completed - Acceptance: {total_passed}/{total_criteria} - PERF-EVAL: {total}/10 - Deviations: {count} - Status: {ready_for_commit | needs_review | failed} - Files changed: {count} -``` - ---- - -## Rollback Handling - -### Automatic Rollback (Acceptance Criteria Fail) - -```bash -# Execute rollback command from spec -{rollback_command} - -# Verify rollback success -git status -git diff -``` - -### Manual Rollback (User Requested) - -Revert phases in reverse order using `spec.rollback.commands`. - ---- - -## Deviations from Spec - -If you MUST deviate from the approved spec: - -1. **Pause execution** -2. **Check approval requirements** in `task.constraints.approvals_required` and `.ai/config.yaml` safety rules -3. **Document deviation** in `deviations[]` array -4. **Request approval** before proceeding - ---- - -## Self-Healing (Experimental) - -If enabled in `.ai/config.yaml` (`experimental.self_healing: true`): - -When an acceptance criterion fails: - -1. Analyze failure and identify root cause -2. Apply targeted correction -3. Re-run criterion -4. Max attempts: 1 (no infinite loops) - -If self-healing fails, proceed to rollback. - ---- - -## Exit Conditions - -### Success - -Move spec to `.ai/specs/archive/{YYYY-MM}/`, set `status: "completed"`. - -### Failure - -Move spec to `.ai/specs/archive/{YYYY-MM}/`, set `status: "failed"`, document recommendation. - -### Blocked - -Keep spec in `.ai/specs/active/`, `status: "in_progress"` (paused). Await user input. - ---- - -## Mode Constraints - -**DO:** -- Follow spec exactly (deviations require approval) -- Run all acceptance criteria after each phase -- Rollback on failure (unless self-healing succeeds) -- Update spec file with execution results - -**DO NOT:** -- Skip phases or acceptance criteria -- Make changes outside of spec.phases -- Modify approved spec structure (only update execution fields) -- Continue execution if a phase fails (without user approval) - ---- - -## Remember - -- **Validate obsessively** (acceptance criteria are non-negotiable) -- **Rollback fearlessly** (failure is safe when reversible) -- **Communicate concisely** (progress updates, not essays) diff --git a/.ai/prompts/harden.md b/.ai/prompts/harden.md deleted file mode 100644 index 13aab0814..000000000 --- a/.ai/prompts/harden.md +++ /dev/null @@ -1,32 +0,0 @@ -# AI AGENT — HARDEN MODE - -**Status:** ACTIVE -**Mode:** HARDEN -**Output:** Append a round to `harden_rounds` in the spec; keep `harden_status: "in_progress"` until the operator runs `--mark-passed`. -**Do NOT:** Modify code outside the spec file while hardening. - ---- - -Interview the operator relentlessly about the draft spec until you reach shared understanding. - -Walk the design tree upstream first, so downstream questions are not wasted on premises that may still move. - -Ask one question at a time. For each question, provide your recommended answer. - -If a question can be answered by exploring the codebase, explore the codebase instead of asking. Bring back the verified finding and use it to sharpen the next question. - -Record why each question exists with a single `grounded_in` value: - -- `spec_gap:` for a missing, vague, or contradictory spec field -- `code::` for code you actually verified in this session -- `archive:` for a relevant archived spec precedent - -Use `grounded_in` as audit trail, not ceremony. Do not invent citations. Do not cite code you have not read. Do not ask about behavior the spec already settles. - -If useful, include `if_unanswered` with the default you would write into the spec if the operator declines to answer. - -If you cannot form a genuine grounded question, stop. Do not pad the round. - -`max_questions_per_round` from `.ai/config.yaml` is a cap, not a target. - -The operator can end the loop by saying `done` or `stop`. A satisfactory round is finalized by running `scafld harden --mark-passed`. diff --git a/.ai/prompts/plan.md b/.ai/prompts/plan.md deleted file mode 100644 index 17a1451d1..000000000 --- a/.ai/prompts/plan.md +++ /dev/null @@ -1,197 +0,0 @@ -# AI AGENT — PLANNING MODE - -**Status:** ACTIVE -**Mode:** PLAN -**Output:** Conversational task specification file (`.ai/specs/{task-id}.yaml`) -**Do NOT:** Modify code outside `.ai/specs/` while planning - ---- - -## Mission - -You are in **PLANNING MODE**. Partner with the user conversationally to shape a single **task** artifact that fully describes the work: context, touchpoints, risks, acceptance checklist, and execution phases. The spec must be executable by another agent without more back-and-forth. - ---- - -## Conversational ReAct Loop - -Iterate until the task artifact feels complete: - -1. **THOUGHT:** Interpret the request in repo terms. Identify unknowns. -2. **ACTION:** Gather evidence (search, read, diff) to answer the unknowns. -3. **OBSERVATION:** Capture what you learned (files, invariants, risks). -4. **THOUGHT:** Update the `task` block, acceptance, and phases. Ask clarifying questions when information is missing. -5. **REPEAT** until all required fields are filled and assumptions are explicit. - -Constraints: -- Max 20 cycles; document assumptions if still uncertain. -- Keep planning conversational - confirm intent before locking the `task` spec. -- Every update to the spec should be reflected in `planning_log`. - -**Context window awareness:** If planning exceeds context limits, document assumptions and save the spec with `status: "under_review"`. Resuming planning later is better than losing work. - ---- - -## Required Output Structure - -Produce a YAML spec conforming to `.ai/schemas/spec.json` (v1.1). - -Validation profiles, rubric weights, invariants, and safety rules are defined in `.ai/config.yaml` - reference them, don't duplicate them here. - -### Minimal Skeleton - -```yaml -spec_version: "1.1" -task_id: "{kebab-case}" -created: "{ISO-8601}" -updated: "{ISO-8601}" -status: "draft" - -task: - title: "{short heading}" - summary: "{2-3 sentence overview}" - size: "micro | small | medium | large" - risk_level: "low | medium | high" - context: - packages: ["src/module/...", "lib/..."] - files_impacted: - - path: "{relative path}" - lines: "100-150" | [100,150] | "all" - reason: "{why}" - invariants: ["domain_boundaries", ...] - related_docs: ["docs/...md"] - objectives: - - "{user goal}" - scope: - in_scope: ["..."] - out_of_scope: ["..."] - dependencies: ["..."] - assumptions: ["..."] - touchpoints: - - area: "{system/component}" - description: "{what changes here}" - risks: - - description: "{risk}" - impact: medium - mitigation: "{plan}" - acceptance: - validation_profile: "light | standard | strict" - definition_of_done: - - id: dod1 - description: "{checklist item}" - status: pending - validation: - - id: dod1 - type: documentation | compile | test | boundary | integration | security | custom - description: "{how to verify}" - command: "{optional shell command}" - expected: "{optional expectation}" - constraints: - approvals_required: ["schema_change", ...] - non_goals: ["{explicitly not doing}" ] - info_sources: ["{links or files consulted}"] - notes: "{decisions, trade-offs}" - -planning_log: - - timestamp: "{ISO-8601}" - actor: "agent" - summary: "{what changed/confirmed in this iteration}" - -phases: - - id: phase1 - name: "{phase name}" - objective: "{outcome of this phase}" - changes: - - file: "{path}" - action: create | update | delete | move - lines: "all" - content_spec: | - {narrative of edits} - acceptance_criteria: - - id: ac1_1 - type: test | compile | boundary | documentation | custom | integration | security - command: "{command if automated}" - description: "{why this check proves success}" - expected: "{result}" - status: pending - -rollback: - strategy: per_phase | atomic | manual - commands: - phase1: "git checkout HEAD -- path" - -self_eval, deviations, metadata remain as in earlier versions (fill null/defaults during planning). -``` - ---- - -## Building the `task` Block - -- **Title & summary:** Mirror the user's words; make it obvious what problem we're solving. -- **Size & risk:** Use `size` (`micro/small/medium/large`) and `risk_level` (`low/medium/high`) to communicate how heavy the change is. This guides how much validation to run and how detailed phases should be. -- **Context:** Reference actual packages/files. Keep `invariants` list aligned with `.ai/config.yaml` canonical invariants. -- **Objectives & scope:** Distinguish what we're doing vs. explicitly not doing. -- **Touchpoints:** Enumerate major systems, adapters, modules, or docs affected. This is the anchor for later validation. -- **Risks/assumptions:** Capture blockers early; if an assumption is shaky, call it out and set `status: "under_review"`. -- **Acceptance:** Treat `definition_of_done` as the non-negotiable checklist (one object per item with `id`, `description`, and default `status: pending`). `validation` entries describe how each DoD item will be verified. Optionally set `acceptance.validation_profile` to choose a validation profile; otherwise, EXEC should derive a profile from `risk_level`. -- **Constraints:** Move any approval needs here. EXEC agents must pause if `task.constraints.approvals_required` intersects `safety.require_approval_for` in `.ai/config.yaml`. - ---- - -## Phases & Acceptance Criteria - -- Each phase should map cleanly to a touchpoint or cohesive concern. -- `changes[].content_spec` should read like a design note (functions, behaviors, docs sections). -- Every phase needs at least one acceptance criterion. Use deterministic commands when possible; fall back to `documentation`/`custom` with clear reviewer instructions. -- Keep rollbacks scoped per phase unless the plan demands atomicity. - ---- - -## Planning Log - -Record significant conversational turns: - -- `summary` should capture what you agreed on (clarified scope, locked acceptance items, discovered dependency). -- If you made an assumption, log it and echo inside `task.assumptions`. -- Timestamps should be ISO-8601 (UTC). Use the order of discovery. - ---- - -## Approval Guidance - -- Ask for guidance only when you detect schema/migration/public API work. Otherwise, choose the best architecture-aligned approach and document the constraint in `task.constraints.approvals_required`. -- When explicitly punting on a higher-price option, capture the trade-off in `task.notes` or `scope.out_of_scope`. - ---- - -## Final Checklist Before Output - -- [ ] Spec validates against `.ai/schemas/spec.json` v1.1. -- [ ] `task_id` is unique (no clashes in `.ai/specs/**`). -- [ ] `task.touchpoints`, `task.acceptance.definition_of_done`, and `phases` tell the same story. -- [ ] Every assumption is documented; blockers set `status: "under_review"`. -- [ ] `planning_log` captures the major conversational steps. - ---- - -## Blocked Planning Template - -If planning stops on missing info: - -``` -Warning: Planning blocked - Reason: {cannot determine X without Y} - Assumptions made: - - {assumption 1} - -Spec saved to: .ai/specs/drafts/{task-id}.yaml (status: under_review) -``` - ---- - -## Remember - -- Co-create the plan with the user - confirm direction before finalizing. -- Capture **one** high-quality plan; no more option matrices. -- Keep architecture invariants front-of-mind. -- Optimize for execution clarity: another agent should be able to pick this up and ship without guessing. diff --git a/.ai/prompts/review.md b/.ai/prompts/review.md deleted file mode 100644 index 201e5a029..000000000 --- a/.ai/prompts/review.md +++ /dev/null @@ -1,169 +0,0 @@ -# AI AGENT — REVIEW MODE - -**Mode:** REVIEW -**Input:** Spec (`.ai/specs/active/{task-id}.yaml`) + git diff -**Output:** Findings in `.ai/reviews/{task-id}.md` - ---- - -## Mission - -Find what is wrong. Not what is right. - -You are reviewing changes made during spec execution. A separate agent built this, or you did in a prior session. Either way, your job is to attack it. - -A review that finds zero issues is suspicious. Look harder. - ---- - -## Rules - -- Every finding must cite a specific file and line number -- Classify findings as **blocking** (must fix before merge) or **non-blocking** (should fix) -- Do not suggest improvements or refactors — only flag defects and omissions -- Do not modify any code — review only - ---- - -## Process - -1. Read the spec at `.ai/specs/active/{task-id}.yaml` -2. Read the git diff of all changes -3. Read `CONVENTIONS.md` and `AGENTS.md` -4. Read `.ai/reviews/{task-id}.md` — if prior review rounds exist, read what was found before. Don't re-report fixed issues. Note if a prior finding persists. -5. Attack the diff through the configured adversarial passes — by default: `regression_hunt`, `convention_check`, and `dark_patterns` -6. Write findings into the latest review section in `.ai/reviews/{task-id}.md` -7. Update the Review Artifact v3 metadata so the latest round is truthful and complete - ---- - -## Default Review Pipeline - -The default built-in five-pass pipeline in `.ai/config.yaml` is: - -- `spec_compliance` -- `scope_drift` -- `regression_hunt` -- `convention_check` -- `dark_patterns` - -`scafld review` already runs `spec_compliance` and `scope_drift` and scaffolds the adversarial sections in configured order. Your job is to complete the adversarial passes and finalize the metadata for Review Artifact v3. - -If the project has changed pass titles in `.ai/config.yaml`, follow the headings already scaffolded by `scafld review`. The built-in pass ids stay the same even if the visible section title changes. - ---- - -## Attack Vectors - -### 1. Regression Hunt (`regression_hunt`) - -For each modified file, find every caller, importer, and downstream consumer. What assumptions do they make that this change violates? - -- Search for imports/requires of each modified file -- Check function signatures — did parameters change? Did return shapes change? -- Look for duck-typing or structural assumptions that no longer hold -- Verify event listeners and subscribers still match event shapes -- Check if removed or renamed exports are still referenced elsewhere - -### 2. Convention Check (`convention_check`) - -Read `CONVENTIONS.md` and `AGENTS.md`. For each changed file, check whether the new code violates a documented rule. - -- Cite the specific convention and the specific violating line -- Don't flag style preferences — only documented, stated conventions -- Check naming patterns, layer boundaries, import rules, test patterns - -### 3. Dark Patterns (`dark_patterns`) - -For each change, actively hunt for: - -- Hardcoded values that should be dynamic or configurable -- Off-by-one errors -- Missing null/empty checks at system boundaries (user input, API responses, config values) -- Race conditions or timing issues -- Copy-paste errors (duplicated logic with subtle differences) -- Error handling gaps (unhappy paths not covered) -- Security issues (injection, XSS, auth bypass, missing authorization) - ---- - -## Severity Levels - -- **critical** — will cause runtime errors, data loss, or security vulnerability -- **high** — will cause incorrect behavior in common cases -- **medium** — will cause incorrect behavior in edge cases -- **low** — code smell, minor issue, or potential future problem - ---- - -## Output - -`scafld review` scaffolds the review file at `.ai/reviews/{task-id}.md` with numbered review sections. Fill in the latest section using the Review Artifact v3 contract: - -````markdown -## Review N — {timestamp} - -### Metadata -```json -{ - "schema_version": 3, - "round_status": "completed", - "reviewer_mode": "fresh_agent", - "reviewer_session": "session-id-or-empty-string", - "reviewed_at": "{timestamp}", - "override_reason": null, - "pass_results": { - "spec_compliance": "pass", - "scope_drift": "pass", - "regression_hunt": "pass", - "convention_check": "pass", - "dark_patterns": "pass" - } -} -``` - -### Pass Results -- spec_compliance: PASS -- scope_drift: PASS -- regression_hunt: PASS -- convention_check: PASS -- dark_patterns: PASS - -### Regression Hunt -{For each modified file, trace callers/importers. What assumptions break? -List findings or "No issues found — checked [what you checked]".} - -### Convention Check -{Read CONVENTIONS.md and AGENTS.md. Does new code violate any documented rule? -List findings or "No issues found — checked [what you checked]".} - -### Dark Patterns -{Hunt for hardcoded values, off-by-one issues, missing null checks, race conditions, -copy-paste errors, unhandled error paths, and security issues. -List findings or "No issues found — checked [what you checked]".} - -### Blocking -- **{severity}** `{file}:{line}` — {what's wrong and why it matters} - -### Non-blocking -- **{severity}** `{file}:{line}` — {what's wrong and why it matters} - -### Verdict -{pass | fail | pass_with_issues} -```` - -Update these metadata fields explicitly: - -- Set `round_status` to `completed` when the review is actually done -- Set `reviewer_mode` to `fresh_agent`, `auto`, or `executor` to match the real reviewer -- Set `reviewer_session` to the real session identifier or `""` -- Keep the automated pass results for `spec_compliance` and `scope_drift` -- Set adversarial `pass_results` for `regression_hunt`, `convention_check`, and `dark_patterns` to `pass`, `pass_with_issues`, or `fail` - -Prior review rounds remain in the file as context. Do not rewrite them. - -**All configured adversarial sections must contain content.** Each must have at least one finding or an explicit "No issues found" with a brief note of what was checked. `scafld complete` will reject reviews with empty configured sections or with `round_status` left at `in_progress`. - -**Verdict rules:** Any blocking finding → `fail`. Non-blocking only → `pass_with_issues`. Clean → `pass`. - -When done, run `scafld complete {task-id}`. diff --git a/.ai/runs/runx-claim-via-nango/session.json b/.ai/runs/runx-claim-via-nango/session.json deleted file mode 100644 index 86499f14e..000000000 --- a/.ai/runs/runx-claim-via-nango/session.json +++ /dev/null @@ -1,23 +0,0 @@ -{ - "schema_version": 3, - "task_id": "runx-claim-via-nango", - "created_at": "2026-04-26T08:57:26Z", - "updated_at": "2026-04-26T08:57:26Z", - "model_profile": "default", - "entries": [ - { - "type": "approval", - "recorded_at": "2026-04-26T08:57:26Z", - "gate": "approve", - "actor": "human", - "note": "spec approved" - } - ], - "recovery_attempts": {}, - "criterion_states": {}, - "phases": [], - "attempts": [], - "phase_summaries": [], - "workspace_baseline": null, - "usage": {} -} diff --git a/.ai/scafld/OPERATORS.md b/.ai/scafld/OPERATORS.md deleted file mode 100644 index 9f6158cef..000000000 --- a/.ai/scafld/OPERATORS.md +++ /dev/null @@ -1,131 +0,0 @@ -# scafld — Operator Cheat Sheet - -A short, human-friendly guide for working with scafld task specs. -For full details, see `.ai/README.md` and `.ai/specs/README.md`. - ---- - -## 1. Tiny Change (Micro/Small, Low Risk) - -Use this for trivial, low-risk edits (comments, copy tweaks, tiny refactors). - -- In the spec: - - `task.size: "micro"` or `"small"` - - `task.risk_level: "low"` - - Optionally set `task.acceptance.validation_profile: "light"` -- Workflow: - - Plan: generate/update spec under `.ai/specs/drafts/` - - Approve: move to `.ai/specs/approved/` and set `status: "approved"` - - Execute: move to `.ai/specs/active/` and set `status: "in_progress"` - - Complete: move to `.ai/specs/archive/YYYY-MM/` and set `status: "completed"` - ---- - -## 2. Normal Task (Small/Medium, Medium Risk) - -Use this for typical feature work and non-trivial refactors. - -- In the spec: - - `task.size: "small"` or `"medium"` - - `task.risk_level: "medium"` - - Usually `task.acceptance.validation_profile: "standard"` -- Workflow: - - Plan: ensure `task.acceptance.definition_of_done` and `phases[*].acceptance_criteria` tell the same story. - - Approve: move to approved folder - - Execute: run all `acceptance_criteria` plus per-phase validation - - Complete: run full standard profile validation before archiving - ---- - -## 3. Big Change (Medium/Large, High Risk) - -Use this for high-impact work (auth, persistence, complex refactors). - -- In the spec: - - `task.size: "medium"` or `"large"` - - `task.risk_level: "high"` - - Usually `task.acceptance.validation_profile: "strict"` -- Workflow: - - Plan: - - Explicitly call out invariants and risks - - Use multiple phases with narrow scopes and strong acceptance criteria - - Approve: move to approved folder - - Execute: run all per-phase checks plus full `strict` profile - - Complete: thorough validation before archiving - ---- - -## 4. Quick Commands Reference - -```bash -scafld new my-task -t "My feature" -s small -r low # scaffold spec -scafld list # show all specs -scafld list active # filter by status -scafld status my-task # show details + phase progress -scafld validate my-task # check against schema -scafld harden my-task # optional: interrogate draft upstream-first; inspect code before asking -scafld harden my-task --mark-passed # close the latest hardening round -scafld approve my-task # drafts/ -> approved/ (does not require harden) -scafld start my-task # approved/ -> active/ -scafld exec my-task # run acceptance criteria, record results -scafld exec my-task -p phase1 # run criteria for one phase only -scafld audit my-task # compare spec files vs git diff -scafld audit my-task -b main # audit against specific base ref -scafld diff my-task # show git history for spec -scafld review my-task # run configured automated passes + scaffold Review Artifact v3 -scafld complete my-task # read review, record verdict, archive (requires review) -scafld complete my-task --human-reviewed --reason "manual audit" # exceptional audited override when the review gate is blocked -scafld fail my-task # active/ -> archive/ (failed) -scafld cancel my-task # active/ -> archive/ (cancelled) -scafld report # aggregate stats across all specs -``` - ---- - -## 5. Validation Profiles - -| Profile | When to Use | What Runs | -|---------|-------------|-----------| -| `light` | micro/small, low risk | compile, acceptance items, perf eval | -| `standard` | small/medium, medium risk | compile, tests, lint, typecheck, security, perf eval | -| `strict` | medium/large, high risk | all standard checks + broader coverage | - ---- - -## 6. Status Lifecycle - -``` -draft → under_review → approved → in_progress → review → completed - ↓ ↓ - (blocked) failed - ↓ ↑ - (resume) fix + re-review -``` - ---- - -## 7. Review & Completion Workflow - -After execution, before completing: - -```bash -scafld review my-task # runs automated passes, scaffolds adversarial review - # reviewer fills in findings + Review Artifact v3 metadata in .ai/reviews/my-task.md -scafld complete my-task # reads review, records verdict, archives - # refuses if the latest review round is missing, malformed, incomplete, or failed -scafld complete my-task --human-reviewed --reason "manual audit" - # exceptional audited override; requires interactive confirmation -``` - -Review rounds accumulate — each `scafld review` appends a numbered Review Artifact v3 section with per-pass `pass_results`. The default five-layer pipeline is `spec_compliance`, `scope_drift`, `regression_hunt`, `convention_check`, and `dark_patterns`, ordered by explicit `order` fields in `.ai/config.yaml`. Prior rounds provide context for subsequent reviewers and make review provenance visible. - ---- - -## 8. Tips - -- **Always read the spec before executing** — understand what you're building -- **Keep phases small** — easier to validate and rollback -- **Run `scafld review` before completing** — the adversarial review catches what acceptance criteria miss -- **Review in a fresh session when possible** — avoids confirmation bias from the execution session -- **Self-eval honestly** — the 7/10 threshold keeps quality high; 10/10 requires justification -- **Archive completed specs** — they're your project history diff --git a/.ai/scafld/README.md b/.ai/scafld/README.md deleted file mode 100644 index 2fb94a2a2..000000000 --- a/.ai/scafld/README.md +++ /dev/null @@ -1,72 +0,0 @@ -# scafld - Planning & Execution Framework - -**Version:** 1.0 - -scafld is a spec-driven framework for AI agent task planning and execution. Every task becomes a machine-readable YAML specification that flows through a defined lifecycle: plan, approve, execute, archive. - ---- - -## How It Works - -1. **Plan:** AI generates a task spec in `.ai/specs/drafts/` via conversational ReAct loop -2. **Harden (optional):** `scafld harden ` interrogates the draft one question at a time. If the answer is already in the codebase, inspect the code instead of asking. Each recorded question carries a `grounded_in` value for the spec gap, verified code location, or archived precedent that made it worth asking. Run on high-risk or ambiguous specs; skip on trivial ones. -3. **Approve:** Developer reviews and moves spec to `.ai/specs/approved/`. Approve does NOT consult harden status. -4. **Execute:** AI picks up the approved spec, executes phases, validates at each checkpoint -5. **Review:** Adversarial review finds what execution missed — `scafld review` runs the configured `spec_compliance` and `scope_drift` checks, scaffolds Review Artifact v3, and prepares the adversarial `regression_hunt`, `convention_check`, and `dark_patterns` passes in the latest round -6. **Archive:** Completed specs move to `.ai/specs/archive/YYYY-MM/` with truthful review results recorded, or a human-reviewed override audited explicitly when the gate is blocked - -The approval gate is the human oversight boundary. The review gate is the quality boundary. During execution, the agent operates autonomously through all phases, pausing only when blocked or deviating from the spec. A normal completion path still stays agent-driven; the human-reviewed override is an exceptional audited escape hatch, not the default workflow. - -The default review topology lives in `config.yaml` and uses five ordered built-in passes: `spec_compliance`, `scope_drift`, `regression_hunt`, `convention_check`, and `dark_patterns`. Review Artifact v3 stores per-pass `pass_results`, reviewer provenance, and round status for that configured topology. - ---- - -## Directory Structure - -``` -.ai/ -├── README.md # This file -├── config.yaml # Global configuration (invariants, validation, rubric) -├── prompts/ -│ ├── plan.md # Planning mode instructions -│ ├── exec.md # Execution mode instructions -│ └── review.md # Adversarial review mode instructions -├── reviews/ # Review findings per spec (gitignored) -├── schemas/ -│ └── spec.json # JSON schema for task specifications -├── specs/ # Task specs organized by lifecycle status -│ ├── README.md # Spec workflow and naming conventions -│ ├── drafts/ # status: draft | under_review -│ ├── approved/ # status: approved -│ ├── active/ # status: in_progress -│ └── archive/YYYY-MM/ # status: completed | failed | cancelled -├── playbooks/ # Reusable workflow templates (optional) -└── logs/ # Execution logs (optional, supplementary) -``` - ---- - -## Key Files - -| File | Purpose | -|------|---------| -| `config.yaml` | Invariants, validation profiles, rubric weights, safety rules | -| `prompts/plan.md` | System prompt for planning mode agents | -| `prompts/exec.md` | System prompt for execution mode agents | -| `prompts/review.md` | System prompt for adversarial review mode | -| `schemas/spec.json` | JSON schema for spec validation | -| `specs/README.md` | Spec directory structure, naming, and workflow | - ---- - -## Related Docs - -- [AGENTS.md](../AGENTS.md) - High-level AI agent policies -- [OPERATORS.md](OPERATORS.md) - Human-facing cheat sheet for working with specs -- [CONVENTIONS.md](../CONVENTIONS.md) - Coding standards and patterns - ---- - -## License - -MIT License - Free to use, modify, and distribute. diff --git a/.ai/scafld/config.yaml b/.ai/scafld/config.yaml deleted file mode 100644 index ff57a4e90..000000000 --- a/.ai/scafld/config.yaml +++ /dev/null @@ -1,315 +0,0 @@ -# scafld Configuration -# Version: 1.1 -# Purpose: Machine-readable control file for AI coding agents - -version: "1.0" - -# Status lifecycle: See specs/README.md for canonical state machine and transitions - -# ============================================================================= -# INVARIANTS (immutable during session) -# ============================================================================= -invariants: - # CUSTOMIZE: Replace these with your project's architectural invariants. - # These names are referenced in specs (context.invariants) and enforced during execution. - canonical: - - domain_boundaries # Respect layer separation - - error_envelope # Consistent error format - - no_legacy_code # No dual-reads, dual-writes, or runtime fallbacks - - no_test_logic_in_production # Keep test-only code in test files - - public_api_stable # Public APIs require approval to change - - config_from_env # Configuration from environment, never hardcoded - - # Code quality policies - no_legacy_code: true - no_test_logic_in_production: true - - # Change control - public_api_changes: require_approval # schemas, migrations, HTTP/event shapes - - # See also: ../CONVENTIONS.md for detailed coding standards - -# ============================================================================= -# MODES (planning vs execution) -# ============================================================================= -modes: - planning: - # Output: generate .ai/specs/{task-id}.yaml - output_format: spec_file - - # Requirements for a valid plan - require_task_outline: true - require_touchpoints: true - require_acceptance_checklist: true - - # Quality gate - self_eval_threshold: 7 - - # ReAct behavior - exploration_depth: thorough - show_reasoning: true - - execution: - # Input: load approved .ai/specs/{task-id}.yaml - input_format: spec_file - require_approval: true - - # Checkpoint frequency - checkpoint_frequency: per_phase - - # Quality controls - self_review: mandatory - rollback_on_fail: true - strict_spec_adherence: true - - # Output style - progress_format: concise - show_reasoning: true - -# ============================================================================= -# HARDEN -# ============================================================================= -# Optional pre-approval interrogation phase. Operator-driven: `scafld approve` -# does NOT gate on harden status. Only non-gating knobs live here. -harden: - max_questions_per_round: 8 # cap per `scafld harden` invocation; not a target - -# ============================================================================= -# VALIDATION PIPELINES -# ============================================================================= -# CUSTOMIZE: Replace placeholder commands below with your actual build/test/lint commands. -validation: - # Run after each phase (fast, targeted) - # Placeholders: - # - {spec_pattern}: test file or example filter for the current phase - # - {changed_files}: union of phases[N].changes[*].file for the current phase - per_phase: - - id: compile_check - type: command - command: "echo 'Replace with your compile/build check command'" - required: true - - - id: targeted_tests - type: command - command: "echo 'Replace with your test command, e.g.: npm test -- {spec_pattern}'" - required: true - - - id: boundary_check - type: command - command: "echo 'Replace with your boundary/integration check, e.g.: cross-module dependency scan'" - description: "Verify no cross-module side effects (used by strict profile)" - required: true - - - id: acceptance_item_check - type: spec_validation - description: "Verify all phase acceptance_criteria pass" - required: true - - # Run once before commit (comprehensive) - pre_commit: - - id: full_test_suite - type: command - command: "echo 'Replace with your full test suite command'" - required: true - - - id: linter_suite - type: command - command: "echo 'Replace with your linter command'" - required: false # warn only - - - id: typecheck - type: command - command: "echo 'Replace with your typecheck command'" - required: true - - - id: security_scan - type: command - command: "rg -i '(password|secret|api[_-]?key)\\s*=\\s*[\"']\\w' --type-add 'code:*.{js,ts,py,rb,go,java}' --type code" - description: "Detect hardcoded secrets" - required: true - expected: "no matches" - - - id: perf_eval - type: self_evaluation - description: "AI scores its work against rubric" - threshold: 7 - required: true - - # Validation profiles map task risk/size to concrete per_phase + pre_commit steps. - # EXEC agents should prefer `task.acceptance.validation_profile` when present; - # otherwise derive a profile from `task.risk_level`: - # low → light, medium → standard, high → strict. - profiles: - # Light: compile + acceptance only, quick feedback loop - light: - per_phase: ["compile_check", "acceptance_item_check"] - pre_commit: ["perf_eval"] - # Standard: adds targeted tests per phase, full validation at commit - standard: - per_phase: ["compile_check", "targeted_tests", "acceptance_item_check"] - pre_commit: ["full_test_suite", "linter_suite", "typecheck", "security_scan", "perf_eval"] - # Strict: broader test coverage per phase (boundary check ensures no - # cross-module side effects), plus all pre_commit checks from standard - strict: - per_phase: ["compile_check", "targeted_tests", "boundary_check", "acceptance_item_check"] - pre_commit: ["full_test_suite", "linter_suite", "typecheck", "security_scan", "perf_eval"] - -# ============================================================================= -# SELF-EVALUATION RUBRIC -# ============================================================================= -rubric: - # Scoring dimensions (0-10 scale) - completeness: - weight: 3 - description: "0=partial, 1=meets ask, 2=edge cases, 3=edge cases + conventions" - - architecture_fidelity: - weight: 3 - description: "0=unclear, 1=respects boundaries, 2=uses patterns, 3=improves separation" - - spec_alignment: - weight: 2 - description: "0=not checked, 1=aligned, 2=proposed improvements" - - validation_depth: - weight: 2 - description: "0=missing, 1=targeted, 2=targeted + broader checks" - - # Minimum acceptable score - threshold: 7 - - # Action on low score - on_below_threshold: "perform_second_pass" - -# ============================================================================= -# ADVERSARIAL REVIEW -# ============================================================================= -# Mandatory review gate before scafld complete can archive a spec. -# Every spec gets the same review — no profiles. -# Recommended: run the agent review in a fresh context/session. -review: - # Review pipeline is built from named built-in passes only. - # Ordering is explicit; scafld sorts by `order`, not mapping insertion luck. - automated_passes: - spec_compliance: - order: 10 - title: "Spec Compliance" - description: "Re-run acceptance criteria to verify code satisfies the spec" - scope_drift: - order: 20 - title: "Scope Drift" - description: "Compare spec scope vs current workspace changes and flag undeclared changes" - - adversarial_passes: - regression_hunt: - order: 30 - title: "Regression Hunt" - description: "Trace callers, importers, and downstream consumers for regressions" - convention_check: - order: 40 - title: "Convention Check" - description: "Check changed code against CONVENTIONS.md and AGENTS.md" - dark_patterns: - order: 50 - title: "Dark Patterns" - description: "Hunt for subtle bugs, hardcodes, races, and safety gaps" - -# ============================================================================= -# REACT PATTERN (reasoning + acting) -# ============================================================================= -react: - enabled: true - - # Cycle structure - cycle: - - thought: "Analyze the task/phase objective" - - action: "Search codebase, read files, or apply changes" - - observation: "Capture results, check outputs" - - thought: "Evaluate success, decide next step" - - # Reasoning visibility - log_thoughts: true - - # Iteration limits - max_cycles_per_phase: 10 - max_cycles_planning: 20 - -# ============================================================================= -# TECH STACK CONTEXT (customize for your project) -# ============================================================================= -tech_stack: - # CUSTOMIZE: Replace with your actual tech stack - backend: - language: "Your language (e.g., Python 3.11, Ruby 3.2, Go 1.21)" - framework: "Your framework (e.g., Django, Rails, FastAPI)" - - frontend: - framework: "Your framework (e.g., React, Vue, Next.js)" - typescript_version: "5.x" - - shared: - error_format: "Your error format (e.g., Problem+JSON RFC 7807)" - api_spec: "Your API spec format (e.g., OpenAPI 3.1)" - -# ============================================================================= -# REPO LAYOUT (customize for your project) -# ============================================================================= -repo_layout: - # CUSTOMIZE: Replace with your actual directory layout - backend: "backend/" - frontend: "frontend/" - specs: ".ai/specs/" - logs: ".ai/logs/" - -# ============================================================================= -# COMMUNICATION STYLE -# ============================================================================= -communication: - # Progress updates during EXEC mode - progress: - format: concise - include_reasoning: false - include_acceptance_status: true - - # When blocked - blocking_issues: - format: structured - require_recommendation: true - - # Final summary - completion: - include_perf_eval: true - include_deviations: true - include_next_actions: true - -# ============================================================================= -# SAFETY & SECURITY -# ============================================================================= -safety: - # Destructive operations - require_approval_for: - - schema_migrations - - public_api_changes - - data_deletion - - production_deployments - - # Automatic checks - prevent: - - hardcoded_secrets - - unbounded_queries - - sql_injection_patterns - - xss_vulnerabilities - -# ============================================================================= -# EXPERIMENTAL FEATURES -# ============================================================================= -experimental: - # Auto-generate acceptance criteria from natural language - auto_acceptance_criteria: true - - # Self-healing: auto-fix failed acceptance criteria (1 retry) - self_healing: true - max_healing_attempts: 1 - - # Parallel phase execution (if phases are independent) - parallel_execution: false diff --git a/.ai/scafld/manifest.json b/.ai/scafld/manifest.json deleted file mode 100644 index 2b0095db1..000000000 --- a/.ai/scafld/manifest.json +++ /dev/null @@ -1,49 +0,0 @@ -{ - "managed_assets": { - ".ai/scafld/OPERATORS.md": { - "sha256": "d0d7e149cf4bfbd827aafb560f4a9aedb35d2462e96f735f30d25030dbd44d6d", - "source": ".ai/OPERATORS.md" - }, - ".ai/scafld/README.md": { - "sha256": "994de441a03e213303514abe6c27b85e6791f5ab05c38d92b0fc5ea2c7e59e4d", - "source": ".ai/README.md" - }, - ".ai/scafld/config.yaml": { - "sha256": "e4c22e5bec6097a507847df522be5d837664292201b08e8077c53919520bc1ab", - "source": ".ai/config.yaml" - }, - ".ai/scafld/prompts/exec.md": { - "sha256": "de8630ef115c368b3343da095d474dce28ecdaa6220eeb898c54a4aa95bc5e88", - "source": ".ai/prompts/exec.md" - }, - ".ai/scafld/prompts/harden.md": { - "sha256": "91119bab1bff4a6166253219ce7be7eb6f3afce3c7a1b87a8f6c18ba59e7dc02", - "source": ".ai/prompts/harden.md" - }, - ".ai/scafld/prompts/plan.md": { - "sha256": "5feb66faf88ec9c85ea404506f166a2c9ca763b0fba78e85952f8bc339855325", - "source": ".ai/prompts/plan.md" - }, - ".ai/scafld/prompts/review.md": { - "sha256": "61a9a8ce6b495c89993a2dd7aa81f675be9eb00cef9c82a4dcbc4a355171f73c", - "source": ".ai/prompts/review.md" - }, - ".ai/scafld/schemas/spec.json": { - "sha256": "c3ff2dc423d4538c58cec1ef1f7095b4d6070aa35c4b31f761436deb8d6e4e49", - "source": ".ai/schemas/spec.json" - }, - ".ai/scafld/specs/README.md": { - "sha256": "e73a3c6f5d68762780ad0248510e8d96bd8685f215a2a9438b88e434a7c96b70", - "source": ".ai/specs/README.md" - }, - ".ai/scafld/specs/examples/add-error-codes.yaml": { - "sha256": "e44e65bf3547a262d114f515fe9b3dcd648789877e1958547a587619b1fb41d5", - "source": ".ai/specs/examples/add-error-codes.yaml" - } - }, - "scafld_version": "1.5.1", - "schema_version": 1, - "source_commit": "2397a68631b2b3befe2c1c30bb9760e3b84bc4ad", - "source_dirty": false, - "workspace_config_mode": "legacy_overlay" -} diff --git a/.ai/scafld/prompts/exec.md b/.ai/scafld/prompts/exec.md deleted file mode 100644 index 31501019d..000000000 --- a/.ai/scafld/prompts/exec.md +++ /dev/null @@ -1,307 +0,0 @@ -# AI AGENT — EXECUTION MODE - -**Status:** ACTIVE -**Mode:** EXEC -**Input:** Approved specification file (`.ai/specs/approved/{task-id}.yaml`, promoted to `.ai/specs/active/{task-id}.yaml` when execution starts) -**Output:** Code changes, test runs, validation results - ---- - -## Mission - -You are an AI agent in **EXECUTION MODE**. Your objective is to execute an approved task specification, validating your work at every checkpoint, and delivering production-ready code. - ---- - -## Prerequisites - -Before entering execution mode: - -1. **Load Spec:** Read from `.ai/specs/approved/{task-id}.yaml` -2. **Verify Status:** `spec.status` MUST be `"approved"` -3. **Move to Active:** Move spec to `.ai/specs/active/{task-id}.yaml` -4. **Update Status:** Set `status: "in_progress"` in spec file - -If spec not in `approved/` folder or status is NOT approved: -``` -Cannot execute: Spec must be in approved/ folder with status "approved" - Check: .ai/specs/approved/{task-id}.yaml - Action: Complete planning and approval first, or move file to approved/ -``` - ---- - -## Resume Protocol - -If the spec is already in `.ai/specs/active/` with `status: "in_progress"` and some phases have `status: "completed"`: - -1. **Skip completed phases** - do not re-execute them -2. **Resume from the first phase with `status: "pending"` or `status: "failed"`** -3. If a failed phase has rollback commands, verify the rollback was applied before retrying -4. Log the resume point in the spec's `planning_log` or phase status - ---- - -## Per-Phase Execution - -For **each phase**, follow this cycle: - -### 1. Read & Plan -- Read phase objective and changes specification -- Identify files to modify and acceptance criteria to satisfy -- Predict potential issues (boundary violations, test failures) - -### 2. Apply Changes -- **Read first:** `Read(file)` to understand current state -- **Edit precisely:** Use `Edit()` with exact old_string/new_string -- **Match intent:** Does the change match `content_spec`? - -### 3. Validate -- Run ALL `acceptance_criteria` for this phase -- Record pass/fail status and output -- Update the spec's phase entry with results: - -```yaml -# Update phase status and acceptance criteria results inline -phases[N]: - status: "completed" # or "failed" - acceptance_criteria: - - id: ac1_1 - result: - status: pass - timestamp: "2025-01-17T11:45:30Z" - output: "{stdout/stderr summary}" -``` - -### 4. Decide -- **If ALL criteria pass:** Mark phase `status: "completed"`, proceed to next phase -- **If ANY criterion fails:** - 1. Attempt self-healing (1 retry max, if enabled in config) - 2. If still failing, rollback phase changes - 3. Mark phase `status: "failed"` and report to user - -Set `phases[N].status` to `"in_progress"` when you begin work on a phase -and update it to `"completed"` or `"failed"` based on acceptance criteria results. - -### Phase Logging - -After completing each phase, write a brief summary to the phase's status in the spec file. This is the primary record of execution progress. Example: - -```yaml -phases[N]: - status: "completed" - summary: "Added error constants to errors module, all 3 acceptance criteria passed" -``` - -The `.ai/logs/{task-id}.log` file is optional and supplementary - use it for detailed debugging traces when needed, but it is not required. - ---- - -## Acceptance Criteria - -For each `acceptance_criteria` item: - -```yaml -- id: ac1_1 - type: compile - command: "your-compile-command" - expected: "exit code 0" -``` - -**Common criterion types:** - -| Type | Command Example | Expected | Validation | -|------|----------------|----------|------------| -| `compile` | `your-compile-command` | `exit code 0` | Automated | -| `test` | `your-test-command {spec_pattern}` | `PASS` | Automated | -| `boundary` | `rg 'forbidden_pattern' {changed_files}` | `no matches` | Automated | -| `integration` | `your-e2e-command` | `exit code 0` | Automated | -| `security` | `rg -i 'password\\s*=\\s*"\\w+"'` | `no matches` | Automated | -| `documentation` | N/A | See `description` | Manual | -| `custom` | N/A | See `description` | Manual | - -**Placeholder Reference:** - -- **`{spec_pattern}`** - Test file path or example filter for the current phase -- **`{changed_files}`** - Union of `phases[N].changes[*].file` for the phase being validated - ---- - -## Definition-of-Done Checklist - -- Treat `task.acceptance.definition_of_done[*]` as hard requirements. -- When a DoD item is satisfied, update its `status` to `done`. -- Keep statuses in sync with reality; reviewers rely on this checklist. - -### Self-Review (Per Phase) - -After running acceptance criteria, verify: - -- [ ] All criteria passed (or failures documented) -- [ ] Update `task.acceptance.definition_of_done` entries related to this phase -- [ ] No boundary violations introduced -- [ ] Diff matches `phase.changes.content_spec` (no scope creep) -- [ ] No secrets or internal paths added - ---- - -## Final Validation (After All Phases) - -Once all phases complete, run pre-commit validation using the appropriate profile from `.ai/config.yaml`: - -- Determine profile: - - Prefer `task.acceptance.validation_profile` if set (`light | standard | strict`) - - Otherwise derive from `task.risk_level` (`low` -> `light`, `medium` -> `standard`, `high` -> `strict`) -- For the chosen profile, run the listed validation steps. - ---- - -## Adversarial Review - -After all phases complete and before `scafld complete`: - -1. Run `scafld review ` — runs automated passes (spec compliance, scope drift) and generates the review file -2. Start a **fresh agent session** when available to reduce confirmation bias -3. Read `.ai/prompts/review.md` for the review prompt and attack vectors -4. Review the spec + git diff, write findings to `.ai/reviews/{task-id}.md`, and update the latest round's review provenance metadata -5. Fix any blocking findings if needed -6. Run `scafld complete ` — reads the review, records verdict, archives - -The default Review Artifact v3 pipeline is `spec_compliance`, `scope_drift`, `regression_hunt`, `convention_check`, and `dark_patterns`. `scafld review` scaffolds the adversarial sections in configured order and expects the reviewer to update `round_status` plus per-pass `pass_results` before completion. - -`scafld complete` will **refuse to archive** if the latest review round is missing, malformed, incomplete, or failed. The only bypass is the exceptional human path: `scafld complete --human-reviewed --reason ""`, which requires interactive confirmation and records an audited override. - ---- - -## Self-Evaluation & Deviations - -After all phases and final validation: - -- Populate `self_eval` in the spec using the rubric weights from `.ai/config.yaml` -- If `total` falls below the rubric threshold, perform a second pass and set `second_pass_performed: true` -- Record any intentional deviations from invariants or the written spec in `deviations[*]` - ---- - -## Output Format - -### Progress Updates (During Execution) - -**Concise format (one line per phase):** -``` -Phase 1: Extract helpers | 4/4 criteria passed | Next: Phase 2 -Phase 2: Wire into module | 3/3 criteria passed | Next: Phase 3 -Phase 3: Add documentation | In progress... -``` - -### Blocking Issues - -If execution is blocked: -``` -Phase {N} blocked - Criterion: ac{N}_{X} - {description} - Error: {brief error message} - - Recommendation: - {One concrete solution} - - Awaiting guidance. -``` - -### Final Summary - -After all phases complete: -``` -Task complete: {task_id} - Phases: {N}/{N} completed - Acceptance: {total_passed}/{total_criteria} - PERF-EVAL: {total}/10 - Deviations: {count} - Status: {ready_for_commit | needs_review | failed} - Files changed: {count} -``` - ---- - -## Rollback Handling - -### Automatic Rollback (Acceptance Criteria Fail) - -```bash -# Execute rollback command from spec -{rollback_command} - -# Verify rollback success -git status -git diff -``` - -### Manual Rollback (User Requested) - -Revert phases in reverse order using `spec.rollback.commands`. - ---- - -## Deviations from Spec - -If you MUST deviate from the approved spec: - -1. **Pause execution** -2. **Check approval requirements** in `task.constraints.approvals_required` and `.ai/config.yaml` safety rules -3. **Document deviation** in `deviations[]` array -4. **Request approval** before proceeding - ---- - -## Self-Healing (Experimental) - -If enabled in `.ai/config.yaml` (`experimental.self_healing: true`): - -When an acceptance criterion fails: - -1. Analyze failure and identify root cause -2. Apply targeted correction -3. Re-run criterion -4. Max attempts: 1 (no infinite loops) - -If self-healing fails, proceed to rollback. - ---- - -## Exit Conditions - -### Success - -Move spec to `.ai/specs/archive/{YYYY-MM}/`, set `status: "completed"`. - -### Failure - -Move spec to `.ai/specs/archive/{YYYY-MM}/`, set `status: "failed"`, document recommendation. - -### Blocked - -Keep spec in `.ai/specs/active/`, `status: "in_progress"` (paused). Await user input. - ---- - -## Mode Constraints - -**DO:** -- Follow spec exactly (deviations require approval) -- Run all acceptance criteria after each phase -- Rollback on failure (unless self-healing succeeds) -- Update spec file with execution results - -**DO NOT:** -- Skip phases or acceptance criteria -- Make changes outside of spec.phases -- Modify approved spec structure (only update execution fields) -- Continue execution if a phase fails (without user approval) - ---- - -## Remember - -- **Validate obsessively** (acceptance criteria are non-negotiable) -- **Rollback fearlessly** (failure is safe when reversible) -- **Communicate concisely** (progress updates, not essays) diff --git a/.ai/scafld/prompts/harden.md b/.ai/scafld/prompts/harden.md deleted file mode 100644 index 13aab0814..000000000 --- a/.ai/scafld/prompts/harden.md +++ /dev/null @@ -1,32 +0,0 @@ -# AI AGENT — HARDEN MODE - -**Status:** ACTIVE -**Mode:** HARDEN -**Output:** Append a round to `harden_rounds` in the spec; keep `harden_status: "in_progress"` until the operator runs `--mark-passed`. -**Do NOT:** Modify code outside the spec file while hardening. - ---- - -Interview the operator relentlessly about the draft spec until you reach shared understanding. - -Walk the design tree upstream first, so downstream questions are not wasted on premises that may still move. - -Ask one question at a time. For each question, provide your recommended answer. - -If a question can be answered by exploring the codebase, explore the codebase instead of asking. Bring back the verified finding and use it to sharpen the next question. - -Record why each question exists with a single `grounded_in` value: - -- `spec_gap:` for a missing, vague, or contradictory spec field -- `code::` for code you actually verified in this session -- `archive:` for a relevant archived spec precedent - -Use `grounded_in` as audit trail, not ceremony. Do not invent citations. Do not cite code you have not read. Do not ask about behavior the spec already settles. - -If useful, include `if_unanswered` with the default you would write into the spec if the operator declines to answer. - -If you cannot form a genuine grounded question, stop. Do not pad the round. - -`max_questions_per_round` from `.ai/config.yaml` is a cap, not a target. - -The operator can end the loop by saying `done` or `stop`. A satisfactory round is finalized by running `scafld harden --mark-passed`. diff --git a/.ai/scafld/prompts/plan.md b/.ai/scafld/prompts/plan.md deleted file mode 100644 index 8c733bbbc..000000000 --- a/.ai/scafld/prompts/plan.md +++ /dev/null @@ -1,203 +0,0 @@ -# AI AGENT — PLANNING MODE - -**Status:** ACTIVE -**Mode:** PLAN -**Output:** Conversational task specification file (`.ai/specs/{task-id}.yaml`) -**Do NOT:** Modify code outside `.ai/specs/` while planning - ---- - -## Mission - -You are in **PLANNING MODE**. Partner with the user conversationally to shape a single **task** artifact that fully describes the work: context, touchpoints, risks, acceptance checklist, and execution phases. The spec must be executable by another agent without more back-and-forth. - ---- - -## Conversational ReAct Loop - -Iterate until the task artifact feels complete: - -1. **THOUGHT:** Interpret the request in repo terms. Identify unknowns. -2. **ACTION:** Gather evidence (search, read, diff) to answer the unknowns. -3. **OBSERVATION:** Capture what you learned (files, invariants, risks). -4. **THOUGHT:** Update the `task` block, acceptance, and phases. Ask clarifying questions when information is missing. -5. **REPEAT** until all required fields are filled and assumptions are explicit. - -Constraints: -- Max 20 cycles; document assumptions if still uncertain. -- Keep planning conversational - confirm intent before locking the `task` spec. -- Every update to the spec should be reflected in `planning_log`. - -**Context window awareness:** If planning exceeds context limits, document assumptions and save the spec with `status: "under_review"`. Resuming planning later is better than losing work. - ---- - -## Required Output Structure - -Produce a YAML spec conforming to `.ai/schemas/spec.json` (v1.1). - -Validation profiles, rubric weights, invariants, and safety rules are defined in `.ai/config.yaml` - reference them, don't duplicate them here. - -### Minimal Skeleton - -```yaml -spec_version: "1.1" -task_id: "{kebab-case}" -created: "{ISO-8601}" -updated: "{ISO-8601}" -status: "draft" - -task: - title: "{short heading}" - summary: "{2-3 sentence overview}" - size: "micro | small | medium | large" - risk_level: "low | medium | high" - context: - packages: ["src/module/...", "lib/..."] - files_impacted: - - path: "{relative path}" - lines: "100-150" | [100,150] | "all" - reason: "{why}" - invariants: ["domain_boundaries", ...] - related_docs: ["docs/...md"] - objectives: - - "{user goal}" - scope: - in_scope: ["..."] - out_of_scope: ["..."] - dependencies: ["..."] - assumptions: ["..."] - touchpoints: - - area: "{system/component}" - description: "{what changes here}" - risks: - - description: "{risk}" - impact: medium - mitigation: "{plan}" - acceptance: - validation_profile: "light | standard | strict" - definition_of_done: - - id: dod1 - description: "{checklist item}" - status: pending - validation: - - id: dod1 - type: documentation | compile | test | boundary | integration | security | custom - description: "{how to verify}" - command: "{optional shell command}" - expected: "{optional expectation}" - constraints: - approvals_required: ["schema_change", ...] - non_goals: ["{explicitly not doing}" ] - info_sources: ["{links or files consulted}"] - notes: "{decisions, trade-offs}" - -planning_log: - - timestamp: "{ISO-8601}" - actor: "agent" - summary: "{what changed/confirmed in this iteration}" - -phases: - - id: phase1 - name: "{phase name}" - objective: "{outcome of this phase}" - changes: - - file: "{path}" - action: create | update | delete | move - lines: "all" - content_spec: | - {narrative of edits} - acceptance_criteria: - - id: ac1_1 - type: test | compile | boundary | documentation | custom | integration | security - command: "{command if automated}" - description: "{why this check proves success}" - expected: "{result}" - status: pending - -rollback: - strategy: per_phase | atomic | manual - commands: - phase1: "git checkout HEAD -- path" - -self_eval, deviations, metadata remain as in earlier versions (fill null/defaults during planning). -``` - ---- - -## Building the `task` Block - -- **Title & summary:** Mirror the user's words; make it obvious what problem we're solving. -- **Size & risk:** Use `size` (`micro/small/medium/large`) and `risk_level` (`low/medium/high`) to communicate how heavy the change is. This guides how much validation to run and how detailed phases should be. -- **Context:** Reference actual packages/files. Keep `invariants` list aligned with `.ai/config.yaml` canonical invariants. -- **Objectives & scope:** Distinguish what we're doing vs. explicitly not doing. -- **Touchpoints:** Enumerate major systems, adapters, modules, or docs affected. This is the anchor for later validation. -- **Risks/assumptions:** Capture blockers early; if an assumption is shaky, call it out and set `status: "under_review"`. -- **Acceptance:** Treat `definition_of_done` as the non-negotiable checklist (one object per item with `id`, `description`, and default `status: pending`). `validation` entries describe how each DoD item will be verified. Optionally set `acceptance.validation_profile` to choose a validation profile; otherwise, EXEC should derive a profile from `risk_level`. -- **Constraints:** Move any approval needs here. EXEC agents must pause if `task.constraints.approvals_required` intersects `safety.require_approval_for` in `.ai/config.yaml`. - ---- - -## Phases & Acceptance Criteria - -- Each phase should map cleanly to a touchpoint or cohesive concern. -- `changes[].content_spec` should read like a design note (functions, behaviors, docs sections). -- Every phase needs at least one acceptance criterion. Use deterministic commands when possible; fall back to `documentation`/`custom` with clear reviewer instructions. -- Keep rollbacks scoped per phase unless the plan demands atomicity. - ---- - -## Planning Log - -Record significant conversational turns: - -- `summary` should capture what you agreed on (clarified scope, locked acceptance items, discovered dependency). -- If you made an assumption, log it and echo inside `task.assumptions`. -- Timestamps should be ISO-8601 (UTC). Use the order of discovery. - ---- - -## Approval Guidance - -- Ask for guidance only when you detect schema/migration/public API work. Otherwise, choose the best architecture-aligned approach and document the constraint in `task.constraints.approvals_required`. -- When explicitly punting on a higher-price option, capture the trade-off in `task.notes` or `scope.out_of_scope`. - ---- - -## Final Checklist Before Output - -- [ ] Spec validates against `.ai/schemas/spec.json` v1.1. -- [ ] `task_id` is unique (no clashes in `.ai/specs/**`). -- [ ] `task.touchpoints`, `task.acceptance.definition_of_done`, and `phases` tell the same story. -- [ ] Every assumption is documented; blockers set `status: "under_review"`. -- [ ] `planning_log` captures the major conversational steps. - ---- - -## Optional Next Step - -When planning is complete, the operator may run `scafld harden ` to interrogate the draft against grounded questions before approval. This step is optional and can be skipped by approving directly. - ---- - -## Blocked Planning Template - -If planning stops on missing info: - -``` -Warning: Planning blocked - Reason: {cannot determine X without Y} - Assumptions made: - - {assumption 1} - -Spec saved to: .ai/specs/drafts/{task-id}.yaml (status: under_review) -``` - ---- - -## Remember - -- Co-create the plan with the user - confirm direction before finalizing. -- Capture **one** high-quality plan; no more option matrices. -- Keep architecture invariants front-of-mind. -- Optimize for execution clarity: another agent should be able to pick this up and ship without guessing. diff --git a/.ai/scafld/prompts/review.md b/.ai/scafld/prompts/review.md deleted file mode 100644 index 201e5a029..000000000 --- a/.ai/scafld/prompts/review.md +++ /dev/null @@ -1,169 +0,0 @@ -# AI AGENT — REVIEW MODE - -**Mode:** REVIEW -**Input:** Spec (`.ai/specs/active/{task-id}.yaml`) + git diff -**Output:** Findings in `.ai/reviews/{task-id}.md` - ---- - -## Mission - -Find what is wrong. Not what is right. - -You are reviewing changes made during spec execution. A separate agent built this, or you did in a prior session. Either way, your job is to attack it. - -A review that finds zero issues is suspicious. Look harder. - ---- - -## Rules - -- Every finding must cite a specific file and line number -- Classify findings as **blocking** (must fix before merge) or **non-blocking** (should fix) -- Do not suggest improvements or refactors — only flag defects and omissions -- Do not modify any code — review only - ---- - -## Process - -1. Read the spec at `.ai/specs/active/{task-id}.yaml` -2. Read the git diff of all changes -3. Read `CONVENTIONS.md` and `AGENTS.md` -4. Read `.ai/reviews/{task-id}.md` — if prior review rounds exist, read what was found before. Don't re-report fixed issues. Note if a prior finding persists. -5. Attack the diff through the configured adversarial passes — by default: `regression_hunt`, `convention_check`, and `dark_patterns` -6. Write findings into the latest review section in `.ai/reviews/{task-id}.md` -7. Update the Review Artifact v3 metadata so the latest round is truthful and complete - ---- - -## Default Review Pipeline - -The default built-in five-pass pipeline in `.ai/config.yaml` is: - -- `spec_compliance` -- `scope_drift` -- `regression_hunt` -- `convention_check` -- `dark_patterns` - -`scafld review` already runs `spec_compliance` and `scope_drift` and scaffolds the adversarial sections in configured order. Your job is to complete the adversarial passes and finalize the metadata for Review Artifact v3. - -If the project has changed pass titles in `.ai/config.yaml`, follow the headings already scaffolded by `scafld review`. The built-in pass ids stay the same even if the visible section title changes. - ---- - -## Attack Vectors - -### 1. Regression Hunt (`regression_hunt`) - -For each modified file, find every caller, importer, and downstream consumer. What assumptions do they make that this change violates? - -- Search for imports/requires of each modified file -- Check function signatures — did parameters change? Did return shapes change? -- Look for duck-typing or structural assumptions that no longer hold -- Verify event listeners and subscribers still match event shapes -- Check if removed or renamed exports are still referenced elsewhere - -### 2. Convention Check (`convention_check`) - -Read `CONVENTIONS.md` and `AGENTS.md`. For each changed file, check whether the new code violates a documented rule. - -- Cite the specific convention and the specific violating line -- Don't flag style preferences — only documented, stated conventions -- Check naming patterns, layer boundaries, import rules, test patterns - -### 3. Dark Patterns (`dark_patterns`) - -For each change, actively hunt for: - -- Hardcoded values that should be dynamic or configurable -- Off-by-one errors -- Missing null/empty checks at system boundaries (user input, API responses, config values) -- Race conditions or timing issues -- Copy-paste errors (duplicated logic with subtle differences) -- Error handling gaps (unhappy paths not covered) -- Security issues (injection, XSS, auth bypass, missing authorization) - ---- - -## Severity Levels - -- **critical** — will cause runtime errors, data loss, or security vulnerability -- **high** — will cause incorrect behavior in common cases -- **medium** — will cause incorrect behavior in edge cases -- **low** — code smell, minor issue, or potential future problem - ---- - -## Output - -`scafld review` scaffolds the review file at `.ai/reviews/{task-id}.md` with numbered review sections. Fill in the latest section using the Review Artifact v3 contract: - -````markdown -## Review N — {timestamp} - -### Metadata -```json -{ - "schema_version": 3, - "round_status": "completed", - "reviewer_mode": "fresh_agent", - "reviewer_session": "session-id-or-empty-string", - "reviewed_at": "{timestamp}", - "override_reason": null, - "pass_results": { - "spec_compliance": "pass", - "scope_drift": "pass", - "regression_hunt": "pass", - "convention_check": "pass", - "dark_patterns": "pass" - } -} -``` - -### Pass Results -- spec_compliance: PASS -- scope_drift: PASS -- regression_hunt: PASS -- convention_check: PASS -- dark_patterns: PASS - -### Regression Hunt -{For each modified file, trace callers/importers. What assumptions break? -List findings or "No issues found — checked [what you checked]".} - -### Convention Check -{Read CONVENTIONS.md and AGENTS.md. Does new code violate any documented rule? -List findings or "No issues found — checked [what you checked]".} - -### Dark Patterns -{Hunt for hardcoded values, off-by-one issues, missing null checks, race conditions, -copy-paste errors, unhandled error paths, and security issues. -List findings or "No issues found — checked [what you checked]".} - -### Blocking -- **{severity}** `{file}:{line}` — {what's wrong and why it matters} - -### Non-blocking -- **{severity}** `{file}:{line}` — {what's wrong and why it matters} - -### Verdict -{pass | fail | pass_with_issues} -```` - -Update these metadata fields explicitly: - -- Set `round_status` to `completed` when the review is actually done -- Set `reviewer_mode` to `fresh_agent`, `auto`, or `executor` to match the real reviewer -- Set `reviewer_session` to the real session identifier or `""` -- Keep the automated pass results for `spec_compliance` and `scope_drift` -- Set adversarial `pass_results` for `regression_hunt`, `convention_check`, and `dark_patterns` to `pass`, `pass_with_issues`, or `fail` - -Prior review rounds remain in the file as context. Do not rewrite them. - -**All configured adversarial sections must contain content.** Each must have at least one finding or an explicit "No issues found" with a brief note of what was checked. `scafld complete` will reject reviews with empty configured sections or with `round_status` left at `in_progress`. - -**Verdict rules:** Any blocking finding → `fail`. Non-blocking only → `pass_with_issues`. Clean → `pass`. - -When done, run `scafld complete {task-id}`. diff --git a/.ai/scafld/schemas/spec.json b/.ai/scafld/schemas/spec.json deleted file mode 100644 index 51fe90139..000000000 --- a/.ai/scafld/schemas/spec.json +++ /dev/null @@ -1,590 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://github.com/nilstate/scafld/spec-v1.1.json", - "title": "scafld Task Specification", - "description": "Machine-readable conversational task specification for AI agents", - "type": "object", - "required": ["spec_version", "task_id", "status", "task", "phases", "planning_log", "created", "updated"], - "additionalProperties": false, - - "properties": { - "spec_version": { - "type": "string", - "pattern": "^[0-9]+\\.[0-9]+$", - "description": "Semantic version of this spec format", - "examples": ["1.1"] - }, - - "task_id": { - "type": "string", - "pattern": "^[a-z0-9-]+$", - "description": "Unique identifier for this task (kebab-case)", - "examples": ["add-user-metrics", "refactor-auth-module"] - }, - - "created": { - "type": "string", - "format": "date-time", - "description": "ISO 8601 timestamp when spec was generated" - }, - - "updated": { - "type": "string", - "format": "date-time", - "description": "ISO 8601 timestamp when spec was last modified" - }, - - "status": { - "type": "string", - "enum": ["draft", "blocked", "under_review", "approved", "in_progress", "completed", "failed", "cancelled"], - "description": "Current lifecycle state of this task" - }, - - "task": { - "type": "object", - "required": ["title", "summary", "size", "risk_level", "context", "objectives", "touchpoints", "acceptance"], - "properties": { - "title": { - "type": "string", - "minLength": 5, - "description": "Human friendly title for this task" - }, - "summary": { - "type": "string", - "minLength": 20, - "description": "Concise description of the problem/goal" - }, - "size": { - "type": "string", - "enum": ["micro", "small", "medium", "large"], - "description": "Relative task size to guide planning and validation depth" - }, - "risk_level": { - "type": "string", - "enum": ["low", "medium", "high"], - "description": "Overall risk tier for this task; used to select validation profile when not explicitly set" - }, - "context": { - "type": "object", - "required": ["packages", "invariants"], - "properties": { - "packages": { - "type": "array", - "items": {"type": "string"}, - "minItems": 1, - "description": "Modules or packages affected" - }, - "files_impacted": { - "type": "array", - "items": { - "type": "object", - "required": ["path", "reason"], - "properties": { - "path": {"type": "string"}, - "lines": { - "oneOf": [ - {"type": "array", "items": {"type": "integer"}}, - {"type": "string", "pattern": "^[0-9]+-[0-9]+$"}, - {"type": "string", "enum": ["all"]} - ] - }, - "reason": {"type": "string"} - } - } - }, - "invariants": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "description": "Architectural/contract invariants that must be preserved (customize in config.yaml)" - }, - "related_docs": { - "type": "array", - "items": {"type": "string"} - }, - "cwd": { - "type": "string", - "description": "Default working directory for acceptance criteria commands, relative to workspace root. Individual criteria can override with their own cwd." - } - } - }, - "objectives": { - "type": "array", - "items": {"type": "string"}, - "minItems": 1, - "description": "Primary goals for this task" - }, - "scope": { - "type": "object", - "properties": { - "in_scope": { - "type": "array", - "items": {"type": "string"} - }, - "out_of_scope": { - "type": "array", - "items": {"type": "string"} - } - } - }, - "dependencies": { - "type": "array", - "items": {"type": "string"} - }, - "assumptions": { - "type": "array", - "items": {"type": "string"} - }, - "touchpoints": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "required": ["area", "description"], - "properties": { - "area": {"type": "string"}, - "description": {"type": "string"}, - "owners": { - "type": "array", - "items": {"type": "string"} - }, - "links": { - "type": "array", - "items": {"type": "string"} - } - } - } - }, - "risks": { - "type": "array", - "items": { - "type": "object", - "required": ["description"], - "properties": { - "description": {"type": "string"}, - "impact": { - "type": "string", - "enum": ["low", "medium", "high"] - }, - "mitigation": {"type": "string"} - } - } - }, - "acceptance": { - "type": "object", - "required": ["definition_of_done", "validation"], - "properties": { - "validation_profile": { - "type": "string", - "enum": ["light", "standard", "strict"], - "description": "Validation profile to apply; defaults based on risk_level if omitted" - }, - "definition_of_done": { - "type": "array", - "minItems": 1, - "description": "Checklist items that must be explicitly checked off during execution", - "items": { - "type": "object", - "required": ["id", "description"], - "properties": { - "id": {"type": "string"}, - "description": {"type": "string"}, - "status": { - "type": "string", - "enum": ["pending", "in_progress", "done"], - "default": "pending" - }, - "checked_at": {"type": "string", "format": "date-time"}, - "notes": {"type": "string"} - } - } - }, - "validation": { - "type": "array", - "items": { - "type": "object", - "required": ["id", "type", "description"], - "properties": { - "id": {"type": "string"}, - "type": { - "type": "string", - "enum": [ - "compile", - "test", - "boundary", - "integration", - "security", - "documentation", - "custom" - ] - }, - "description": {"type": "string"}, - "command": {"type": "string"}, - "expected": {"type": "string"}, - "cwd": {"type": "string", "description": "Working directory relative to workspace root"}, - "timeout_seconds": { - "type": "integer", - "minimum": 1, - "description": "Command timeout in seconds. Defaults to 600 when omitted." - } - } - } - } - } - }, - "notes": {"type": "string"} - } - }, - - "planning_log": { - "type": "array", - "items": { - "type": "object", - "required": ["timestamp", "summary"], - "properties": { - "timestamp": {"type": "string", "format": "date-time"}, - "actor": {"type": "string"}, - "summary": {"type": "string"}, - "notes": {"type": "string"} - } - } - }, - - "phases": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "required": ["id", "name", "objective", "changes", "acceptance_criteria"], - "properties": { - "id": { - "type": "string", - "pattern": "^phase[0-9]+$" - }, - "name": { - "type": "string", - "minLength": 5 - }, - "objective": { - "type": "string", - "minLength": 10 - }, - "dependencies": { - "type": "array", - "items": {"type": "string"} - }, - "changes": { - "type": "array", - "items": { - "type": "object", - "required": ["file", "action", "content_spec"], - "properties": { - "file": {"type": "string"}, - "action": { - "type": "string", - "enum": ["create", "update", "delete", "move"] - }, - "ownership": { - "type": "string", - "enum": ["exclusive", "shared"], - "description": "Whether this file is exclusively owned by this spec (default) or intentionally shared with other active specs." - }, - "move_to": { - "type": "string", - "description": "Destination path when action is 'move'" - }, - "lines": { - "oneOf": [ - {"type": "array", "items": {"type": "integer"}}, - {"type": "string", "pattern": "^[0-9]+-[0-9]+$"}, - {"type": "string", "enum": ["all"]} - ] - }, - "content_spec": {"type": "string"} - } - } - }, - "acceptance_criteria": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "required": ["id", "type", "description"], - "properties": { - "id": {"type": "string"}, - "type": { - "type": "string", - "enum": [ - "compile", - "test", - "boundary", - "integration", - "security", - "documentation", - "custom" - ], - "description": "Criterion type. For automated types (compile, test, boundary, integration, security), a 'command' field is expected. For manual types (documentation, custom), 'command' is optional." - }, - "description": {"type": "string"}, - "command": { - "type": "string", - "description": "Shell command to run for automated validation. Expected for compile, test, boundary, integration, and security types." - }, - "expected": {"type": "string"}, - "cwd": { - "type": "string", - "description": "Working directory for the command, relative to workspace root. Useful in monorepo/workspace setups where different criteria target different submodules." - }, - "timeout_seconds": { - "type": "integer", - "minimum": 1, - "description": "Command timeout in seconds. Defaults to 600 when omitted." - }, - "result": { - "oneOf": [ - { - "type": "string", - "enum": ["pass", "fail"], - "description": "Flat result recorded by scafld exec" - }, - { - "type": "object", - "required": ["status"], - "properties": { - "status": { - "type": "string", - "enum": ["pass", "fail"] - }, - "timestamp": { - "type": "string", - "format": "date-time" - }, - "output": { - "type": "string" - } - }, - "additionalProperties": false, - "description": "Nested result block supported for execution records" - } - ] - }, - "executed_at": { - "type": "string", - "format": "date-time", - "description": "When the criterion was last executed" - }, - "result_output": { - "type": "string", - "description": "Truncated command output from scafld exec" - } - } - } - }, - "status": { - "type": "string", - "enum": ["pending", "in_progress", "completed", "failed", "skipped"] - } - } - } - }, - - "rollback": { - "type": "object", - "properties": { - "strategy": { - "type": "string", - "enum": ["per_phase", "atomic", "manual"], - "default": "per_phase" - }, - "commands": { - "type": "object", - "patternProperties": { - "^phase[0-9]+$": {"type": "string"} - } - } - } - }, - - "review": { - "type": "object", - "description": "Adversarial review results recorded by scafld complete", - "properties": { - "timestamp": {"type": "string", "format": "date-time"}, - "verdict": { - "type": "string", - "enum": ["pass", "fail", "pass_with_issues"], - "description": "pass = no findings, fail = blocking findings, pass_with_issues = non-blocking only" - }, - "passes": { - "type": "array", - "items": { - "type": "object", - "required": ["id", "result"], - "properties": { - "id": {"type": "string"}, - "result": { - "type": "string", - "enum": ["pass", "fail", "pass_with_issues"] - } - } - } - }, - "review_rounds": {"type": "integer", "minimum": 0, "description": "Number of review rounds before passing"}, - "blocking_count": {"type": "integer", "minimum": 0}, - "non_blocking_count": {"type": "integer", "minimum": 0} - } - }, - - "self_eval": { - "type": "object", - "properties": { - "completeness": {"type": "integer", "minimum": 0, "maximum": 3}, - "architecture_fidelity": {"type": "integer", "minimum": 0, "maximum": 3}, - "spec_alignment": {"type": "integer", "minimum": 0, "maximum": 2}, - "validation_depth": {"type": "integer", "minimum": 0, "maximum": 2}, - "total": {"type": "integer", "minimum": 0, "maximum": 10}, - "notes": {"type": "string"}, - "second_pass_performed": {"type": "boolean"} - } - }, - - "deviations": { - "type": "array", - "items": { - "type": "object", - "required": ["rule", "reason"], - "properties": { - "rule": {"type": "string"}, - "reason": {"type": "string"}, - "mitigation": {"type": "string"}, - "approved_by": {"type": "string"} - } - } - }, - - "metadata": { - "type": "object", - "properties": { - "estimated_effort_hours": {"type": "number", "minimum": 0}, - "actual_effort_hours": {"type": "number", "minimum": 0}, - "ai_model": {"type": "string"}, - "react_cycles": {"type": "integer"}, - "tags": { - "type": "array", - "items": {"type": "string"} - } - } - }, - - "origin": { - "type": "object", - "description": "Optional. Provider-neutral task origin and git binding metadata.", - "additionalProperties": false, - "properties": { - "source": { - "type": "object", - "additionalProperties": false, - "properties": { - "system": {"type": "string"}, - "kind": {"type": "string"}, - "id": {"type": "string"}, - "url": {"type": "string"}, - "title": {"type": "string"} - } - }, - "repo": { - "type": "object", - "additionalProperties": false, - "properties": { - "root": {"type": "string"}, - "remote": {"type": "string"}, - "remote_url": {"type": "string"} - } - }, - "git": { - "type": "object", - "additionalProperties": false, - "properties": { - "branch": {"type": "string"}, - "base_ref": {"type": "string"}, - "upstream": {"type": "string"}, - "mode": { - "type": "string", - "enum": ["created_branch", "checked_out_existing", "bound_current"] - }, - "bound_at": {"type": "string", "format": "date-time"} - } - }, - "sync": { - "type": "object", - "additionalProperties": false, - "properties": { - "status": { - "type": "string", - "enum": ["unbound", "in_sync", "drift", "unavailable"] - }, - "last_checked_at": {"type": "string", "format": "date-time"}, - "reasons": { - "type": "array", - "items": {"type": "string"} - }, - "actual": { - "type": "object", - "additionalProperties": false, - "properties": { - "branch": {"type": "string"}, - "head_sha": {"type": "string"}, - "upstream": {"type": "string"}, - "remote": {"type": "string"}, - "remote_url": {"type": "string"}, - "default_base_ref": {"type": "string"}, - "dirty": {"type": "boolean"}, - "detached": {"type": "boolean"} - } - } - } - } - } - }, - - "harden_status": { - "type": "string", - "enum": ["not_run", "in_progress", "passed"], - "description": "Optional. Tracks whether the operator has run `scafld harden` against this spec. Independent of the lifecycle `status` field; not consulted by `scafld approve`." - }, - - "harden_rounds": { - "type": "array", - "description": "Optional. One entry per `scafld harden` invocation.", - "items": { - "type": "object", - "required": ["round", "started_at", "questions"], - "properties": { - "round": {"type": "integer", "minimum": 1}, - "started_at": {"type": "string", "format": "date-time"}, - "ended_at": {"type": "string", "format": "date-time"}, - "outcome": {"type": "string", "enum": ["in_progress", "passed", "abandoned"]}, - "questions": { - "type": "array", - "items": { - "type": "object", - "required": ["question", "grounded_in"], - "properties": { - "question": {"type": "string"}, - "grounded_in": { - "type": "string", - "pattern": "^(spec_gap:|code:|archive:).+" - }, - "recommended_answer": {"type": "string"}, - "if_unanswered": {"type": "string"}, - "answered_with": {"type": "string"} - } - } - } - } - } - } - } -} diff --git a/.ai/scafld/specs/README.md b/.ai/scafld/specs/README.md deleted file mode 100644 index 73891aabc..000000000 --- a/.ai/scafld/specs/README.md +++ /dev/null @@ -1,99 +0,0 @@ -# Task Specifications - -This directory contains machine-readable task specifications organized by lifecycle status. - ---- - -## Directory Structure - -``` -specs/ -├── drafts/ # Planning in progress -│ └── *.yaml (status: draft | under_review) -├── approved/ # Ready for execution -│ └── *.yaml (status: approved) -├── active/ # Currently executing -│ └── *.yaml (status: in_progress) -└── archive/ # Completed work - └── YYYY-MM/ - └── *.yaml (status: completed | failed | cancelled) -``` - ---- - -## File Naming - -**Convention:** `{task-id}.yaml` using kebab-case, descriptive names. - -Good: `add-user-metrics.yaml`, `refactor-auth-module.yaml`, `fix-chunk-dedup.yaml` -Bad: `task-123.yaml` (not descriptive), `AddMetrics.yaml` (not kebab-case) - ---- - -## Workflow - -### 1. Planning - -AI generates spec in `drafts/` with `status: "draft"`. If blocked, set `status: "under_review"`. - -### 2. Review & Approval - -Developer reviews, then approves: - -```bash -scafld approve my-task -``` - -### 3. Execution - -AI moves spec to `active/`, sets `status: "in_progress"`, and executes phases. - -### 4. Review - -Run adversarial review before completing: - -```bash -scafld review my-task -# Fill in findings in .ai/reviews/my-task.md -``` - -### 5. Completion - -Mark complete (reads review, records verdict, moves to `archive/YYYY-MM/`): - -```bash -scafld complete my-task -``` - ---- - -## Spec Anatomy - -Each spec validated by `.ai/schemas/spec.json` includes: - -- **`task` block:** Title, summary, context, objectives, scope, touchpoints, risks, acceptance checklist, constraints -- **`planning_log`:** Chronological entries summarizing planning steps -- **`phases`:** Ordered execution units with `changes[].content_spec`, acceptance criteria, and per-phase status -- **`rollback`:** Strategy and per-phase commands for safe reversions -- **`review`:** Verdict, pass results, and finding counts recorded by `scafld complete` -- **`self_eval` / `deviations` / `metadata`:** Populated during execution - ---- - -## Finding Work - -```bash -scafld list # All specs -scafld list active # Currently executing -scafld list approved # Awaiting execution -scafld list drafts # Planning in progress -scafld list archive # Completed work -``` - ---- - -## See Also - -- [AGENTS.md](../../AGENTS.md) - Status lifecycle and agent policies -- [config.yaml](../config.yaml) - Validation profiles and size/risk tiers -- [schemas/spec.json](../schemas/spec.json) - Spec validation schema diff --git a/.ai/scafld/specs/examples/add-error-codes.yaml b/.ai/scafld/specs/examples/add-error-codes.yaml deleted file mode 100644 index f0e91ee8b..000000000 --- a/.ai/scafld/specs/examples/add-error-codes.yaml +++ /dev/null @@ -1,365 +0,0 @@ -# scafld Example Spec — Complete reference showing every schema field -# See .ai/schemas/spec.json for the formal definition - -spec_version: "1.1" -task_id: "add-error-codes" -created: "2026-02-18T09:15:00Z" -updated: "2026-02-18T14:42:00Z" -status: "completed" - -task: - title: "Add typed error codes to document processing module" - summary: > - The document processor uses unstructured string errors, making it difficult for - callers to programmatically handle failures. Introduce a typed error code enum - and structured error class so consumers can match on specific failure modes. - size: "small" - risk_level: "medium" - context: - packages: - - "src/services/documents" - - "src/errors" - files_impacted: - - path: "src/errors/codes.ts" - lines: "all" - reason: "New file defining DocumentErrorCode enum and error map" - - path: "src/errors/document-error.ts" - lines: "all" - reason: "New DocumentProcessingError class using typed codes" - - path: "src/services/documents/processor.ts" - lines: "45-120" - reason: "Replace string throws with DocumentProcessingError instances" - - path: "src/services/documents/processor.test.ts" - lines: "all" - reason: "Update assertions to check error codes instead of message strings" - invariants: - - "domain_boundaries" - - "error_envelope" - related_docs: - - "docs/error-handling.md" - - "docs/architecture/service-layer.md" - objectives: - - "Define a DocumentErrorCode enum covering all known failure modes" - - "Create a structured error class that carries code, message, and context" - - "Migrate processor.ts from string throws to typed errors" - scope: - in_scope: - - "Document processor error paths" - - "Unit tests for error scenarios" - out_of_scope: - - "Other service modules (auth, billing)" - - "HTTP error response mapping (handled by controller layer)" - - "Error monitoring/alerting integration" - dependencies: - - "No external dependencies required" - assumptions: - - "Existing error helper utilities in src/errors/ are compatible with subclassing" - - "No downstream consumers rely on exact error message strings for control flow" - touchpoints: - - area: "src/errors" - description: "New error code enum and DocumentProcessingError class" - owners: - - "backend-team" - links: - - "https://internal.wiki/error-handling-standards" - - area: "src/services/documents/processor.ts" - description: "Replace raw throws with typed error instances" - owners: - - "documents-team" - - area: "src/services/documents/processor.test.ts" - description: "Update test assertions to verify error codes" - links: - - "https://internal.wiki/testing-conventions" - risks: - - description: "Downstream callers may catch generic Error and miss new type" - impact: "low" - mitigation: "DocumentProcessingError extends Error, so existing catch blocks still work" - - description: "Incomplete coverage of error paths in processor.ts" - impact: "medium" - mitigation: "Grep for all throw statements before and after migration to ensure full coverage" - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "DocumentErrorCode enum covers all processor failure modes" - status: "done" - checked_at: "2026-02-18T13:20:00Z" - notes: "8 error codes identified matching 8 throw sites in processor.ts" - - id: "dod2" - description: "All throw statements in processor.ts use DocumentProcessingError" - status: "done" - checked_at: "2026-02-18T14:05:00Z" - notes: "Verified via grep: 0 raw Error throws remain" - - id: "dod3" - description: "Tests assert on error codes, not message strings" - status: "done" - checked_at: "2026-02-18T14:30:00Z" - - id: "dod4" - description: "No regressions in existing test suite" - status: "done" - checked_at: "2026-02-18T14:35:00Z" - notes: "Full suite: 142 passed, 0 failed" - validation: - - id: "v1" - type: "compile" - description: "Project compiles with no type errors" - command: "npm run build" - expected: "Exit code 0, no type errors" - - id: "v2" - type: "test" - description: "All unit tests pass including updated error assertions" - command: "npm test -- --filter documents" - expected: "All tests pass" - - id: "v3" - type: "boundary" - description: "No throw of raw Error or string in processor.ts" - command: "rg 'throw new Error\\|throw \"' src/services/documents/processor.ts" - expected: "No matches found" - - id: "v4" - type: "security" - description: "No hardcoded secrets in changed files" - command: "rg -i '(password|secret|api[_-]?key)\\s*=\\s*[\"'']\\w' src/errors/ src/services/documents/" - expected: "No matches found" - constraints: - approvals_required: - - "error_envelope" - non_goals: - - "Refactoring the processor's happy path logic" - - "Adding error codes to other modules" - info_sources: - - "docs/error-handling.md" - - "https://internal.wiki/error-handling-standards" - - "src/errors/base-error.ts (existing base class)" - notes: > - Chose a flat enum over a class hierarchy to keep things simple. The error code - enum can be extended later when other modules adopt the same pattern. Considered - using numeric codes but string enums are more readable in logs and debuggers. - -planning_log: - - timestamp: "2026-02-18T09:15:00Z" - actor: "agent" - summary: "Identified processor.ts as primary target. Found 8 throw statements using raw strings." - notes: "Searched with: rg 'throw new Error' src/services/documents/" - - timestamp: "2026-02-18T09:40:00Z" - actor: "agent" - summary: "Confirmed src/errors/ has base helpers. Proposed enum + error class approach." - notes: "BaseError class exists at src/errors/base-error.ts with code property pattern" - - timestamp: "2026-02-18T10:05:00Z" - actor: "user" - summary: "User confirmed no schema changes needed. No downstream string matching on error messages." - - timestamp: "2026-02-18T10:30:00Z" - actor: "agent" - summary: "Locked three-phase plan: define codes, migrate processor, update tests. Spec ready for review." - notes: "Moved from two-phase to three-phase after realizing test updates are substantial enough to warrant isolation" - -phases: - - id: "phase1" - name: "Define error codes and error class" - objective: "Create the DocumentErrorCode enum and DocumentProcessingError class in src/errors/" - changes: - - file: "src/errors/codes.ts" - action: "create" - lines: "all" - content_spec: | - Export a DocumentErrorCode string enum with values: - INVALID_FORMAT, PARSE_FAILED, SIZE_EXCEEDED, ENCODING_UNSUPPORTED, - PERMISSION_DENIED, STORAGE_UNAVAILABLE, TEMPLATE_MISSING, TIMEOUT. - Each value should be a SCREAMING_SNAKE string matching the enum key. - - file: "src/errors/document-error.ts" - action: "create" - lines: "all" - content_spec: | - Export DocumentProcessingError extending Error. - Constructor accepts (code: DocumentErrorCode, message: string, context?: Record). - Exposes readonly code, context properties. Sets name to 'DocumentProcessingError'. - Re-export DocumentErrorCode for convenience. - acceptance_criteria: - - id: "ac1_1" - type: "compile" - description: "New files compile without errors" - command: "npx tsc --noEmit src/errors/codes.ts src/errors/document-error.ts" - expected: "Exit code 0" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T11:45:00Z" - output: "tsc completed with exit code 0" - notes: "Clean compile, no warnings" - - id: "ac1_2" - type: "test" - description: "Error class instantiation works correctly" - command: "npm test -- --filter document-error" - expected: "Error instances carry correct code and extend Error" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T11:50:00Z" - output: "2 tests passed" - - id: "ac1_3" - type: "documentation" - description: "Error codes are documented in docs/error-handling.md" - validation: "manual" - result: - status: "pass" - timestamp: "2026-02-18T12:00:00Z" - notes: "Added table of error codes with descriptions to error-handling.md" - status: "completed" - - - id: "phase2" - name: "Migrate processor error paths" - objective: "Replace all raw throws in processor.ts with DocumentProcessingError using appropriate codes" - dependencies: - - "phase1" - changes: - - file: "src/services/documents/processor.ts" - action: "update" - lines: "45-120" - content_spec: | - Import DocumentProcessingError and DocumentErrorCode from src/errors. - Replace each `throw new Error("...")` with the appropriate - `throw new DocumentProcessingError(DocumentErrorCode.X, message, { context })`. - Map each existing error string to the matching enum value: - - "Invalid document format" -> INVALID_FORMAT - - "Failed to parse document" -> PARSE_FAILED - - "Document exceeds size limit" -> SIZE_EXCEEDED - - "Unsupported encoding" -> ENCODING_UNSUPPORTED - - "Permission denied" -> PERMISSION_DENIED - - "Storage service unavailable" -> STORAGE_UNAVAILABLE - - "Template not found" -> TEMPLATE_MISSING - - "Processing timeout" -> TIMEOUT - - file: "src/errors/index.ts" - action: "update" - lines: "1-10" - content_spec: | - Add re-exports for DocumentErrorCode and DocumentProcessingError - so they can be imported from 'src/errors' directly. - acceptance_criteria: - - id: "ac2_1" - type: "boundary" - description: "No raw Error throws remain in processor.ts" - command: "rg -c 'throw new Error' src/services/documents/processor.ts" - expected: "No matches (exit code 1)" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T13:15:00Z" - output: "exit code 1 - no matches" - notes: "All 8 throw sites migrated" - - id: "ac2_2" - type: "compile" - description: "Processor compiles with new error imports" - command: "npx tsc --noEmit src/services/documents/processor.ts" - expected: "Exit code 0" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T13:18:00Z" - output: "tsc completed with exit code 0" - - id: "ac2_3" - type: "security" - description: "No hardcoded secrets introduced" - command: "rg -i '(password|secret|api[_-]?key)\\s*=\\s*[\"'']\\w' src/services/documents/processor.ts" - expected: "No matches" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T13:20:00Z" - output: "No matches found" - status: "completed" - - - id: "phase3" - name: "Update tests to assert on error codes" - objective: "Migrate test assertions from message matching to code matching and add coverage for each error code" - dependencies: - - "phase2" - changes: - - file: "src/services/documents/processor.test.ts" - action: "update" - lines: "all" - content_spec: | - Import DocumentErrorCode and DocumentProcessingError. - For each error-path test: - - Replace `.toThrow("message")` with a catch block that asserts - `error instanceof DocumentProcessingError` and - `error.code === DocumentErrorCode.X`. - - Verify error.context contains expected metadata where applicable. - - Add one new test per error code to confirm the correct code is thrown - for each failure scenario. - - file: "src/errors/document-error.test.ts" - action: "update" - lines: "all" - content_spec: | - Add tests for edge cases: missing context, serialization, - instanceof checks, and name property. - acceptance_criteria: - - id: "ac3_1" - type: "test" - description: "All processor tests pass with code-based assertions" - command: "npm test -- --filter documents" - expected: "All tests pass, 0 failures" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T14:28:00Z" - output: "18 tests passed, 0 failed" - notes: "Added 8 new tests (one per error code), updated 6 existing tests" - - id: "ac3_2" - type: "test" - description: "Full test suite passes with no regressions" - command: "npm test" - expected: "Exit code 0" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T14:35:00Z" - output: "142 tests passed, 0 failed, 0 skipped" - - id: "ac3_3" - type: "integration" - description: "Document upload endpoint returns structured error on invalid input" - command: "npm run test:integration -- --filter document-upload" - expected: "Exit code 0" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T14:38:00Z" - output: "3 integration tests passed" - - id: "ac3_4" - type: "custom" - description: "Error code coverage matches throw site count" - validation: "manual" - result: - status: "pass" - timestamp: "2026-02-18T14:40:00Z" - notes: "8 error codes defined, 8 throw sites migrated, 8 dedicated test cases added - 1:1:1 coverage" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- src/errors/codes.ts src/errors/document-error.ts" - phase2: "git checkout HEAD -- src/services/documents/processor.ts src/errors/index.ts" - phase3: "git checkout HEAD -- src/services/documents/processor.test.ts src/errors/document-error.test.ts" - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 2 - validation_depth: 2 - total: 10 - notes: | - All 8 error paths migrated with 1:1 enum coverage. Error class follows existing - BaseError pattern in the codebase. Tests cover every error code individually plus - integration test for the upload endpoint. No deviations from spec. - second_pass_performed: false - -deviations: [] - -metadata: - estimated_effort_hours: 2.5 - actual_effort_hours: 3.0 - ai_model: "claude-opus-4-6" - react_cycles: 12 - tags: - - "error-handling" - - "typescript" - - "refactor" diff --git a/.ai/schemas/spec.json b/.ai/schemas/spec.json deleted file mode 100644 index 9d3ab3b71..000000000 --- a/.ai/schemas/spec.json +++ /dev/null @@ -1,476 +0,0 @@ -{ - "$schema": "http://json-schema.org/draft-07/schema#", - "$id": "https://github.com/nilstate/scafld/spec-v1.1.json", - "title": "scafld Task Specification", - "description": "Machine-readable conversational task specification for AI agents", - "type": "object", - "required": ["spec_version", "task_id", "status", "task", "phases", "planning_log", "created", "updated"], - "additionalProperties": false, - - "properties": { - "spec_version": { - "type": "string", - "pattern": "^[0-9]+\\.[0-9]+$", - "description": "Semantic version of this spec format", - "examples": ["1.1"] - }, - - "task_id": { - "type": "string", - "pattern": "^[a-z0-9-]+$", - "description": "Unique identifier for this task (kebab-case)", - "examples": ["add-user-metrics", "refactor-auth-module"] - }, - - "created": { - "type": "string", - "format": "date-time", - "description": "ISO 8601 timestamp when spec was generated" - }, - - "updated": { - "type": "string", - "format": "date-time", - "description": "ISO 8601 timestamp when spec was last modified" - }, - - "status": { - "type": "string", - "enum": ["draft", "blocked", "under_review", "approved", "in_progress", "completed", "failed", "cancelled"], - "description": "Current lifecycle state of this task" - }, - - "task": { - "type": "object", - "required": ["title", "summary", "size", "risk_level", "context", "objectives", "touchpoints", "acceptance"], - "properties": { - "title": { - "type": "string", - "minLength": 5, - "description": "Human friendly title for this task" - }, - "summary": { - "type": "string", - "minLength": 20, - "description": "Concise description of the problem/goal" - }, - "size": { - "type": "string", - "enum": ["micro", "small", "medium", "large"], - "description": "Relative task size to guide planning and validation depth" - }, - "risk_level": { - "type": "string", - "enum": ["low", "medium", "high"], - "description": "Overall risk tier for this task; used to select validation profile when not explicitly set" - }, - "context": { - "type": "object", - "required": ["packages", "invariants"], - "properties": { - "packages": { - "type": "array", - "items": {"type": "string"}, - "minItems": 1, - "description": "Modules or packages affected" - }, - "files_impacted": { - "type": "array", - "items": { - "type": "object", - "required": ["path", "reason"], - "properties": { - "path": {"type": "string"}, - "lines": { - "oneOf": [ - {"type": "array", "items": {"type": "integer"}}, - {"type": "string", "pattern": "^[0-9]+-[0-9]+$"}, - {"type": "string", "enum": ["all"]} - ] - }, - "reason": {"type": "string"} - } - } - }, - "invariants": { - "type": "array", - "items": { - "type": "string" - }, - "minItems": 1, - "description": "Architectural/contract invariants that must be preserved (customize in config.yaml)" - }, - "related_docs": { - "type": "array", - "items": {"type": "string"} - }, - "cwd": { - "type": "string", - "description": "Default working directory for acceptance criteria commands, relative to workspace root. Individual criteria can override with their own cwd." - } - } - }, - "objectives": { - "type": "array", - "items": {"type": "string"}, - "minItems": 1, - "description": "Primary goals for this task" - }, - "scope": { - "type": "object", - "properties": { - "in_scope": { - "type": "array", - "items": {"type": "string"} - }, - "out_of_scope": { - "type": "array", - "items": {"type": "string"} - } - } - }, - "dependencies": { - "type": "array", - "items": {"type": "string"} - }, - "assumptions": { - "type": "array", - "items": {"type": "string"} - }, - "touchpoints": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "required": ["area", "description"], - "properties": { - "area": {"type": "string"}, - "description": {"type": "string"}, - "owners": { - "type": "array", - "items": {"type": "string"} - }, - "links": { - "type": "array", - "items": {"type": "string"} - } - } - } - }, - "risks": { - "type": "array", - "items": { - "type": "object", - "required": ["description"], - "properties": { - "description": {"type": "string"}, - "impact": { - "type": "string", - "enum": ["low", "medium", "high"] - }, - "mitigation": {"type": "string"} - } - } - }, - "acceptance": { - "type": "object", - "required": ["definition_of_done", "validation"], - "properties": { - "validation_profile": { - "type": "string", - "enum": ["light", "standard", "strict"], - "description": "Validation profile to apply; defaults based on risk_level if omitted" - }, - "definition_of_done": { - "type": "array", - "minItems": 1, - "description": "Checklist items that must be explicitly checked off during execution", - "items": { - "type": "object", - "required": ["id", "description"], - "properties": { - "id": {"type": "string"}, - "description": {"type": "string"}, - "status": { - "type": "string", - "enum": ["pending", "in_progress", "done"], - "default": "pending" - }, - "checked_at": {"type": "string", "format": "date-time"}, - "notes": {"type": "string"} - } - } - }, - "validation": { - "type": "array", - "items": { - "type": "object", - "required": ["id", "type", "description"], - "properties": { - "id": {"type": "string"}, - "type": { - "type": "string", - "enum": [ - "compile", - "test", - "boundary", - "integration", - "security", - "documentation", - "custom" - ] - }, - "description": {"type": "string"}, - "command": {"type": "string"}, - "expected": {"type": "string"}, - "cwd": {"type": "string", "description": "Working directory relative to workspace root"}, - "timeout_seconds": { - "type": "integer", - "minimum": 1, - "description": "Command timeout in seconds. Defaults to 600 when omitted." - } - } - } - } - } - }, - "notes": {"type": "string"} - } - }, - - "planning_log": { - "type": "array", - "items": { - "type": "object", - "required": ["timestamp", "summary"], - "properties": { - "timestamp": {"type": "string", "format": "date-time"}, - "actor": {"type": "string"}, - "summary": {"type": "string"}, - "notes": {"type": "string"} - } - } - }, - - "phases": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "required": ["id", "name", "objective", "changes", "acceptance_criteria"], - "properties": { - "id": { - "type": "string", - "pattern": "^phase[0-9]+$" - }, - "name": { - "type": "string", - "minLength": 5 - }, - "objective": { - "type": "string", - "minLength": 10 - }, - "dependencies": { - "type": "array", - "items": {"type": "string"} - }, - "changes": { - "type": "array", - "items": { - "type": "object", - "required": ["file", "action", "content_spec"], - "properties": { - "file": {"type": "string"}, - "action": { - "type": "string", - "enum": ["create", "update", "delete", "move"] - }, - "move_to": { - "type": "string", - "description": "Destination path when action is 'move'" - }, - "lines": { - "oneOf": [ - {"type": "array", "items": {"type": "integer"}}, - {"type": "string", "pattern": "^[0-9]+-[0-9]+$"}, - {"type": "string", "enum": ["all"]} - ] - }, - "content_spec": {"type": "string"} - } - } - }, - "acceptance_criteria": { - "type": "array", - "minItems": 1, - "items": { - "type": "object", - "required": ["id", "type", "description"], - "properties": { - "id": {"type": "string"}, - "type": { - "type": "string", - "enum": [ - "compile", - "test", - "boundary", - "integration", - "security", - "documentation", - "custom" - ], - "description": "Criterion type. For automated types (compile, test, boundary, integration, security), a 'command' field is expected. For manual types (documentation, custom), 'command' is optional." - }, - "description": {"type": "string"}, - "command": { - "type": "string", - "description": "Shell command to run for automated validation. Expected for compile, test, boundary, integration, and security types." - }, - "expected": {"type": "string"}, - "cwd": { - "type": "string", - "description": "Working directory for the command, relative to workspace root. Useful in monorepo/workspace setups where different criteria target different submodules." - }, - "timeout_seconds": { - "type": "integer", - "minimum": 1, - "description": "Command timeout in seconds. Defaults to 600 when omitted." - }, - "result": { - "oneOf": [ - { - "type": "string", - "enum": ["pass", "fail"], - "description": "Flat result recorded by scafld exec" - }, - { - "type": "object", - "required": ["status"], - "properties": { - "status": { - "type": "string", - "enum": ["pass", "fail"] - }, - "timestamp": { - "type": "string", - "format": "date-time" - }, - "output": { - "type": "string" - } - }, - "additionalProperties": false, - "description": "Nested result block supported for execution records" - } - ] - }, - "executed_at": { - "type": "string", - "format": "date-time", - "description": "When the criterion was last executed" - }, - "result_output": { - "type": "string", - "description": "Truncated command output from scafld exec" - } - } - } - }, - "status": { - "type": "string", - "enum": ["pending", "in_progress", "completed", "failed", "skipped"] - } - } - } - }, - - "rollback": { - "type": "object", - "properties": { - "strategy": { - "type": "string", - "enum": ["per_phase", "atomic", "manual"], - "default": "per_phase" - }, - "commands": { - "type": "object", - "patternProperties": { - "^phase[0-9]+$": {"type": "string"} - } - } - } - }, - - "review": { - "type": "object", - "description": "Adversarial review results recorded by scafld complete", - "properties": { - "timestamp": {"type": "string", "format": "date-time"}, - "verdict": { - "type": "string", - "enum": ["pass", "fail", "pass_with_issues"], - "description": "pass = no findings, fail = blocking findings, pass_with_issues = non-blocking only" - }, - "passes": { - "type": "array", - "items": { - "type": "object", - "required": ["id", "result"], - "properties": { - "id": {"type": "string"}, - "result": { - "type": "string", - "enum": ["pass", "fail", "pass_with_issues"] - } - } - } - }, - "review_rounds": {"type": "integer", "minimum": 0, "description": "Number of review rounds before passing"}, - "blocking_count": {"type": "integer", "minimum": 0}, - "non_blocking_count": {"type": "integer", "minimum": 0} - } - }, - - "self_eval": { - "type": "object", - "properties": { - "completeness": {"type": "integer", "minimum": 0, "maximum": 3}, - "architecture_fidelity": {"type": "integer", "minimum": 0, "maximum": 3}, - "spec_alignment": {"type": "integer", "minimum": 0, "maximum": 2}, - "validation_depth": {"type": "integer", "minimum": 0, "maximum": 2}, - "total": {"type": "integer", "minimum": 0, "maximum": 10}, - "notes": {"type": "string"}, - "second_pass_performed": {"type": "boolean"} - } - }, - - "deviations": { - "type": "array", - "items": { - "type": "object", - "required": ["rule", "reason"], - "properties": { - "rule": {"type": "string"}, - "reason": {"type": "string"}, - "mitigation": {"type": "string"}, - "approved_by": {"type": "string"} - } - } - }, - - "metadata": { - "type": "object", - "properties": { - "estimated_effort_hours": {"type": "number", "minimum": 0}, - "actual_effort_hours": {"type": "number", "minimum": 0}, - "ai_model": {"type": "string"}, - "react_cycles": {"type": "integer"}, - "tags": { - "type": "array", - "items": {"type": "string"} - } - } - } - } -} diff --git a/.ai/specs/README.md b/.ai/specs/README.md deleted file mode 100644 index 73891aabc..000000000 --- a/.ai/specs/README.md +++ /dev/null @@ -1,99 +0,0 @@ -# Task Specifications - -This directory contains machine-readable task specifications organized by lifecycle status. - ---- - -## Directory Structure - -``` -specs/ -├── drafts/ # Planning in progress -│ └── *.yaml (status: draft | under_review) -├── approved/ # Ready for execution -│ └── *.yaml (status: approved) -├── active/ # Currently executing -│ └── *.yaml (status: in_progress) -└── archive/ # Completed work - └── YYYY-MM/ - └── *.yaml (status: completed | failed | cancelled) -``` - ---- - -## File Naming - -**Convention:** `{task-id}.yaml` using kebab-case, descriptive names. - -Good: `add-user-metrics.yaml`, `refactor-auth-module.yaml`, `fix-chunk-dedup.yaml` -Bad: `task-123.yaml` (not descriptive), `AddMetrics.yaml` (not kebab-case) - ---- - -## Workflow - -### 1. Planning - -AI generates spec in `drafts/` with `status: "draft"`. If blocked, set `status: "under_review"`. - -### 2. Review & Approval - -Developer reviews, then approves: - -```bash -scafld approve my-task -``` - -### 3. Execution - -AI moves spec to `active/`, sets `status: "in_progress"`, and executes phases. - -### 4. Review - -Run adversarial review before completing: - -```bash -scafld review my-task -# Fill in findings in .ai/reviews/my-task.md -``` - -### 5. Completion - -Mark complete (reads review, records verdict, moves to `archive/YYYY-MM/`): - -```bash -scafld complete my-task -``` - ---- - -## Spec Anatomy - -Each spec validated by `.ai/schemas/spec.json` includes: - -- **`task` block:** Title, summary, context, objectives, scope, touchpoints, risks, acceptance checklist, constraints -- **`planning_log`:** Chronological entries summarizing planning steps -- **`phases`:** Ordered execution units with `changes[].content_spec`, acceptance criteria, and per-phase status -- **`rollback`:** Strategy and per-phase commands for safe reversions -- **`review`:** Verdict, pass results, and finding counts recorded by `scafld complete` -- **`self_eval` / `deviations` / `metadata`:** Populated during execution - ---- - -## Finding Work - -```bash -scafld list # All specs -scafld list active # Currently executing -scafld list approved # Awaiting execution -scafld list drafts # Planning in progress -scafld list archive # Completed work -``` - ---- - -## See Also - -- [AGENTS.md](../../AGENTS.md) - Status lifecycle and agent policies -- [config.yaml](../config.yaml) - Validation profiles and size/risk tiers -- [schemas/spec.json](../schemas/spec.json) - Spec validation schema diff --git a/.ai/specs/active/runx-unified-workspace-topology.yaml b/.ai/specs/active/runx-unified-workspace-topology.yaml deleted file mode 100644 index 30b6b174c..000000000 --- a/.ai/specs/active/runx-unified-workspace-topology.yaml +++ /dev/null @@ -1,295 +0,0 @@ -spec_version: "1.1" -task_id: "runx-unified-workspace-topology" -created: "2026-04-24T00:45:00Z" -updated: "2026-04-26T15:40:48Z" -status: "in_progress" - -task: - title: "Converge runx onto one real workspace and remove nested-repo hybrid debt" - summary: > - The parent workspace root now exists, but the current parent repo plus - nested oss/cloud git repos is still a hybrid. The ideal shape from here is a - single authoritative workspace rooted at /home/kam/dev/runx, with manifest - dependencies expressed as workspace package edges and no gitlink-style nested - repos. Converge the topology so the package graph, tooling, and versioning - all describe the same reality. - size: "large" - risk_level: "high" - context: - packages: - - ".." - - "../oss/packages/*" - - "../cloud/apps/*" - - "../cloud/packages/*" - files_impacted: - - path: "../package.json" - lines: "all" - reason: "Parent repo is already the workspace root and should become the only authoritative repo root." - - path: "../pnpm-workspace.yaml" - lines: "all" - reason: "Workspace membership is declared at the real root and should stay authoritative." - - path: "../cloud/package.json" - lines: "all" - reason: "Cloud should consume @runxhq/* through workspace refs, not local links." - - path: "../oss/package.json" - lines: "all" - reason: "Top-level oss workspace behavior should move to the root or become a package-local concern." - - path: "../.github/workflows" - lines: "all" - reason: "CI should run from the real workspace root, not through nested-repo assumptions." - - path: "../oss" - lines: "all" - reason: "Nested git-repo packaging assumptions should be removed." - - path: "../cloud" - lines: "all" - reason: "Nested git-repo packaging assumptions should be removed." - invariants: - - "Package edges must be real workspace edges, not hidden source or link hacks." - - "There is exactly one authoritative git/workspace root." - - "Cloud and oss remain separately buildable within the unified workspace." - objectives: - - "Finish promoting /home/kam/dev/runx to the only real workspace root." - - "Keep cloud manifest dependencies on workspace package edges instead of link:../oss references." - - "Remove nested gitlink-style repos and normalize tooling and CI around the root." - scope: - in_scope: - - "Workspace manifests, dependency edges, repo topology, and root-level tooling." - out_of_scope: - - "Physically moving every directory if the unified root can be achieved without it." - - "Publishing external package versions to a remote registry." - dependencies: - - "runx-verification-foundation-and-fast-lanes" - - "runx-cli-kernel-final-split" - - "runx-runner-local-facade-final-split" - - "runx-hosted-api-domain-service-split" - - "runx-contracts-single-authority" - assumptions: - - "The preferred end state is one real monorepo workspace, not separate published package release trains." - touchpoints: - - area: "/home/kam/dev/runx" - description: "Future authoritative git and package-manager root." - - area: "../cloud/package.json" - description: "Current local-link consumer that should use workspace refs." - - area: "../oss and ../cloud git topology" - description: "Current nested-repo debt that should disappear." - risks: - - description: "Repo-topology changes can disrupt daily workflows if done before structural code work settles." - impact: "high" - mitigation: "Execute this after the major code-shape refactors and only with a stable fast verification lane." - - description: "Workspace convergence can accidentally break scripts that assume the old cwd layout." - impact: "medium" - mitigation: "Move tooling and scripts in phases and keep root-level entrypoints explicit." - acceptance: - validation_profile: "strict" - definition_of_done: - - id: "dod1" - description: "The parent repo is the only authoritative workspace root." - - id: "dod2" - description: "Cloud consumes @runxhq/* through workspace refs instead of link:../oss/package paths." - - id: "dod3" - description: "oss and cloud are no longer tracked as nested gitlink-style repos." - - id: "dod4" - description: "Root-level install and verification commands operate over the unified workspace." - validation: - - id: "v1" - type: "integration" - description: "Root workspace install succeeds." - command: "pnpm install" - cwd: ".." - expected: "exit code 0" - - id: "v2" - type: "compile" - description: "Root-driven oss and cloud verification succeeds." - command: "pnpm --dir oss typecheck && pnpm --dir cloud typecheck" - cwd: ".." - expected: "exit code 0" - - id: "v3" - type: "boundary" - description: "No cloud package manifest still uses link:../oss package edges." - command: "! rg -n 'link:\\.\\./oss/packages' cloud -g 'package.json'" - cwd: ".." - expected: "exit code 0" - - id: "v4" - type: "boundary" - description: "oss and cloud are no longer tracked as gitlink-style nested repos." - command: "test -z \"$(git ls-files -s oss cloud | awk '$1 == 160000 { print }')\"" - cwd: ".." - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-24T00:45:00Z" - actor: "user" - summary: "Asked for concrete execution specs covering the full path to ideal shape." - - timestamp: "2026-04-24T00:45:00Z" - actor: "agent" - summary: "Chose one real workspace as the target end state instead of keeping the current parent-plus-nested-repo hybrid." - - timestamp: "2026-04-25T14:31:49Z" - actor: "agent" - summary: "Rebased the draft on the current root workspace manifests; remaining topology risk is nested gitlink removal and root-driven verification." - - timestamp: "2026-04-26T12:58:00Z" - actor: "agent" - summary: "Executed root workspace install and fixed the blocking workspace-edge issue by including oss/cloud roots and converting local @runxhq package edges to workspace refs." - - timestamp: "2026-04-26T12:58:00Z" - actor: "agent" - summary: "Adversarial review kept phase3 open because parent git still tracks oss and cloud as 160000 gitlinks; removing nested repo history requires an explicit destructive topology cutover." - - timestamp: "2026-04-26T15:40:48Z" - actor: "agent" - summary: "Added a precise final topology cutover checklist and rollback path; phase3 remains blocked until the user explicitly approves the gitlink removal." - -phases: - - id: "phase1" - name: "Normalize the existing parent workspace root" - objective: "Keep /home/kam/dev/runx as the package-manager root with explicit workspace membership and root-level commands." - changes: - - file: "../package.json" - action: "update" - lines: "all" - content_spec: > - Audit and expand the existing root package manifest so it exposes the - authoritative workspace-level scripts and package manager settings. - - file: "../pnpm-workspace.yaml" - action: "update" - lines: "all" - content_spec: > - Keep oss and cloud workspace members declared from the real root. - - file: "../oss/package.json" - action: "update" - lines: "all" - content_spec: > - Remove assumptions that oss itself is the only workspace root when - they should now live at the parent level. - - file: "../cloud/package.json" - action: "update" - lines: "all" - content_spec: > - Align cloud package-manager behavior with the new root workspace. - acceptance_criteria: - - id: "ac1_1" - type: "integration" - description: "Root workspace install succeeds." - command: "pnpm install" - cwd: ".." - expected: "exit code 0" - status: "completed" - - - id: "phase2" - name: "Replace link edges with workspace edges" - objective: "Make the package graph honest at the manifest level." - dependencies: - - "phase1" - changes: - - file: "../cloud/package.json" - action: "update" - lines: "all" - content_spec: > - Replace link:../oss package edges with workspace: references to the - unified root workspace packages. - - file: "../cloud/pnpm-lock.yaml" - action: "update" - lines: "all" - content_spec: > - Refresh the lockfile against workspace-based package edges. PNPM may - still render resolved workspace packages as link: entries in the - lockfile; the invariant is that package manifests no longer declare - link:../oss dependencies. - - file: "../cloud/tsconfig.base.json" - action: "update" - lines: "all" - content_spec: > - Keep compile-time path resolution aligned with the workspace package - graph after the manifest change. - acceptance_criteria: - - id: "ac2_1" - type: "boundary" - description: "No cloud package manifest still uses link:../oss package refs." - command: "! rg -n 'link:\\.\\./oss/packages' cloud -g 'package.json'" - cwd: ".." - expected: "exit code 0" - status: "completed" - - - id: "phase3" - name: "Remove nested gitlink topology and normalize tooling" - objective: "Finish the topology migration so git, CI, and developer commands all operate from the root." - dependencies: - - "phase2" - changes: - - file: "../.github/workflows" - action: "update" - lines: "all" - content_spec: > - Move workspace verification and release automation to the parent root. - - file: "../oss" - action: "update" - lines: "all" - content_spec: > - Remove nested git-repo assumptions and keep only package-level - concerns inside the directory tree. - - file: "../cloud" - action: "update" - lines: "all" - content_spec: > - Remove nested git-repo assumptions and keep only package-level - concerns inside the directory tree. - acceptance_criteria: - - id: "ac3_1" - type: "boundary" - description: "oss and cloud are no longer tracked as nested gitlinks." - command: "test -z \"$(git ls-files -s oss cloud | awk '$1 == 160000 { print }')\"" - cwd: ".." - expected: "exit code 0" - - id: "ac3_2" - type: "compile" - description: "Root-driven oss and cloud verification succeeds." - command: "pnpm --dir oss typecheck && pnpm --dir cloud typecheck" - cwd: ".." - expected: "exit code 0" - status: "pending" - blocked_reason: "Parent git still tracks oss and cloud as 160000 gitlinks. Completing this phase requires removing nested .git directories or otherwise converting both trees into parent-tracked files, which is intentionally not hidden inside this spec execution while both nested repos have active dirt." - cutover_checklist: - - "Freeze nested repo work: `git -C oss status --short --branch` and `git -C cloud status --short --branch` must be clean except intended final commits." - - "Record exact nested SHAs and parent gitlink SHAs before mutation: `git -C oss rev-parse HEAD`, `git -C cloud rev-parse HEAD`, and `git ls-files -s oss cloud`." - - "Create rollback anchors before destructive topology changes: parent branch/tag plus timestamped backups of `oss/.git` and `cloud/.git` outside the workspace." - - "Commit the parent gitlink updates first so the parent repo records the final nested SHAs before the cutover." - - "Choose history strategy explicitly: squash-import current trees into parent, or use subtree/filter import if preserving nested history is required." - - "Remove gitlink index entries only after backups exist: `git rm --cached oss cloud`; remove `.gitmodules` entries if any are present." - - "Move nested `.git` directories out of the tree rather than deleting them: for example `.git-backups/runx-oss-` and `.git-backups/runx-cloud-` outside `/home/kam/dev/runx`." - - "Re-add `oss` and `cloud` as ordinary parent-tracked directories, respecting parent `.gitignore` so `node_modules`, caches, and generated build output stay out." - - "Verify no gitlinks remain: `test -z \"$(git ls-files -s oss cloud | awk '$1 == 160000 { print }')\"`." - - "Run root install and verification from `/home/kam/dev/runx`: `pnpm install`, `pnpm --dir oss typecheck`, `pnpm --dir cloud typecheck`, and targeted fast suites." - - "Commit the cutover as one topology commit that contains only gitlink removal, ordinary file tracking, root ignore/tooling updates, and verification notes." - - "Rollback path: restore the pre-cutover parent commit, move backed-up `.git` directories back into `oss/.git` and `cloud/.git`, and reset the parent gitlinks to the recorded SHAs." - -rollback: - strategy: "per_phase" - commands: - phase1: "git -C /home/kam/dev/runx checkout HEAD -- package.json pnpm-workspace.yaml && git -C /home/kam/dev/runx/oss checkout HEAD -- package.json && git -C /home/kam/dev/runx/cloud checkout HEAD -- package.json" - phase2: "git -C /home/kam/dev/runx/cloud checkout HEAD -- package.json pnpm-lock.yaml tsconfig.base.json && git -C /home/kam/dev/runx checkout HEAD -- pnpm-lock.yaml" - phase3: "git -C /home/kam/dev/runx checkout HEAD -- .github/workflows oss cloud" - -review: - verdict: "blocked" - reviewed_at: "2026-04-26T12:58:00Z" - reviewer: "agent" - finding_counts: - critical: 0 - high: 1 - medium: 0 - low: 0 - findings: - - severity: "high" - area: "repo topology" - evidence: "git ls-files -s oss cloud still returns mode 160000 entries for both directories." - impact: "The parent repo is not yet the only authoritative git root, so definition-of-done item dod3 remains unmet." - recommendation: "Schedule a dedicated cutover that commits nested repos, removes gitlinks, removes or migrates nested .git directories, and adds the full oss/cloud trees to the parent repo in one reviewed operation." - notes: - - "Root workspace install now succeeds with 25 workspace projects." - - "Cloud package manifests no longer declare link:../oss package edges." - - "Root-driven oss and cloud typechecks pass." - -metadata: - estimated_effort_hours: 12 - ai_model: "gpt-5" - tags: - - "workspace" - - "repo-topology" - - "package-boundaries" diff --git a/.ai/specs/archive/2026-04/icey-cli-upstream-binding.yaml b/.ai/specs/archive/2026-04/icey-cli-upstream-binding.yaml deleted file mode 100644 index bbf38d152..000000000 --- a/.ai/specs/archive/2026-04/icey-cli-upstream-binding.yaml +++ /dev/null @@ -1,239 +0,0 @@ -spec_version: "1.1" -task_id: "icey-cli-upstream-registry-binding" -created: "2026-04-16T01:35:44Z" -updated: "2026-04-23T15:27:08Z" -status: "completed" - -task: - title: "Bind merged icey-cli SKILL.md into runx registry" - summary: > - nilstate/icey-cli accepted the upstream portable SKILL.md. Add the runx-owned - registry binding layer that pins the upstream source, supplies X.yaml runner - metadata and harness cases, and materializes a reproducible registry package - without treating a copied SKILL.md as source of truth. - size: "medium" - risk_level: "medium" - context: - packages: - - "packages/registry" - - "packages/harness" - - "bindings" - - "scripts" - files_impacted: - - path: "bindings/nilstate/icey-server-operator/registry-binding.json" - lines: "all" - reason: "Pinned upstream source, trust tier, harness state, and publication metadata" - - path: "bindings/nilstate/icey-server-operator/X.yaml" - lines: "all" - reason: "runx-owned runner metadata and harness cases for the upstream skill" - - path: "scripts/materialize-upstream-skill-binding.mjs" - lines: "all" - reason: "Materialize upstream SKILL.md plus local X.yaml into a registry package" - - path: "packages/registry/src/ingest.ts" - lines: "all" - reason: "Carry runner tags from X.yaml into registry rows" - - path: "tests/upstream-registry-binding.test.ts" - lines: "all" - reason: "Binding, harness, and materialization coverage" - invariants: - - "Upstream SKILL.md remains source of truth" - - "runx execution metadata stays outside upstream repos" - - "Registry artifacts are reproducible from pinned commit/blob" - related_docs: - - "bindings/README.md" - - "../docs/skill-learning-contribution-spec.md" - objectives: - - "Represent nilstate/icey-cli as an upstream-owned registry binding" - - "Add harnessed X.yaml metadata without modifying upstream" - - "Materialize and locally publish the binding from the pinned upstream blob" - - "Propagate X.yaml tags to registry search metadata" - scope: - in_scope: - - "runx/oss binding files, materializer script, registry metadata extraction, and tests" - out_of_scope: - - "Hosted registry remote publish without RUNX_HOSTED_REGISTRY_PUBLISH_TOKEN" - - "Changing nilstate/icey-cli after merge" - - "Implementing generic runx add github:owner/repo resolution" - dependencies: - - "nilstate/icey-cli PR #2 merged at ee9aa1cc05055c2490537e762c81c9f28451f578" - assumptions: - - "The upstream SKILL.md blob sha a1e1de7b5ea8b32c164d61fecc3c7ae4401b4c97 is immutable for the pinned commit" - - "Registry publish stores a pinned copy as an immutable artifact while preserving upstream provenance" - touchpoints: - - area: "bindings" - description: "New upstream-owned binding contract and X.yaml harness" - - area: "registry ingest" - description: "Runner-level runx.tags become registry search tags" - - area: "materialization" - description: "Script fetches or reads the upstream SKILL.md, verifies blob sha, writes a package, and optionally publishes locally" - risks: - - description: "A registry package could be mistaken as the source SKILL.md" - impact: "medium" - mitigation: "Binding JSON marks upstream.source_of_truth=true and materialized_package_is_registry_artifact=true" - - description: "Hosted publish cannot complete without registry publish token" - impact: "medium" - mitigation: "Local publish dogfood is complete; remote publication remains explicit pending state" - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "Binding pins upstream repo/path/commit/blob and PR proof" - status: "done" - checked_at: "2026-04-16T01:35:44Z" - - id: "dod2" - description: "X.yaml declares a default runner and two passing harness cases" - status: "done" - checked_at: "2026-04-16T01:35:44Z" - - id: "dod3" - description: "Materializer verifies blob sha and writes SKILL.md, X.yaml, binding, and materialization report" - status: "done" - checked_at: "2026-04-16T01:35:44Z" - - id: "dod4" - description: "Local registry publish succeeds from the materialized package" - status: "done" - checked_at: "2026-04-16T01:35:44Z" - validation: - - id: "v1" - type: "test" - description: "Binding and registry tests pass" - command: "pnpm exec vitest run tests/upstream-registry-binding.test.ts packages/registry/src/index.test.ts" - expected: "2 files, 6 tests pass" - - id: "v2" - type: "integration" - description: "Materialize and publish binding to a temporary local registry" - command: "tmp=$(mktemp -d) && node scripts/materialize-upstream-skill-binding.mjs bindings/nilstate/icey-server-operator/registry-binding.json --output-dir dist/upstream-bindings/nilstate/icey-server-operator --registry-dir \"$tmp/registry\"" - expected: "publish.status is published and harness.status is passed" - - id: "v3" - type: "boundary" - description: "No upstream SKILL.md copy is committed under bindings" - command: "! rg -n \"# icey-server Operator Workflow\" bindings" - expected: "No match under tracked binding files" - notes: > - The binding is ready for hosted publication once a registry publish token is - available. Until then, state is harness_verified with publication pending. - -planning_log: - - timestamp: "2026-04-16T01:18:46Z" - actor: "user" - summary: "nilstate/icey-cli PR #2 merged upstream." - - timestamp: "2026-04-16T01:29:28Z" - actor: "agent" - summary: "Aster watcher produced accepted_upstream and registry_binding_request artifacts." - - timestamp: "2026-04-16T01:35:44Z" - actor: "agent" - summary: "Implemented runx upstream binding, harness, materializer, registry tag extraction, and tests." - -phases: - - id: "phase1" - name: "Declare upstream binding" - objective: "Pin the upstream icey-cli SKILL.md and add runx-owned X.yaml metadata." - changes: - - file: "bindings/nilstate/icey-server-operator/registry-binding.json" - action: "create" - lines: "all" - content_spec: "Upstream repo/path/commit/blob, trust tier, harness status, proof links, and publication pending state." - - file: "bindings/nilstate/icey-server-operator/X.yaml" - action: "create" - lines: "all" - content_spec: "Default operator-plan runner with two harness cases for web smoke and release pin preservation." - - file: "bindings/README.md" - action: "create" - lines: "all" - content_spec: "Explain upstream source-of-truth and generated registry artifact boundary." - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "Binding test validates source, runner, and harness shape" - command: "pnpm exec vitest run tests/upstream-registry-binding.test.ts" - expected: "3 tests pass" - result: - status: "pass" - timestamp: "2026-04-16T01:33:52Z" - output: "tests/upstream-registry-binding.test.ts passed" - status: "completed" - - - id: "phase2" - name: "Materialize registry artifact" - objective: "Build a reproducible registry package from upstream SKILL.md and local X.yaml." - dependencies: - - "phase1" - changes: - - file: "scripts/materialize-upstream-skill-binding.mjs" - action: "create" - lines: "all" - content_spec: "Fetch or read upstream SKILL.md, verify git blob sha, write package files, and optionally publish locally." - - file: "schemas/registry-binding.schema.json" - action: "create" - lines: "all" - content_spec: "Machine-readable schema for runx upstream registry bindings." - acceptance_criteria: - - id: "ac2_1" - type: "integration" - description: "Materializer fetches pinned upstream skill and writes package" - command: "node scripts/materialize-upstream-skill-binding.mjs bindings/nilstate/icey-server-operator/registry-binding.json --output-dir dist/upstream-bindings/nilstate/icey-server-operator" - expected: "Materialized package reports upstream blob sha a1e1de7b5ea8b32c164d61fecc3c7ae4401b4c97" - result: - status: "pass" - timestamp: "2026-04-16T01:33:30Z" - output: "status materialized; skill_id nilstate/icey-server-operator" - - id: "ac2_2" - type: "integration" - description: "Materialized package publishes to local registry and harness passes" - command: "tmp=$(mktemp -d) && node scripts/materialize-upstream-skill-binding.mjs bindings/nilstate/icey-server-operator/registry-binding.json --output-dir dist/upstream-bindings/nilstate/icey-server-operator --registry-dir \"$tmp/registry\"" - expected: "publish.status published; harness.status passed" - result: - status: "pass" - timestamp: "2026-04-16T01:35:03Z" - output: "published nilstate/icey-server-operator@upstream-ee9aa1c with 2 harness cases" - status: "completed" - - - id: "phase3" - name: "Complete registry metadata" - objective: "Expose X.yaml tags in registry rows so upstream bindings are searchable without modifying upstream SKILL.md." - dependencies: - - "phase1" - changes: - - file: "packages/registry/src/ingest.ts" - action: "update" - lines: "all" - content_spec: "Merge runner runx.tags with portable SKILL.md runx tags when building registry records." - - file: "packages/registry/src/index.test.ts" - action: "update" - lines: "all" - content_spec: "Add coverage for runner-level tags flowing into registry versions." - acceptance_criteria: - - id: "ac3_1" - type: "test" - description: "Registry ingest extracts runner tags" - command: "pnpm exec vitest run packages/registry/src/index.test.ts" - expected: "registry package tests pass" - result: - status: "pass" - timestamp: "2026-04-16T01:35:00Z" - output: "packages/registry/src/index.test.ts passed" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- bindings/README.md bindings/nilstate/icey-server-operator/registry-binding.json bindings/nilstate/icey-server-operator/X.yaml" - phase2: "git checkout HEAD -- scripts/materialize-upstream-skill-binding.mjs schemas/registry-binding.schema.json" - phase3: "git checkout HEAD -- packages/registry/src/ingest.ts packages/registry/src/index.test.ts" - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 2 - validation_depth: 2 - total: 10 - notes: "Binding source-of-truth boundary, harness verification, materialization, and local publish are covered." - second_pass_performed: true - -metadata: - estimated_effort_hours: 3 - actual_effort_hours: 3 - ai_model: "gpt-5" - tags: - - "registry-binding" - - "skill-contribution" - - "icey-cli" diff --git a/.ai/specs/archive/2026-04/runx-capability-execution-envelope.yaml b/.ai/specs/archive/2026-04/runx-capability-execution-envelope.yaml deleted file mode 100644 index c020b1af2..000000000 --- a/.ai/specs/archive/2026-04/runx-capability-execution-envelope.yaml +++ /dev/null @@ -1,205 +0,0 @@ -spec_version: "1.1" -task_id: "runx-capability-execution-envelope" -created: "2026-04-25T13:30:00Z" -updated: "2026-04-25T13:35:00Z" -status: "completed" - -task: - title: "Freeze and implement the generic capability execution envelope" - summary: > - Sourcey outreach already has the right high-level decomposition: Sourcey - owns the workflow as a local runx capability pack, while GitHub issue - threads hold review state and handoff history. The remaining architectural - gap is that transport-specific trigger data is still reconstructed ad hoc - from CLI flags, local bindings, and thread metadata. The clean cut is a - generic runx capability execution envelope that every transport can build, - every capability can consume, and every thread-backed review artifact can - persist. - size: "medium" - risk_level: "medium" - context: - packages: - - "packages/contracts" - - "packages/core/src/sdk" - - "../sourcey.com/skills/outreach" - - "../sourcey.com/.runx/tools/outreach" - - "../sourcey.com/.runx/tools/docs" - invariants: - - "Runx stays generic; no product-specific `docs` or `sourcey` command surface is added to the engine." - - "Sourcey outreach remains a local capability pack executed through generic runx skill invocation." - - "The GitHub thread is a first-class control object and context surface, not the executor." - - "CLI, API, and GitHub-comment execution paths must converge on the same normalized request contract." - - "Unrelated in-flight runx issue-to-pr edits are not touched or reverted." - related_docs: - - "README.md" - - "../sourcey.com/README.md" - - "../sourcey.com/skills/outreach/SKILL.md" - - "../sourcey.com/skills/outreach/X.yaml" - - "../sourcey.com/.runx/tools/outreach/control.mjs" - objectives: - - "Define a generic runx-level capability execution envelope contract." - - "Make thread refs explicit, stable, and transport-neutral." - - "Define deterministic idempotency semantics shared by CLI, API, and GitHub-triggered executions." - - "Cut Sourcey outreach over to the envelope without adding a public Sourcey CLI or a privileged runx product command." - - "Persist the normalized execution request in thread review metadata so future transports can recover it." - scope: - in_scope: - - "A new runx contract for capability execution envelopes." - - "A small generic runx helper that canonicalizes inputs and derives idempotency keys." - - "Sourcey outreach control tooling building and returning the normalized envelope." - - "Persisting the normalized request inside review-thread control metadata." - - "Documentation and tests for the new transport/capability/thread model." - out_of_scope: - - "A webhook worker or GitHub command bridge." - - "A public Sourcey CLI binary." - - "Generic runx execution changes unrelated to the capability-envelope seam." - decisions: - - "The canonical envelope lives in `@runxhq/contracts`, not in Sourcey. It is a generic runx contract any capability can reuse." - - "The canonical thread ref is the existing thread-locator URI string, exposed as `thread_ref` in the envelope. For GitHub control threads that is `github://owner/repo/issues/N`." - - "Thread resolution remains adapter-backed. The envelope carries the thread ref; the consuming capability resolves it through its configured thread adapter." - - "Idempotency uses two related keys:" - - "`intent_key`: semantic hash of capability ref, runner, thread ref, and normalized runner inputs." - - "`trigger_key`: optional exact-trigger hash derived from transport kind plus trigger ref; used to dedupe replayed webhook/comment events." - - "The same semantic rerun may be intentionally executed again later. `intent_key` is for collision/concurrency reasoning, not an eternal no-op cache." - - "Transport supplies actor identity and scope set; capability behavior is the same, but reachable actions can still be gated by those scopes." - deliverables: - - "A runx capability execution envelope schema with runtime validation." - - "A core helper to build normalized envelopes and derive stable idempotency keys." - - "Sourcey outreach control actions that emit `capability_execution` in results." - - "Review and outreach thread comments that persist `capability_execution` in control metadata." - - "Docs explaining the capability / transport / thread split." - -phases: - - id: "phase1" - name: "Freeze the contract" - objective: "Define the generic request model before code changes." - changes: - - file: "packages/contracts/src/index.ts" - action: "update" - lines: "contract ids, logical schemas, new execution-envelope schemas" - content_spec: > - Add the generic capability execution envelope contract and nested - transport/actor/idempotency schemas. Keep naming generic and - product-agnostic. - - file: "packages/contracts/src/index.test.ts" - action: "update" - lines: "contract coverage" - content_spec: > - Add validation coverage for stable schema ids, transport actor/scope - fields, and deterministic idempotency fields. - acceptance_criteria: - - id: "ac1_1" - type: "test" - command: "pnpm exec vitest run packages/contracts/src/index.test.ts" - description: "The generic envelope contract validates and exports stable schema ids." - - - id: "phase2" - name: "Add the generic builder" - objective: "Create one reusable normalizer for all transports." - dependencies: - - "phase1" - changes: - - file: "packages/core/src/sdk/capability-execution.ts" - action: "add" - lines: "all" - content_spec: > - Add a small generic helper that normalizes input overrides, builds - the envelope, and derives `intent_key`, `trigger_key`, and - `content_hash` deterministically. - - file: "packages/core/src/sdk/index.ts" - action: "update" - lines: "exports" - content_spec: "Export the new generic capability-execution helpers." - - file: "packages/core/src/sdk/capability-execution.test.ts" - action: "add" - lines: "all" - content_spec: > - Cover stable hashing, omission of undefined fields, and the split - between semantic intent and exact trigger dedupe. - acceptance_criteria: - - id: "ac2_1" - type: "test" - command: "pnpm exec vitest run packages/core/src/sdk/capability-execution.test.ts" - description: "The builder produces stable intent and trigger hashes." - - - id: "phase3" - name: "Cut Sourcey outreach over" - objective: "Make Sourcey consume the normalized envelope without changing the public operator surface." - dependencies: - - "phase2" - changes: - - file: "../sourcey.com/.runx/tools/outreach/control.mjs" - action: "update" - lines: "control-state and result packaging" - content_spec: > - Build a capability-execution envelope for each thread-facing runner, - return it in control results, and persist it into control metadata. - - file: "../sourcey.com/.runx/tools/outreach/control/src/index.ts" - action: "update" - lines: "inputs and action handlers" - content_spec: > - Accept optional thread-ref and transport metadata, build the envelope - centrally, and pass it through to docs-pr/docs-outreach packaging. - - file: "../sourcey.com/skills/docs-pr/X.yaml" - action: "update" - lines: "runner inputs and package step" - content_spec: > - Thread the normalized capability execution object into - `docs.package_pr` so review comments persist it. - - file: "../sourcey.com/skills/docs-outreach/X.yaml" - action: "update" - lines: "runner inputs and package step" - content_spec: > - Thread the normalized capability execution object into - `docs.package_outreach` so review comments persist it. - - file: "../sourcey.com/.runx/tools/docs/package_pr/src/index.ts" - action: "update" - lines: "review metadata packaging" - content_spec: > - Accept the capability-execution envelope and persist it under - control metadata in the review message outbox entry. - - file: "../sourcey.com/.runx/tools/docs/package_outreach/src/index.ts" - action: "update" - lines: "review metadata packaging" - content_spec: > - Persist the same normalized request contract for outreach review - and outbound message artifacts. - acceptance_criteria: - - id: "ac3_1" - type: "test" - command: "npm test" - description: "Sourcey tool and runtime tests pass with the new envelope path." - - id: "ac3_2" - type: "command" - command: "npm exec runx -- outreach --runner status --issue sourcey/sourcey.com#issue/3 --json" - description: "The installed CLI can still recover current control state and return normalized execution metadata." - - - id: "phase4" - name: "Document the model" - objective: "Make the intended extension shape explicit." - dependencies: - - "phase3" - changes: - - file: "README.md" - action: "update" - lines: "capability-pack guidance" - content_spec: > - Explain that transports trigger capabilities through the same - generic envelope while threads remain the review/control surface. - - file: "../sourcey.com/README.md" - action: "update" - lines: "outreach operations" - content_spec: > - Explain that `outreach` is a local capability, the GitHub issue is - context, and CLI/API/GitHub triggers should all normalize into the - same request contract. - - file: "../sourcey.com/skills/outreach/SKILL.md" - action: "update" - lines: "operator guidance" - content_spec: > - Clarify that the runner examples are one transport over the same - underlying capability execution model. - acceptance_criteria: - - id: "ac4_1" - type: "documentation" - description: "The docs explain the capability / transport / thread split without implying a public Sourcey CLI." diff --git a/.ai/specs/archive/2026-04/runx-claim-via-github-app.yaml b/.ai/specs/archive/2026-04/runx-claim-via-github-app.yaml deleted file mode 100644 index 1ac5d7d74..000000000 --- a/.ai/specs/archive/2026-04/runx-claim-via-github-app.yaml +++ /dev/null @@ -1,462 +0,0 @@ -spec_version: "1.1" -task_id: "runx-claim-via-github-app" -created: "2026-04-26T11:17:33Z" -updated: "2026-04-26T14:58:57Z" -status: "completed" -harden_status: "ready_for_implementation" - -task: - title: "Claim via GitHub App: paste URL first, verify and sync second" - summary: > - The Nango claim flow proves repo permission and upgrades an existing - URL-published listing, but it does not install repository webhooks. The - follow-on GitHub App flow should make the clean path one input: paste a - GitHub URL, ensure the listing exists at community tier, install or select - the exact repo through the GitHub App, verify the installation has access - to that repo, promote snapshot-matched listings to verified, and use - GitHub App webhooks for future push/tag/delete sync. The browser must not - long-poll and the backend must not persist installation access tokens. - size: "large" - risk_level: "high" - context: - packages: - - "../cloud/packages/api" - - "../cloud/packages/ui" - - "../cloud/apps/web" - - "packages/contracts" - files_impacted: - - path: "../cloud/packages/api/src/github-app-claim-model.ts" - lines: "all" - reason: "Durable state for GitHub App claim/install sessions." - - path: "../cloud/packages/api/src/github-app-client.ts" - lines: "all" - reason: "GitHub App JWT, installation token exchange, repo access verification, and webhook signature helpers." - - path: "../cloud/packages/api/src/github-app-claim-service.ts" - lines: "all" - reason: "Orchestrates URL-first start, installation finalize, promotion, repo binding, and sync handoff." - - path: "../cloud/packages/api/src/claim-routes.ts" - lines: "all" - reason: "Adds GitHub App claim session routes next to the existing Nango session routes." - - path: "../cloud/packages/api/src/self-publish-routes.ts" - lines: "webhook routes" - reason: "Adds a GitHub App webhook route that verifies GitHub signatures and event types." - - path: "../cloud/packages/api/src/self-publish-model.ts" - lines: "SelfPublishEnrollmentRecord" - reason: "Persists successful installation binding metadata, not pending install state." - - path: "../cloud/packages/api/src/server-config.ts" - lines: "GitHub App config" - reason: "Reads app id, app slug, private key, webhook secret, and public callback URL settings." - - path: "../cloud/packages/api/src/server.ts" - lines: "service construction" - reason: "Wires GitHub App client, claim service, stores, routes, and webhook handling." - - path: "../cloud/packages/ui/src/ClaimAction" - lines: "all" - reason: "Replaces OAuth-first claim UI with URL/listing-first GitHub App claim flow." - - path: "../cloud/apps/web/src/pages/x/claim/index.astro" - lines: "all" - reason: "Allows claim start from either a GitHub URL or existing owner/name query params." - - path: "../cloud/apps/web/src/pages/api/claim" - lines: "all" - reason: "Adds web proxies for GitHub App start/finalize/status routes if the web app continues proxying API calls." - - path: "packages/contracts/src/openapi-public.ts" - lines: "claim schemas" - reason: "Documents the public GitHub App claim route request/response envelopes." - invariants: - - "URL-publish stays anonymous and immediate; claim remains an optional trust upgrade." - - "A GitHub App installation id is not proof by itself. The backend must verify the installation includes the exact source repo." - - "Successful repo bindings live in SelfPublishEnrollmentStore. Pending, rejected, and expired install sessions do not." - - "No raw GitHub OAuth token or GitHub App installation access token is persisted." - - "Future sync is keyed by repo_full_name plus installation_id and never downgrades verified or first_party listings." - - "Nango claim remains valid during migration; this spec adds a cleaner GitHub App path instead of breaking existing sessions." - - "Nango/provider implementation details are never surfaced in browser code, package dependencies, public integration docs links, or frontend-visible URLs." - related_docs: - - ".ai/specs/approved/runx-claim-via-nango.yaml" - - ".ai/specs/active/runx-url-as-publish.yaml" - - "../cloud/packages/api/src/claim-service.ts" - - "../cloud/packages/api/src/self-publish-service.ts" - - "../cloud/apps/web/src/pages/x/claim/index.astro" - cwd: "." - objectives: - - "Make claim start from a GitHub URL or existing listing target, with no OAuth prerequisite." - - "Use GitHub App installation as the durable repo sync authority." - - "Verify exact repo access before promotion or webhook binding." - - "Promote only snapshot-matched community versions and preserve first_party/verified tiers." - - "Replace manual/shared-secret GitHub webhook assumptions with GitHub App signed webhooks for claimed repos." - - "Keep Nango claim routes and data compatible until the UI switch is explicitly complete." - scope: - in_scope: - - "GitHub App claim session model, store, routes, service, and tests." - - "GitHub App client for JWT signing, installation token exchange, installation repo verification, and webhook signature verification." - - "URL-first /x/claim UX and one-shot finalize after GitHub redirects back with installation_id/setup_action/state." - - "SelfPublishEnrollment metadata for successful GitHub App bindings." - - "GitHub App webhook ingestion for push, create/tag, repository deleted, installation suspended/deleted, and installation_repositories changes." - - "OpenAPI public schemas for the GitHub App claim route family." - out_of_scope: - - "Private repository indexing." - - "Claim dispute/revocation UI beyond automatic installation removal/suspension handling." - - "Replacing Nango principal-bound connect flows." - - "Multi-repo bulk install onboarding." - - "Hosted operator moderation dashboards." - decisions: - - "Use a separate GitHubAppClaimSessionStore instead of forcing GitHub App sessions into Nango-specific ClaimSessionRecord fields." - - "Build the install URL with a server-generated `state`/request_id and configured app slug; never trust a browser-supplied installation_id without matching a pending session." - - "The start route accepts `repo_url` and optional owner/name. If the listing is missing, it runs the existing URL-publish/index path first and returns the resulting listing target plus install URL." - - "Finalize is one-shot. The browser calls finalize once after GitHub redirects back. Pending responses show a manual retry button, not polling." - - "Installation access tokens are short-lived runtime credentials. They may be used to verify repo access and sync immediately, but are never written to session or enrollment records." - - "The successful enrollment stores installation_id, app_account_login, app_account_type, repo_full_name, active listing id/version, and claim session id." - - "GitHub App webhooks use GitHub's X-Hub-Signature-256 with a distinct app webhook secret. Do not reuse the Nango webhook secret or legacy self-publish shared secret." - - "If the GitHub App is already installed on the exact repo, start may verify and promote immediately instead of redirecting the user through another install screen." - - "Installation removal, suspension, or repo-access removal disables sync for the matching binding; only repository deletion tombstones registry versions." - - "Keep raw provider docs/logo metadata internally, but strip vendor-hosted docs links from public payloads and serve vendor-hosted logos through runx-owned URLs." - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "POST /v1/claim/github-app/sessions accepts a GitHub repo URL, ensures a community listing exists when possible, persists a pending app claim session, and returns install_url plus request_id." - status: "done" - - id: "dod2" - description: "Finalize rejects missing, mismatched, expired, or wrong-repo installation callbacks without promoting registry records." - status: "done" - - id: "dod3" - description: "Finalize verifies the installation includes the exact listing source repo, promotes snapshot-matched versions to verified, and writes a successful SelfPublishEnrollment binding with installation metadata." - status: "done" - - id: "dod4" - description: "GitHub App webhooks reindex push/tag events for bound repos and tombstone repository.deleted or installation removal events." - status: "done" - - id: "dod5" - description: "/x/claim supports a single GitHub URL input and existing owner/name links, then performs exactly one finalize request after the GitHub install callback." - status: "done" - - id: "dod6" - description: "No code path stores raw GitHub OAuth tokens or GitHub App installation access tokens." - status: "done" - - id: "dod7" - description: "Frontend packages and web routes contain no Nango references; public integration logos resolve through runx-owned URLs, and vendor docs links are not exposed." - status: "done" - validation: - - id: "v1" - type: "test" - description: "GitHub App claim service tests cover URL-first start, finalize success, wrong installation, wrong repo, expiry, idempotency, and no-downgrade behavior." - command: "cd ../cloud && pnpm exec vitest run packages/api/src/github-app-claim-service.test.ts" - expected: "exit code 0" - - id: "v2" - type: "test" - description: "GitHub App client tests cover JWT signing seam, installation token exchange, repo selection verification, and webhook signature verification." - command: "cd ../cloud && pnpm exec vitest run packages/api/src/github-app-client.test.ts" - expected: "exit code 0" - - id: "v3" - type: "test" - description: "Route tests cover start/status/finalize envelopes and GitHub App webhook event handling." - command: "cd ../cloud && pnpm exec vitest run packages/api/src/claim-routes.test.ts packages/api/src/self-publish-routes.test.ts" - expected: "exit code 0" - - id: "v4" - type: "test" - description: "Claim UI tests cover URL input, install redirect, callback finalize, terminal states, and no polling loops." - command: "cd ../cloud && pnpm exec vitest run packages/ui/src/ClaimAction/ClaimAction.test.tsx" - expected: "exit code 0" - - id: "v5" - type: "boundary" - description: "No persisted token fields are introduced in claim or enrollment models." - command: "cd ../cloud && rg -n 'access_token|installation_token|github_token|Authorization.*github' packages/api/src/*claim* packages/api/src/self-publish-model.ts packages/api/src/github-app-client.ts" - expected: "Only runtime HTTP client/header code in github-app-client.ts may match." - - id: "v6" - type: "compile" - description: "Cloud and OSS builds stay green after public schema changes." - command: "cd ../cloud && pnpm build && cd ../oss && pnpm build" - expected: "exit code 0" - - id: "v7" - type: "boundary" - description: "Frontend code and package metadata do not mention Nango." - command: "cd ../cloud && ! rg -n 'Nango|nango|@nangohq' apps/web packages/ui" - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-26T11:17:33Z" - actor: "user" - summary: "Created a placeholder spec via scafld plan for GitHub App claim." - - timestamp: "2026-04-26T11:24:14Z" - actor: "agent" - summary: "Replaced the placeholder with a concrete GitHub App follow-on design aligned to the completed Nango claim architecture." - notes: > - The key correction is to keep pending app installation state separate - from successful repo bindings, verify exact repo access after GitHub - redirects back, and use app webhooks for ongoing sync rather than - treating OAuth permission as webhook installation. - - - timestamp: "2026-04-26T11:56:50Z" - actor: "cli" - summary: "Spec approved" - - timestamp: "2026-04-26T11:57:31Z" - actor: "cli" - summary: "Execution started" - - timestamp: "2026-04-26T14:58:57Z" - actor: "cli" - summary: "Spec completed" -phases: - - id: "phase1" - name: "Durable GitHub App claim sessions" - objective: "Capture URL-first app-install attempts without mixing pending state into successful repo bindings." - changes: - - file: "../cloud/packages/api/src/github-app-claim-model.ts" - action: "create" - content_spec: | - Define GitHubAppClaimSessionRecord: - request_id, state, owner?, name?, repo_url, repo_full_name, - skill_id?, status pending_install|installed|verified|rejected|expired|error, - installation_id?, app_account_login?, app_account_type?, - version_snapshot, created_at, updated_at, expires_at, completed_at?, - rejection_reason?. - request_id/state are generated server-side with cryptographic entropy. - - file: "../cloud/packages/api/src/github-app-claim-stores.ts" - action: "create" - content_spec: | - Add file and in-memory stores with get, put, list, - findByState, findByInstallationId, findActiveByRepo, and pruneExpired. - File writes are atomic one-record-per-session JSON writes. - - file: "../cloud/packages/api/src/self-publish-model.ts" - action: "update" - content_spec: | - Add successful binding metadata only: - github_app_claim_session_id?, github_app_installation_id?, - github_app_account_login?, github_app_account_type?. - Add `sync_disabled` status plus disabled timestamp/reason for app - access removal without tombstoning still-visible listings. - Do not add pending/rejected GitHub App statuses to SelfPublishEnrollmentRecord. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "GitHubAppClaimSessionStore round-trips pending, verified, rejected, expired, and error records." - - id: "ac1_2" - type: "boundary" - description: "SelfPublishEnrollmentRecord has only successful GitHub App binding metadata, not pending app session fields." - status: "completed" - - - id: "phase2" - name: "GitHub App client and config" - objective: "Use app installation authority without persisting short-lived installation tokens." - dependencies: - - "phase1" - changes: - - file: "../cloud/packages/api/src/server-config.ts" - action: "update" - content_spec: | - Read RUNX_GITHUB_APP_ID, RUNX_GITHUB_APP_SLUG, - RUNX_GITHUB_APP_PRIVATE_KEY or *_FILE, RUNX_GITHUB_APP_WEBHOOK_SECRET, - RUNX_GITHUB_APP_CALLBACK_URL?, and RUNX_GITHUB_API_BASE_URL?. - Require app id, slug, private key, and webhook secret when the app - claim route is enabled. - - file: "../cloud/packages/api/src/github-app-client.ts" - action: "create" - content_spec: | - Export GitHubAppClient: - buildInstallUrl({ state, repoFullName? }) - createAppJwt() - createInstallationAccessToken(installationId) - getInstallation(installationId) - listInstallationRepos(installationId) - installationHasRepo(installationId, repoFullName) - verifyWebhookSignature(secret, rawBody, signature) - Do not expose or persist installation access tokens outside runtime calls. - acceptance_criteria: - - id: "ac2_1" - type: "test" - description: "Install URL includes configured app slug and server state." - - id: "ac2_2" - type: "test" - description: "Repo verification rejects installations that do not include the exact source repo." - - id: "ac2_3" - type: "test" - description: "Webhook signature verification accepts valid X-Hub-Signature-256 and rejects invalid signatures." - status: "completed" - - - id: "phase3" - name: "GitHub App claim service" - objective: "Start from URL/listing, finalize installation, promote verified listings, and write repo bindings." - dependencies: - - "phase1" - - "phase2" - changes: - - file: "../cloud/packages/api/src/github-app-claim-service.ts" - action: "create" - content_spec: | - start({ repo_url, owner?, name? }): - - Normalize GitHub URL to repo_full_name and optional ref. - - If owner/name is absent or listing is missing, call existing - URL-publish indexing for the repo URL and choose the matching - listing target when exactly one listing is produced. - - Snapshot current versions for the target listing. - - If the GitHub App is already installed on the exact repo, - verify repo access and promote immediately without returning - an install redirect. - - Persist pending session before returning install_url. - - finalize({ request_id, state, installation_id, setup_action }): - - Resolve by state/request_id and reject mismatch. - - Expire stale sessions. - - Verify setup_action is usable and installation includes repo_full_name. - - Promote snapshot-matched community versions to verified while - preserving verified and first_party. - - Write/update SelfPublishEnrollment with GitHub App installation metadata. - - Optionally run immediate self-publish reindex through installation authority. - - Mark verified/rejected/error idempotently. - acceptance_criteria: - - id: "ac3_1" - type: "test" - description: "Start indexes a missing URL-published listing before returning an install URL." - - id: "ac3_1b" - type: "test" - description: "Start fast-paths already-installed repos to verified without returning an install URL." - - id: "ac3_2" - type: "test" - description: "Finalize promotes only snapshot-matched versions and writes installation metadata." - - id: "ac3_3" - type: "test" - description: "Wrong repo, wrong state, expired session, and deleted/suspended installation paths reject without registry mutation." - - id: "ac3_4" - type: "test" - description: "Finalize is idempotent if GitHub redirects or the browser retries." - status: "completed" - - - id: "phase4" - name: "Routes, OpenAPI, and web proxies" - objective: "Expose the app claim lifecycle without breaking existing Nango claim sessions." - dependencies: - - "phase3" - changes: - - file: "../cloud/packages/api/src/claim-routes.ts" - action: "update" - content_spec: | - Add: - POST /v1/claim/github-app/sessions - GET /v1/claim/github-app/sessions/:request_id - POST /v1/claim/github-app/sessions/:request_id/finalize - Keep /v1/claim/sessions Nango routes intact during migration. - - file: "../cloud/packages/api/src/openapi-route-catalog.ts" - action: "update" - content_spec: "Add GitHub App claim route entries and examples." - - file: "packages/contracts/src/openapi-public.ts" - action: "update" - content_spec: "Add public GitHub App claim request/status envelope schemas." - - file: "../cloud/apps/web/src/pages/api/claim/github-app" - action: "create" - content_spec: "Proxy start/status/finalize requests if web continues to isolate browser clients from the API origin." - acceptance_criteria: - - id: "ac4_1" - type: "test" - description: "Route tests return 201 for start, terminal status for verified/rejected, and clear 409/404/503 envelopes." - - id: "ac4_2" - type: "test" - description: "Existing Nango claim route tests still pass." - status: "completed" - - - id: "phase5" - name: "GitHub App webhooks for repo sync" - objective: "Let successful app bindings drive future push/tag/delete updates." - dependencies: - - "phase3" - changes: - - file: "../cloud/packages/api/src/self-publish-routes.ts" - action: "update" - content_spec: | - Add a GitHub App webhook route that reads X-GitHub-Event, verifies - X-Hub-Signature-256 with RUNX_GITHUB_APP_WEBHOOK_SECRET, extracts - installation.id and repository.full_name, and forwards normalized - push/tag/delete/install-repository events to SelfPublishService. - - file: "../cloud/packages/api/src/self-publish-service.ts" - action: "update" - content_spec: | - Add handling for GitHub App installation metadata. Reindex only - enrollments whose repo_full_name and installation_id match. Treat - installation removed/suspended or repository access removed as - sync_disabled, and tombstone only when the repository itself is - deleted. - acceptance_criteria: - - id: "ac5_1" - type: "test" - description: "Push/tag webhooks reindex bound repos and preserve verified trust tier." - - id: "ac5_2" - type: "test" - description: "Repository deleted tombstones the matching binding only; installation/repo access removal marks only the matching binding sync_disabled." - - id: "ac5_3" - type: "boundary" - description: "Legacy shared-secret webhook route remains isolated from GitHub App webhook handling." - status: "completed" - - - id: "phase6" - name: "URL-first /x/claim UX" - objective: "Make the primary user path paste URL -> install app -> verified/synced." - dependencies: - - "phase4" - changes: - - file: "../cloud/packages/ui/src/ClaimAction/ClaimAction.tsx" - action: "update" - content_spec: | - Support repo_url input and owner/name prefill. On start, render the - install_url returned by the API and navigate or open it. On callback, - make exactly one finalize request. Pending state shows a manual retry - button. Already-verified start responses render success immediately. - No setInterval, recursive timeout, or long-poll request. - - file: "../cloud/apps/web/src/pages/x/claim/index.astro" - action: "update" - content_spec: | - Render a URL-first claim panel even without owner/name query params. - Preserve existing owner/name links from /x/add by pre-populating the - listing target and source repo if available. - acceptance_criteria: - - id: "ac6_1" - type: "test" - description: "/x/claim renders a single URL input when no target query params exist." - - id: "ac6_2" - type: "test" - description: "Callback finalize runs once and then renders verified/rejected/pending_manual_retry." - - id: "ac6_3" - type: "boundary" - description: "ClaimAction contains no polling loop." - command: "cd ../cloud && ! rg -n 'setInterval|setTimeout|while \\(|/await' packages/ui/src/ClaimAction apps/web/src/pages/api/claim" - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git -C /home/kam/dev/runx/cloud rm packages/api/src/github-app-claim-{model,stores}.ts && git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/api/src/self-publish-model.ts" - phase2: "git -C /home/kam/dev/runx/cloud rm packages/api/src/github-app-client.ts && git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/api/src/server-config.ts" - phase3: "git -C /home/kam/dev/runx/cloud rm packages/api/src/github-app-claim-service.ts" - phase4: "git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/api/src/claim-routes.ts packages/api/src/openapi-route-catalog.ts apps/web/src/pages/api/claim && git -C /home/kam/dev/runx/oss checkout HEAD -- packages/contracts/src/openapi-public.ts" - phase5: "git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/api/src/self-publish-routes.ts packages/api/src/self-publish-service.ts" - phase6: "git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/ui/src/ClaimAction apps/web/src/pages/x/claim/index.astro" - -review: - timestamp: "2026-04-26T14:58:28Z" - verdict: "pass" - review_rounds: 3 - reviewer_mode: "executor" - reviewer_session: "" - round_status: "completed" - override_applied: false - override_reason: null - override_confirmed_at: null - reviewed_head: "56090c44573848cc4ca1a70b13fbc8decde5e6ff" - reviewed_dirty: false - reviewed_diff: "bd3e625c9ea6d5e075b10911e42031bcb0c64e28fa9bda9c040f81b5b2a5ebf1" - passes: - - id: spec_compliance - result: "pass" - - id: scope_drift - result: "pass" - - id: regression_hunt - result: "pass" - - id: convention_check - result: "pass" - - id: dark_patterns - result: "pass" - blocking_count: 0 - non_blocking_count: 0 -metadata: - estimated_effort_hours: 10 - ai_model: "gpt-5" - tags: - - "claim" - - "github-app" - - "url-publish" - - "self-publish" - - "webhooks" diff --git a/.ai/specs/archive/2026-04/runx-claim-via-nango.yaml b/.ai/specs/archive/2026-04/runx-claim-via-nango.yaml deleted file mode 100644 index 200d97521..000000000 --- a/.ai/specs/archive/2026-04/runx-claim-via-nango.yaml +++ /dev/null @@ -1,686 +0,0 @@ -spec_version: "1.1" -task_id: "runx-claim-via-nango" -created: "2026-04-26T00:00:00Z" -updated: "2026-04-26T09:00:00Z" -status: "completed" - -task: - title: "Claim via Nango: durable GitHub repo ownership proof" - summary: > - URL-as-publish lands every listing at `community` tier. Promotion to - `verified` requires proof that the connected GitHub actor can maintain the - source repo for the exact listing being claimed. The architecture is durable - and webhook-driven: runx creates a persisted claim session, returns a Nango - Connect session token, the browser opens Nango Connect UI, and a single - finalize call reconciles the finished connection. Nango's signed auth - webhook performs the same completion path idempotently. There is no - long-poll route, no in-process promise resolver, no client polling loop, and - no single-replica deployment constraint. - - size: "large" - risk_level: "medium" - - context: - packages: - - "cloud/packages/api/src" - - "cloud/packages/auth/src" - - "cloud/apps/web/src" - - "cloud/packages/ui/src" - - "oss/packages/contracts/src" - files_impacted: - - path: "cloud/packages/api/src/claim-session-model.ts" - lines: "all" - reason: "New durable claim-session model. Pending/rejected state lives here, not in self-publish enrollments." - - path: "cloud/packages/api/src/claim-session-stores.ts" - lines: "all" - reason: "New file + in-memory stores keyed by request_id and runx_flow_id." - - path: "cloud/packages/api/src/self-publish-model.ts" - lines: "SelfPublishEnrollmentRecord" - reason: "Only successful repo bindings need claim metadata: claim_session_id, connection_id, github_user, github_permission. Do not model pending/rejected claim sessions here." - - path: "cloud/packages/api/src/self-publish-helpers.ts" - lines: "normalizeEnrollment" - reason: "Round-trip successful-claim metadata only." - - path: "cloud/packages/api/src/self-publish-stores.ts" - lines: "FileSelfPublishStore + InMemorySelfPublishStore" - reason: "Keep findByRepo for webhook reindex; add optional findByClaimSessionId if useful. No pending-session lookup here." - - path: "cloud/packages/api/src/github-identity.ts" - lines: "all" - reason: "New module. Fetch GitHub user and verify repo-level permissions through Nango proxy." - - path: "cloud/packages/auth/src/nango-hosted.ts" - lines: "HostedNangoClient" - reason: "Add official Connect-session token support, list-connections by endUserId, proxyGet via GET /proxy/{path}, dual webhook signature header support, and remove webhookSecret fallback." - - path: "cloud/packages/api/src/claim-service.ts" - lines: "all" - reason: "New orchestration service for start, finalize, webhook completion, permission verification, and tier promotion." - - path: "cloud/packages/api/src/claim-routes.ts" - lines: "all" - reason: "New routes: POST /v1/claim/sessions, GET /v1/claim/sessions/:request_id, POST /v1/claim/sessions/:request_id/finalize." - - path: "cloud/packages/api/src/rate-limit.ts" - lines: "factory" - reason: "Add claim-session rate limiters. Do not single-flight anonymous sessions by listing." - - path: "cloud/packages/api/src/self-publish-routes.ts" - lines: "remove /v1/claim block" - reason: "Delete the 503 stub. The only claim surface is /v1/claim/sessions." - - path: "cloud/packages/api/src/openapi-route-catalog.ts" - lines: "/v1/claim removed; claim-session entries added" - reason: "Catalog must match the live route surface." - - path: "oss/packages/contracts/src/openapi-public.ts" - lines: "ClaimRequest schema removed; claim-session schemas added" - reason: "Public OpenAPI follows the new route surface." - - path: "cloud/packages/api/src/index.ts" - lines: "HostedApiOptions + route registration" - reason: "Register claim routes and pass ClaimService into the hosted API app." - - path: "cloud/packages/api/src/server.ts" - lines: "service construction + webhook wiring" - reason: "Construct ClaimSessionStore, GithubIdentityClient, ClaimService; inject claim completion into the Nango webhook handler." - - path: "cloud/packages/api/src/server-config.ts" - lines: "RUNX_PUBLIC_BASE_URL + Nango webhook validation" - reason: "Expose app base URL and require a distinct Nango webhook secret when Nango mode is enabled." - - path: "cloud/packages/api/src/skill-indexer.ts" - lines: "indexValidatedCandidate trust tier" - reason: "URL-publish inherits an existing trust_tier for the same source; first publish still defaults to community." - - path: "cloud/packages/api/src/self-publish-service.ts" - lines: "delete claimListing method" - reason: "Remove the pre-OAuth promotion foot-gun." - - path: "cloud/packages/api/src/self-publish-service.test.ts" - lines: "claimListing tests" - reason: "Delete or replace tests that exercise the removed unsafe method." - - path: "cloud/apps/web/src/pages/x/claim.astro" - lines: "delete file" - reason: "Remove duplicate Astro route; /x/claim/index.astro is canonical." - - path: "cloud/apps/web/src/pages/api/claim.ts" - lines: "delete file" - reason: "Replace legacy proxy with /api/claim/sessions routes." - - path: "cloud/apps/web/src/pages/api/claim/sessions.ts" - lines: "all" - reason: "New Astro proxy for POST start claim." - - path: "cloud/apps/web/src/pages/api/claim/sessions/[request_id].ts" - lines: "all" - reason: "New Astro proxy for GET status and POST finalize. No await/long-poll endpoint." - - path: "cloud/packages/ui/src/ClaimAction/ClaimAction.tsx" - lines: "all" - reason: "Replace placeholder with Nango Connect UI state machine and one-shot finalize call." - - path: "cloud/packages/ui/package.json" - lines: "dependencies" - reason: "Add @nangohq/frontend if ClaimAction owns the Connect UI import." - - invariants: - - "No runx account is required. A claim session is a short-lived capability, not a user identity." - - "Pending/rejected claim state lives in ClaimSessionStore. SelfPublishEnrollmentStore records only successful repo bindings and tombstones." - - "No broad org-membership claim. A connected actor must have repo-level write, maintain, or admin permission on the exact source repo for the listing." - - "The browser never polls. ClaimAction opens Nango Connect UI and makes one finalize request when Nango reports a connect event. Manual retry is user-triggered only." - - "Nango signed webhooks and explicit finalize both call the same idempotent completion method." - - "No in-process resolver, no long-poll endpoint, no server-held browser request, no single-replica assumption." - - "GitHub identity and permission checks use Nango proxy. runx never reads or stores raw GitHub OAuth tokens." - - "Hard cutover on /v1/claim: the previous 503 stub is deleted, no alias, no redirect." - - "Claim never downgrades: verified and first_party versions remain at least as trusted as before." - - "Promotion is locked to the version-digest snapshot taken at startClaim. New versions URL-published during the pending window are not promoted by that claim." - - "A successful claim creates a repo binding for one (owner, name, source_repo) only. It does not authorize any other repo owned by the same actor." - - "OAuth-user connection does not auto-install GitHub webhooks. Existing GitHub webhook ingestion honors claimed repo bindings when events arrive; automatic repo webhook installation belongs to a GitHub App follow-on, not this OAuth claim flow." - - "Nango webhook signature verification uses an explicit webhook secret, never the API secret key fallback. Support both current local `x-nango-hmac-sha256` and Nango-documented `X-Nango-Signature` headers during migration." - - related_docs: - - "oss/.ai/specs/active/runx-url-as-publish.yaml" - - "cloud/packages/auth/src/nango-hosted.ts" - - "cloud/packages/auth/src/http.ts" - - "Nango docs: Connect sessions return a short-lived session token for frontend Connect UI." - - "Nango docs: auth webhooks carry connectionId and endUser identity for backend reconciliation." - - "Nango docs: proxy GET uses /proxy/{path} with Connection-Id and Provider-Config-Key headers." - - "GitHub docs: authenticated-user repos and collaborator permission APIs expose repo-level permissions." - - objectives: - - "Ship self-serve verified claims without creating runx accounts." - - "Use durable state and idempotent reconciliation instead of long-polling or in-memory promises." - - "Verify actual source-repo permission, not merely public org membership." - - "Persist the successful GitHub connection and repo binding for one listing." - - "Remove every unsafe legacy promotion path." - - scope: - in_scope: - - "Anonymous claim-session creation for an existing URL-published listing." - - "Nango Connect session-token flow using `end_user.id = claim:` and `allowed_integrations = [github integration id]`." - - "Webhook completion through the existing /webhooks/nango surface." - - "Finalize endpoint for one-shot browser reconciliation after Nango Connect UI emits a connect event." - - "GitHub user + repo permission verification via Nango proxy." - - "Tier promotion for snapshot-matched RegistrySkillVersion records." - - "Successful repo binding stored in SelfPublishEnrollmentStore for future GitHub webhook ingestion." - - "Per-IP and per-target claim-session rate limits." - - "URL-publish tier inheritance so verified listings are not downgraded by later URL-publish reindexes." - - "Tests for race ordering, idempotency, permission mismatch, duplicate concurrent valid claims, stale sessions, and no-poll UI behavior." - out_of_scope: - - "Public runx sign-up or long-lived runx user accounts." - - "CLI `runx connect github` changes beyond preserving current behavior." - - "Private-repo URL-publish." - - "Installing GitHub repo/org webhooks from OAuth user tokens." - - "GitHub App installation flow for automatic webhook delivery. Recommended follow-on for the cleanest repo-add experience." - - "Disputes, revocation UI, and operator demotion workflows." - - decisions: - - "Use a dedicated ClaimSessionStore. The previous draft overloaded SelfPublishEnrollment with pending/rejected states; that mixes UI workflow state with claimed-repo bindings and makes webhook code harder to reason about." - - "Do not single-flight anonymous sessions by (owner, name). Returning the same Nango token to another anonymous requester lets strangers interfere with an in-progress claim. Rate-limit instead; concurrent sessions are harmless because completion is idempotent and permission-gated." - - "Use Nango Connect UI session tokens, not a hand-built long-poll tab. The frontend SDK gives a connect event; backend webhooks remain the source of truth for the connection ID." - - "Finalize is one-shot reconciliation, not polling. It first returns terminal session state if already completed; otherwise it asks Nango for the newest connection for `endUserId = claim:` and completes if found." - - "Verification is repo-level. Accept GitHub permissions equivalent to write, maintain, or admin on the source repo. Reject read-only org membership." - - "Nango proxy implementation follows the documented GET `/proxy/{githubPath}` API with `Connection-Id` and `Provider-Config-Key` headers. The earlier POST `/proxy` body shape is not the target." - - "Keep OAuth scopes small for public-repo v1: `read:user`, `read:org`, and `public_repo` if required for repo permission reads. Private repo and webhook-management scopes are separate work." - - "A successful claim writes or updates one SelfPublishEnrollment for `repo_full_name`, with connection_id, github_user, github_permission, indexed_skill_id, and published_versions. Push/tag webhook reindex remains keyed by repo_full_name." - - "Nango webhook handling checks claim sessions before the existing principal-bound flow Map. Unknown claim flow IDs are 202-ignored." - - "Identity/permission failures mark the claim session rejected with a specific reason and leave registry trust tiers unchanged." - - "Nango/registry transient failures mark the claim session error and are safe to retry through finalize; webhook responses stay 2xx after durable recording to avoid unbounded retries." - - "Hard-delete `SelfPublishService.claimListing` and its tests. All promotion must flow through ClaimService." - - deliverables: - - "ClaimSession model and file/in-memory stores." - - "HostedNangoClient methods: createConnectSession, findConnectionsByEndUser, proxyGet, strict webhook secret handling." - - "GithubIdentityClient with repo-permission verification." - - "ClaimService start/finalize/complete lifecycle." - - "Claim HTTP routes and OpenAPI schemas." - - "Nango webhook branch for claim sessions." - - "ClaimAction using Nango Connect UI and one-shot finalize." - - "Deletion of /v1/claim, legacy /api/claim, duplicate /x/claim.astro, and unsafe claimListing." - - "Focused unit and integration tests." - - assumptions: - - "The configured Nango GitHub integration can create Connect sessions with an end_user.id and sends auth creation webhooks that include connectionId plus endUser or equivalent tags." - - "Nango connection listing can filter by endUserId; this is required for browser-triggered finalize when webhook delivery is slower than the UI event." - - "Nango proxy can call GitHub REST endpoints for `/user`, `/user/repos`, and/or `/repos/{owner}/{repo}/collaborators/{username}/permission` for the connected account." - - "GitHub public-repo claims can be verified without requesting private-repo `repo` scope. If GitHub requires broader scope for a specific permission endpoint, use the authenticated-user repos endpoint first and keep private-repo claim out of v1." - - "Existing GitHub webhook ingestion is already deployed for events that runx receives. This spec creates bindings that make those events trusted; it does not provision GitHub webhooks." - - risks: - - description: "Nango webhook is delayed or not delivered." - impact: "low" - mitigation: "ClaimAction's one finalize call reconciles by endUserId through Nango. If neither webhook nor list-connections sees a connection yet, the UI shows a manual retry button." - - description: "Connected GitHub user is a public org member but lacks repo write/admin permission." - impact: "expected rejection." - mitigation: "Session is rejected with a repo-permission reason; registry tiers stay unchanged." - - description: "Two valid maintainers claim the same listing concurrently." - impact: "low" - mitigation: "Both sessions may complete, but promotion is idempotent and the binding is updated to the latest successful connection. No downgrade is possible." - - description: "The OAuth connection does not install repository webhooks." - impact: "medium" - mitigation: "Spec states this boundary explicitly. Existing webhook ingestion works for delivered events; automatic webhook delivery moves to GitHub App installation work." - - description: "Nango API shape differs between local code and current docs." - impact: "medium" - mitigation: "Implement documented APIs for new claim code while preserving existing beginOauth behavior for /v1/connect. Tests cover both legacy connect_link and session-token paths where necessary." - - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "POST /v1/claim/sessions returns 201 with request_id, connect_session_token, expires_at, and persists a ClaimSession pending_connection." - - id: "dod2" - description: "No /v1/claim route remains; it returns framework 404." - - id: "dod3" - description: "Nango auth webhook for a claim session completes it idempotently and never touches principal-bound connect flows." - - id: "dod4" - description: "POST /v1/claim/sessions/:request_id/finalize completes a session when Nango already has a connection for endUserId claim:." - - id: "dod5" - description: "Repo-level write/maintain/admin permission promotes snapshot-matched versions to verified and writes a successful self-publish repo binding." - - id: "dod6" - description: "Read-only org membership or missing repo permission rejects the session and leaves trust tiers unchanged." - - id: "dod7" - description: "ClaimAction opens Nango Connect UI, makes exactly one finalize request after a connect event, and contains no setInterval, polling loop, or long-poll call." - - id: "dod8" - description: "URL-publish after a claim does not downgrade verified listings when publishing from the same source." - - id: "dod9" - description: "No code path reads or stores raw GitHub access tokens." - validation: - - id: "v1" - type: "test" - description: "Claim-session store tests cover lookup, expiration, rejection retention, and idempotent terminal updates." - command: "cd ../cloud && pnpm exec vitest run packages/api/src/claim-session-stores.test.ts" - expected: "All pass." - - id: "v2" - type: "test" - description: "Claim-service tests cover start, finalize, webhook completion, permission match, permission mismatch, duplicate valid claims, expired sessions, and URL-publish race." - command: "cd ../cloud && pnpm exec vitest run packages/api/src/claim-service.test.ts" - expected: "All pass." - - id: "v3" - type: "test" - description: "Nango-hosted tests cover createConnectSession token parsing, findConnectionsByEndUser, proxyGet GET headers, dual signature headers, and no webhookSecret fallback." - command: "cd ../cloud && pnpm exec vitest run packages/auth/src/nango-hosted.test.ts" - expected: "All pass." - - id: "v4" - type: "boundary" - description: "No in-process resolver or await route is implemented." - command: "cd ../cloud && rg -n 'ClaimResolver|/await|long-poll|setInterval|setTimeout\\(' packages/api/src/claim-* apps/web/src/pages/api/claim packages/ui/src/ClaimAction" - expected: "No matches." - - id: "v5" - type: "boundary" - description: "No raw GitHub token handling in claim code." - command: "cd ../cloud && rg -n 'access_token|github_token|Authorization.*github' packages/api/src/claim-* packages/api/src/github-identity.ts" - expected: "No matches." - - constraints: - approvals_required: - - "registry_invariants" - - "nango_proxy_permissions" - - "github_repo_permission_semantics" - non_goals: - - "Runx user accounts." - - "Automatic GitHub webhook installation." - - "Private-repo publishing." - - "Claim dispute or revocation UI." - - info_sources: - - "cloud/packages/auth/src/nango-hosted.ts" - - "cloud/packages/auth/src/http.ts" - - "cloud/packages/api/src/self-publish-service.ts" - - "cloud/packages/api/src/url-publish-service.ts" - - "Nango official docs: Connect session creation, frontend Connect UI, auth webhooks, list connections, proxy GET." - - "GitHub official docs: list repositories for authenticated user and repository collaborator permissions." - - notes: > - I do not agree with the previous in-memory resolver/long-poll shape. It was - workable for a single replica but not a clean architecture. The revised - shape treats claim completion as a durable state transition and uses both - webhook and browser finalize as idempotent ways to drive that transition. - It also tightens the authorization check from broad org membership to actual - source-repo permission. - -planning_log: - - timestamp: "2026-04-26T00:00:00Z" - actor: "agent" - summary: "Drafted initial Nango-backed claim spec after /v1/claim was left as a 503 stub." - - timestamp: "2026-04-26T01:00:00Z" - actor: "agent" - summary: "Earlier hardening pass moved away from redirect assumptions but still used an in-process resolver and long-poll." - - timestamp: "2026-04-26T03:00:00Z" - actor: "codex" - summary: "Reviewed the runx cloud and oss codebase with scafld status/validate. Replaced the long-poll/in-memory resolver design with durable ClaimSessionStore + Nango Connect UI session token + one-shot finalize + idempotent webhook completion. Tightened GitHub verification to repo-level permission and corrected Nango proxy API shape." - - timestamp: "2026-04-26T09:00:00Z" - actor: "codex" - summary: "Implemented the durable claim-session design across cloud and OSS contracts, verified focused claim/Nango tests, cloud fast/build, and OSS fast/build." - - - timestamp: "2026-04-26T08:57:26Z" - actor: "cli" - summary: "Spec approved" -phases: - - id: "phase1" - name: "Durable claim-session model" - objective: "Separate claim workflow state from successful self-publish repo bindings." - changes: - - file: "cloud/packages/api/src/claim-session-model.ts" - action: "create" - lines: "all" - content_spec: | - Define ClaimSessionRecord with: - request_id, runx_flow_id, nango_end_user_id, owner, name, skill_id, - repo_full_name, source_repo_owner, source_repo_name, - status enum pending_connection|verified|rejected|expired|error, - connect_session_token?, connection_id?, github_user?, - github_permission?, claim_reason?, version_snapshot, - created_at, updated_at, expires_at, completed_at?. - request_id and runx_flow_id are generated with crypto.randomUUID-derived - entropy. request_id is the browser capability. Do not make it guessable. - - file: "cloud/packages/api/src/claim-session-stores.ts" - action: "create" - lines: "all" - content_spec: | - Add FileClaimSessionStore and InMemoryClaimSessionStore with: - get(request_id), put(record), list(), findByRunxFlowId(flow_id), - findActiveByConnectionId(connection_id), pruneExpired(now). - File store writes one JSON file per request_id atomically. - - file: "cloud/packages/api/src/self-publish-model.ts" - action: "update" - lines: "SelfPublishEnrollmentRecord" - content_spec: | - Keep statuses to indexed|tombstoned for repo bindings. Add successful - claim metadata only if absent: claim_session_id?, connection_id?, - github_user?, github_permission?. Pending/rejected claim sessions do - not belong in SelfPublishEnrollmentRecord. - - file: "cloud/packages/api/src/self-publish-helpers.ts" - action: "update" - lines: "normalizeEnrollment" - content_spec: "Round-trip only successful claim metadata." - - file: "cloud/packages/api/src/self-publish-stores.ts" - action: "update" - lines: "stores" - content_spec: "Keep findByRepo. Optionally add findByClaimSessionId. Do not add pending-claim lookup methods here." - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "ClaimSessionStore round-trips pending, verified, rejected, expired, and error records." - - id: "ac1_2" - type: "test" - description: "SelfPublishEnrollment normalization does not expose pending_connection or claim_rejected statuses." - - id: "ac1_3" - type: "boundary" - description: "No pending claim lookup is implemented on SelfPublishStore." - status: "completed" - - - id: "phase2" - name: "Nango + GitHub permission clients" - objective: "Use official Nango surfaces and verify exact repo authority without raw tokens." - dependencies: ["phase1"] - changes: - - file: "cloud/packages/auth/src/nango-hosted.ts" - action: "update" - lines: "HostedNangoClient" - content_spec: | - Add createConnectSession(request) returning - { connectSessionToken, authorizationUrl?, expiresAt? }. Body uses: - end_user: { id: request.principalId, display_name, tags: - { runx_flow_id, runx_provider, runx_scopes, runx_claim_request_id? } }, - allowed_integrations: [providerConfigKey], - integrations_config_defaults for GitHub user scopes. - Preserve existing beginOauth/connect_link behavior for /v1/connect. - Add findConnectionsByEndUser(provider, endUserId) using Nango list - connections filtered by endUserId. - Add proxyGet(connectionId, provider, githubPath) using documented - GET ${baseUrl}/proxy/{githubPath} with Authorization, - Connection-Id, and Provider-Config-Key headers. - Remove webhookSecret fallback to secretKey. Constructor throws if - webhookSecret is absent in Nango mode. verifyWebhookSignature supports - both x-nango-hmac-sha256 and X-Nango-Signature during migration. - - file: "cloud/packages/api/src/github-identity.ts" - action: "create" - lines: "all" - content_spec: | - Export GithubIdentityClient with verifyRepoAuthority(connectionId, - repoFullName): Promise<{ user, permission, public_orgs? }>. - It fetches /user for login, then verifies permission for the exact - source repo. Prefer /repos/{owner}/{repo}/collaborators/{user}/permission - when available; otherwise use /user/repos with pagination and inspect - the matching repo's permissions. Accept admin, maintain, write, or - permissions.push/admin/maintain true. Reject read/triage/none. - acceptance_criteria: - - id: "ac2_1" - type: "test" - description: "createConnectSession sends end_user.id claim:, allowed_integrations, and GitHub scopes." - - id: "ac2_2" - type: "test" - description: "proxyGet uses GET /proxy/{path} with Connection-Id and Provider-Config-Key headers." - - id: "ac2_3" - type: "test" - description: "GithubIdentityClient accepts write/maintain/admin and rejects read-only org membership." - - id: "ac2_4" - type: "boundary" - description: "No access_token references in github-identity.ts." - command: "rg 'access_token' cloud/packages/api/src/github-identity.ts" - expected: "No matches." - status: "completed" - - - id: "phase3" - name: "ClaimService" - objective: "Start durable sessions and complete them idempotently from either webhook or finalize." - dependencies: ["phase1", "phase2"] - changes: - - file: "cloud/packages/api/src/claim-service.ts" - action: "create" - lines: "all" - content_spec: | - ClaimService constructor injects registryStore, claimSessionStore, - selfPublishStore, nangoClient, githubIdentity, publicBaseUrl, now, - ttlMs (default 10 minutes), rejectedRetentionMs (24h). - - startClaim({ owner, name }): - - Normalize owner/name. - - Load registryStore.listVersions(skill_id); 404 if absent. - - Require latest.source_metadata.repo; 409 if absent. - - Snapshot version+digest for all existing versions. - - Create request_id and runx_flow_id. - - Persist ClaimSessionRecord pending_connection before calling Nango. - - Call nangoClient.createConnectSession with principalId - `claim:${request_id}`, provider github, and public-repo identity scopes. - - Persist connect_session_token and Nango expires_at. - - Return request_id, connect_session_token, expires_at. - - No single-flight by listing. - - finalizeClaim(request_id): - - Return terminal state if session is verified/rejected/error/expired. - - If pending and expired, mark expired. - - If pending has connection_id, call completeClaimWithConnection. - - Otherwise call nangoClient.findConnectionsByEndUser("github", - `claim:${request_id}`); if none, return pending. - - Complete with the newest matching connection. - - completeClaimFromWebhook(event): - - Resolve claim by endUser.id / endUserId / tags.runx_claim_request_id - / tags.runx_flow_id before principal-bound connect flow lookup. - - If not a claim, return false. - - If success=false, mark rejected/error with Nango error details. - - If connectionId is present, call completeClaimWithConnection. - - Return true when handled. - - completeClaimWithConnection(session, connection_id): - - Idempotent for terminal sessions. - - Verify repo authority through GithubIdentityClient. - - On accepted permission, promote only snapshot-matched versions to - verified while preserving first_party, write/update one - SelfPublishEnrollment repo binding, mark session verified. - - On mismatch, mark session rejected and do not mutate registry. - - On transient Nango/GitHub errors from finalize, mark error only if - error is deterministic; otherwise keep pending and return retryable. - acceptance_criteria: - - id: "ac3_1" - type: "test" - description: "startClaim persists before creating Nango session and returns a token." - - id: "ac3_2" - type: "test" - description: "finalizeClaim completes when Nango list-connections returns a connection." - - id: "ac3_3" - type: "test" - description: "webhook completion and finalize are idempotent under every ordering." - - id: "ac3_4" - type: "test" - description: "valid repo permission promotes snapshot-matched versions and writes a successful repo binding." - - id: "ac3_5" - type: "test" - description: "read-only or missing repo permission rejects without promotion." - - id: "ac3_6" - type: "test" - description: "new URL-published version during pending window is not promoted by the old snapshot." - status: "completed" - - - id: "phase4" - name: "HTTP routes + webhook branch" - objective: "Expose durable sessions and wire Nango auth webhooks cleanly." - dependencies: ["phase3"] - changes: - - file: "cloud/packages/api/src/claim-routes.ts" - action: "create" - lines: "all" - content_spec: | - Add routes: - POST /v1/claim/sessions: - body { owner, name }, rate-limited by IP and target. - Returns 201 { status:"success", request_id, connect_session_token, - expires_at }. 404 listing missing, 409 unclaimable source, 429. - GET /v1/claim/sessions/:request_id: - status read only. Does not return connect_session_token. - POST /v1/claim/sessions/:request_id/finalize: - calls claimService.finalizeClaim and returns current/final state. - 202-style pending is represented as 200 { request_status:"pending_connection" } - to keep browser handling simple. - - file: "cloud/packages/api/src/rate-limit.ts" - action: "update" - lines: "factory" - content_spec: "Add createClaimSessionRateLimiters: per-IP and per-target budgets. Do not coalesce sessions globally." - - file: "cloud/packages/auth/src/nango-hosted.ts" - action: "update" - lines: "createNangoWebhookHandler" - content_spec: | - Add optional claimComplete callback. After signature verification and - parsing, before getFlow(flowId), pass the normalized auth webhook event - to claimComplete. If it returns true, respond 200. If false, fall - through to existing principal-bound connect behavior. - - file: "cloud/packages/api/src/index.ts" - action: "update" - lines: "HostedApiOptions + route registration" - content_spec: "Add claimService?: ClaimService and register claim routes." - - file: "cloud/packages/api/src/server.ts" - action: "update" - lines: "service construction + webhook wiring" - content_spec: | - Construct FileClaimSessionStore, GithubIdentityClient, ClaimService. - Call claimSessionStore.pruneExpired at boot. Wire claimComplete into - createNangoWebhookHandler. Keep connect-surface routing unchanged. - - file: "cloud/packages/api/src/self-publish-routes.ts" - action: "update" - lines: "remove /v1/claim" - content_spec: "Delete the app.post('/v1/claim') 503 stub." - - file: "cloud/packages/api/src/openapi-route-catalog.ts" - action: "update" - lines: "claim route catalog" - content_spec: "Remove /v1/claim. Add POST/GET/POST-finalize claim-session operations." - - file: "oss/packages/contracts/src/openapi-public.ts" - action: "update" - lines: "claim schemas" - content_spec: | - Replace ClaimRequest with ClaimSessionRequest, ClaimSessionEnvelope, - ClaimSessionStatusEnvelope. Status enum: - pending_connection|verified|rejected|expired|error. - - file: "cloud/packages/api/src/self-publish-service.ts" - action: "update" - lines: "claimListing" - content_spec: "Delete claimListing and now-unused imports." - - file: "cloud/packages/api/src/self-publish-service.test.ts" - action: "update" - lines: "claimListing tests" - content_spec: "Delete claimListing tests or replace with claim-service tests." - - file: "cloud/apps/web/src/pages/x/claim.astro" - action: "delete" - lines: "all" - content_spec: "Delete duplicate route." - - file: "cloud/apps/web/src/pages/api/claim.ts" - action: "delete" - lines: "all" - content_spec: "Delete legacy proxy." - acceptance_criteria: - - id: "ac4_1" - type: "test" - description: "POST /v1/claim/sessions persists a claim session and returns a token." - - id: "ac4_2" - type: "test" - description: "POST finalize returns terminal state if webhook completed first." - - id: "ac4_3" - type: "test" - description: "POST finalize completes if Nango has a connection and webhook has not arrived." - - id: "ac4_4" - type: "test" - description: "Claim webhook short-circuits before principal-bound getFlow; non-claim webhook falls through." - - id: "ac4_5" - type: "boundary" - description: "/v1/claim is a 404." - - id: "ac4_6" - type: "boundary" - description: "SelfPublishService.claimListing no longer exists." - command: "rg 'claimListing' cloud/packages/api/src cloud/tests" - expected: "No matches." - status: "completed" - - - id: "phase5" - name: "Web ClaimAction without polling" - objective: "Use Nango Connect UI events and one finalize request." - dependencies: ["phase4"] - changes: - - file: "cloud/apps/web/src/pages/api/claim/sessions.ts" - action: "create" - lines: "all" - content_spec: "POST proxy to upstream /v1/claim/sessions." - - file: "cloud/apps/web/src/pages/api/claim/sessions/[request_id].ts" - action: "create" - lines: "all" - content_spec: "GET proxies status. POST proxies finalize. No await route." - - file: "cloud/packages/ui/package.json" - action: "update" - lines: "dependencies" - content_spec: "Add @nangohq/frontend if ClaimAction imports it directly." - - file: "cloud/packages/ui/src/ClaimAction/ClaimAction.tsx" - action: "update" - lines: "all" - content_spec: | - State machine: - idle -> connecting -> connected_event -> finalizing -> verified|rejected|expired|error|pending_manual_retry. - On click, POST /api/claim/sessions. Instantiate Nango frontend SDK - with connect_session_token and open Connect UI for GitHub. - On Nango connect event, POST /api/claim/sessions/:request_id/finalize once. - On close/cancel, show retry. On finalize pending, show a manual "check - again" button that calls finalize once per click. No setInterval, no - recursive fetch, no long-poll. - - file: "cloud/apps/web/src/pages/x/claim/index.astro" - action: "update" - lines: "copy + ClaimAction props" - content_spec: | - Drop coming-soon copy. Explain that claim verifies repo maintainer - permission and creates a repo binding. Do not promise OAuth installs - GitHub webhooks. - acceptance_criteria: - - id: "ac5_1" - type: "test" - description: "ClaimAction starts a session and opens Nango Connect UI with the returned token." - - id: "ac5_2" - type: "test" - description: "A Nango connect event triggers exactly one finalize request." - - id: "ac5_3" - type: "test" - description: "Pending finalize renders manual retry without automatic retry." - - id: "ac5_4" - type: "boundary" - description: "No polling APIs or timers in ClaimAction." - command: "cd ../cloud && rg -n 'setInterval|setTimeout|/await|while \\(' packages/ui/src/ClaimAction apps/web/src/pages/api/claim" - expected: "No matches." - status: "completed" - - - id: "phase6" - name: "Integration tests + cleanup" - objective: "Prove the whole flow and remove unsafe leftovers." - dependencies: ["phase5"] - changes: - - file: "cloud/tests/claim-via-nango.test.ts" - action: "create" - lines: "all" - content_spec: | - Build a fake HostedNangoClient that creates connect session tokens, - lists connections by endUserId, and proxies GitHub responses. Cover: - - happy path via webhook; - - happy path via finalize before webhook; - - webhook before finalize; - - finalize before Nango connection exists returns pending; - - repo permission read-only rejection; - - public org membership alone rejected; - - duplicate valid concurrent sessions are idempotent; - - expired session cannot promote; - - URL-publish race promotes only snapshot versions; - - /v1/claim 404 and no claimListing method; - - existing /v1/connect Nango webhook flow still works. - - file: "cloud/packages/api/src/skill-indexer.ts" - action: "update" - lines: "trust tier inheritance" - content_spec: | - If context.trustTier is absent, get latest existing version for - skill_id and inherit trust_tier; otherwise default first publish to - community. URL-publish stops passing trustTier explicitly. Webhook - reindex may still pass trustTier explicitly. - acceptance_criteria: - - id: "ac6_1" - type: "test" - description: "End-to-end claim-via-nango integration suite passes." - - id: "ac6_2" - type: "test" - description: "Existing runx-connect Nango webhook tests still pass." - - id: "ac6_3" - type: "test" - description: "URL-publish preserves existing verified trust tier from same source." - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git rm cloud/packages/api/src/claim-session-{model,stores}.ts && git checkout HEAD -- cloud/packages/api/src/self-publish-{model,helpers,stores}.ts" - phase2: "git rm cloud/packages/api/src/github-identity.ts && git checkout HEAD -- cloud/packages/auth/src/nango-hosted.ts" - phase3: "git rm cloud/packages/api/src/claim-service.ts" - phase4: "git rm cloud/packages/api/src/claim-routes.ts && git checkout HEAD -- cloud/packages/api/src/index.ts cloud/packages/api/src/server.ts cloud/packages/api/src/server-config.ts cloud/packages/api/src/rate-limit.ts cloud/packages/api/src/self-publish-routes.ts cloud/packages/api/src/self-publish-service.ts cloud/packages/api/src/self-publish-service.test.ts cloud/packages/api/src/openapi-route-catalog.ts oss/packages/contracts/src/openapi-public.ts && git checkout HEAD -- cloud/apps/web/src/pages/x/claim.astro cloud/apps/web/src/pages/api/claim.ts" - phase5: "git rm -r cloud/apps/web/src/pages/api/claim/sessions.ts cloud/apps/web/src/pages/api/claim/sessions && git checkout HEAD -- cloud/packages/ui/package.json cloud/packages/ui/src/ClaimAction/ClaimAction.tsx cloud/apps/web/src/pages/x/claim/index.astro" - phase6: "git rm cloud/tests/claim-via-nango.test.ts && git checkout HEAD -- cloud/packages/api/src/skill-indexer.ts" - -metadata: - estimated_effort_hours: 16 - tags: - - "claim" - - "nango" - - "github" - - "trust-tier" - - "repo-permission" diff --git a/.ai/specs/archive/2026-04/runx-cli-command-modules.yaml b/.ai/specs/archive/2026-04/runx-cli-command-modules.yaml deleted file mode 100644 index cbde69f50..000000000 --- a/.ai/specs/archive/2026-04/runx-cli-command-modules.yaml +++ /dev/null @@ -1,171 +0,0 @@ -spec_version: "1.1" -task_id: "runx-cli-command-modules" -created: "2026-04-23T10:39:12Z" -updated: "2026-04-23T12:18:34Z" -status: "completed" -harden_status: "not_run" - -task: - title: "Split CLI command kernel into library handlers" - summary: > - oss/packages/cli/src/index.ts is still the biggest OSS entrypoint and mixes - parsing, dispatch, command execution, and rendering. Move the remaining - heavy command paths into library modules so the root index stays focused on - argv parsing and top-level dispatch while cloud or other entrypoints can - reuse command logic without re-implementing it. - size: "medium" - risk_level: "medium" - context: - packages: - - "packages/cli" - - "packages/contracts" - files_impacted: - - path: "packages/cli/src/index.ts" - lines: "dispatch, doctor/dev/list/history/inspect rendering, command execution" - reason: "Reduce index.ts to parse, dispatch, and thin wiring" - - path: "packages/cli/src/commands" - lines: "all" - reason: "New command modules for remaining heavy commands" - - path: "packages/cli/src/command-*.ts" - lines: "all" - reason: "Shared command context and rendering helpers if needed" - - path: "packages/cli/src/index.test.ts" - lines: "doctor/dev/list command coverage" - reason: "Keep behavior stable while moving handlers" - invariants: - - "CLI output contracts stay unchanged" - - "Argument parsing remains centralized" - - "Command handlers remain callable as library code" - objectives: - - "Extract heavy command handlers out of index.ts into command modules" - - "Extract matching renderers so command behavior and presentation stay colocated" - - "Leave index.ts as argv parsing, command selection, and thin dispatch" - touchpoints: - - area: "packages/cli/src/index.ts" - description: "Current monolithic parse, dispatch, and render entrypoint" - - area: "packages/cli/src/commands" - description: "Target library boundary for reusable command handlers" - - area: "cloud/packages/api" - description: "Longer-term consumer of extracted command logic" - acceptance: - definition_of_done: - - id: "dod1" - description: "doctor and dev command execution live outside packages/cli/src/index.ts" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod2" - description: "Major CLI renderers for extracted commands live outside packages/cli/src/index.ts" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod3" - description: "packages/cli/src/index.ts stays below 4000 lines" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - validation: - - id: "v1" - type: "compile" - description: "OSS workspace typechecks after command extraction" - command: "pnpm typecheck" - expected: "exit code 0" - - id: "v2" - type: "test" - description: "CLI command coverage remains green" - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - expected: "exit code 0" - - id: "v3" - type: "boundary" - description: "CLI root file budget drops under the target threshold" - command: "test $(wc -l < packages/cli/src/index.ts) -lt 4000" - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-23T10:39:12Z" - actor: "user" - summary: "Spec created via scafld new" - - timestamp: "2026-04-23T10:45:00Z" - actor: "agent" - summary: "Scoped the remaining CLI monolith to command extraction and renderer colocation." - - timestamp: "2026-04-23T12:18:34Z" - actor: "agent" - summary: "Extracted doctor, dev, tool, and UI command surfaces; CLI root now stays focused on dispatch and budgeted below 4000 lines." - -phases: - - id: "phase1" - name: "Extract doctor and dev command modules" - objective: "Move the heaviest command logic out of index.ts first." - changes: - - file: "packages/cli/src/index.ts" - action: "update" - lines: "command dispatch and extracted render/handler functions" - content_spec: | - Replace in-file doctor/dev handler bodies with imports from command - modules and keep only thin dispatch wiring. - - file: "packages/cli/src/commands/doctor.ts" - action: "create" - lines: "all" - content_spec: | - Own doctor command execution, diagnostics, and doctor-specific - rendering helpers. - - file: "packages/cli/src/commands/dev.ts" - action: "create" - lines: "all" - content_spec: | - Own dev command execution, fixture helpers, and dev-specific rendering - helpers. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "CLI doctor and dev coverage stays green" - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - expected: "exit code 0" - status: "completed" - - - id: "phase2" - name: "Extract remaining command rendering surfaces" - objective: "Move list/history/inspect and related renderer weight out of index.ts." - dependencies: - - "phase1" - changes: - - file: "packages/cli/src/index.ts" - action: "update" - lines: "renderListResult, renderHistory, renderReceiptInspection, related helpers" - content_spec: | - Remove remaining extracted renderers from the root file and keep only - imports plus top-level command selection. - - file: "packages/cli/src/commands/list.ts" - action: "update" - lines: "all" - content_spec: | - Expand the existing list module to own list rendering and detail - formatting. - - file: "packages/cli/src/commands/history.ts" - action: "create" - lines: "all" - content_spec: | - Own history and receipt inspection rendering helpers. - acceptance_criteria: - - id: "ac2_1" - type: "boundary" - description: "CLI root file shrinks under 4000 lines" - command: "test $(wc -l < packages/cli/src/index.ts) -lt 4000" - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- packages/cli/src/index.ts packages/cli/src/commands/doctor.ts packages/cli/src/commands/dev.ts" - phase2: "git checkout HEAD -- packages/cli/src/index.ts packages/cli/src/commands/list.ts packages/cli/src/commands/history.ts" - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 2 - validation_depth: 1 - total: 9 - notes: "The CLI command kernel is materially split and the root file budget is met; compile verification passed." - second_pass_performed: true - -deviations: - - description: "The targeted CLI vitest acceptance command was not rerun before completion." - reason: "User explicitly prioritized continuing the refactor over additional test execution." diff --git a/.ai/specs/archive/2026-04/runx-cli-kernel-final-split.yaml b/.ai/specs/archive/2026-04/runx-cli-kernel-final-split.yaml deleted file mode 100644 index b970c11d6..000000000 --- a/.ai/specs/archive/2026-04/runx-cli-kernel-final-split.yaml +++ /dev/null @@ -1,225 +0,0 @@ -spec_version: "1.1" -task_id: "runx-cli-kernel-final-split" -created: "2026-04-24T00:25:00Z" -updated: "2026-04-23T15:27:08Z" -status: "completed" - -task: - title: "Finish the CLI kernel split into library command handlers" - summary: > - packages/cli/src/index.ts is materially smaller than before, but it still - owns too much command-specific behavior. Finish the split so the root file - is parse-and-dispatch only, while command modules own execution and - rendering in reusable library form. - size: "medium" - risk_level: "medium" - context: - packages: - - "packages/cli" - - "packages/contracts" - - "../cloud/packages/api" - files_impacted: - - path: "packages/cli/src/index.ts" - lines: "all" - reason: "Reduce the root entrypoint to parsing, dispatch, and top-level errors." - - path: "packages/cli/src/commands" - lines: "all" - reason: "Command modules should own heavy execution and rendering logic." - - path: "packages/cli/src/ui.ts" - lines: "all" - reason: "Shared formatting should live outside the root file." - - path: "packages/cli/src/index.test.ts" - lines: "all" - reason: "CLI behavior should stay stable while command ownership moves." - - path: "../cloud/packages/api/src" - lines: "all" - reason: "Where cloud currently duplicates CLI-adjacent behavior, it should consume handler libraries." - invariants: - - "CLI output contracts remain stable." - - "Argument parsing stays centralized." - - "Command handlers remain callable as library code." - objectives: - - "Move the remaining heavy commands out of packages/cli/src/index.ts." - - "Extract shared formatter and command-context helpers." - - "Make the root file small enough that future growth is obviously wrong." - scope: - in_scope: - - "CLI command/module extraction and shared formatting cleanup." - - "Replacing cloud-side duplicated command logic with library calls where already practical." - out_of_scope: - - "Changing command UX or output schemas for users." - - "New product features unrelated to the split." - dependencies: - - "runx-verification-foundation-and-fast-lanes" - touchpoints: - - area: "packages/cli/src/index.ts" - description: "The remaining OSS command monolith." - - area: "packages/cli/src/commands" - description: "Target home for reusable command execution and rendering." - - area: "../cloud/packages/api" - description: "Consumer surface that should reuse extracted command logic instead of duplicating it." - risks: - - description: "Command extraction can accidentally drift CLI formatting or exit-code behavior." - impact: "medium" - mitigation: "Keep behavior covered by the existing CLI test surface." - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "Add/search/publish/evolve/config/init/help command logic lives outside packages/cli/src/index.ts." - - id: "dod2" - description: "Shared formatting helpers live outside packages/cli/src/index.ts." - - id: "dod3" - description: "packages/cli/src/index.ts stays at or below 1000 lines." - validation: - - id: "v1" - type: "compile" - description: "OSS typecheck stays green after command extraction." - command: "pnpm typecheck" - cwd: "." - expected: "exit code 0" - - id: "v2" - type: "test" - description: "CLI behavior stays green." - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - cwd: "." - expected: "exit code 0" - - id: "v3" - type: "boundary" - description: "CLI root stays under the final budget." - command: "test $(wc -l < packages/cli/src/index.ts) -le 1000" - cwd: "." - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-24T00:25:00Z" - actor: "user" - summary: "Requested concrete execution specs for the remaining path to ideal shape." - - timestamp: "2026-04-24T00:25:00Z" - actor: "agent" - summary: "Scoped the remaining CLI work to the final root-file collapse and library-command reuse." - -phases: - - id: "phase1" - name: "Extract remaining registry and mutation commands" - objective: "Move the heaviest remaining command families out of the root file." - changes: - - file: "packages/cli/src/index.ts" - action: "update" - lines: "all" - content_spec: > - Replace in-file add, search, publish, and evolve command bodies with - imports and thin dispatch wiring. - - file: "packages/cli/src/commands/add.ts" - action: "create" - lines: "all" - content_spec: > - Own skill install/add command execution, validation, and rendering. - - file: "packages/cli/src/commands/search.ts" - action: "create" - lines: "all" - content_spec: > - Own registry search execution and result formatting. - - file: "packages/cli/src/commands/publish.ts" - action: "create" - lines: "all" - content_spec: > - Own publish-related command execution and result shaping. - - file: "packages/cli/src/commands/evolve.ts" - action: "create" - lines: "all" - content_spec: > - Own evolve command execution and any evolve-specific rendering helpers. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "CLI tests stay green after registry and mutation command extraction." - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - cwd: "." - expected: "exit code 0" - status: "pending" - - - id: "phase2" - name: "Extract config and bootstrap command plumbing" - objective: "Move lower-volume but still root-owned commands into focused modules." - dependencies: - - "phase1" - changes: - - file: "packages/cli/src/index.ts" - action: "update" - lines: "all" - content_spec: > - Remove config, init, and help-specific execution and formatting logic - from the root file. - - file: "packages/cli/src/commands/config.ts" - action: "create" - lines: "all" - content_spec: > - Own config read/write/display behavior and config-specific formatting. - - file: "packages/cli/src/commands/init.ts" - action: "create" - lines: "all" - content_spec: > - Own workspace/bootstrap initialization behavior and output. - - file: "packages/cli/src/commands/help.ts" - action: "create" - lines: "all" - content_spec: > - Own help text generation so root dispatch is not burdened with static - command narration. - acceptance_criteria: - - id: "ac2_1" - type: "boundary" - description: "CLI root shrinks below 1400 lines after the second extraction wave." - command: "test $(wc -l < packages/cli/src/index.ts) -le 1400" - cwd: "." - expected: "exit code 0" - status: "pending" - - - id: "phase3" - name: "Collapse root to dispatcher-only" - objective: "Leave packages/cli/src/index.ts as parse, dispatch, and top-level error mapping." - dependencies: - - "phase2" - changes: - - file: "packages/cli/src/index.ts" - action: "update" - lines: "all" - content_spec: > - Keep only argv parsing, command selection, and top-level error/exit - behavior in the root file. - - file: "packages/cli/src/ui.ts" - action: "update" - lines: "all" - content_spec: > - Centralize any remaining shared formatting helpers that commands still - use. - - file: "../cloud/packages/api/src" - action: "update" - lines: "all" - content_spec: > - Where cloud duplicates extracted CLI behavior, switch it to call the - reusable handler surface rather than re-implementing logic. - acceptance_criteria: - - id: "ac3_1" - type: "boundary" - description: "CLI root stays under the final 1000-line target." - command: "test $(wc -l < packages/cli/src/index.ts) -le 1000" - cwd: "." - expected: "exit code 0" - status: "pending" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- packages/cli/src/index.ts packages/cli/src/commands/add.ts packages/cli/src/commands/search.ts packages/cli/src/commands/publish.ts packages/cli/src/commands/evolve.ts" - phase2: "git checkout HEAD -- packages/cli/src/index.ts packages/cli/src/commands/config.ts packages/cli/src/commands/init.ts packages/cli/src/commands/help.ts" - phase3: "git checkout HEAD -- packages/cli/src/index.ts packages/cli/src/ui.ts ../cloud/packages/api/src" - -metadata: - estimated_effort_hours: 6 - ai_model: "gpt-5" - tags: - - "cli" - - "modularization" - - "library-reuse" diff --git a/.ai/specs/archive/2026-04/runx-cloud-api-service-split.yaml b/.ai/specs/archive/2026-04/runx-cloud-api-service-split.yaml deleted file mode 100644 index 2192ea22d..000000000 --- a/.ai/specs/archive/2026-04/runx-cloud-api-service-split.yaml +++ /dev/null @@ -1,158 +0,0 @@ -spec_version: "1.1" -task_id: "runx-cloud-api-service-split" -created: "2026-04-23T10:39:12Z" -updated: "2026-04-23T12:18:34Z" -status: "completed" -harden_status: "not_run" - -task: - title: "Split hosted API route and page services" - summary: > - cloud/packages/api/src/openapi.ts and public-site.ts are now the biggest - hosted files and mix data loading, domain shaping, HTML rendering, and API - schema assembly. Break them into route-level and service-level modules so - the hosted surface stops accreting logic in single files. - size: "medium" - risk_level: "medium" - context: - packages: - - "../cloud/packages/api" - files_impacted: - - path: "../cloud/packages/api/src/index.ts" - lines: "route wiring and inline handler logic" - reason: "Thin the HTTP entrypoint further" - - path: "../cloud/packages/api/src/openapi.ts" - lines: "operations, schema assembly, helper builders" - reason: "Split schema and path assembly" - - path: "../cloud/packages/api/src/public-site.ts" - lines: "data loading, feed shaping, HTML rendering" - reason: "Split data services from rendering" - - path: "../cloud/packages/api/src/*.ts" - lines: "all" - reason: "New focused route, service, and rendering modules" - invariants: - - "Hosted API behavior stays stable" - - "OpenAPI document shape stays stable" - - "Public site rendering remains server-side and deterministic" - objectives: - - "Split OpenAPI schema/path assembly out of the giant document file" - - "Split public-site data loading and rendering helpers into focused modules" - - "Thin the hosted API entrypoint so route registration is readable" - touchpoints: - - area: "../cloud/packages/api/src/openapi.ts" - description: "Largest hosted schema assembly surface" - - area: "../cloud/packages/api/src/public-site.ts" - description: "Largest hosted page/data surface" - - area: "../cloud/packages/api/src/index.ts" - description: "HTTP route registration entrypoint" - acceptance: - definition_of_done: - - id: "dod1" - description: "openapi.ts stays below 1600 lines" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod2" - description: "public-site.ts stays below 1500 lines" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod3" - description: "API route registration no longer embeds large helper bodies" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - validation: - - id: "v1" - type: "compile" - description: "Cloud workspace typechecks after modularization" - command: "pnpm typecheck" - expected: "exit code 0" - - id: "v2" - type: "boundary" - description: "OpenAPI file budget meets target" - command: "test $(wc -l < packages/api/src/openapi.ts) -lt 1600" - expected: "exit code 0" - - id: "v3" - type: "boundary" - description: "Public-site file budget meets target" - command: "test $(wc -l < packages/api/src/public-site.ts) -lt 1500" - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-23T10:39:12Z" - actor: "user" - summary: "Spec created via scafld new" - - timestamp: "2026-04-23T10:45:00Z" - actor: "agent" - summary: "Scoped hosted API work around OpenAPI schema assembly, public-site data/rendering, and route wiring." - - timestamp: "2026-04-23T12:18:34Z" - actor: "agent" - summary: "Split hosted OpenAPI and public-site helpers into focused modules and thinned API route registration to a dedicated public-page route module." - -phases: - - id: "phase1" - name: "Extract OpenAPI schema and path builders" - objective: "Break openapi.ts into schema/path helper modules." - changes: - - file: "../cloud/packages/api/src/openapi.ts" - action: "update" - lines: "path definitions, schema helpers, utility builders" - content_spec: | - Keep top-level OpenAPI assembly in openapi.ts and move path and schema - helper weight into dedicated modules. - - file: "../cloud/packages/api/src/openapi-*.ts" - action: "create" - lines: "all" - content_spec: | - Introduce focused modules for OpenAPI operations, schema components, - and common helper builders. - acceptance_criteria: - - id: "ac1_1" - type: "compile" - description: "Cloud typecheck passes after OpenAPI extraction" - command: "pnpm typecheck" - expected: "exit code 0" - status: "completed" - - - id: "phase2" - name: "Extract public-site data and rendering modules" - objective: "Separate registry/feed data shaping from HTML rendering." - dependencies: - - "phase1" - changes: - - file: "../cloud/packages/api/src/public-site.ts" - action: "update" - lines: "list/read/build/render helpers" - content_spec: | - Keep top-level page entrypoints in public-site.ts and move data loading, - feed shaping, and HTML fragment renderers into dedicated modules. - - file: "../cloud/packages/api/src/public-site-*.ts" - action: "create" - lines: "all" - content_spec: | - Introduce focused modules for public registry data, feed shaping, page - rendering, and shared HTML helpers. - acceptance_criteria: - - id: "ac2_1" - type: "boundary" - description: "public-site.ts drops under the target budget" - command: "test $(wc -l < packages/api/src/public-site.ts) -lt 1500" - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- ../cloud/packages/api/src/openapi.ts ../cloud/packages/api/src/openapi-*.ts" - phase2: "git checkout HEAD -- ../cloud/packages/api/src/public-site.ts ../cloud/packages/api/src/public-site-*.ts" - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 2 - validation_depth: 1 - total: 9 - notes: "The hosted API hot files are materially thinner and the cloud compile gate passed." - second_pass_performed: true - -deviations: - - description: "The cloud spec was executed without rerunning a broader behavioral test suite." - reason: "User explicitly directed focus toward structural work rather than spending more time on tests." diff --git a/.ai/specs/archive/2026-04/runx-contract-typebox-authority.yaml b/.ai/specs/archive/2026-04/runx-contract-typebox-authority.yaml deleted file mode 100644 index 0e01df138..000000000 --- a/.ai/specs/archive/2026-04/runx-contract-typebox-authority.yaml +++ /dev/null @@ -1,140 +0,0 @@ -spec_version: "1.1" -task_id: "runx-contract-typebox-authority" -created: "2026-04-23T10:39:13Z" -updated: "2026-04-23T12:18:34Z" -status: "completed" -harden_status: "not_run" - -task: - title: "Expand TypeBox contract authority" - summary: > - Contracts are still split between TypeScript interfaces, hand-written JSON - schema objects, and ad hoc runtime shapes. Extend the TypeBox-based - contracts package so more machine-facing CLI surfaces are defined once and - generated rather than maintained in parallel. - size: "medium" - risk_level: "medium" - context: - packages: - - "packages/contracts" - - "packages/cli" - - "scripts" - files_impacted: - - path: "packages/contracts/src/index.ts" - lines: "doctor/list/dev schema declarations" - reason: "Replace hand-written schema objects with TypeBox-owned definitions" - - path: "scripts/generate-contract-schemas.ts" - lines: "all" - reason: "Ensure generated JSON schema includes new TypeBox-owned contracts" - - path: "packages/contracts/src/index.test.ts" - lines: "all" - reason: "Protect logical schema ids and exported documents" - - path: "packages/cli/src/index.ts" - lines: "report typing or schema references where needed" - reason: "Consume generated contract exports consistently" - invariants: - - "One schema authority per machine-facing contract" - - "Generated JSON schema remains checked in and reproducible" - - "CLI machine outputs keep their current logical schema ids" - objectives: - - "Move doctor/list/dev contracts to TypeBox-owned definitions" - - "Generate JSON schema artifacts from those definitions" - - "Keep CLI report types aligned to the generated contracts" - touchpoints: - - area: "packages/contracts/src/index.ts" - description: "Current mixed contract authority surface" - - area: "scripts/generate-contract-schemas.ts" - description: "Schema generation entrypoint" - - area: "packages/cli/src/index.ts" - description: "Primary producer of the machine-facing report objects" - acceptance: - definition_of_done: - - id: "dod1" - description: "doctor, list, and dev machine contracts come from TypeBox-owned definitions" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod2" - description: "Generated JSON schema artifacts refresh cleanly from the contracts package" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod3" - description: "Contracts tests and CLI machine-output consumers remain green" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - validation: - - id: "v1" - type: "compile" - description: "OSS workspace typechecks after contract changes" - command: "pnpm typecheck" - expected: "exit code 0" - - id: "v2" - type: "integration" - description: "Generated contract schemas refresh cleanly" - command: "pnpm schemas:generate" - expected: "exit code 0" - - id: "v3" - type: "test" - description: "Contracts coverage stays green" - command: "pnpm exec vitest run packages/contracts/src/index.test.ts packages/cli/src/index.test.ts" - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-23T10:39:13Z" - actor: "user" - summary: "Spec created via scafld new" - - timestamp: "2026-04-23T10:45:00Z" - actor: "agent" - summary: "Scoped contract cleanup around doctor/list/dev machine outputs and generated schema authority." - - timestamp: "2026-04-23T12:18:34Z" - actor: "agent" - summary: "Moved doctor, dev, and list contracts to TypeBox-owned definitions, refreshed generated schemas, and updated CLI consumers." - -phases: - - id: "phase1" - name: "Move CLI report contracts to TypeBox" - objective: "Make doctor, list, and dev reports TypeBox-owned contracts." - changes: - - file: "packages/contracts/src/index.ts" - action: "update" - lines: "doctor/list/dev contract declarations" - content_spec: | - Replace hand-written JSON schema object definitions for machine-facing - CLI reports with TypeBox-owned definitions that export JSON schema and - TypeScript types from one source. - - file: "scripts/generate-contract-schemas.ts" - action: "update" - lines: "schema generation export list" - content_spec: | - Ensure the generator emits refreshed JSON schema artifacts for the new - TypeBox-owned report contracts. - - file: "packages/contracts/src/index.test.ts" - action: "update" - lines: "contract coverage" - content_spec: | - Add assertions that the logical schema ids and generated schema - exports remain stable for doctor/list/dev. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "Contracts tests stay green after TypeBox migration" - command: "pnpm exec vitest run packages/contracts/src/index.test.ts" - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- packages/contracts/src/index.ts scripts/generate-contract-schemas.ts packages/contracts/src/index.test.ts" - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 2 - validation_depth: 1 - total: 9 - notes: "Machine-facing CLI contracts now flow from one authority and schema generation remains reproducible; compile and schema generation passed." - second_pass_performed: true - -deviations: - - description: "The targeted contracts and CLI vitest command was not rerun before completion." - reason: "User explicitly prioritized continuing structural cleanup over additional test execution." diff --git a/.ai/specs/archive/2026-04/runx-contracts-single-authority.yaml b/.ai/specs/archive/2026-04/runx-contracts-single-authority.yaml deleted file mode 100644 index aacca4d06..000000000 --- a/.ai/specs/archive/2026-04/runx-contracts-single-authority.yaml +++ /dev/null @@ -1,281 +0,0 @@ -spec_version: "1.1" -task_id: "runx-contracts-single-authority" -created: "2026-04-24T00:40:00Z" -updated: "2026-04-26T12:58:00Z" -status: "completed" -harden_status: "reviewed" - -task: - title: "Make contracts the single authority for machine-readable runx schemas" - summary: > - Runx still carries contract drift risk because machine-readable shapes exist - as parallel TypeScript types, generated schemas, loose schema files, and - imperative validators. Collapse those surfaces into packages/contracts so - TypeBox-backed definitions generate TypeScript, runtime validators, and - checked-in schema artifacts from one source of truth. - size: "large" - risk_level: "high" - context: - packages: - - "packages/contracts" - - "packages/cli" - - "packages/core" - - "packages/adapters" - - "../cloud/packages/api" - files_impacted: - - path: "packages/contracts/src/index.ts" - lines: "all" - reason: "Target home for canonical machine-readable contract definitions." - - path: "schemas" - lines: "all" - reason: "Generated schema artifacts should come from contracts." - - path: "scripts/generate-contract-schemas.ts" - lines: "all" - reason: "Generation should stay deterministic and complete." - - path: "packages/cli/src" - lines: "all" - reason: "CLI report envelopes should consume generated validators and types." - - path: "packages/core/src" - lines: "all" - reason: "Runtime and executor contracts should stop using hand-maintained parallel validators." - - path: "../cloud/packages/api/src" - lines: "all" - reason: "Hosted envelopes should consume contracts rather than local duplicate shapes." - invariants: - - "Every machine-readable contract has one canonical definition." - - "Generated artifacts are deterministic and checked in." - - "Runtime validation remains available where behavior depends on external input." - objectives: - - "Move remaining envelopes and payloads into packages/contracts." - - "Generate runtime validators, TypeScript types, and schema artifacts from the same definitions." - - "Retire imperative validators where contracts can supply the runtime guard." - scope: - in_scope: - - "Doctor/dev/list outputs, hosted/public envelopes, manifests, packet/receipt adjuncts, and executor-facing machine contracts." - - "Schema generation and drift detection." - out_of_scope: - - "Purely internal in-memory helper types with no machine boundary." - - "Unrelated domain refactors outside contract ownership." - dependencies: - - "runx-verification-foundation-and-fast-lanes" - touchpoints: - - area: "packages/contracts" - description: "Canonical home for contract authority." - - area: "packages/core/src/executor" - description: "Largest remaining imperative validation surface." - - area: "packages/cli and ../cloud/packages/api" - description: "Consumers that should use generated validators instead of local duplicates." - risks: - - description: "Large contract migrations can cause broad call-site churn." - impact: "high" - mitigation: "Migrate by envelope family and keep generation deterministic at every step." - - description: "Generated artifacts can drift from checked-in files if the generation path is incomplete." - impact: "medium" - mitigation: "Make regeneration part of validation and fail on drift." - acceptance: - validation_profile: "strict" - definition_of_done: - - id: "dod1" - description: "CLI and hosted machine-readable report envelopes are defined in packages/contracts." - status: "done" - checked_at: "2026-04-26T12:58:00Z" - - id: "dod2" - description: "Receipt, manifest, and packet-oriented schemas are generated from packages/contracts." - status: "done" - checked_at: "2026-04-26T12:58:00Z" - - id: "dod3" - description: "Imperative validators in executor/runtime are removed or reduced to glue around contract-generated validators." - status: "done" - checked_at: "2026-04-26T12:58:00Z" - - id: "dod4" - description: "Schema generation produces no unchecked drift." - status: "done" - checked_at: "2026-04-26T12:58:00Z" - validation: - - id: "v1" - type: "integration" - description: "Schema generation completes successfully." - command: "pnpm schemas:generate" - cwd: "." - expected: "exit code 0" - - id: "v2" - type: "boundary" - description: "Generated contract artifacts are fully checked in." - command: "pnpm schemas:generate && git diff --exit-code packages/contracts/src schemas" - cwd: "." - expected: "exit code 0" - - id: "v3" - type: "compile" - description: "OSS typecheck stays green." - command: "pnpm typecheck" - cwd: "." - expected: "exit code 0" - - id: "v4" - type: "compile" - description: "Cloud typecheck stays green against the migrated contracts." - command: "pnpm typecheck" - cwd: "../cloud" - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-24T00:40:00Z" - actor: "user" - summary: "Requested concrete execution specs for the remaining path to ideal shape." - - timestamp: "2026-04-24T00:40:00Z" - actor: "agent" - summary: "Scoped contract debt to a packages/contracts authority migration with deterministic generation and drift enforcement." - - timestamp: "2026-04-25T14:31:49Z" - actor: "agent" - summary: "Updated rollback scope for the current split git topology; cross-repo rollback must use explicit git roots." - - timestamp: "2026-04-26T12:58:00Z" - actor: "agent" - summary: "Added contract-owned executor control protocol schemas, validators, generated artifacts, and core executor wrappers that delegate structural validation to packages/contracts." - - timestamp: "2026-04-26T12:58:00Z" - actor: "agent" - summary: "Adversarial validation exposed a CLI process-tree cancellation bug in the fast suite; fixed POSIX process-group termination and bubblewrap session handling before completion." - -phases: - - id: "phase1" - name: "Migrate control-plane report envelopes" - objective: "Move the most user-visible machine envelopes into packages/contracts first." - changes: - - file: "packages/contracts/src/index.ts" - action: "update" - lines: "all" - content_spec: > - Add canonical TypeBox definitions for CLI and hosted report envelopes - such as doctor, dev, list, and public status outputs. - - file: "packages/cli/src" - action: "update" - lines: "all" - content_spec: > - Replace local report types and validators with imports from - packages/contracts. - - file: "../cloud/packages/api/src" - action: "update" - lines: "all" - content_spec: > - Replace locally shaped hosted/public envelopes with contract imports - where the response is machine-consumed. - acceptance_criteria: - - id: "ac1_1" - type: "compile" - description: "OSS typechecks after control-plane envelope migration." - command: "pnpm typecheck" - cwd: "." - expected: "exit code 0" - - id: "ac1_2" - type: "compile" - description: "Cloud typechecks against the migrated control-plane envelopes." - command: "pnpm typecheck" - cwd: "../cloud" - expected: "exit code 0" - status: "completed" - - - id: "phase2" - name: "Migrate receipt, manifest, and packet schemas" - objective: "Move the remaining checked-in machine contract families under one authority." - dependencies: - - "phase1" - changes: - - file: "packages/contracts/src/index.ts" - action: "update" - lines: "all" - content_spec: > - Add canonical definitions for receipt adjuncts, manifest-like payloads, - packet schemas, and skill metadata that still live in parallel forms. - - file: "schemas" - action: "update" - lines: "all" - content_spec: > - Regenerate checked-in schema artifacts so they are entirely derived - from packages/contracts. - - file: "scripts/generate-contract-schemas.ts" - action: "update" - lines: "all" - content_spec: > - Ensure the generation script covers the full machine-readable contract - surface deterministically. - acceptance_criteria: - - id: "ac2_1" - type: "integration" - description: "Schema generation covers the expanded contract surface." - command: "pnpm schemas:generate" - cwd: "." - expected: "exit code 0" - - id: "ac2_2" - type: "boundary" - description: "Generation produces no unchecked drift." - command: "pnpm schemas:generate && git diff --exit-code packages/contracts/src schemas" - cwd: "." - expected: "exit code 0" - status: "completed" - - - id: "phase3" - name: "Retire imperative validator duplication" - objective: "Replace hand-maintained validator code with contract-driven runtime validation where possible." - dependencies: - - "phase2" - changes: - - file: "packages/core/src/executor" - action: "update" - lines: "all" - content_spec: > - Replace large imperative validators with imports from - packages/contracts or shrink them to glue around contract-generated - validation results. - - file: "packages/core/src" - action: "update" - lines: "all" - content_spec: > - Use the generated validators consistently wherever external machine - input enters the runtime. - acceptance_criteria: - - id: "ac3_1" - type: "compile" - description: "OSS still typechecks after validator consolidation." - command: "pnpm typecheck" - cwd: "." - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git -C /home/kam/dev/runx/oss checkout HEAD -- packages/contracts/src/index.ts packages/cli/src && git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/api/src" - phase2: "git -C /home/kam/dev/runx/oss checkout HEAD -- packages/contracts/src/index.ts schemas scripts/generate-contract-schemas.ts" - phase3: "git -C /home/kam/dev/runx/oss checkout HEAD -- packages/core/src/executor packages/core/src" - -review: - verdict: "pass" - reviewed_at: "2026-04-26T12:58:00Z" - reviewer: "agent" - finding_counts: - critical: 0 - high: 0 - medium: 0 - low: 0 - notes: - - "Structural executor contracts now originate in packages/contracts; core keeps only runtime-dependent resolution-response glue." - - "Generated schema artifacts include executor control protocol, credential envelope, and scope admission schemas." - - "Cloud credential envelope typing now consumes the contract package." - - "Second-pass validation found and fixed unrelated process-tree cancellation flake before marking the spec complete." - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 3 - validation_depth: 3 - total: 12 - notes: "Contracts are the authority for the executor control protocol and existing machine schemas; generation, OSS typecheck/test, and cloud typecheck passed." - second_pass_performed: true - -deviations: [] - -metadata: - estimated_effort_hours: 10 - ai_model: "gpt-5" - tags: - - "contracts" - - "typebox" - - "schema-generation" diff --git a/.ai/specs/archive/2026-04/runx-doctor-structure-enforcement.yaml b/.ai/specs/archive/2026-04/runx-doctor-structure-enforcement.yaml deleted file mode 100644 index 3fd39ab2d..000000000 --- a/.ai/specs/archive/2026-04/runx-doctor-structure-enforcement.yaml +++ /dev/null @@ -1,140 +0,0 @@ -spec_version: "1.1" -task_id: "runx-doctor-structure-enforcement" -created: "2026-04-23T10:39:13Z" -updated: "2026-04-23T12:18:34Z" -status: "completed" -harden_status: "not_run" - -task: - title: "Teach doctor to fail structural drift" - summary: > - The current doctor path is green but still misses structural drift that - directly undermines the cleanup: stale official skill lockfiles, giant - monolith files, and forbidden package reach-ins. Extend doctor so those - regressions fail quickly instead of waiting for manual review. - size: "small" - risk_level: "medium" - context: - packages: - - "packages/cli" - - "scripts" - - "tests" - files_impacted: - - path: "packages/cli/src/index.ts" - lines: "doctor diagnostics and scanning logic" - reason: "Add structural diagnostics and explanations" - - path: "packages/cli/src/official-skills.lock.json" - lines: "all" - reason: "Doctor should verify this generated file is current" - - path: "scripts/generate-official-lock.mjs" - lines: "all" - reason: "Canonical generation path for lock verification" - - path: "packages/cli/src/index.test.ts" - lines: "doctor coverage" - reason: "Add failing and passing structural-drift cases" - invariants: - - "doctor stays machine-actionable" - - "Diagnostics carry explicit ids and repair guidance" - - "No structural check depends on hidden state" - objectives: - - "Fail doctor when official-skills.lock.json is stale" - - "Fail or warn when designated monolith files exceed declared budgets" - - "Fail on forbidden cross-package relative src reach-ins" - touchpoints: - - area: "packages/cli/src/index.ts" - description: "Doctor implementation and diagnostic explanation table" - - area: "packages/cli/src/official-skills.lock.json" - description: "Generated official skill lock that should stay current" - - area: "scripts/generate-official-lock.mjs" - description: "Ground truth for the official lock content" - acceptance: - definition_of_done: - - id: "dod1" - description: "doctor emits a stable diagnostic when official-skills.lock.json is stale" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod2" - description: "doctor emits a stable diagnostic for overbudget monolith files" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod3" - description: "doctor emits a stable diagnostic for forbidden cross-package src reach-ins" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - validation: - - id: "v1" - type: "compile" - description: "OSS workspace typechecks after doctor changes" - command: "pnpm typecheck" - expected: "exit code 0" - - id: "v2" - type: "test" - description: "Doctor coverage includes the new diagnostics" - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - expected: "exit code 0" - - id: "v3" - type: "integration" - description: "Workspace doctor still passes after required generated files are refreshed" - command: "pnpm exec tsx packages/cli/src/index.ts doctor --json" - expected: "status success" - -planning_log: - - timestamp: "2026-04-23T10:39:13Z" - actor: "user" - summary: "Spec created via scafld new" - - timestamp: "2026-04-23T10:45:00Z" - actor: "agent" - summary: "Scoped doctor enforcement around stale generated metadata, monolith budgets, and forbidden import reach-ins." - - - timestamp: "2026-04-23T10:49:46Z" - actor: "cli" - summary: "Spec approved" - - timestamp: "2026-04-23T10:49:47Z" - actor: "cli" - summary: "Execution started" - - timestamp: "2026-04-23T12:18:34Z" - actor: "agent" - summary: "Completed doctor structural diagnostics for stale lockfiles, file budgets, and cross-package source reach-ins, and verified OSS typecheck." -phases: - - id: "phase1" - name: "Add structural drift diagnostics" - objective: "Teach doctor to detect stale locks, file budgets, and package reach-ins." - changes: - - file: "packages/cli/src/index.ts" - action: "update" - lines: "doctor scanning logic and explainDoctorDiagnostic table" - content_spec: | - Add deterministic checks for stale official skill locks, monolith file - budgets, and forbidden relative cross-package src imports. Emit stable - diagnostic ids with repair guidance. - - file: "packages/cli/src/index.test.ts" - action: "update" - lines: "doctor tests" - content_spec: | - Add fixtures that prove each new diagnostic triggers and that the clean - workspace still passes once regenerated. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "Doctor tests pass with the new structural diagnostics" - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- packages/cli/src/index.ts packages/cli/src/index.test.ts" - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 2 - validation_depth: 1 - total: 9 - notes: "Doctor now enforces the main structural drift checks; compile verification passed and broader test reruns were intentionally deferred." - second_pass_performed: true - -deviations: - - description: "The targeted CLI vitest acceptance command was not rerun as part of completion." - reason: "User explicitly directed the work away from spending additional time on tests." diff --git a/.ai/specs/archive/2026-04/runx-fanout-gate-resolution-semantics.yaml b/.ai/specs/archive/2026-04/runx-fanout-gate-resolution-semantics.yaml deleted file mode 100644 index 43ce66c8c..000000000 --- a/.ai/specs/archive/2026-04/runx-fanout-gate-resolution-semantics.yaml +++ /dev/null @@ -1,101 +0,0 @@ -spec_version: "1.1" -task_id: "runx-fanout-gate-resolution-semantics" -created: "2026-04-25T15:35:00Z" -updated: "2026-04-26T08:18:08Z" -status: "completed" - -task: - title: "Make fanout pause and escalate gates first-class graph states" - summary: > - Fanout threshold and conflict gates can declare actions named pause or - escalate, but the current runner records the sync decision and then returns - a failed graph. Implement resumable pause/escalation semantics so these - actions are not aliases for failure. - size: "medium" - risk_level: "high" - context: - packages: - - "packages/core" - - "packages/cli" - - "packages/adapters" - files_impacted: - - path: "packages/core/src/state-machine/index.ts" - lines: "fanout planning" - reason: "Represent pause and escalate plans distinctly from failure." - - path: "packages/core/src/runner-local/orchestrator.ts" - lines: "fanout sync handling" - reason: "Return a resumable pending graph state or explicit escalation result." - - path: "packages/core/src/runner-local/graph-hydration.ts" - lines: "resume support" - reason: "Hydrate completed fanout branches so a paused graph can resume after the gate decision." - - path: "packages/core/src/sdk/host-protocol.ts" - lines: "paused run mapping" - reason: "Expose gate pauses through the same host protocol as other pending resolution." - - path: "packages/cli/src/cli-presentation.ts" - lines: "paused and escalated graph output" - reason: "Render fanout gate pauses and escalations distinctly from execution failures." - objectives: - - "Add a graph result path for fanout gate pause that includes a structured resolution request." - - "Add explicit escalation behavior with a receipt disposition and host status that is not generic failure." - - "Persist enough fanout branch ledger state to resume after a gate pause." - - "Keep halt and branch execution failure semantics unchanged." - scope: - in_scope: - - "Fanout sync decisions with action pause or escalate." - - "Ledger, receipt, SDK, and CLI behavior needed to inspect and resume paused fanout gates." - - "Regression tests for threshold and conflict gates." - out_of_scope: - - "Changing fanout execution strategy or branch scheduling." - - "Semantic/prose gates; gates remain structured-field only." - acceptance: - validation_profile: "strict" - definition_of_done: - - id: "dod1" - description: "A threshold gate with action pause returns a paused/resolution-needed graph result, not status failure." - - id: "dod2" - description: "Resuming a paused fanout gate reuses existing branch receipts and continues or halts deterministically from the recorded decision." - - id: "dod3" - description: "A conflict gate with action escalate returns an explicit escalation outcome and receipt metadata." - - id: "dod4" - description: "Existing halt, quorum, and all-success fanout tests remain green." - validation: - - id: "v1" - type: "compile" - description: "OSS typecheck stays green." - command: "pnpm typecheck" - cwd: "." - expected: "exit code 0" - - id: "v2" - type: "test" - description: "Fanout, surface, resume, and replay behavior stays coherent." - command: "pnpm exec vitest run tests/chain-fanout.test.ts tests/replay-run.test.ts packages/core/src/sdk/index.test.ts" - cwd: "." - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-25T15:35:00Z" - actor: "agent" - summary: "Created from deep review finding that pause/escalate fanout gates currently collapse into graph failure." - - timestamp: "2026-04-25T16:18:00Z" - actor: "agent" - summary: "Implemented distinct paused/escalated fanout plans, approval-style gate resolution, fanout branch hydration on resume, and focused state-machine/runner coverage." - - timestamp: "2026-04-26T08:18:08Z" - actor: "agent" - summary: "Completed surface semantics: pause remains resumable, escalation now writes a terminal escalated graph receipt with pending outcome metadata, and SDK/CLI/MCP surfaces expose escalated separately from generic failure." - -phases: - - id: "phase1" - name: "Result Model" - objective: "Add first-class plan and result states for fanout pause and escalation." - status: "completed" - - id: "phase2" - name: "Resume Hydration" - objective: "Persist and hydrate completed fanout branch state so graph resume works after a gate pause." - status: "completed" - - id: "phase3" - name: "Surfaces" - objective: "Update SDK and CLI surfaces to render gate pause/escalate outcomes distinctly from failure." - status: "completed" - -metadata: - estimated_effort_hours: 8 diff --git a/.ai/specs/archive/2026-04/runx-handoff-signal-core-model.yaml b/.ai/specs/archive/2026-04/runx-handoff-signal-core-model.yaml deleted file mode 100644 index fb27dbf95..000000000 --- a/.ai/specs/archive/2026-04/runx-handoff-signal-core-model.yaml +++ /dev/null @@ -1,341 +0,0 @@ -spec_version: "1.1" -task_id: "runx-handoff-signal-core-model" -created: "2026-04-24T02:15:00Z" -updated: "2026-04-26T11:38:00Z" -status: "completed" - -task: - title: "Harden the generic handoff signal model for post-boundary state" - summary: > - Runx already has generic transport and delivery primitives for external - work: thread hydration, outbox packaging, explicit decisions, and boundary - semantics. The generic handoff contracts and reducer now exist in core, but - the draft still needs to describe the remaining hardening work accurately: - keep the canonical nouns stable, verify generated schemas and reducer tests, - and add any missing persistence/query/tool surfaces without letting - Sourcey-specific names become platform vocabulary. The stable runx concept is - an outward handoff crossing an explicit boundary and then receiving - normalized response signals, reduced state, and suppression policy. - size: "medium" - risk_level: "medium" - context: - packages: - - "packages/contracts" - - "packages/core" - - "skills" - - "tools/thread" - files_impacted: - - path: "packages/contracts/src/index.ts" - lines: "all" - reason: "Canonical home for existing handoff signal, handoff state, and suppression contracts." - - path: "packages/contracts/src/handoff-contracts.test.ts" - lines: "all" - reason: "Focused contract coverage for the generic handoff model." - - path: "schemas/handoff-*.schema.json" - lines: "all" - reason: "Generated schema artifacts for the handoff contract family." - - path: "packages/core/src/knowledge/index.ts" - lines: "all" - reason: "Generic knowledge/boundary helpers own validation and reduction, and should own persistence/query if added." - - path: "packages/core/src/knowledge/*handoff*.test.ts" - lines: "all" - reason: "Focused knowledge-layer coverage for handoff state reduction." - - path: "tools/thread/handoff_state" - lines: "all" - reason: "Neutral tool surface for reducing generic handoff signals and suppression state." - - path: "tests/thread-handoff-state-tool.test.ts" - lines: "all" - reason: "Tool-level coverage for generic handoff state reduction." - - path: "skills/draft-content/SKILL.md" - lines: "all" - reason: "Existing boundary terminology should stay aligned with the new handoff model." - - path: "skills/issue-to-pr/SKILL.md" - lines: "all" - reason: "Issue-to-PR is the current thin wrapper around generic transport and delivery surfaces." - - path: "../plans/sourcey-adoption-engine.md" - lines: "all" - reason: "Sourcey adoption planning currently names a docs-specific signal surface and should map to the generic model." - invariants: - - "Thread and outbox stay transport and delivery primitives, not domain posture models." - - "Boundary terminology stays aligned with existing boundary_kind and boundary_state concepts." - - "Observed response signals stay distinct from explicit suppression policy." - - "Sourcey and other domain lanes map into generic handoff concepts instead of becoming the platform vocabulary." - related_docs: - - "../plans/sourcey-adoption-engine.md" - - "../docs/skill-lab-contribution-spec.md" - - "skills/draft-content/SKILL.md" - - "packages/core/src/knowledge/index.ts" - - "packages/contracts/src/index.ts" - cwd: "." - objectives: - - "Lock the canonical runx nouns for post-handoff state." - - "Verify immutable observed signals, reduced current state, and durable suppression policy stay separate in contracts and tests." - - "Place any remaining generic persistence/query capability in knowledge, not in Sourcey-specific lanes or runner-local kernel code." - - "Leave Sourcey, skill-upstream, and future outreach workflows as thin wrappers over the generic model." - scope: - in_scope: - - "Canonical contracts for handoff_signal, handoff_state, and suppression_record." - - "Knowledge-layer validation, reduction, and any needed persistence/query responsibilities for post-handoff state." - - "Tool and skill naming rules for generic versus domain-specific wrappers." - - "Mapping from Sourcey docs review/PR/outreach flows onto the generic model." - out_of_scope: - - "Crawler, ranking, scheduling, or portfolio-scale outreach automation." - - "Hosted moderation UI or suppression dashboard implementation." - - "Provider-specific polling infrastructure beyond the boundary contract shape." - assumptions: - - "Runx should continue treating explicit external handoff boundaries as first-class concepts." - - "Sourcey is only the first strong consumer of the generic post-handoff model, not its owner." - - "Email, GitHub, discussions, and future channels all need to fit the same response model." - touchpoints: - - area: "contracts" - description: "Canonical contract ids, TypeBox schemas, generated artifacts, and runtime validation for generic post-handoff state." - links: - - "packages/contracts/src/index.ts" - - area: "knowledge" - description: "Generic boundary-state validation and reduction already live here; persistence/query extensions should stay here too." - links: - - "packages/core/src/knowledge/index.ts" - - area: "boundary semantics" - description: "Existing boundary_kind and boundary_state language in draft-content must remain coherent with the new model." - links: - - "skills/draft-content/SKILL.md" - - "skills/draft-content/X.yaml" - - area: "Sourcey adoption" - description: "Sourcey docs PR and outreach lanes should consume the generic model instead of defining platform nouns." - links: - - "../plans/sourcey-adoption-engine.md" - - area: "upstream handoff flows" - description: "Issue-to-PR and future skill-upstream lanes should be able to reuse the same post-handoff primitives." - links: - - "skills/issue-to-pr/SKILL.md" - risks: - - description: "A docs-specific or maintainer-specific name could leak into core and become hard to unwind later." - impact: "high" - mitigation: "Freeze the canonical nouns before implementation and treat docs-specific names as wrappers only." - - description: "Signals, decisions, and suppression rules could collapse into one object and muddy operator reasoning." - impact: "high" - mitigation: "Keep immutable observations, reduced state, and policy records as separate contracts." - - description: "A thread-centric model could exclude email or other non-thread surfaces." - impact: "medium" - mitigation: "Anchor the core concept on outward handoff and boundary response, not on GitHub thread mechanics." - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "Canonical runx nouns remain frozen as handoff_signal, handoff_state, and suppression_record." - - id: "dod2" - description: "The design and tests keep docs-signal and maintainer-signal as consumer-level names, not core contract names." - - id: "dod3" - description: "Contracts stay in packages/contracts; validation/reduction and any persistence/query helpers stay in packages/core knowledge." - - id: "dod4" - description: "The mapping from Sourcey docs PR/outreach flows to the generic model is explicit without adding Sourcey-specific core vocabulary." - validation: - - id: "v1" - type: "test" - description: "Focused handoff contract and reducer tests stay green." - command: "pnpm exec vitest run packages/contracts/src/handoff-contracts.test.ts packages/core/src/knowledge/handoff-state.test.ts packages/core/src/knowledge/index.test.ts tests/thread-handoff-state-tool.test.ts" - cwd: "." - expected: "exit code 0" - - id: "v2" - type: "boundary" - description: "Generated handoff schema artifacts stay in sync with contracts." - command: "pnpm schemas:generate && git diff --exit-code packages/contracts/src schemas/handoff-signal.schema.json schemas/handoff-state.schema.json schemas/suppression-record.schema.json" - cwd: "." - expected: "exit code 0" - - id: "v3" - type: "documentation" - description: "The spec leaves room for GitHub, email, and future channels under the same core model." - notes: > - Canonical nomenclature: - - - `thread`: hydrated provider conversation or engagement surface. - - `outbox_entry`: outbound artifact proposed or published through that surface. - - `boundary_state`: pre-send or handoff-semantics object describing who acts - next at the boundary and what acknowledgement is expected. - - `handoff_signal`: immutable normalized observation captured after an - outward handoff crosses an explicit boundary. - - `handoff_state`: reduced current posture for one handoff or target after - signals and suppression are considered. - - `suppression_record`: explicit durable no-contact or operator-block rule. - - Non-canonical names: - - - `docs-signal`: acceptable only as a Sourcey wrapper or lane label. - - `maintainer_signal`: acceptable only as a consumer-facing explanation when - the downstream actor really is an upstream maintainer. - - `thread_signal`: rejected as the core term because email and other - boundary surfaces must also fit. - -planning_log: - - timestamp: "2026-04-24T02:15:00Z" - actor: "user" - summary: "Asked whether docs-signal should be core and requested a proper future-proof design with correct nomenclature." - - timestamp: "2026-04-24T02:15:00Z" - actor: "agent" - summary: "Chose handoff as the stable core concept, with signals and suppression layered on top of existing thread and outbox transport surfaces." - notes: > - The existing knowledge package already owns thread, outbox, and decision - contracts. The missing layer is generic post-handoff state, not another - Sourcey-specific workflow primitive. - - timestamp: "2026-04-25T14:31:49Z" - actor: "agent" - summary: "Rebased the draft on current code, where handoff contracts, generated schema artifacts, reducer helpers, and focused tests already exist." - notes: > - The remaining work should harden and expose the existing generic model - instead of adding a second docs-specific signal vocabulary. - - timestamp: "2026-04-26T11:24:14Z" - actor: "agent" - summary: "Hardened generic knowledge helpers and added the neutral thread.handoff_state tool surface." - notes: > - Outbox control queries now avoid stateful regex behavior, outbox file - materialization normalizes relative paths before reading, and the - issue-to-pr skill text keeps post-handoff signal capture in the generic - handoff model rather than in PR packaging. - - timestamp: "2026-04-26T11:38:00Z" - actor: "agent" - summary: "Completed the Sourcey crossover by keeping generic execution surfaces in runx." - notes: > - Control outbox lookup now treats entry id patterns as legacy fallback - selectors when structured control metadata exists, and the CLI package - test locks the neutral thread.handoff_state tool into the shipped tool - surface. - -phases: - - id: "phase1" - name: "Audit canonical contracts and naming" - objective: "Lock the existing generic nouns and generated artifacts before integration drift hardens." - changes: - - file: "packages/contracts/src/index.ts" - action: "update" - lines: "all" - content_spec: > - Keep the existing canonical contract families named - runx.handoff_signal.v1, runx.handoff_state.v1, and - runx.suppression_record.v1. The handoff signal represents one - immutable normalized observation after an outward handoff. The handoff - state represents the reduced posture for a handoff or target after - replaying signals and suppression. The suppression record remains a - separate explicit policy object rather than a signal subtype. - - file: "schemas/handoff-*.schema.json" - action: "update" - lines: "all" - content_spec: > - Keep generated handoff schema artifacts synchronized with - packages/contracts. Do not hand-edit generated artifacts except through - the schema generation path. - - file: "packages/contracts/src/index.ts" - action: "update" - lines: "all" - content_spec: > - Keep boundary_kind as the taxonomy hook for who or what sits on the - far side of the boundary. Use handoff as the noun for the attempt - crossing that boundary. Do not make docs, maintainer, PR, or thread - part of the canonical contract name. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "Focused handoff contract tests stay green." - command: "pnpm exec vitest run packages/contracts/src/handoff-contracts.test.ts" - cwd: "." - expected: "exit code 0" - - id: "ac1_2" - type: "boundary" - description: "Generated handoff schema artifacts stay synchronized with packages/contracts." - command: "pnpm schemas:generate && git diff --exit-code packages/contracts/src schemas/handoff-signal.schema.json schemas/handoff-state.schema.json schemas/suppression-record.schema.json" - cwd: "." - expected: "exit code 0" - status: "completed" - - - id: "phase2" - name: "Harden knowledge reduction and persistence boundary" - objective: "Keep generic post-handoff state beside thread and outbox knowledge instead of burying it in a product lane." - dependencies: - - "phase1" - changes: - - file: "packages/core/src/knowledge/index.ts" - action: "update" - lines: "all" - content_spec: > - Keep reducer helpers generic and pure. If durable append/load/query - helpers are added, place them here beside thread and outbox knowledge, - validate all records through packages/contracts, and keep the reducer - usable without a storage adapter. - - file: "packages/core/src/knowledge/index.ts" - action: "update" - lines: "all" - content_spec: > - Keep this out of runner-local orchestration code. This is boundary - knowledge and reduction logic, not execution-kernel logic. - acceptance_criteria: - - id: "ac2_1" - type: "test" - description: "Knowledge-layer handoff reducer coverage stays green." - command: "pnpm exec vitest run packages/core/src/knowledge/handoff-state.test.ts packages/core/src/knowledge/index.test.ts" - cwd: "." - expected: "exit code 0" - - id: "ac2_2" - type: "documentation" - description: "The design keeps decisions, signals, and suppression as distinct concepts." - status: "completed" - - - id: "phase3" - name: "Expose generic tools and keep domain wrappers thin" - objective: "Ensure product lanes consume the generic model instead of duplicating it." - dependencies: - - "phase2" - changes: - - file: "tools/thread" - action: "update" - lines: "all" - content_spec: > - Introduce or document generic post-handoff helpers under a neutral - surface such as handoff or boundary, for example record signal, reduce - state, and check suppression. Do not make docs or maintainer part of - the generic tool namespace. - - file: "tools/thread/handoff_state" - action: "create" - lines: "all" - content_spec: > - Provide a neutral thread.handoff_state tool that reduces generic - handoff_signal records and suppression_record policy into a - handoff_state, reports the active suppression record, and exposes the - generic outbox-push and candidate-signal gates. - - file: "../plans/sourcey-adoption-engine.md" - action: "update" - lines: "all" - content_spec: > - Reframe docs-signal as a Sourcey consumer of the generic handoff - model. Sourcey may still expose docs-specific policy, but it should - emit and consume the generic contracts. - - file: "skills/issue-to-pr/SKILL.md" - action: "update" - lines: "all" - content_spec: > - Clarify that issue-to-pr owns packaging and push boundaries, while - post-handoff signal capture is a separate generic concern that can be - reused by Sourcey, skill-upstream, and future outreach lanes. - acceptance_criteria: - - id: "ac3_1" - type: "documentation" - description: "The design leaves Sourcey docs-signal as a thin wrapper name, not the platform primitive." - - id: "ac3_2" - type: "documentation" - description: "The design allows future skill-upstream and outreach lanes to consume the same generic contracts." - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git -C /home/kam/dev/runx/oss checkout HEAD -- packages/contracts/src/index.ts packages/contracts/src/handoff-contracts.test.ts packages/contracts/src/index.test.ts schemas/handoff-signal.schema.json schemas/handoff-state.schema.json schemas/suppression-record.schema.json scripts/generate-contract-schemas.ts" - phase2: "git -C /home/kam/dev/runx/oss checkout HEAD -- packages/core/src/knowledge/index.ts packages/core/src/knowledge/index.test.ts packages/core/src/knowledge/handoff-state.test.ts" - phase3: "git -C /home/kam/dev/runx/oss checkout HEAD -- tools/thread skills/draft-content/SKILL.md skills/issue-to-pr/SKILL.md && git -C /home/kam/dev/runx checkout HEAD -- plans/sourcey-adoption-engine.md" - -metadata: - estimated_effort_hours: 6 - ai_model: "gpt-5" - tags: - - "architecture" - - "nomenclature" - - "boundary" - - "handoff" - - "knowledge" diff --git a/.ai/specs/archive/2026-04/runx-hosted-api-domain-service-split.yaml b/.ai/specs/archive/2026-04/runx-hosted-api-domain-service-split.yaml deleted file mode 100644 index 027401326..000000000 --- a/.ai/specs/archive/2026-04/runx-hosted-api-domain-service-split.yaml +++ /dev/null @@ -1,250 +0,0 @@ -spec_version: "1.1" -task_id: "runx-hosted-api-domain-service-split" -created: "2026-04-24T00:35:00Z" -updated: "2026-04-26T12:04:40Z" -status: "completed" - -task: - title: "Close residual hosted API domain-service cleanup" - summary: > - The hosted hot files have already been reduced to thin entrypoints. The - remaining work is to lock in that shape, clean up any residual domain - duplication, and make the structure hard to regress: route files should stay - registrars over focused services, OpenAPI should stay assembled from helper - modules, and public-site data/model/render responsibilities should remain - separated. - size: "medium" - risk_level: "medium" - context: - packages: - - "../cloud/packages/api" - - "../cloud/apps/api" - - "packages/cli" - - "packages/core" - files_impacted: - - path: "../cloud/packages/api/src/index.ts" - lines: "all" - reason: "Keep the hosted app factory as top-level route wiring." - - path: "../cloud/packages/api/src/*-routes.ts" - lines: "all" - reason: "Flat domain route registrars are the current hosted route shape." - - path: "../cloud/packages/api/src/*-service.ts" - lines: "all" - reason: "Business logic should stay outside route registration." - - path: "../cloud/packages/api/src/openapi*.ts" - lines: "all" - reason: "OpenAPI document assembly should stay split across helpers, schemas, and route catalog modules." - - path: "../cloud/packages/api/src/public-site*.ts" - lines: "all" - reason: "Public-site loading, model shaping, page composition, and rendering should stay separated." - invariants: - - "Hosted API behavior stays stable." - - "OpenAPI output shape stays stable." - - "Public-site rendering stays deterministic and server-side." - objectives: - - "Preserve the current thin hosted entrypoints." - - "Close residual duplicate behavior between routes and services." - - "Keep OpenAPI generation and public-site rendering behind focused helper modules." - - "Add structure checks that catch regression back toward hot files." - scope: - in_scope: - - "Hosted route, service, OpenAPI, and public-site cleanup inside the current flat module layout." - - "Structure validation that protects the current split." - - "Swapping duplicate hosted behavior over to library code where available." - out_of_scope: - - "Changing public API contracts." - - "Provider-integration rewrites beyond what modularization requires." - dependencies: - - "runx-verification-foundation-and-fast-lanes" - - "runx-cli-kernel-final-split" - - "runx-runner-local-facade-final-split" - touchpoints: - - area: "../cloud/packages/api/src/index.ts" - description: "Hosted API registrar that should remain thin." - - area: "../cloud/packages/api/src/openapi.ts" - description: "Top-level OpenAPI document assembly over helper modules." - - area: "../cloud/packages/api/src/public-site.ts" - description: "Top-level public-site orchestration over data/model/render modules." - risks: - - description: "Cleanup across route/service boundaries can accidentally change auth or handler wiring." - impact: "high" - mitigation: "Keep fast hosted tests and targeted API route tests green after each cleanup slice." - - description: "OpenAPI or public-site helper cleanup can drift document ordering, schema names, or rendered HTML." - impact: "medium" - mitigation: "Preserve the current document surface and keep existing API tests as the oracle." - acceptance: - validation_profile: "strict" - definition_of_done: - - id: "dod1" - description: "packages/api/src/index.ts remains route registration only and stays at or below 150 lines." - - id: "dod2" - description: "packages/api/src/openapi.ts delegates to helper/schema/catalog modules and stays at or below 150 lines." - - id: "dod3" - description: "packages/api/src/public-site.ts delegates to public-site data/model/page/render modules and stays at or below 100 lines." - - id: "dod4" - description: "Hosted domains remain grouped in the current flat *-routes.ts and *-service.ts module style, with no duplicate routes/ or services/ tree introduced." - validation: - - id: "v1" - type: "compile" - description: "Cloud typecheck stays green." - command: "pnpm typecheck" - cwd: "../cloud" - expected: "exit code 0" - - id: "v2" - type: "test" - description: "Hosted fast lane stays green." - command: "pnpm test:fast" - cwd: "../cloud" - expected: "exit code 0" - - id: "v3" - type: "boundary" - description: "Hosted entrypoint files meet their final thin-entrypoint budgets." - command: "test $(wc -l < packages/api/src/index.ts) -le 150 && test $(wc -l < packages/api/src/openapi.ts) -le 150 && test $(wc -l < packages/api/src/public-site.ts) -le 100" - cwd: "../cloud" - expected: "exit code 0" - - id: "v4" - type: "boundary" - description: "Hosted code does not reintroduce duplicate routes/ or services/ trees beside the current flat modules." - command: "test ! -d packages/api/src/routes && test ! -d packages/api/src/services" - cwd: "../cloud" - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-24T00:35:00Z" - actor: "user" - summary: "Asked for concrete execution specs for the remaining architectural work." - - timestamp: "2026-04-24T00:35:00Z" - actor: "agent" - summary: "Scoped the hosted-side work to route-domain registrars, OpenAPI builders, and public-site service/render separation." - - timestamp: "2026-04-25T14:31:49Z" - actor: "agent" - summary: "Rebased the draft on the current cloud state, where hosted API entrypoints are already thin and remaining work is regression-proof cleanup." - - timestamp: "2026-04-26T12:04:40Z" - actor: "agent" - summary: "Audited the current cloud tree and found this cleanup already satisfied." - notes: > - packages/api/src/index.ts is 102 lines, openapi.ts is 79 lines, - public-site.ts is 29 lines, focused openapi/public-site helper modules - exist, and no duplicate routes/ or services/ trees are present. - -phases: - - id: "phase1" - name: "Codify current route registrar ownership" - objective: "Keep the existing flat hosted route registrars focused on HTTP wiring over service functions." - changes: - - file: "../cloud/packages/api/src/index.ts" - action: "update" - lines: "all" - content_spec: > - Keep this file as the hosted app factory and route-registration - coordinator only. Do not move business logic back into the root - entrypoint. - - file: "../cloud/packages/api/src/*-routes.ts" - action: "update" - lines: "all" - content_spec: > - Audit the existing flat domain route registrars and move any remaining - reusable business behavior into service/helper modules. - - file: "../cloud/packages/api/src/*-service.ts" - action: "update" - lines: "all" - content_spec: > - Keep domain behavior reusable and testable outside HTTP registration. - acceptance_criteria: - - id: "ac1_1" - type: "boundary" - description: "Hosted API root stays thin after route cleanup." - command: "test $(wc -l < packages/api/src/index.ts) -le 150" - cwd: "../cloud" - expected: "exit code 0" - - id: "ac1_2" - type: "boundary" - description: "Cleanup keeps the current flat route/service module layout." - command: "test ! -d packages/api/src/routes && test ! -d packages/api/src/services" - cwd: "../cloud" - expected: "exit code 0" - status: "completed" - - - id: "phase2" - name: "Consolidate OpenAPI builder ownership" - objective: "Keep OpenAPI document assembly delegated to helper, schema, and route catalog modules." - dependencies: - - "phase1" - changes: - - file: "../cloud/packages/api/src/openapi.ts" - action: "update" - lines: "all" - content_spec: > - Keep only top-level document assembly in this file. Route paths, - schemas, and reusable response helpers should stay in the existing - openapi-* modules. - - file: "../cloud/packages/api/src/openapi-*.ts" - action: "update" - lines: "all" - content_spec: > - Consolidate duplicated schema fragments, operation helpers, and route - catalog entries without changing the emitted OpenAPI surface. - acceptance_criteria: - - id: "ac2_1" - type: "test" - description: "Hosted API tests that assert OpenAPI shape stay green." - command: "pnpm exec vitest run packages/api/src/index.test.ts" - cwd: "../cloud" - expected: "exit code 0" - - id: "ac2_2" - type: "boundary" - description: "OpenAPI root stays a thin document assembler." - command: "test $(wc -l < packages/api/src/openapi.ts) -le 150" - cwd: "../cloud" - expected: "exit code 0" - status: "completed" - - - id: "phase3" - name: "Consolidate public-site model and render ownership" - objective: "Keep public-site data shaping, page composition, and HTML rendering in focused modules." - dependencies: - - "phase2" - changes: - - file: "../cloud/packages/api/src/public-site.ts" - action: "update" - lines: "all" - content_spec: > - Keep only top-level public-site orchestration in this file and leave - data, model, pages, activity, and render responsibilities in focused - public-site-* modules. - - file: "../cloud/packages/api/src/public-site-*.ts" - action: "update" - lines: "all" - content_spec: > - Consolidate any remaining duplicated page-model, feed-shaping, or HTML - rendering logic without changing server-rendered output. - acceptance_criteria: - - id: "ac3_1" - type: "test" - description: "Public-site and hosted boundary tests stay green." - command: "pnpm exec vitest run tests/public-site-install-count.test.ts tests/workspace-boundary.test.ts" - cwd: "../cloud" - expected: "exit code 0" - - id: "ac3_2" - type: "boundary" - description: "Hosted entrypoint files meet their final thin-entrypoint budgets." - command: "test $(wc -l < packages/api/src/index.ts) -le 150 && test $(wc -l < packages/api/src/openapi.ts) -le 150 && test $(wc -l < packages/api/src/public-site.ts) -le 100" - cwd: "../cloud" - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/api/src/index.ts 'packages/api/src/*-routes.ts' 'packages/api/src/*-service.ts'" - phase2: "git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/api/src/openapi.ts 'packages/api/src/openapi-*.ts'" - phase3: "git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/api/src/public-site.ts 'packages/api/src/public-site-*.ts'" - -metadata: - estimated_effort_hours: 8 - ai_model: "gpt-5" - tags: - - "cloud" - - "api" - - "openapi" - - "public-site" diff --git a/.ai/specs/archive/2026-04/runx-langchain-adoption-path.yaml b/.ai/specs/archive/2026-04/runx-langchain-adoption-path.yaml deleted file mode 100644 index c07321ef2..000000000 --- a/.ai/specs/archive/2026-04/runx-langchain-adoption-path.yaml +++ /dev/null @@ -1,221 +0,0 @@ -spec_version: "1.1" -task_id: "runx-langchain-adoption-path" -created: "2026-04-24T03:10:00Z" -updated: "2026-04-24T11:20:00Z" -status: "completed" - -task: - title: "Make LangChain a first-class adoption and tool-bridge path" - summary: > - Runx already exposes thin framework adapters, but the product plan still - treats LangChain as a late-stage sidecar. That undershoots the real - opportunity. LangChain is a major year-1 adoption surface because it brings - a large builder ecosystem, a broad prebuilt tool catalog, MCP adapters, and - an official integrations/discovery channel. Runx should keep a native - kernel while adding an optional LangChain bridge that expands distribution - and tool reach without surrendering receipts, approvals, or policy. - size: "large" - risk_level: "medium" - context: - packages: - - "packages/core" - - "packages/adapters" - - "packages/sdk-python" - - "../plans" - - "../docs" - files_impacted: - - path: "packages/core/src/sdk/framework-adapters.ts" - lines: "all" - reason: "Current thin framework bridge and response wrappers are the starting point." - - path: "packages/sdk-python/runx/framework_adapters.py" - lines: "all" - reason: "Python should stay aligned with the JS bridge semantics where feasible." - - path: "../plans/runx.md" - lines: "framework and adoption sections" - reason: "Top-level product positioning should treat LangChain as a near-term adoption lane." - - path: "../plans/sourcey-adoption-engine.md" - lines: "public capability and adoption loop sections" - reason: "Sourcey should have an explicit LangChain distribution path without depending on it." - - path: "../docs/framework-adapters.md" - lines: "all" - reason: "Framework docs should distinguish the thin host adapter from the broader LangChain tool bridge." - invariants: - - "Runx stays the native execution kernel for policy, receipts, approvals, and resume." - - "LangChain remains optional and additive, not a required core dependency." - - "Provider-native execution adapters for OpenAI and Anthropic remain first-class." - objectives: - - "Promote LangChain from a vague future integration to an explicit adoption strategy." - - "Define an optional package surface that exposes runx skills and chains as LangChain-callable tools." - - "Use LangChain as a distribution and ecosystem bridge without replacing runx orchestration." - scope: - in_scope: - - "Plan and package design for a LangChain bridge." - - "Adoption and demo pathways around Sourcey, docs PRs, and governed workflows." - - "Official docs, examples, and integration-channel positioning." - out_of_scope: - - "Rebuilding runx on LangGraph or any other orchestration framework." - - "Replacing the native receipt, policy, or approval model with LangChain semantics." - dependencies: - - "runx-runner-local-facade-final-split" - touchpoints: - - area: "Framework bridge" - description: "Existing thin host wrappers are the kernel-safe starting point." - - area: "Adoption strategy" - description: "The product plan should explicitly name LangChain as a distribution multiplier." - - area: "Sourcey dogfood path" - description: "Sourcey is the best first public workflow to prove the bridge." - risks: - - description: "LangChain enthusiasm could pull runx into framework dependence." - impact: "high" - mitigation: "Keep LangChain in optional bridge packages and preserve native provider adapters." - - description: "A vague integration plan could create docs noise without a clear product surface." - impact: "medium" - mitigation: "Specify concrete package APIs, demos, and official distribution goals." - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "The main runx plan names LangChain as a year-1 adoption and tool-bridge path." - - id: "dod2" - description: "The Sourcey adoption plan includes a LangChain distribution lane that does not replace the native pipeline." - - id: "dod3" - description: "A concrete implementation path exists for an optional LangChain bridge package and demo surface." - validation: - - id: "v1" - type: "boundary" - description: "The product plan explicitly distinguishes native kernel vs optional LangChain bridge." - command: "rg -n \"LangChain|native kernel|optional LangChain bridge|distribution\" ../plans/runx.md ../plans/sourcey-adoption-engine.md" - cwd: "." - expected: "exit code 0" - - id: "v2" - type: "boundary" - description: "The framework docs still present a thin bridge and do not imply LangChain owns runx execution." - command: "rg -n \"thin|bridge|optional|tool bridge|does not\" ../docs/framework-adapters.md" - cwd: "." - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-24T03:10:00Z" - actor: "user" - summary: "Said the LangChain pathway is huge and must be included in the runx adoption plan." - - timestamp: "2026-04-24T03:10:00Z" - actor: "agent" - summary: "Scoped LangChain as a distribution and tool-bridge strategy rather than a kernel dependency." - - timestamp: "2026-04-24T11:20:00Z" - actor: "agent" - summary: "Landed the LangChain-grounded seed reset and adoption-positioning updates across plans and framework docs." - -phases: - - id: "phase1" - name: "Align strategy and package boundaries" - objective: "Make the plan and docs say exactly what LangChain is and is not for runx." - changes: - - file: "../plans/runx.md" - action: "update" - lines: "adoption and framework sections" - content_spec: > - Treat LangChain as a year-1 adoption and tool-bridge path, while - keeping runx-native execution, receipts, and policy in the kernel. - - file: "../plans/sourcey-adoption-engine.md" - action: "update" - lines: "public capability and pipeline sections" - content_spec: > - Add a LangChain distribution lane for Sourcey-facing workflows that - packages the existing pipeline instead of replacing it. - - file: "../docs/framework-adapters.md" - action: "update" - lines: "LangChain and supported-surface sections" - content_spec: > - Clarify that the current bridge is a thin response-shaping adapter and - that the broader opportunity is an optional LangChain tool bridge. - acceptance_criteria: - - id: "ac1_1" - type: "boundary" - description: "Plans and framework docs all express the same kernel-vs-bridge model." - command: "rg -n \"optional LangChain|native kernel|tool bridge|distribution\" ../plans/runx.md ../plans/sourcey-adoption-engine.md ../docs/framework-adapters.md" - cwd: "." - expected: "exit code 0" - status: "completed" - - - id: "phase2" - name: "Define the optional LangChain bridge package" - objective: "Turn the strategy into a concrete implementation target for JS and Python consumers." - dependencies: - - "phase1" - changes: - - file: "packages/core/src/sdk/framework-adapters.ts" - action: "update" - lines: "all" - content_spec: > - Keep the current framework bridge stable while carving the LangChain - path into a clearer tool-oriented package surface and response model. - - file: "packages/sdk-python/runx/framework_adapters.py" - action: "update" - lines: "all" - content_spec: > - Preserve parity where Python needs the same pause/resume bridge - semantics for LangChain-adjacent hosts. - - file: "packages/langchain or packages/sdk-langchain" - action: "create" - lines: "all" - content_spec: > - Add an optional package that exposes runx skills/chains as - LangChain-callable tools and keeps resolution/approval pauses explicit. - acceptance_criteria: - - id: "ac2_1" - type: "compile" - description: "The optional LangChain bridge package builds without pulling LangChain into the kernel." - command: "pnpm build" - cwd: "." - expected: "exit code 0" - status: "completed" - - - id: "phase3" - name: "Ship adoption assets and prove the path" - objective: "Use Sourcey and one governed mutation flow to prove the LangChain lane publicly." - dependencies: - - "phase2" - changes: - - file: "../docs/framework-adapters.md" - action: "update" - lines: "examples and supported surface" - content_spec: > - Add official examples showing Sourcey and one PR-oriented workflow as - LangChain-callable governed runx operations. - - file: "../plans/sourcey-adoption-engine.md" - action: "update" - lines: "adoption loop and public capability details" - content_spec: > - Name the LangChain demo and docs pathway as a real adoption asset for - Sourcey rather than a hypothetical future idea. - - file: "examples or docs examples" - action: "create" - lines: "all" - content_spec: > - Provide a minimal public example that wraps `sourcey` and a PR-capable - workflow through the LangChain bridge with explicit pause/resume - handling. - acceptance_criteria: - - id: "ac3_1" - type: "boundary" - description: "The public story includes a real Sourcey-shaped LangChain example." - command: "rg -n \"Sourcey|sourcey|LangChain\" ../plans/sourcey-adoption-engine.md ../docs/framework-adapters.md" - cwd: "." - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- ../plans/runx.md ../plans/sourcey-adoption-engine.md ../docs/framework-adapters.md" - phase2: "git checkout HEAD -- packages/core/src/sdk/framework-adapters.ts packages/sdk-python/runx/framework_adapters.py packages/langchain packages/sdk-langchain" - phase3: "git checkout HEAD -- ../docs/framework-adapters.md ../plans/sourcey-adoption-engine.md examples docs/examples" - -metadata: - estimated_effort_hours: 10 - ai_model: "gpt-5" - tags: - - "langchain" - - "adoption" - - "frameworks" - - "distribution" diff --git a/.ai/specs/archive/2026-04/runx-local-sandbox-enforcement.yaml b/.ai/specs/archive/2026-04/runx-local-sandbox-enforcement.yaml deleted file mode 100644 index c2c24258c..000000000 --- a/.ai/specs/archive/2026-04/runx-local-sandbox-enforcement.yaml +++ /dev/null @@ -1,102 +0,0 @@ -spec_version: "1.1" -task_id: "runx-local-sandbox-enforcement" -created: "2026-04-25T15:35:00Z" -updated: "2026-04-26T08:18:08Z" -status: "completed" - -task: - title: "Enforce local sandbox policy instead of recording declarations only" - summary: > - Local cli-tool and MCP execution currently validate sandbox declarations and - record declared policy in receipts, but the spawned processes still receive - ambient filesystem, network, cwd, and environment access. Close that trust - gap or make unsupported enforcement explicit at admission time. - size: "large" - risk_level: "high" - context: - packages: - - "packages/core" - - "packages/adapters" - - "packages/cli" - files_impacted: - - path: "packages/core/src/policy/sandbox.ts" - lines: "all" - reason: "Separate policy validation from runtime enforcement capabilities." - - path: "packages/adapters/src/cli-tool/index.ts" - lines: "process spawn and environment assembly" - reason: "Apply cwd, env, filesystem, and network enforcement to local tools." - - path: "packages/core/src/mcp/index.ts" - lines: "process spawn" - reason: "Apply the same enforcement model to MCP stdio servers." - - path: "packages/core/src/receipts/index.ts" - lines: "sandbox metadata" - reason: "Receipts must report enforced, unsupported, or degraded guarantees truthfully." - objectives: - - "Define which sandbox modes are enforceable on local Node runtimes and which require host support." - - "Default local process environments to an explicit allowlist rather than full ambient env." - - "Constrain cwd and write access for readonly and workspace-write modes." - - "Make MCP server execution use the same sandbox enforcement path as cli-tool execution." - - "Fail closed or require approval when a declared sandbox cannot be enforced." - scope: - in_scope: - - "Local process execution for cli-tool and MCP sources." - - "Receipt metadata that distinguishes enforced controls from declared-only controls." - - "Focused tests for env leakage, cwd escape, write denial, and MCP parity." - out_of_scope: - - "Container orchestration or remote sandbox providers." - - "Changing skill authoring syntax unless required to express enforcement capabilities." - acceptance: - validation_profile: "strict" - definition_of_done: - - id: "dod1" - description: "A readonly cli-tool skill cannot write outside allowed paths during local execution." - - id: "dod2" - description: "Ambient secrets are not passed to cli-tool or MCP processes unless explicitly allowlisted." - - id: "dod3" - description: "Network-disabled declarations are either enforced or denied with a clear policy reason." - - id: "dod4" - description: "Receipts no longer claim declared-policy-only when controls were actually enforced, and they fail closed when controls are unsupported." - validation: - - id: "v1" - type: "compile" - description: "OSS typecheck stays green." - command: "pnpm typecheck" - cwd: "." - expected: "exit code 0" - - id: "v2" - type: "test" - description: "Sandbox coverage proves env, cwd, filesystem, and MCP behavior." - command: "pnpm exec vitest run tests/cli-tool-sandbox.test.ts tests/mcp-skill-runner.test.ts packages/adapters/src/cli-tool/index.test.ts packages/adapters/src/mcp/index.test.ts" - cwd: "." - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-25T15:35:00Z" - actor: "agent" - summary: "Created from deep review finding that sandbox policy is admission and metadata only." - - timestamp: "2026-04-25T16:18:00Z" - actor: "agent" - summary: "Added a shared local process sandbox preparation helper, default env allowlisting, cwd boundary checks, writable path admission for workspace-write, MCP/cli-tool spawn integration, and focused tests." - - timestamp: "2026-04-26T07:06:47Z" - actor: "agent" - summary: "Completed Linux Bubblewrap-backed local process enforcement for cli-tool and MCP, including readonly mount namespaces, workspace-write path mounts, private temp/input spill paths, network namespace isolation, MCP sandbox metadata, and focused coverage for write denial, env allowlisting, and host network blocking." - - timestamp: "2026-04-26T08:18:08Z" - actor: "agent" - summary: "Reviewed the Bubblewrap implementation after validation, fixed denied-admission temp cleanup ordering, and added coverage that PATH commands outside the mounted workspace are blocked unless unrestricted-local-dev is approved." - -phases: - - id: "phase1" - name: "Capability Matrix" - objective: "Define enforceable local sandbox capabilities and fail-closed behavior." - status: "completed" - - id: "phase2" - name: "Process Enforcement" - objective: "Implement shared cli-tool/MCP process sandbox assembly for cwd, env, filesystem, and network controls." - status: "completed" - - id: "phase3" - name: "Receipts And Tests" - objective: "Update receipt metadata and add regression coverage for enforcement and unsupported-control denial." - status: "completed" - -metadata: - estimated_effort_hours: 10 diff --git a/.ai/specs/archive/2026-04/runx-runner-local-facade-final-split.yaml b/.ai/specs/archive/2026-04/runx-runner-local-facade-final-split.yaml deleted file mode 100644 index 47ec70459..000000000 --- a/.ai/specs/archive/2026-04/runx-runner-local-facade-final-split.yaml +++ /dev/null @@ -1,248 +0,0 @@ -spec_version: "1.1" -task_id: "runx-runner-local-facade-final-split" -created: "2026-04-24T00:30:00Z" -updated: "2026-04-26T12:04:40Z" -status: "completed" - -task: - title: "Finish splitting runner-local into orchestration and runtime services" - summary: > - packages/core/src/runner-local/index.ts has improved substantially, but it - still owns too many real seams: orchestration, resume, receipt assembly, - adapter/auth bootstrap, and context handling. Finish the split so the root - file reads like a façade over focused runtime services. - size: "large" - risk_level: "high" - context: - packages: - - "packages/core" - - "packages/adapters" - - "packages/cli" - - "../cloud/packages/worker" - files_impacted: - - path: "packages/core/src/runner-local/index.ts" - lines: "all" - reason: "Reduce the root façade to orchestration entrypoints and exports." - - path: "packages/core/src/runner-local/*.ts" - lines: "all" - reason: "Extract orchestration, resume, receipt, and context services." - - path: "packages/adapters/src/runtime.ts" - lines: "all" - reason: "Shared runtime/bootstrap should be the default path for callers." - - path: "packages/cli/src" - lines: "all" - reason: "CLI should consume the shared runtime/bootstrap path rather than bespoke wiring." - - path: "../cloud/packages/worker/src/index.ts" - lines: "all" - reason: "Hosted worker should keep using the shared bootstrap path and avoid bespoke defaults." - invariants: - - "Runtime behavior and receipt semantics stay stable." - - "Resume behavior stays durable and replay-safe." - - "Callers should not need to know runner-local internals to bootstrap adapters and temp paths." - objectives: - - "Move remaining orchestration and resume logic out of runner-local/index.ts." - - "Split receipt/context assembly into focused modules." - - "Adopt one shared runtime/bootstrap path across CLI, hosted worker, and scripts." - scope: - in_scope: - - "runner-local modularization and bootstrap unification." - - "Caller cleanup that removes ad hoc adapter/env defaults." - out_of_scope: - - "Changing receipt schema semantics." - - "New execution features unrelated to the split." - dependencies: - - "runx-verification-foundation-and-fast-lanes" - touchpoints: - - area: "packages/core/src/runner-local/index.ts" - description: "Remaining OSS runtime monolith." - - area: "packages/adapters/src/runtime.ts" - description: "Shared runtime bootstrap surface." - - area: "../cloud/packages/worker/src/index.ts" - description: "Hosted execution caller that should consume the same bootstrap assumptions as CLI." - risks: - - description: "Execution orchestration changes can subtly break resume or receipt behavior." - impact: "high" - mitigation: "Keep focused runner, harness, and hosted-worker coverage green while moving seams." - - description: "Bootstrap unification may accidentally change default adapter coverage." - impact: "medium" - mitigation: "Treat adapters/runtime as the canonical default path and test hosted worker plus CLI callers." - acceptance: - validation_profile: "strict" - definition_of_done: - - id: "dod1" - description: "Graph orchestration, resume reconstruction, and receipt assembly live outside runner-local/index.ts." - - id: "dod2" - description: "CLI and hosted worker use the shared runtime/bootstrap path by default." - - id: "dod3" - description: "packages/core/src/runner-local/index.ts becomes a façade and stays at or below 1200 lines." - validation: - - id: "v1" - type: "compile" - description: "OSS typecheck stays green." - command: "pnpm typecheck" - cwd: "." - expected: "exit code 0" - - id: "v2" - type: "test" - description: "Core SDK and harness coverage stay green." - command: "pnpm exec vitest run packages/core/src/sdk/index.test.ts packages/core/src/harness/runner.test.ts" - cwd: "." - expected: "exit code 0" - - id: "v3" - type: "test" - description: "Hosted worker coverage stays green against the shared bootstrap path." - command: "pnpm exec vitest run packages/worker/src/index.test.ts" - cwd: "../cloud" - expected: "exit code 0" - - id: "v4" - type: "boundary" - description: "runner-local root meets the final façade budget and no longer owns graph orchestration internals." - command: "test $(wc -l < packages/core/src/runner-local/index.ts) -le 1200 && ! rg -n 'planSequentialGraphTransition|evaluateFanoutSync|runFanout|writeLocalGraphReceipt' packages/core/src/runner-local/index.ts" - cwd: "." - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-24T00:30:00Z" - actor: "user" - summary: "Asked for concrete execution specs covering the remaining path to ideal shape." - - timestamp: "2026-04-24T00:30:00Z" - actor: "agent" - summary: "Scoped the remaining runtime work to orchestration, resume, receipts, and bootstrap unification." - - timestamp: "2026-04-25T14:31:49Z" - actor: "agent" - summary: "Tightened the draft because the current runner-local root already passes the old line budget while still owning graph orchestration internals." - - timestamp: "2026-04-26T12:04:40Z" - actor: "agent" - summary: "Audited the current runner-local tree and found this final split already satisfied." - notes: > - packages/core/src/runner-local/index.ts is 994 lines, graph/fanout - orchestration lives in focused modules such as orchestrator.ts and - fanout.ts, and the root file no longer references - planSequentialGraphTransition, evaluateFanoutSync, runFanout, or - writeLocalGraphReceipt. - -phases: - - id: "phase1" - name: "Extract graph orchestration and resume services" - objective: "Move graph progression, fanout sync, transition planning, and resume reconstruction into dedicated modules." - changes: - - file: "packages/core/src/runner-local/index.ts" - action: "update" - lines: "all" - content_spec: > - Replace in-file orchestration and resume logic with imports from - focused services while keeping the public entrypoints stable. - - file: "packages/core/src/runner-local/orchestrator.ts" - action: "create" - lines: "all" - content_spec: > - Own single-step and graph-step orchestration, transition planning, and - fanout control flow wiring. The root index should call into this - module rather than importing transition planning and fanout internals. - - file: "packages/core/src/runner-local/resume.ts" - action: "create" - lines: "all" - content_spec: > - Own run resumption, ledger replay hydration, and selected-runner/input - carry-forward behavior. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "Core SDK and harness tests stay green after orchestration extraction." - command: "pnpm exec vitest run packages/core/src/sdk/index.test.ts packages/core/src/harness/runner.test.ts" - cwd: "." - expected: "exit code 0" - - id: "ac1_2" - type: "boundary" - description: "runner-local root no longer imports graph transition and fanout internals directly." - command: "! rg -n 'planSequentialGraphTransition|evaluateFanoutSync|runFanout' packages/core/src/runner-local/index.ts" - cwd: "." - expected: "exit code 0" - status: "completed" - - - id: "phase2" - name: "Extract receipt and context composition" - objective: "Move output shaping, receipt assembly, and context materialization into focused modules." - dependencies: - - "phase1" - changes: - - file: "packages/core/src/runner-local/index.ts" - action: "update" - lines: "all" - content_spec: > - Remove remaining receipt-building and context-shaping internals from - the root file. - - file: "packages/core/src/runner-local/receipt-composer.ts" - action: "create" - lines: "all" - content_spec: > - Own execution receipt assembly, graph-step receipt projection, and - terminal result shaping. - - file: "packages/core/src/runner-local/context-materializer.ts" - action: "create" - lines: "all" - content_spec: > - Own context-edge resolution, output-path lookup, and artifact - projection for graph execution. - acceptance_criteria: - - id: "ac2_1" - type: "boundary" - description: "runner-local root shrinks below 1500 lines after receipt and context extraction." - command: "test $(wc -l < packages/core/src/runner-local/index.ts) -le 1500" - cwd: "." - expected: "exit code 0" - status: "completed" - - - id: "phase3" - name: "Unify runtime bootstrap across callers" - objective: "Make adapters/runtime the default path for CLI, hosted worker, and scripts." - dependencies: - - "phase2" - changes: - - file: "packages/adapters/src/runtime.ts" - action: "update" - lines: "all" - content_spec: > - Expose the canonical default bootstrap API for adapters, env defaults, - and runtime paths. - - file: "packages/cli/src" - action: "update" - lines: "all" - content_spec: > - Replace remaining bespoke adapter/env/bootstrap wiring with the shared - runtime bootstrap surface. - - file: "../cloud/packages/worker/src/index.ts" - action: "update" - lines: "all" - content_spec: > - Keep hosted worker aligned with the same shared bootstrap behavior as - local callers. - acceptance_criteria: - - id: "ac3_1" - type: "test" - description: "Hosted worker and local runtime callers still execute through the shared bootstrap path." - command: "pnpm exec vitest run packages/worker/src/index.test.ts" - cwd: "../cloud" - expected: "exit code 0" - - id: "ac3_2" - type: "boundary" - description: "runner-local root meets the final façade target." - command: "test $(wc -l < packages/core/src/runner-local/index.ts) -le 1200 && ! rg -n 'planSequentialGraphTransition|evaluateFanoutSync|runFanout|writeLocalGraphReceipt' packages/core/src/runner-local/index.ts" - cwd: "." - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git -C /home/kam/dev/runx/oss checkout HEAD -- packages/core/src/runner-local/index.ts && git -C /home/kam/dev/runx/oss clean -f -- packages/core/src/runner-local/orchestrator.ts packages/core/src/runner-local/resume.ts" - phase2: "git -C /home/kam/dev/runx/oss checkout HEAD -- packages/core/src/runner-local/index.ts && git -C /home/kam/dev/runx/oss clean -f -- packages/core/src/runner-local/receipt-composer.ts packages/core/src/runner-local/context-materializer.ts" - phase3: "git -C /home/kam/dev/runx/oss checkout HEAD -- packages/adapters/src/runtime.ts packages/cli/src && git -C /home/kam/dev/runx/cloud checkout HEAD -- packages/worker/src/index.ts" - -metadata: - estimated_effort_hours: 8 - ai_model: "gpt-5" - tags: - - "runner-local" - - "runtime" - - "bootstrap" diff --git a/.ai/specs/archive/2026-04/runx-runner-local-kernel-split.yaml b/.ai/specs/archive/2026-04/runx-runner-local-kernel-split.yaml deleted file mode 100644 index 1ebd8b206..000000000 --- a/.ai/specs/archive/2026-04/runx-runner-local-kernel-split.yaml +++ /dev/null @@ -1,175 +0,0 @@ -spec_version: "1.1" -task_id: "runx-runner-local-kernel-split" -created: "2026-04-23T10:39:12Z" -updated: "2026-04-23T12:18:34Z" -status: "completed" -harden_status: "not_run" - -task: - title: "Split runner-local into execution modules" - summary: > - packages/core/src/runner-local/index.ts still centralizes graph execution, - ledger/reporting, context loading, resume reconstruction, and reflect - projection. Split along the real runtime seams so the entrypoint keeps - orchestration responsibilities while the support domains become focused - modules. - size: "medium" - risk_level: "medium" - context: - packages: - - "packages/core" - - "tests" - files_impacted: - - path: "packages/core/src/runner-local/index.ts" - lines: "graph execution orchestration, ledger helpers, context, reflect" - reason: "Shrink the main runtime entrypoint" - - path: "packages/core/src/runner-local/*.ts" - lines: "all" - reason: "New focused runtime modules" - - path: "tests/local-skill-runner.test.ts" - lines: "all" - reason: "Protect direct local-skill execution behavior" - - path: "tests/chain-runner.test.ts" - lines: "all" - reason: "Protect graph execution behavior" - - path: "tests/reflect-digest-skill.test.ts" - lines: "all" - reason: "Protect reflect projection path after extraction" - invariants: - - "runLocalSkill and runLocalGraph behavior stays stable" - - "Receipt and ledger semantics stay unchanged" - - "Reflect projection remains post-run and bounded" - objectives: - - "Extract graph ledger/reporting helpers into dedicated modules" - - "Extract context and historical context loading into dedicated modules" - - "Extract reflect projection helpers into a dedicated module" - - "Leave index.ts as orchestration and adapter assembly" - touchpoints: - - area: "packages/core/src/runner-local/index.ts" - description: "Current runtime monolith" - - area: "packages/core/src/runner-local" - description: "Target home for execution-support modules" - - area: "tests/*runner*" - description: "Behavioral protection for direct skill and graph execution" - acceptance: - definition_of_done: - - id: "dod1" - description: "Graph ledger/reporting helpers no longer live in runner-local/index.ts" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod2" - description: "Context and reflect helpers no longer live in runner-local/index.ts" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod3" - description: "packages/core/src/runner-local/index.ts stays below 3800 lines" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - validation: - - id: "v1" - type: "compile" - description: "OSS workspace typechecks after runtime extraction" - command: "pnpm typecheck" - expected: "exit code 0" - - id: "v2" - type: "test" - description: "Core runtime regression tests stay green" - command: "pnpm exec vitest run tests/local-skill-runner.test.ts tests/chain-runner.test.ts tests/reflect-digest-skill.test.ts" - expected: "exit code 0" - - id: "v3" - type: "boundary" - description: "runner-local root file budget drops under the target threshold" - command: "test $(wc -l < packages/core/src/runner-local/index.ts) -lt 3800" - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-23T10:39:12Z" - actor: "user" - summary: "Spec created via scafld new" - - timestamp: "2026-04-23T10:45:00Z" - actor: "agent" - summary: "Scoped runtime extraction around graph support, context loading, and reflect projection seams." - - timestamp: "2026-04-23T12:18:34Z" - actor: "agent" - summary: "Split runner-local support domains into context, graph-ledger, graph-reporting, and reflect modules, bringing the root runtime file under budget." - -phases: - - id: "phase1" - name: "Extract graph ledger and reporting helpers" - objective: "Remove graph ledger/reporting weight from the main runtime file." - changes: - - file: "packages/core/src/runner-local/index.ts" - action: "update" - lines: "appendGraph* helpers, step reporting, graph receipt helper glue" - content_spec: | - Replace in-file graph ledger/reporting helpers with imports from - focused modules. - - file: "packages/core/src/runner-local/graph-ledger.ts" - action: "create" - lines: "all" - content_spec: | - Own graph ledger append helpers and related receipt-link material. - - file: "packages/core/src/runner-local/graph-reporting.ts" - action: "create" - lines: "all" - content_spec: | - Own graph step start/wait/complete reporting and receipt projection - helpers. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "Graph runner behavior remains stable after ledger/report extraction" - command: "pnpm exec vitest run tests/chain-runner.test.ts" - expected: "exit code 0" - status: "completed" - - - id: "phase2" - name: "Extract context and reflect helpers" - objective: "Move context loading and post-run reflect logic into dedicated modules." - dependencies: - - "phase1" - changes: - - file: "packages/core/src/runner-local/index.ts" - action: "update" - lines: "context loading, historical context, reflect projection helpers" - content_spec: | - Replace in-file context and reflect helpers with imports from focused - modules and keep orchestration flow intact. - - file: "packages/core/src/runner-local/context.ts" - action: "create" - lines: "all" - content_spec: | - Own loadContext, loadHistoricalAgentContext, prepareAgentContext, and - related project document helpers. - - file: "packages/core/src/runner-local/reflect.ts" - action: "create" - lines: "all" - content_spec: | - Own post-run reflect policy checks, reflect projection construction, - and knowledge indexing glue. - acceptance_criteria: - - id: "ac2_1" - type: "test" - description: "Local skill and reflect behavior stays green" - command: "pnpm exec vitest run tests/local-skill-runner.test.ts tests/reflect-digest-skill.test.ts" - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- packages/core/src/runner-local/index.ts packages/core/src/runner-local/graph-ledger.ts packages/core/src/runner-local/graph-reporting.ts" - phase2: "git checkout HEAD -- packages/core/src/runner-local/index.ts packages/core/src/runner-local/context.ts packages/core/src/runner-local/reflect.ts" - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 2 - validation_depth: 1 - total: 9 - notes: "The runtime seams are now explicit modules and the root file budget is met; compile verification passed." - second_pass_performed: true - -deviations: - - description: "The targeted runner vitest commands in the spec were not rerun before completion." - reason: "User explicitly directed the work away from spending more time on tests." diff --git a/.ai/specs/archive/2026-04/runx-runtime-bootstrap.yaml b/.ai/specs/archive/2026-04/runx-runtime-bootstrap.yaml deleted file mode 100644 index 4379ef797..000000000 --- a/.ai/specs/archive/2026-04/runx-runtime-bootstrap.yaml +++ /dev/null @@ -1,151 +0,0 @@ -spec_version: "1.1" -task_id: "runx-runtime-bootstrap" -created: "2026-04-23T10:39:13Z" -updated: "2026-04-23T12:18:34Z" -status: "completed" -harden_status: "not_run" - -task: - title: "Add shared local-skill runtime bootstrap" - summary: > - Dogfood uncovered that raw runLocalSkill call sites are now easy to get - wrong after the core/adapters split. Introduce one shared helper for tests - and scripts so local execution consistently carries default adapters, - runtime directories, and env defaults. - size: "small" - risk_level: "low" - context: - packages: - - "tests" - - "scripts" - - "packages/adapters" - - "packages/core" - files_impacted: - - path: "tests/helpers" - lines: "all" - reason: "New shared runtime bootstrap helper" - - path: "scripts/dogfood-github-issue-to-pr.mjs" - lines: "all" - reason: "Use the shared runtime helper instead of open-coded adapter wiring" - - path: "tests/external-skill-proving-ground.test.ts" - lines: "all" - reason: "Use shared bootstrap for fresh-caller proving ground" - - path: "tests/reflect-digest-skill.test.ts" - lines: "all" - reason: "Use shared bootstrap for direct skill execution" - - path: "tests/issue-to-pr-chain.test.ts" - lines: "direct runLocalSkill call sites" - reason: "Use shared bootstrap for composite-skill execution" - invariants: - - "Default adapter assembly stays outside @runxhq/core" - - "Scripts and tests use the same bootstrap semantics" - - "Callers can still override env, receipt dirs, and adapters when needed" - objectives: - - "Create one helper that injects default adapters and sane local-runtime defaults" - - "Use that helper in dogfood and proving-ground paths" - - "Reduce repeated raw runLocalSkill setup in direct tests" - touchpoints: - - area: "tests/helpers" - description: "Shared local execution helper" - - area: "scripts/dogfood-github-issue-to-pr.mjs" - description: "Dogfood script that previously hand-wired adapters" - - area: "tests/*" - description: "Direct runLocalSkill tests that should use one runtime path" - acceptance: - definition_of_done: - - id: "dod1" - description: "Dogfood and proving-ground paths use one shared bootstrap" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - - id: "dod2" - description: "At least the direct skill tests that previously failed use the shared helper" - status: "done" - checked_at: "2026-04-23T12:18:34Z" - validation: - - id: "v1" - type: "compile" - description: "OSS workspace typechecks after bootstrap extraction" - command: "pnpm typecheck" - expected: "exit code 0" - - id: "v2" - type: "test" - description: "Direct skill regression tests stay green with the helper" - command: "pnpm exec vitest run tests/external-skill-proving-ground.test.ts tests/reflect-digest-skill.test.ts tests/issue-to-pr-chain.test.ts" - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-23T10:39:13Z" - actor: "user" - summary: "Spec created via scafld new" - - timestamp: "2026-04-23T10:45:00Z" - actor: "agent" - summary: "Scoped bootstrap work around shared adapter/env setup for tests and dogfood scripts." - - - timestamp: "2026-04-23T10:43:11Z" - actor: "cli" - summary: "Spec approved" - - timestamp: "2026-04-23T10:43:11Z" - actor: "cli" - summary: "Execution started" - - timestamp: "2026-04-23T12:18:34Z" - actor: "agent" - summary: "Completed shared runtime bootstrap extraction, adopted it in dogfood and direct skill tests, and verified OSS typecheck." -phases: - - id: "phase1" - name: "Create and adopt runtime bootstrap helper" - objective: "Introduce one shared local runtime helper and migrate the highest-value call sites." - changes: - - file: "tests/helpers/run-local-skill.ts" - action: "create" - lines: "all" - content_spec: | - Export helper utilities that wrap runLocalSkill with createDefaultSkillAdapters, - temp receipt/home dirs, and predictable env defaults. - - file: "scripts/dogfood-github-issue-to-pr.mjs" - action: "update" - lines: "runtime assembly" - content_spec: | - Replace open-coded adapter wiring with the shared helper or shared - runtime assembly utility. - - file: "tests/external-skill-proving-ground.test.ts" - action: "update" - lines: "runLocalSkill setup" - content_spec: | - Use the shared runtime helper instead of hand-assembling adapters and - directories inline. - - file: "tests/reflect-digest-skill.test.ts" - action: "update" - lines: "runLocalSkill setup" - content_spec: | - Use the shared runtime helper for direct skill execution. - - file: "tests/issue-to-pr-chain.test.ts" - action: "update" - lines: "direct runLocalSkill setup" - content_spec: | - Use the shared runtime helper at direct issue-to-pr call sites where - default adapter assembly is required. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "Shared-bootstrap call sites stay green" - command: "pnpm exec vitest run tests/external-skill-proving-ground.test.ts tests/reflect-digest-skill.test.ts tests/issue-to-pr-chain.test.ts" - expected: "exit code 0" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- tests/helpers/run-local-skill.ts scripts/dogfood-github-issue-to-pr.mjs tests/external-skill-proving-ground.test.ts tests/reflect-digest-skill.test.ts tests/issue-to-pr-chain.test.ts" - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 2 - validation_depth: 1 - total: 9 - notes: "Shared runtime bootstrap landed and the main OSS compile gate passed; targeted test reruns were skipped by direction." - second_pass_performed: true - -deviations: - - description: "Targeted vitest acceptance commands in the spec were not rerun before completion." - reason: "User explicitly prioritized structural work over spending more time on tests." diff --git a/.ai/specs/archive/2026-04/runx-sourcey-capability-pack-cutover.yaml b/.ai/specs/archive/2026-04/runx-sourcey-capability-pack-cutover.yaml deleted file mode 100644 index 9b1a3bd0b..000000000 --- a/.ai/specs/archive/2026-04/runx-sourcey-capability-pack-cutover.yaml +++ /dev/null @@ -1,325 +0,0 @@ -spec_version: "1.1" -task_id: "runx-sourcey-capability-pack-cutover" -created: "2026-04-25T10:10:00Z" -updated: "2026-04-25T15:50:00Z" -status: "completed" - -task: - title: "Cut Sourcey over to a clean runx capability-pack model" - summary: > - Sourcey currently proves the wrong extension shape: product-specific docs - outreach control lives inside the runx CLI as `runx docs ...`, while the - Sourcey repo shells out to those bespoke product commands. That makes the - engine own service nouns and leaves the example product consuming runx - through a privileged escape hatch instead of the generic execution model. - The clean cut is: runx keeps only generic runtime and invocation verbs, - while Sourcey owns its outreach operator flows as registered local - skills/chains/tools executed through normal runx skill invocation. - size: "large" - risk_level: "high" - context: - packages: - - "packages/cli" - - "packages/core" - - "packages/contracts" - - "../sourcey.com/skills" - - "../sourcey.com/.runx/tools" - - "../sourcey.com/README.md" - - "../sourcey.com/package.json" - files_impacted: - - path: "packages/cli/src/index.ts" - lines: "all" - reason: "Remove product-specific docs command parsing from the runx CLI." - - path: "packages/cli/src/dispatch.ts" - lines: "all" - reason: "Remove docs command dispatch and keep only generic engine verbs." - - path: "packages/cli/src/help.ts" - lines: "all" - reason: "Delete product-specific docs command help and replace it with generic extension guidance." - - path: "../sourcey.com/skills" - lines: "all" - reason: "Add Sourcey-owned operator skills/chains for outreach control flows." - - path: "../sourcey.com/.runx/tools" - lines: "all" - reason: "Move control-state, doctor, and dogfood behavior into Sourcey-owned tools." - - path: "../sourcey.com/README.md" - lines: "all" - reason: "Document the new generic runx invocation path for Sourcey skills." - - path: "../sourcey.com/package.json" - lines: "all" - reason: "Route outreach scripts through normal runx skill execution instead of a special docs subcommand." - invariants: - - "Runx owns generic runtime, thread, outbox, receipts, and handoff primitives only." - - "Sourcey owns docs/outreach product workflows as skills, chains, and tools in its own repo." - - "Operators execute Sourcey flows through generic runx skill invocation, not through runx product commands or a separate Sourcey CLI." - - "No unrelated in-flight issue-to-pr work in runx/oss is touched or reverted." - related_docs: - - "README.md" - - "packages/cli/src/index.ts" - - "packages/cli/src/dispatch.ts" - - "../sourcey.com/README.md" - - "../sourcey.com/skills/docs-pr/SKILL.md" - - "../sourcey.com/skills/docs-outreach/SKILL.md" - - "../sourcey.com/skills/docs-signal/SKILL.md" - cwd: "." - objectives: - - "Remove the Sourcey-specific docs command surface from runx." - - "Re-express Sourcey outreach operator flows as Sourcey-owned runx skills/chains/tools." - - "Keep runx as the generic execution engine and Sourcey as the capability pack." - - "Update docs, scripts, and dogfood so Sourcey consumes runx through the same public model other services would use." - scope: - in_scope: - - "Deleting `runx docs ...` parsing, dispatch, help, and tests from runx." - - "Porting status, bind-repo, rerun, push-pr, signal, doctor, and dogfood flows into Sourcey-owned skills/tools." - - "Updating Sourcey scripts and docs to invoke those flows through generic `runx ` execution." - - "Dogfooding the new Sourcey invocation path and recording UX gaps." - out_of_scope: - - "Changing generic runx thread/outbox/handoff contracts that are already correct." - - "Building a separate Sourcey CLI." - - "Adding another runx product namespace or plugin framework beyond the existing generic skill invocation path." - assumptions: - - "Local skill resolution through `runx ` in a repo with `skills//SKILL.md` is the intended extension seam." - - "Sourcey operator convenience can be achieved with Sourcey-owned wrapper skills rather than a special-case runx command." - - "Sourcey doctor/dogfood should continue to prove the review-first thread model after the cut." - touchpoints: - - area: "runx CLI" - description: "The engine CLI must shed product-specific Sourcey/docs nouns." - links: - - "packages/cli/src/index.ts" - - "packages/cli/src/dispatch.ts" - - "packages/cli/src/help.ts" - - area: "Sourcey operator surface" - description: "Sourcey needs its own operator chains for outreach status, rerun, push, signal, doctor, and dogfood." - links: - - "../sourcey.com/skills" - - "../sourcey.com/.runx/tools" - - area: "Documentation" - description: "Both repos must explain the new capability-pack model clearly." - links: - - "README.md" - - "../sourcey.com/README.md" - risks: - - description: "The cut could strand Sourcey without a usable operator path if the new wrapper skills are under-specified." - impact: "high" - mitigation: "Port the existing working control logic into Sourcey tools and dogfood every operator action before finishing." - - description: "The runx CLI could lose valuable generic capability if docs-specific code is deleted without preserving the underlying primitives elsewhere." - impact: "medium" - mitigation: "Delete only product orchestration; keep generic thread/handoff/runtime contracts untouched." - - description: "The new Sourcey invocation model could be technically pure but ergonomically bad." - impact: "medium" - mitigation: "Dogfood non-JSON operator paths and record concrete UX notes in docs and follow-up notes." - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "runx no longer parses, dispatches, or documents a `docs` product command." - - id: "dod2" - description: "Sourcey exposes outreach operator flows as Sourcey-owned skills/chains/tools executed through generic runx skill invocation." - - id: "dod3" - description: "Sourcey package scripts and docs no longer use `runx docs ...`." - - id: "dod4" - description: "Sourcey dogfood and doctor pass on the new invocation model." - - id: "dod5" - description: "The docs in both repos explain Sourcey as a runx capability pack instead of a runx subcommand." - validation: - - id: "v1" - type: "command" - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - description: "runx CLI parser/tests stay clean after removing the docs command." - - id: "v2" - type: "command" - command: "npm run verify:outreach" - description: "Sourcey outreach doctor/tests/dogfood pass on the new invocation path." - - id: "v3" - type: "command" - command: "npm exec runx -- outreach --runner status --issue sourcey/sourcey.com#issue/2 --json" - description: "A real Sourcey-owned operator skill can be invoked through generic runx execution." - notes: > - Canonical operator model after the cut: - - - runx: generic verbs such as direct skill execution, `surface`, `doctor`, - `resume`, `inspect`, `history`, and generic runtime contracts. - - Sourcey: a local `outreach` skill package with operator runners such as - `status`, `bind-repo`, `rerun`, `push-pr`, `signal`, `doctor`, and - `dogfood`. - - Invocation: `runx outreach --runner status --issue ...` from the - Sourcey repo, or `runx ./skills/outreach --runner status --issue ...` - from elsewhere. - -planning_log: - - timestamp: "2026-04-25T10:10:00Z" - actor: "user" - summary: "Rejected both a separate Sourcey CLI and a runx product subcommand; required Sourcey outreach to be a runx chain/capability pack." - - timestamp: "2026-04-25T10:10:00Z" - actor: "agent" - summary: "Chose the capability-pack model: generic runx engine, a Sourcey-owned outreach skill package with operator runners, and no `runx docs` command." - -phases: - - id: "phase1" - name: "Freeze the capability-pack architecture" - objective: "Record the end state before code moves begin." - changes: - - file: "README.md" - action: "update" - lines: "Local CLI and extension sections" - content_spec: > - Explain that services extend runx by shipping skills/tools/chains that - execute through generic runx verbs, and remove any implication that - product workflows belong inside the runx CLI itself. - - file: "../sourcey.com/README.md" - action: "update" - lines: "operator workflow sections" - content_spec: > - Reframe Sourcey as a runx capability pack and document the intended - generic invocation style using Sourcey-owned skills. - acceptance_criteria: - - id: "ac1_1" - type: "documentation" - description: "The architecture docs describe Sourcey as a capability pack, not a runx subcommand." - status: "completed" - - - id: "phase2" - name: "Delete the product command from runx" - objective: "Strip the Sourcey/docs command surface out of the engine CLI." - dependencies: - - "phase1" - changes: - - file: "packages/cli/src/index.ts" - action: "update" - lines: "all docs-command parsing and support" - content_spec: > - Remove docsAction parsing, remove `docs` from builtinRootCommands, - and leave only the generic skill invocation path. - - file: "packages/cli/src/dispatch.ts" - action: "update" - lines: "all docs-command dispatch" - content_spec: > - Remove handleDocsCommand/renderDocsResult routing and delete any dead - imports introduced solely for the docs command. - - file: "packages/cli/src/help.ts" - action: "update" - lines: "docs help sections" - content_spec: > - Remove `runx docs ...` examples and replace them with generic skill - invocation guidance where needed. - - file: "packages/cli/src/commands/docs*.ts" - action: "delete_or_stop_referencing" - lines: "all" - content_spec: > - Remove the product-specific docs command implementation from runx. - - file: "packages/cli/src/index.test.ts" - action: "update" - lines: "docs parser tests" - content_spec: > - Delete tests that assert a `docs` command and replace them with - coverage for generic local skill invocation where needed. - acceptance_criteria: - - id: "ac2_1" - type: "command" - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - description: "The runx CLI no longer recognizes a docs product command." - status: "completed" - - - id: "phase3" - name: "Port operator flows into Sourcey-owned tools and skills" - objective: "Make Sourcey consume runx through local capabilities instead of a privileged CLI path." - dependencies: - - "phase2" - changes: - - file: "../sourcey.com/.runx/tools/**" - action: "update_or_add" - lines: "control-state and verification helpers" - content_spec: > - Add Sourcey-owned tools for outreach control-state loading, repo - binding, rerun orchestration, push gating, signal packaging, doctor, - and dogfood as needed. Shared logic may live in local helper modules - under `.runx/tools`, but no implementation should depend on a runx - product command. - - file: "../sourcey.com/skills/outreach/{SKILL.md,X.yaml}" - action: "add" - lines: "all" - content_spec: > - Add one Sourcey-owned outreach skill package with multiple operator - runners such as status, bind-repo, rerun, push-pr, signal, doctor, - and dogfood. Use Sourcey-owned tools to orchestrate the existing - docs-scan/docs-build/docs-pr/docs-outreach/docs-signal flows while - keeping the operator surface as generic runx skill execution. - - file: "../sourcey.com/package.json" - action: "update" - lines: "scripts" - content_spec: > - Replace `runx docs ...` scripts with generic - `runx outreach --runner ` execution from the Sourcey repo - root. - acceptance_criteria: - - id: "ac3_1" - type: "command" - command: "npm exec runx -- outreach --runner doctor --json" - description: "A Sourcey-owned outreach runner can run through generic runx execution." - - id: "ac3_2" - type: "command" - command: "npm exec runx -- outreach --runner status --issue sourcey/sourcey.com#issue/2 --json" - description: "A Sourcey-owned issue control runner resolves through generic runx invocation." - status: "completed" - - - id: "phase4" - name: "Refresh docs, scripts, and proof loops" - objective: "Make the new model legible and proven end to end." - dependencies: - - "phase3" - changes: - - file: "../sourcey.com/README.md" - action: "update" - lines: "operator workflow sections" - content_spec: > - Document the new runx capability-pack invocation model with concrete - commands for doctor, dogfood, status, rerun, signal, bind-repo, and - push-pr using Sourcey-owned skills. - - file: "README.md" - action: "update" - lines: "extension sections" - content_spec: > - Show Sourcey as the example of a service extending runx through local - skills/tools/chains rather than a runx subcommand. - - file: "../sourcey.com/tests/**" - action: "update" - lines: "operator-surface and doctor expectations" - content_spec: > - Update tests and doctor assertions to reflect Sourcey-owned skills and - the absence of `runx docs ...`. - acceptance_criteria: - - id: "ac4_1" - type: "command" - command: "npm run verify:outreach" - description: "Sourcey doctor, tests, and dogfood all pass on the new model." - status: "completed" - -rollback: - strategy: "Revert the runx CLI removal commit and the Sourcey capability-pack commit independently if the cut exposes an operator gap." - commands: - - "git revert " - - "git revert " - -review: - status: "reviewed" - summary: > - The cut holds the intended boundary: runx keeps generic engine/runtime - primitives while Sourcey owns the outreach capability pack, its operator - runners, and its control-plane logic. - -self_eval: - status: "completed" - summary: > - Completed with one material follow-up caught during verification: published - @runxhq packages needed real semver dependency metadata plus packaged tool - runtimes in the CLI tarball. Sourcey now consumes packaged runx artifacts - correctly, and the live issue status path works through the installed CLI. - -metadata: - owner: "agent" - repository: "runx/oss" - tags: - - "architecture" - - "cli" - - "sourcey" - - "capability-pack" diff --git a/.ai/specs/archive/2026-04/runx-url-as-publish.yaml b/.ai/specs/archive/2026-04/runx-url-as-publish.yaml deleted file mode 100644 index ca0b6c25d..000000000 --- a/.ai/specs/archive/2026-04/runx-url-as-publish.yaml +++ /dev/null @@ -1,482 +0,0 @@ -spec_version: "1.1" -task_id: "runx-url-as-publish" -created: "2026-04-25T00:00:00Z" -updated: "2026-04-26T09:05:00Z" -status: "completed" - -task: - title: "URL-as-publish: zero-friction skill adoption with structural abuse defenses" - summary: > - The current /x/add flow requires four server-side handshakes before a skill - listing exists (github oauth → repo picker → enrollment record → indexer → - optional draft PR). That ceremony is the wrong shape for adoption. This - spec collapses publish into a single operation: "given a public github - repo URL, index every SKILL.md it contains and surface them as registry - listings — no account, no enrollment, no PR." OAuth becomes an optional - upgrade ("claim"), not a gate. Abuse is contained structurally — handle - derivation is bound to the github owner, the catalog browse view is a - curated subset of the listing universe, and rank is engagement-weighted — - rather than by friction at publish time. - - size: "large" - risk_level: "medium" - - context: - packages: - - "oss/packages/core/src/registry" - - "cloud/packages/api/src" - - "cloud/apps/web/src/pages/x" - - "cloud/packages/ui/src" - files_impacted: - - path: "cloud/packages/api/src/skill-indexer.ts" - lines: "all" - reason: "Shared indexing core (walk repo, parse SKILL.md, validate, derive digest, putVersion). Used by both UrlPublishService and the existing SelfPublishService — eliminates duplication." - - path: "cloud/packages/api/src/url-publish-service.ts" - lines: "all" - reason: "Anon publish transport on top of skill-indexer. No OAuth state." - - path: "cloud/packages/api/src/url-publish-routes.ts" - lines: "all" - reason: "POST /v1/index, GET /v1/index/:owner/:name (anonymous publish endpoints)." - - path: "cloud/packages/api/src/url-publish-model.ts" - lines: "all" - reason: "Indexer contract: IndexRequest, IndexResult, SkillSourceCandidate." - - path: "cloud/packages/api/src/rate-limit.ts" - lines: "all" - reason: "Rate-limit middleware keyed by github owner + IP." - - path: "cloud/packages/api/src/public-site-data.ts" - lines: "catalog filter helpers" - reason: "Catalog browse default filters by trust_tier + engagement floor." - - path: "oss/packages/core/src/registry/store.ts" - lines: "RegistrySourceMetadata, RegistrySkillVersion" - reason: "Add multi-skill-per-repo support: skill_path is already present; tighten semantics + uniqueness." - - path: "oss/packages/core/src/registry/github-source.ts" - lines: "GitHubSourceSnapshot, resolveGitHubSource" - reason: "Parameterize skill_path (currently hardcoded 'SKILL.md'). Required for multi-skill-per-repo. Default keeps existing single-skill callers backwards-compatible." - - path: "cloud/packages/api/src/url-publish-provider.ts" - lines: "all" - reason: "Unauthenticated github contents API + walker for the URL-publish flow. Distinct from SelfPublishProvider (oauth, draft-PRs)." - - path: "cloud/packages/api/src/self-publish-service.ts" - lines: "indexRepository" - reason: "Refactor to delegate validate/build/store/tombstone/evidence to skill-indexer.ts. Removes inline duplication." - - path: "oss/packages/core/src/registry/trust.ts" - lines: "engagement signal helpers" - reason: "Add non-publisher install count helper used by catalog rank." - - path: "oss/packages/cli/src/commands/add.ts" - lines: "all" - reason: "Replace OAuth-bound add flow with `runx add `." - - path: "cloud/apps/web/src/pages/x/add.astro" - lines: "all" - reason: "One-input redesign. OAuth path moves to /x/claim." - - path: "cloud/apps/web/src/pages/x/claim/index.astro" - lines: "all" - reason: "Optional upgrade flow (verified tier)." - - path: "cloud/packages/ui/src/AddSkillFlow" - lines: "all" - reason: "Replace stepper UI with single-input + result-card." - invariants: - - "Handle is bound to the github owner. `@stripe/x` requires a SKILL.md inside `github.com/stripe/*`. No exceptions." - - "Publish has no account requirement. OAuth is an optional upgrade for tier and private-repo support." - - "The registry is the source of truth for listings; the github repo is the source of truth for content. Indexing never copies markdown into a server-only namespace." - - "Catalog browse is a *view* over the listing universe. Spam can publish but cannot be promoted into browse without earned engagement." - - "Multiple SKILL.md files per repo are first-class. Listing key is `(github_owner, skill_name)`, not `(repo)`." - - "Existing OAuth-enrolled skills (SelfPublishEnrollmentRecord) keep working unchanged. New flow is additive." - - "All abuse defenses must default to *adoption-friendly* — friction lives in promotion, not publish." - related_docs: - - "cloud/packages/api/src/self-publish-model.ts" - - "oss/packages/core/src/registry/store.ts" - - "cloud/packages/api/src/public-site-model.ts" - - objectives: - - "Define an indexer contract that maps a public github URL to one or more registry listings without authentication." - - "Allow multiple skills per repo via per-SKILL.md indexing." - - "Encode the four hard structural abuse rules into the indexer (handle binding, SKILL.md validation, owner-scoped name uniqueness, generous rate limits)." - - "Add a tiered catalog visibility model so spam is invisible by default without friction at publish." - - "Ship the CLI command `runx add ` and the redesigned single-input `/x/add` page." - - "Keep OAuth-based self-publish working as the `/x/claim` upgrade path." - - "Avoid touching unrelated registry, run, or receipts code." - - scope: - in_scope: - - "URL-as-publish indexer service, model, and HTTP routes." - - "Multi-skill walk of the repo (root SKILL.md + `skills/*/SKILL.md`)." - - "Hard structural rules + per-owner + per-IP rate limiting." - - "Catalog browse filter: trust tier + engagement floor." - - "CLI `runx add `." - - "Redesigned `/x/add` page (single input, no OAuth)." - - "`/x/claim` route (oauth-upgrade)." - - "Tests across all of the above." - out_of_scope: - - "README badge SVG endpoint and embed UX (follow-on outer-ring spec)." - - "Receipt-as-share UI on the skill page (follow-on outer-ring spec)." - - "Automated `claim`/dispute resolution beyond first-publisher-wins." - - "Rewriting the existing SelfPublishService — it remains for OAuth-claimed listings." - - "Changes to runtime, harness, or run-control surfaces." - - decisions: - - "skill_id remains `/` — unchanged shape, but `name` may now come from a SKILL.md found at any indexed path inside the repo, not only at root." - - "Skill name uniqueness is per-owner. Two SKILL.md files in different repos owned by the same github user must declare distinct `name` fields, or the second one fails to index with a clear `name_taken_by_repo` error." - - "Trust tier on URL-publish defaults to `community`. `verified` requires a github oauth claim. `first_party` requires a runx-internal attestation (existing flow)." - - "Catalog browse default filter: `trust_tier in [first_party, verified] OR (trust_tier = community AND non_publisher_install_count >= 1)`. The 1-install floor is intentionally low; the goal is to keep manufactured-by-publisher listings out of browse, not to gatekeep real adoption." - - "Catalog rank: `engagement_score = non_publisher_install_count * tier_weight + recency_decay`. Tier weights: first_party=4, verified=2, community=1." - - "All non-claimed (community-tier) skill detail pages emit `` until they cross the engagement floor or are claimed. Kills SEO/affiliate spam vector." - - "Rate limits: per github owner = 10 indexes/day, per anonymous IP = 5 indexes/day. Reindex of an existing (owner, name, digest) tuple is free and does not consume budget. Only successful, distinct-content indexes count." - - "Indexer is idempotent on `(owner, name, content_digest)` — re-publishing the same content is a no-op write that refreshes `updated_at`." - - "Multi-skill walk paths (in priority order): `/SKILL.md`, `skills/*/SKILL.md`, `skills/*/*/SKILL.md` (max depth 3). Configurable via `runx.discover` field in repo-root `X.yaml` if present." - - "Profile resolution per skill: prefer co-located `X.yaml` next to the SKILL.md, fall back to repo-root `X.yaml`, fall back to legacy `.runx/X.yaml`." - - "No anonymous claim of github-owned handles. To publish under `@stripe`, the github API must show the SKILL.md sitting in a repo whose owner is `stripe`. We re-validate this on every reindex." - - "An anonymous URL-publish creates a listing visible at its permalink immediately. Catalog browse inclusion waits for either claim or the engagement floor." - - deliverables: - - "A URL-publish indexer service that takes a github repo URL and returns one or more `RegistrySkillVersion` records." - - "Public HTTP routes: `POST /v1/index`, `GET /v1/index/:owner/:name/status`." - - "Catalog list query updated to apply the trust+engagement filter by default, with `?include=all` to opt out." - - "`runx add ` CLI command writing into the local registry view and printing the resulting permalinks." - - "Redesigned `/x/add` Astro page using a single input + result card." - - "`/x/claim` Astro page wrapping the existing OAuth+enrollment flow, repurposed as a tier-upgrade rather than a publish gate." - - "Tests covering: handle binding rejection, multi-skill repo, name collision, rate limit, catalog filter, idempotent reindex, and a smoke test for each transport (CLI, HTTP, web)." - - assumptions: - - "Public github repos are reachable via the unauthenticated github contents API. We accept the public-API rate limit for the indexer and document the runtime cap." - - "SKILL.md and X.yaml validators already exist in oss/packages/core (used by the OAuth flow). We reuse them unchanged." - - "RegistrySkillVersion's existing `source_metadata.skill_path` and `publisher_handle` fields are sufficient to represent multi-skill-per-repo. No core schema additions required." - - risks: - - description: "github rate limits on the unauthenticated API hit batch indexers." - impact: "medium" - mitigation: "Indexer caches by `(repo, sha)`; reuses the github ETag for HEAD checks; backs off and surfaces a retryable error to the caller." - - description: "First-publisher-wins on a name lets a squatter take `@kam/research` from a real `@kam` who hasn't onboarded." - impact: "low" - mitigation: "Name is scoped to github owner. The squatter must already control `github.com/kam/*`. If `@kam` is the github user, only they can publish under that handle." - - description: "Catalog filter excludes legitimate brand-new skills until first install." - impact: "low" - mitigation: "Permalink and direct sharing always work. Catalog is for discovery; new-skill funnel is via creator-shared link → first install → catalog." - - description: "Existing SelfPublishEnrollmentRecord and the new URL-publish path could double-list the same skill." - impact: "medium" - mitigation: "Indexer checks for an existing enrollment record on the same `(owner, repo, skill_path)`. If one exists, it routes through the OAuth-aware path and treats the URL-publish as a refresh." - - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "POST /v1/index with a public github URL containing one SKILL.md returns a registry listing reachable at /x//." - - id: "dod2" - description: "POST /v1/index with a repo containing N SKILL.md files (root + skills/*/SKILL.md) returns N listings." - - id: "dod3" - description: "Indexing a SKILL.md whose `name` is already used by the same github owner in a different repo returns `name_taken_by_repo` with a hint." - - id: "dod4" - description: "Catalog browse default excludes community-tier listings with zero non-publisher installs. `?include=all` returns them." - - id: "dod5" - description: "Unclaimed community-tier skill pages emit `robots: noindex`." - - id: "dod6" - description: "Rate limit returns 429 after the per-owner or per-IP cap. Reindex-of-same-digest does not count against the cap." - - id: "dod7" - description: "`runx add github.com//` runs end-to-end without any auth, prints permalinks, and exits 0." - - id: "dod8" - description: "/x/add renders a single input field, accepts a github URL, and lands on a result card with permalinks. No OAuth modal appears." - - id: "dod9" - description: "/x/claim runs the existing OAuth+enrollment flow and upgrades the listing trust_tier from community → verified on success." - - id: "dod10" - description: "Existing OAuth-enrolled SelfPublishEnrollmentRecord listings remain reachable and unchanged." - validation: - - id: "v1" - type: "test" - description: "Indexer unit + integration tests pass." - command: "cd ../cloud && pnpm exec vitest run packages/api/src/url-publish-service.test.ts packages/api/src/index.test.ts" - expected: "All pass." - - id: "v2" - type: "test" - description: "CLI integration test for `runx add ` passes." - command: "pnpm exec vitest run packages/cli/src/commands/url-add.test.ts" - expected: "All pass." - - id: "v3" - type: "test" - description: "Web E2E for /x/add and /x/claim passes." - command: "cd ../cloud && pnpm build:web" - expected: "Build passes." - - id: "v4" - type: "boundary" - description: "No new public route writes without rate-limit middleware." - command: "rg -n 'POST /v1/index' cloud/packages/api/src | rg -v 'rate'" - expected: "No matches." - - constraints: - approvals_required: - - "registry_invariants" - - "runx_ai_surface_scope" - non_goals: - - "Renaming or restructuring the existing self-publish service." - - "Changing the runtime / sandbox / scope-grant model." - - "Designing the README badge SVG (separate spec)." - - info_sources: - - "oss/packages/core/src/registry/store.ts (RegistrySkillVersion shape — no changes required)" - - "cloud/packages/api/src/self-publish-model.ts (existing OAuth-bound flow remains)" - - "cloud/packages/api/src/public-site-model.ts (catalog list query)" - - "cloud/apps/web/src/pages/x/add.astro (current four-step UI being replaced)" - - notes: > - The reframe driving this spec: publishing is open; *being shown* is earned. - Anyone can publish a SKILL.md from a public github repo, no account needed. - The catalog browse view is a curated subset, ranked by real engagement - against the governed runtime. The runtime is the moat; publish is the - funnel. Hard structural rules contain the abuse vector for free - (handle == github owner, SKILL.md must validate, names unique per owner, - generous rate limits). Visibility tiering contains the rest. Friction is - not a substitute for governance — and governance is what runx already has. - -planning_log: - - timestamp: "2026-04-25T00:00:00Z" - actor: "agent" - summary: "Drafted URL-as-publish spec covering indexer, multi-skill walk, hard structural rules, visibility tiering, and CLI/web/api transports. Inner ring + claim flow only; badges and receipt-as-share UX deferred to outer-ring spec." - - timestamp: "2026-04-26T09:05:00Z" - actor: "codex" - summary: "Implemented URL-as-publish, single-input add UI, CLI URL add, API routes, rate limits, and trust-tier preservation; validated with cloud/OSS fast suites and builds." - -phases: - - id: "phase1" - name: "Hard structural rules + shared indexer + url-publish service" - objective: "Land the indexer contract, shared indexing core, rate-limit primitive, and the anon publish service. No UI yet." - changes: - - file: "cloud/packages/api/src/skill-indexer.ts" - action: "create" - lines: "all" - content_spec: | - Shared indexing core. Pure functions over a github contents fetcher. - Exports: - - walkSkillSources(repoFiles, discoverPaths): readonly SkillSourceCandidate[] - - validateSkillSource(candidate): { ok: true; parsed } | { ok: false; reason } - - buildRegistryVersion(candidate, owner, repo, ref, sha): RegistrySkillVersion - - DEFAULT_DISCOVER_PATHS: readonly ["/SKILL.md", "skills/*/SKILL.md", "skills/*/*/SKILL.md"] - Used by both UrlPublishService (anon) and SelfPublishService (oauth) — neither owns the indexing logic. - - file: "cloud/packages/api/src/url-publish-model.ts" - action: "create" - lines: "all" - content_spec: | - Export: - - IndexRequest { repo_url: string; ref?: string; requested_by?: { actor_kind: "anon" | "claimed"; actor_id?: string } } - - SkillSourceCandidate { skill_path: string; skill_name: string; markdown: string; profile_document?: string; content_digest: string } - - IndexResult { listings: readonly { owner: string; name: string; version: string; permalink: string; trust_tier: "community" | "verified" | "first_party" }[]; warnings: readonly string[] } - - IndexError discriminated union: { code: "handle_mismatch" | "skill_md_invalid" | "name_taken_by_repo" | "repo_unreachable" | "rate_limited"; detail: string; hint?: string } - - file: "cloud/packages/api/src/rate-limit.ts" - action: "create" - lines: "all" - content_spec: | - A small in-memory + persistable rate limiter keyed by: - - github_owner: max 10 successful indexes / 24h - - source_ip: max 5 successful indexes / 24h - Reindex of an existing (owner, name, digest) tuple is free and does not consume budget. - Failed validation does not consume budget (only successful, distinct-content indexes count). - Exposed as Hono middleware for the index routes. - - file: "cloud/packages/api/src/url-publish-service.ts" - action: "create" - lines: "all" - content_spec: | - UrlPublishService.index(request): IndexResult. - Steps: - 1. Parse repo_url into (owner, repo). Reject non-github URLs. - 2. Hit github contents API (unauth) for the resolved ref. 404 → repo_unreachable. - 3. Walk discover paths: /SKILL.md, skills/*/SKILL.md, skills/*/*/SKILL.md (max depth 3). - If repo-root X.yaml has runx.discover, override the walk paths. - 4. For each SKILL.md: parse + validate. Skip with warning if invalid (no hard fail unless zero valid skills). - 5. For each valid SkillSourceCandidate: enforce handle == repo owner. Enforce name unique per owner: query registry by (owner, name); if a record exists with a different (repo, skill_path), return name_taken_by_repo. - 6. putVersion into RegistryStore with trust_tier=community, source_metadata.skill_path set, publisher_handle=undefined. - 7. Return IndexResult. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "Service rejects non-github URLs." - - id: "ac1_2" - type: "test" - description: "Service returns N listings for a repo with N SKILL.md files at supported paths." - - id: "ac1_3" - type: "test" - description: "Service rejects a SKILL.md whose `owner` doesn't match the repo owner." - - id: "ac1_4" - type: "test" - description: "Same-digest reindex returns the existing version and does not consume rate budget." - status: "completed" - - - id: "phase2" - name: "Public HTTP routes" - objective: "Expose the indexer as anonymous endpoints with rate limiting." - dependencies: - - "phase1" - changes: - - file: "cloud/packages/api/src/url-publish-routes.ts" - action: "create" - lines: "all" - content_spec: | - POST /v1/index — body: IndexRequest. Wraps UrlPublishService.index. Returns IndexResult or IndexError. - GET /v1/index/:owner/:name/status — returns { trust_tier, latest_digest, in_catalog: boolean, non_publisher_install_count }. - Both routes mount the abuse-rate-limit middleware. - - file: "cloud/packages/api/src/index.ts" - action: "update" - lines: "route registration" - content_spec: "Register url-publish-routes alongside existing self-publish-routes." - acceptance_criteria: - - id: "ac2_1" - type: "test" - description: "POST /v1/index 200 with one SKILL.md." - - id: "ac2_2" - type: "test" - description: "POST /v1/index 429 after the per-owner cap." - - id: "ac2_3" - type: "boundary" - description: "No new public POST without rate-limit middleware." - command: "rg -n 'app\\.post\\(\"/v1/index' cloud/packages/api/src/url-publish-routes.ts | rg 'rateLimit'" - expected: "Match found." - status: "completed" - - - id: "phase3" - name: "Catalog visibility tiering" - objective: "Make spam invisible without friction at publish." - dependencies: - - "phase1" - changes: - - file: "cloud/packages/api/src/public-site-data.ts" - action: "update" - lines: "listSkills helpers" - content_spec: | - Add a default catalog filter: - trust_tier in [first_party, verified] - OR (trust_tier == community AND non_publisher_install_count >= 1) - Honour `?include=all` to bypass for admin/debug. - Catalog rank: engagement_score = non_publisher_install_count * tier_weight + recency_decay. - Tier weights: first_party=4, verified=2, community=1. - - file: "cloud/packages/api/src/public-site-render.ts" - action: "update" - lines: "skill detail head metadata" - content_spec: | - Emit when: - trust_tier == community AND non_publisher_install_count == 0 AND not claimed. - - file: "oss/packages/core/src/registry/trust.ts" - action: "update" - lines: "engagement helpers" - content_spec: | - Add deriveEngagementScore(version, installSignals): number. - installSignals supplies { non_publisher_install_count, last_install_at }. - acceptance_criteria: - - id: "ac3_1" - type: "test" - description: "Default catalog list excludes community+0-install listings; ?include=all returns them." - - id: "ac3_2" - type: "test" - description: "Skill detail page sets noindex meta on community+0-install." - - id: "ac3_3" - type: "test" - description: "engagement_score sorts first_party > verified > community at equal install counts." - status: "completed" - - - id: "phase4" - name: "CLI: runx add " - objective: "Replace the OAuth-bound add path with the URL-publish transport." - dependencies: - - "phase2" - changes: - - file: "oss/packages/cli/src/commands/add.ts" - action: "update" - lines: "all" - content_spec: | - Detect URL form vs. registry-id form: - - URL: github.com//[?ref=...] → POST /v1/index, print resulting permalinks + claim hint. - - registry-id: existing install path unchanged. - Suppress OAuth prompts entirely on the URL form. Output: - published → https://runx.ai/x// - run it: runx run @/ - claim it: runx claim @/ - acceptance_criteria: - - id: "ac4_1" - type: "test" - description: "`runx add github.com/test/sample` indexes and prints expected permalinks." - - id: "ac4_2" - type: "test" - description: "`runx add @owner/name` (registry-id form) still uses the existing install path." - status: "completed" - - - id: "phase5" - name: "Web: redesigned /x/add" - objective: "Single-input page replacing the four-step stepper." - dependencies: - - "phase2" - changes: - - file: "cloud/apps/web/src/pages/x/add.astro" - action: "update" - lines: "all" - content_spec: | - Replace AddSkillFlow stepper with a single input + submit hitting /v1/index via fetch. - On success: render a result card per listing with the permalink and a "claim this listing" link to /x/claim?owner=&name=. - Strip OAuth-related copy, repo-picker, and draft-PR FAQ items. Keep the FAQ section but rewrite for the no-OAuth flow. - - file: "cloud/packages/ui/src/SingleInputPublish" - action: "create" - lines: "all" - content_spec: | - New component: input + submit hitting /v1/index, renders a result-card list per listing. - - file: "cloud/packages/ui/src/AddSkillFlow" - action: "delete" - lines: "all" - content_spec: | - Old stepper component (OAuth + repo picker + draft PR) is removed entirely. - /x/add now imports SingleInputPublish; /x/claim uses the existing self-publish flow. - - file: "cloud/packages/ui/src/index.ts" - action: "update" - lines: "exports" - content_spec: | - Drop AddSkillFlow export, add SingleInputPublish export. - acceptance_criteria: - - id: "ac5_1" - type: "test" - description: "/x/add renders one input, no OAuth UI." - - id: "ac5_2" - type: "test" - description: "Submitting a github URL renders N result cards for an N-skill repo." - status: "completed" - - - id: "phase6" - name: "Web: /x/claim (oauth-as-upgrade)" - objective: "Repurpose the existing OAuth flow as an optional tier upgrade, not a publish gate." - dependencies: - - "phase3" - changes: - - file: "cloud/apps/web/src/pages/x/claim/index.astro" - action: "create" - lines: "all" - content_spec: | - Reuse the existing self-publish OAuth + enrollment flow, but: - - Frame copy as "claim a listing" not "publish a skill." - - Pre-populate the target listing from query params (?owner=&name=). - - On success, upgrade the listing's trust_tier from community → verified and link the listing to the SelfPublishEnrollmentRecord. - - file: "cloud/packages/api/src/self-publish-service.ts" - action: "update" - lines: "claim entrypoint" - content_spec: | - Add claimListing(actor, owner, name): SelfPublishEnrollmentRecord. - Validates that the actor's github identity matches the listing owner. - Promotes trust_tier to verified across **all existing RegistrySkillVersion records** for `(owner, name)`, not just future versions. - Idempotent: re-running claim is a no-op write that refreshes updated_at. - Links the new SelfPublishEnrollmentRecord to the listing's source_metadata.publisher_handle. - acceptance_criteria: - - id: "ac6_1" - type: "test" - description: "Claim flow upgrades a community listing to verified." - - id: "ac6_2" - type: "test" - description: "Claim by a github actor whose identity doesn't match the listing owner is rejected." - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git rm cloud/packages/api/src/url-publish-{model,service}.ts cloud/packages/api/src/rate-limit.ts" - phase2: "git rm cloud/packages/api/src/url-publish-routes.ts && git checkout HEAD -- cloud/packages/api/src/index.ts" - phase3: "git checkout HEAD -- cloud/packages/api/src/public-site-data.ts cloud/packages/api/src/public-site-render.ts oss/packages/core/src/registry/trust.ts" - phase4: "git checkout HEAD -- oss/packages/cli/src/commands/add.ts" - phase5: "git checkout HEAD -- cloud/apps/web/src/pages/x/add.astro cloud/packages/ui/src/AddSkillFlow" - phase6: "git rm -r cloud/apps/web/src/pages/x/claim && git checkout HEAD -- cloud/packages/api/src/self-publish-service.ts" - -metadata: - estimated_effort_hours: 14 - tags: - - "registry" - - "adoption" - - "abuse-defense" - - "publish" diff --git a/.ai/specs/archive/2026-04/runx-verification-foundation-and-fast-lanes.yaml b/.ai/specs/archive/2026-04/runx-verification-foundation-and-fast-lanes.yaml deleted file mode 100644 index 2af0dec91..000000000 --- a/.ai/specs/archive/2026-04/runx-verification-foundation-and-fast-lanes.yaml +++ /dev/null @@ -1,228 +0,0 @@ -spec_version: "1.1" -task_id: "runx-verification-foundation-and-fast-lanes" -created: "2026-04-24T00:20:00Z" -updated: "2026-04-23T15:27:08Z" -status: "completed" - -task: - title: "Restore trustworthy fast verification and structural lanes" - summary: > - The refactor pace is ahead of reliable verification. OSS typecheck is green, - but direct Vitest invocation still misses workspace alias resolution, and - there is no single cheap lane that proves the refactor-safe subset across - oss and cloud. Make fast verification explicit, deterministic, and cheap - enough to run before every structural change. - size: "medium" - risk_level: "high" - context: - packages: - - "packages/cli" - - "packages/core" - - "tests" - - "vitest.config.ts" - - "vitest.fast.config.ts" - - "../cloud/tests" - - "../cloud/package.json" - files_impacted: - - path: "vitest.config.ts" - lines: "all" - reason: "Direct Vitest runs need to resolve @runxhq/* workspace aliases." - - path: "vitest.fast.config.ts" - lines: "all" - reason: "The fast lane should target the structural safety subset intentionally." - - path: "package.json" - lines: "all" - reason: "Expose a stable fast verification entrypoint in oss." - - path: "scripts/verify-fast.mjs" - lines: "all" - reason: "One command should orchestrate the expected fast checks." - - path: "../cloud/package.json" - lines: "all" - reason: "Cloud should expose an equally explicit fast lane." - - path: "../cloud/tests/workspace-boundary.test.ts" - lines: "all" - reason: "Structural checks belong in the fast lane, not as tribal knowledge." - invariants: - - "Fast verification must run from a clean checkout without manual path patching." - - "Structural checks must stay cheap and deterministic." - - "No budget or boundary rule may be loosened only to make the lane pass." - objectives: - - "Fix OSS test runner path resolution so direct Vitest invocation is trustworthy." - - "Define explicit fast verification entrypoints for oss and cloud." - - "Bundle structural budgets and boundary checks into the fast lane." - scope: - in_scope: - - "Vitest path resolution and fast-lane scripts for oss and cloud." - - "Structural checks that should always run before refactors land." - out_of_scope: - - "Broad end-to-end or slow integration coverage." - - "Major product refactors outside verification and guardrails." - assumptions: - - "The intended fast lane is smaller than the full test suite but must cover architecture regressions." - touchpoints: - - area: "oss Vitest configs" - description: "Direct test execution must honor workspace aliases." - - area: "workspace scripts" - description: "Refactor-safe commands should be explicit and reusable by CI." - - area: "cloud structural tests" - description: "Boundary and hot-file budgets should be part of the default fast pass." - risks: - - description: "Alias fixes may hide real packaging problems if they diverge from runtime resolution." - impact: "medium" - mitigation: "Keep Vitest aliases aligned with tsconfig paths and package exports." - - description: "A too-broad fast lane will be skipped in practice." - impact: "high" - mitigation: "Keep the lane intentionally small and structural." - acceptance: - validation_profile: "strict" - definition_of_done: - - id: "dod1" - description: "Direct OSS Vitest invocation resolves @runxhq/* imports without manual setup." - - id: "dod2" - description: "oss and cloud each expose a stable fast verification entrypoint." - - id: "dod3" - description: "Structural budgets and boundary checks are included in the fast lane." - validation: - - id: "v1" - type: "compile" - description: "OSS still typechecks after test-runner and script changes." - command: "pnpm typecheck" - cwd: "." - expected: "exit code 0" - - id: "v2" - type: "test" - description: "Direct CLI Vitest invocation resolves workspace aliases." - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - cwd: "." - expected: "exit code 0" - - id: "v3" - type: "test" - description: "OSS fast lane passes." - command: "pnpm test:fast" - cwd: "." - expected: "exit code 0" - - id: "v4" - type: "test" - description: "Cloud fast lane passes." - command: "pnpm test:fast" - cwd: "../cloud" - expected: "exit code 0" - -planning_log: - - timestamp: "2026-04-24T00:20:00Z" - actor: "user" - summary: "Requested a concrete execution-spec set for the remaining path to ideal shape." - - timestamp: "2026-04-24T00:20:00Z" - actor: "agent" - summary: "Identified verification credibility as the first unblocker because direct OSS Vitest invocation still fails on workspace alias resolution." - -phases: - - id: "phase1" - name: "Fix OSS workspace-aware test resolution" - objective: "Make direct Vitest execution resolve @runxhq/* aliases the same way typecheck does." - changes: - - file: "vitest.config.ts" - action: "update" - lines: "all" - content_spec: > - Add workspace alias resolution through tsconfig-aware or explicit alias - wiring so tests can import @runxhq/* packages directly. - - file: "vitest.fast.config.ts" - action: "update" - lines: "all" - content_spec: > - Apply the same alias handling to the fast config so the short lane and - direct Vitest invocation behave consistently. - acceptance_criteria: - - id: "ac1_1" - type: "test" - description: "CLI index test file resolves contracts imports directly." - command: "pnpm exec vitest run packages/cli/src/index.test.ts" - cwd: "." - expected: "exit code 0" - status: "pending" - - - id: "phase2" - name: "Define explicit fast verification entrypoints" - objective: "Expose one stable command per workspace that developers and CI can run without guessing." - dependencies: - - "phase1" - changes: - - file: "package.json" - action: "update" - lines: "all" - content_spec: > - Add or tighten fast verification scripts so oss has one intentional - refactor-safe entrypoint. - - file: "../cloud/package.json" - action: "update" - lines: "all" - content_spec: > - Ensure cloud exposes a similarly narrow fast verification script. - - file: "scripts/verify-fast.mjs" - action: "create" - lines: "all" - content_spec: > - Orchestrate the required fast checks and present a small, predictable - failure surface for local use and CI reuse. - acceptance_criteria: - - id: "ac2_1" - type: "test" - description: "OSS fast lane passes." - command: "pnpm test:fast" - cwd: "." - expected: "exit code 0" - - id: "ac2_2" - type: "test" - description: "Cloud fast lane passes." - command: "pnpm test:fast" - cwd: "../cloud" - expected: "exit code 0" - status: "pending" - - - id: "phase3" - name: "Bundle structural checks into the fast lane" - objective: "Make budgets and boundary checks part of the default fast verification path." - dependencies: - - "phase2" - changes: - - file: "../cloud/tests/workspace-boundary.test.ts" - action: "update" - lines: "all" - content_spec: > - Keep structural boundaries and file budgets covered by a cheap, - always-on fast test surface. - - file: "packages/cli/src/commands/doctor.ts" - action: "update" - lines: "all" - content_spec: > - Align doctor output and fast-lane expectations so the same budgets are - enforced consistently. - - file: "README.md" - action: "update" - lines: "all" - content_spec: > - Document the required fast verification path for structural work. - acceptance_criteria: - - id: "ac3_1" - type: "test" - description: "Fast lane includes structural checks rather than relying on ad hoc commands." - command: "pnpm test:fast" - cwd: "." - expected: "exit code 0 with structural checks exercised" - status: "pending" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- vitest.config.ts vitest.fast.config.ts" - phase2: "git checkout HEAD -- package.json ../cloud/package.json scripts/verify-fast.mjs" - phase3: "git checkout HEAD -- README.md packages/cli/src/commands/doctor.ts ../cloud/tests/workspace-boundary.test.ts" - -metadata: - estimated_effort_hours: 4 - ai_model: "gpt-5" - tags: - - "verification" - - "vitest" - - "guardrails" diff --git a/.ai/specs/examples/add-error-codes.yaml b/.ai/specs/examples/add-error-codes.yaml deleted file mode 100644 index f0e91ee8b..000000000 --- a/.ai/specs/examples/add-error-codes.yaml +++ /dev/null @@ -1,365 +0,0 @@ -# scafld Example Spec — Complete reference showing every schema field -# See .ai/schemas/spec.json for the formal definition - -spec_version: "1.1" -task_id: "add-error-codes" -created: "2026-02-18T09:15:00Z" -updated: "2026-02-18T14:42:00Z" -status: "completed" - -task: - title: "Add typed error codes to document processing module" - summary: > - The document processor uses unstructured string errors, making it difficult for - callers to programmatically handle failures. Introduce a typed error code enum - and structured error class so consumers can match on specific failure modes. - size: "small" - risk_level: "medium" - context: - packages: - - "src/services/documents" - - "src/errors" - files_impacted: - - path: "src/errors/codes.ts" - lines: "all" - reason: "New file defining DocumentErrorCode enum and error map" - - path: "src/errors/document-error.ts" - lines: "all" - reason: "New DocumentProcessingError class using typed codes" - - path: "src/services/documents/processor.ts" - lines: "45-120" - reason: "Replace string throws with DocumentProcessingError instances" - - path: "src/services/documents/processor.test.ts" - lines: "all" - reason: "Update assertions to check error codes instead of message strings" - invariants: - - "domain_boundaries" - - "error_envelope" - related_docs: - - "docs/error-handling.md" - - "docs/architecture/service-layer.md" - objectives: - - "Define a DocumentErrorCode enum covering all known failure modes" - - "Create a structured error class that carries code, message, and context" - - "Migrate processor.ts from string throws to typed errors" - scope: - in_scope: - - "Document processor error paths" - - "Unit tests for error scenarios" - out_of_scope: - - "Other service modules (auth, billing)" - - "HTTP error response mapping (handled by controller layer)" - - "Error monitoring/alerting integration" - dependencies: - - "No external dependencies required" - assumptions: - - "Existing error helper utilities in src/errors/ are compatible with subclassing" - - "No downstream consumers rely on exact error message strings for control flow" - touchpoints: - - area: "src/errors" - description: "New error code enum and DocumentProcessingError class" - owners: - - "backend-team" - links: - - "https://internal.wiki/error-handling-standards" - - area: "src/services/documents/processor.ts" - description: "Replace raw throws with typed error instances" - owners: - - "documents-team" - - area: "src/services/documents/processor.test.ts" - description: "Update test assertions to verify error codes" - links: - - "https://internal.wiki/testing-conventions" - risks: - - description: "Downstream callers may catch generic Error and miss new type" - impact: "low" - mitigation: "DocumentProcessingError extends Error, so existing catch blocks still work" - - description: "Incomplete coverage of error paths in processor.ts" - impact: "medium" - mitigation: "Grep for all throw statements before and after migration to ensure full coverage" - acceptance: - validation_profile: "standard" - definition_of_done: - - id: "dod1" - description: "DocumentErrorCode enum covers all processor failure modes" - status: "done" - checked_at: "2026-02-18T13:20:00Z" - notes: "8 error codes identified matching 8 throw sites in processor.ts" - - id: "dod2" - description: "All throw statements in processor.ts use DocumentProcessingError" - status: "done" - checked_at: "2026-02-18T14:05:00Z" - notes: "Verified via grep: 0 raw Error throws remain" - - id: "dod3" - description: "Tests assert on error codes, not message strings" - status: "done" - checked_at: "2026-02-18T14:30:00Z" - - id: "dod4" - description: "No regressions in existing test suite" - status: "done" - checked_at: "2026-02-18T14:35:00Z" - notes: "Full suite: 142 passed, 0 failed" - validation: - - id: "v1" - type: "compile" - description: "Project compiles with no type errors" - command: "npm run build" - expected: "Exit code 0, no type errors" - - id: "v2" - type: "test" - description: "All unit tests pass including updated error assertions" - command: "npm test -- --filter documents" - expected: "All tests pass" - - id: "v3" - type: "boundary" - description: "No throw of raw Error or string in processor.ts" - command: "rg 'throw new Error\\|throw \"' src/services/documents/processor.ts" - expected: "No matches found" - - id: "v4" - type: "security" - description: "No hardcoded secrets in changed files" - command: "rg -i '(password|secret|api[_-]?key)\\s*=\\s*[\"'']\\w' src/errors/ src/services/documents/" - expected: "No matches found" - constraints: - approvals_required: - - "error_envelope" - non_goals: - - "Refactoring the processor's happy path logic" - - "Adding error codes to other modules" - info_sources: - - "docs/error-handling.md" - - "https://internal.wiki/error-handling-standards" - - "src/errors/base-error.ts (existing base class)" - notes: > - Chose a flat enum over a class hierarchy to keep things simple. The error code - enum can be extended later when other modules adopt the same pattern. Considered - using numeric codes but string enums are more readable in logs and debuggers. - -planning_log: - - timestamp: "2026-02-18T09:15:00Z" - actor: "agent" - summary: "Identified processor.ts as primary target. Found 8 throw statements using raw strings." - notes: "Searched with: rg 'throw new Error' src/services/documents/" - - timestamp: "2026-02-18T09:40:00Z" - actor: "agent" - summary: "Confirmed src/errors/ has base helpers. Proposed enum + error class approach." - notes: "BaseError class exists at src/errors/base-error.ts with code property pattern" - - timestamp: "2026-02-18T10:05:00Z" - actor: "user" - summary: "User confirmed no schema changes needed. No downstream string matching on error messages." - - timestamp: "2026-02-18T10:30:00Z" - actor: "agent" - summary: "Locked three-phase plan: define codes, migrate processor, update tests. Spec ready for review." - notes: "Moved from two-phase to three-phase after realizing test updates are substantial enough to warrant isolation" - -phases: - - id: "phase1" - name: "Define error codes and error class" - objective: "Create the DocumentErrorCode enum and DocumentProcessingError class in src/errors/" - changes: - - file: "src/errors/codes.ts" - action: "create" - lines: "all" - content_spec: | - Export a DocumentErrorCode string enum with values: - INVALID_FORMAT, PARSE_FAILED, SIZE_EXCEEDED, ENCODING_UNSUPPORTED, - PERMISSION_DENIED, STORAGE_UNAVAILABLE, TEMPLATE_MISSING, TIMEOUT. - Each value should be a SCREAMING_SNAKE string matching the enum key. - - file: "src/errors/document-error.ts" - action: "create" - lines: "all" - content_spec: | - Export DocumentProcessingError extending Error. - Constructor accepts (code: DocumentErrorCode, message: string, context?: Record). - Exposes readonly code, context properties. Sets name to 'DocumentProcessingError'. - Re-export DocumentErrorCode for convenience. - acceptance_criteria: - - id: "ac1_1" - type: "compile" - description: "New files compile without errors" - command: "npx tsc --noEmit src/errors/codes.ts src/errors/document-error.ts" - expected: "Exit code 0" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T11:45:00Z" - output: "tsc completed with exit code 0" - notes: "Clean compile, no warnings" - - id: "ac1_2" - type: "test" - description: "Error class instantiation works correctly" - command: "npm test -- --filter document-error" - expected: "Error instances carry correct code and extend Error" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T11:50:00Z" - output: "2 tests passed" - - id: "ac1_3" - type: "documentation" - description: "Error codes are documented in docs/error-handling.md" - validation: "manual" - result: - status: "pass" - timestamp: "2026-02-18T12:00:00Z" - notes: "Added table of error codes with descriptions to error-handling.md" - status: "completed" - - - id: "phase2" - name: "Migrate processor error paths" - objective: "Replace all raw throws in processor.ts with DocumentProcessingError using appropriate codes" - dependencies: - - "phase1" - changes: - - file: "src/services/documents/processor.ts" - action: "update" - lines: "45-120" - content_spec: | - Import DocumentProcessingError and DocumentErrorCode from src/errors. - Replace each `throw new Error("...")` with the appropriate - `throw new DocumentProcessingError(DocumentErrorCode.X, message, { context })`. - Map each existing error string to the matching enum value: - - "Invalid document format" -> INVALID_FORMAT - - "Failed to parse document" -> PARSE_FAILED - - "Document exceeds size limit" -> SIZE_EXCEEDED - - "Unsupported encoding" -> ENCODING_UNSUPPORTED - - "Permission denied" -> PERMISSION_DENIED - - "Storage service unavailable" -> STORAGE_UNAVAILABLE - - "Template not found" -> TEMPLATE_MISSING - - "Processing timeout" -> TIMEOUT - - file: "src/errors/index.ts" - action: "update" - lines: "1-10" - content_spec: | - Add re-exports for DocumentErrorCode and DocumentProcessingError - so they can be imported from 'src/errors' directly. - acceptance_criteria: - - id: "ac2_1" - type: "boundary" - description: "No raw Error throws remain in processor.ts" - command: "rg -c 'throw new Error' src/services/documents/processor.ts" - expected: "No matches (exit code 1)" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T13:15:00Z" - output: "exit code 1 - no matches" - notes: "All 8 throw sites migrated" - - id: "ac2_2" - type: "compile" - description: "Processor compiles with new error imports" - command: "npx tsc --noEmit src/services/documents/processor.ts" - expected: "Exit code 0" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T13:18:00Z" - output: "tsc completed with exit code 0" - - id: "ac2_3" - type: "security" - description: "No hardcoded secrets introduced" - command: "rg -i '(password|secret|api[_-]?key)\\s*=\\s*[\"'']\\w' src/services/documents/processor.ts" - expected: "No matches" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T13:20:00Z" - output: "No matches found" - status: "completed" - - - id: "phase3" - name: "Update tests to assert on error codes" - objective: "Migrate test assertions from message matching to code matching and add coverage for each error code" - dependencies: - - "phase2" - changes: - - file: "src/services/documents/processor.test.ts" - action: "update" - lines: "all" - content_spec: | - Import DocumentErrorCode and DocumentProcessingError. - For each error-path test: - - Replace `.toThrow("message")` with a catch block that asserts - `error instanceof DocumentProcessingError` and - `error.code === DocumentErrorCode.X`. - - Verify error.context contains expected metadata where applicable. - - Add one new test per error code to confirm the correct code is thrown - for each failure scenario. - - file: "src/errors/document-error.test.ts" - action: "update" - lines: "all" - content_spec: | - Add tests for edge cases: missing context, serialization, - instanceof checks, and name property. - acceptance_criteria: - - id: "ac3_1" - type: "test" - description: "All processor tests pass with code-based assertions" - command: "npm test -- --filter documents" - expected: "All tests pass, 0 failures" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T14:28:00Z" - output: "18 tests passed, 0 failed" - notes: "Added 8 new tests (one per error code), updated 6 existing tests" - - id: "ac3_2" - type: "test" - description: "Full test suite passes with no regressions" - command: "npm test" - expected: "Exit code 0" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T14:35:00Z" - output: "142 tests passed, 0 failed, 0 skipped" - - id: "ac3_3" - type: "integration" - description: "Document upload endpoint returns structured error on invalid input" - command: "npm run test:integration -- --filter document-upload" - expected: "Exit code 0" - validation: "automated" - result: - status: "pass" - timestamp: "2026-02-18T14:38:00Z" - output: "3 integration tests passed" - - id: "ac3_4" - type: "custom" - description: "Error code coverage matches throw site count" - validation: "manual" - result: - status: "pass" - timestamp: "2026-02-18T14:40:00Z" - notes: "8 error codes defined, 8 throw sites migrated, 8 dedicated test cases added - 1:1:1 coverage" - status: "completed" - -rollback: - strategy: "per_phase" - commands: - phase1: "git checkout HEAD -- src/errors/codes.ts src/errors/document-error.ts" - phase2: "git checkout HEAD -- src/services/documents/processor.ts src/errors/index.ts" - phase3: "git checkout HEAD -- src/services/documents/processor.test.ts src/errors/document-error.test.ts" - -self_eval: - completeness: 3 - architecture_fidelity: 3 - spec_alignment: 2 - validation_depth: 2 - total: 10 - notes: | - All 8 error paths migrated with 1:1 enum coverage. Error class follows existing - BaseError pattern in the codebase. Tests cover every error code individually plus - integration test for the upload endpoint. No deviations from spec. - second_pass_performed: false - -deviations: [] - -metadata: - estimated_effort_hours: 2.5 - actual_effort_hours: 3.0 - ai_model: "claude-opus-4-6" - react_cycles: 12 - tags: - - "error-handling" - - "typescript" - - "refactor" From 40f5f9dd8461064f0a2277f5faf82d42bb468bf8 Mon Sep 17 00:00:00 2001 From: KidSkills Date: Tue, 23 Jun 2026 15:02:16 +0800 Subject: [PATCH 64/64] Add prospect sequence skill --- crates/runx-cli/src/official_skills.rs | 5 + packages/cli/src/official-skills.lock.json | 7 + skills/prospect-sequence/SKILL.md | 98 +++++++ skills/prospect-sequence/X.yaml | 82 ++++++ .../missing-public-sources-refuses.yaml | 15 + .../fixtures/off-allowlist-denied.yaml | 18 ++ .../public-sources-yield-sequence.yaml | 26 ++ skills/prospect-sequence/run.mjs | 274 ++++++++++++++++++ skills/prospect-sequence/test.mjs | 87 ++++++ 9 files changed, 612 insertions(+) create mode 100644 skills/prospect-sequence/SKILL.md create mode 100644 skills/prospect-sequence/X.yaml create mode 100644 skills/prospect-sequence/fixtures/missing-public-sources-refuses.yaml create mode 100644 skills/prospect-sequence/fixtures/off-allowlist-denied.yaml create mode 100644 skills/prospect-sequence/fixtures/public-sources-yield-sequence.yaml create mode 100644 skills/prospect-sequence/run.mjs create mode 100644 skills/prospect-sequence/test.mjs diff --git a/crates/runx-cli/src/official_skills.rs b/crates/runx-cli/src/official_skills.rs index 8469e4b01..abccdb4a2 100644 --- a/crates/runx-cli/src/official_skills.rs +++ b/crates/runx-cli/src/official_skills.rs @@ -215,6 +215,11 @@ pub(crate) const OFFICIAL_SKILLS: &[OfficialSkillLockEntry] = &[ version: "sha-537dd9fc3c6b", digest: "b073ec884f56c9e412d0c1039d5f28f163df0f5530eb0bee922ed4c557955c52", }, + OfficialSkillLockEntry { + skill_id: "runx/prospect-sequence", + version: "sha-14eddf4ad0e3", + digest: "c0f2e2d71a46d9ee9756a4c30203a735b30476f455118efb3057be9def3d9387", + }, OfficialSkillLockEntry { skill_id: "runx/prior-art", version: "sha-2555f66bde78", diff --git a/packages/cli/src/official-skills.lock.json b/packages/cli/src/official-skills.lock.json index 5ce7c23e9..f2e4633b9 100644 --- a/packages/cli/src/official-skills.lock.json +++ b/packages/cli/src/official-skills.lock.json @@ -286,6 +286,13 @@ "catalog_visibility": "public", "catalog_role": "context" }, + { + "skill_id": "runx/prospect-sequence", + "version": "sha-14eddf4ad0e3", + "digest": "c0f2e2d71a46d9ee9756a4c30203a735b30476f455118efb3057be9def3d9387", + "catalog_visibility": "public", + "catalog_role": "context" + }, { "skill_id": "runx/prior-art", "version": "sha-2555f66bde78", diff --git a/skills/prospect-sequence/SKILL.md b/skills/prospect-sequence/SKILL.md new file mode 100644 index 000000000..53edc851f --- /dev/null +++ b/skills/prospect-sequence/SKILL.md @@ -0,0 +1,98 @@ +--- +name: prospect-sequence +description: Research an account from allowlisted public sources and draft a gated outreach sequence. +metadata: + category: sales + tags: + - prospecting + - outreach + - research +--- + +# Prospect Sequence + +`prospect-sequence` turns bounded public account research into a sourced sales +angle, a short multi-touch outreach sequence, and a gated `send-as` proposal. It +is for operators who need the judgment and evidence behind an AI SDR motion +without allowing the skill to send anything itself. + +## When To Use + +Use this skill when: + +- You have a named prospect company and contact reference. +- You can provide public source snippets from an explicit allowlist. +- You need a reviewable outreach angle and sequence before a human or provider + adapter sends. + +Do not use it to scrape private networks, infer facts without source evidence, +or send messages directly. + +## Inputs + +- `prospect` (required): object with `company` and optional `contact`. +- `icp` (required): object describing the target customer profile, pain, and + offer. +- `source_allowlist` (required): list of permitted hosts or URL prefixes. +- `sources` (required): public source objects with `url`, `title`, and + `excerpt`. Every source URL must match the allowlist. + +## Outputs + +- `research`: object with `sources[]` and `angle`. +- `sequence`: array of outreach touches with channel, subject, body, and source + citations. +- `send_proposal`: gated proposed Effect for `send-as`. + +## Guardrails + +1. Treat `source_allowlist` as the network boundary. Reject private or + off-allowlist URLs before synthesizing. +2. Refuse when no source is available; the skill does not fabricate account + facts. +3. Cite each source used in the angle and sequence. +4. Emit only a proposed `send-as` effect with `approval_required: true` and + `sends_directly: false`. +5. Keep output deterministic enough for harness replay. + +## Example + +Input: + +```yaml +prospect: + company: Acme Logistics + contact: VP Operations +icp: + offer: governed agent workflows for operations teams + pain: manual exception handling across support and finance +source_allowlist: + - acme.example +sources: + - url: https://acme.example/blog/exception-ops + title: Exception operations update + excerpt: Acme describes new SLA pressure from invoice and shipment exceptions. +``` + +Output: + +```yaml +research: + angle: Acme's public operations update shows SLA pressure around invoice and + shipment exceptions, which maps to governed workflow automation. +sequence: + - step: 1 + channel: email + subject: Reducing exception-handling drag at Acme +send_proposal: + effect: send-as + gated: true + approval_required: true +``` + +## Failure Modes + +- No public sources: return `decision.status: refused`. +- Off-allowlist or private-network URL: return `decision.status: + policy_denied`. +- Missing prospect or ICP: return `decision.status: refused`. diff --git a/skills/prospect-sequence/X.yaml b/skills/prospect-sequence/X.yaml new file mode 100644 index 000000000..f35d67cbe --- /dev/null +++ b/skills/prospect-sequence/X.yaml @@ -0,0 +1,82 @@ +skill: prospect-sequence +version: "0.1.0" +catalog: + kind: skill + audience: operator + visibility: public + role: context +runners: + decide: + default: true + type: cli-tool + command: node + args: + - run.mjs + outputs: + decision: object + research: object + sequence: array + send_proposal: object + artifacts: + wrap_as: prospect_sequence_packet + packet: runx.sales.prospect_sequence.v1 + inputs: + prospect: + type: json + required: true + description: Prospect account and contact reference. + icp: + type: json + required: true + description: Ideal customer profile, pain, and offer context. + source_allowlist: + type: json + required: true + description: Allowed public hosts or URL prefixes for source evidence. + sources: + type: json + required: true + description: Public source records with url, title, and excerpt. + stop: + type: cli-tool + command: /bin/false + outputs: + decision: object + inputs: + reason: + type: string + required: false + description: Harness-only stop path proving the package records stop/error outcomes. +harness: + cases: + - name: public-sources-yield-sequence + runner: decide + inputs: + prospect: + company: Acme Logistics + contact: VP Operations + icp: + offer: governed agent workflows for operations teams + pain: manual exception handling across support and finance + source_allowlist: + - acme.example + sources: + - url: https://acme.example/blog/exception-ops + title: Exception operations update + excerpt: Acme describes new SLA pressure from invoice and shipment exceptions. + - url: https://acme.example/news/finance-automation + title: Finance automation note + excerpt: The finance team is consolidating manual approval queues this quarter. + expect: + status: sealed + receipt: + schema: runx.receipt.v1 + state: sealed + disposition: closed + reason_code: process_closed + - name: stop-runner-fails + runner: stop + inputs: + reason: off-allowlist network target + expect: + status: failure diff --git a/skills/prospect-sequence/fixtures/missing-public-sources-refuses.yaml b/skills/prospect-sequence/fixtures/missing-public-sources-refuses.yaml new file mode 100644 index 000000000..bbc95d85b --- /dev/null +++ b/skills/prospect-sequence/fixtures/missing-public-sources-refuses.yaml @@ -0,0 +1,15 @@ +name: missing-public-sources-refuses +input: + prospect: + company: PrivateCo + contact: Revenue Operations + icp: + offer: governed outreach planning + pain: unverified account context + source_allowlist: + - private.example + sources: [] +expect: + decision: + status: needs_agent + sequence: [] diff --git a/skills/prospect-sequence/fixtures/off-allowlist-denied.yaml b/skills/prospect-sequence/fixtures/off-allowlist-denied.yaml new file mode 100644 index 000000000..2e37a418f --- /dev/null +++ b/skills/prospect-sequence/fixtures/off-allowlist-denied.yaml @@ -0,0 +1,18 @@ +name: off-allowlist-denied +input: + prospect: + company: Acme Logistics + contact: VP Operations + icp: + offer: governed workflows + pain: manual queues + source_allowlist: + - acme.example + sources: + - url: https://evil.example/post + title: Untrusted source + excerpt: This source should not be used because its host is outside the allowlist. +expect: + decision: + status: policy_denied + sequence: [] diff --git a/skills/prospect-sequence/fixtures/public-sources-yield-sequence.yaml b/skills/prospect-sequence/fixtures/public-sources-yield-sequence.yaml new file mode 100644 index 000000000..65b670e20 --- /dev/null +++ b/skills/prospect-sequence/fixtures/public-sources-yield-sequence.yaml @@ -0,0 +1,26 @@ +name: public-sources-yield-sequence +input: + prospect: + company: Acme Logistics + contact: VP Operations + icp: + offer: governed agent workflows for operations teams + pain: manual exception handling across support and finance + source_allowlist: + - acme.example + sources: + - url: https://acme.example/blog/exception-ops + title: Exception operations update + excerpt: Acme describes new SLA pressure from invoice and shipment exceptions. + - url: https://acme.example/news/finance-automation + title: Finance automation note + excerpt: The finance team is consolidating manual approval queues this quarter. +expect: + decision: + status: sealed + sequence: + min_items: 3 + send_proposal: + effect: send-as + gated: true + sends_directly: false diff --git a/skills/prospect-sequence/run.mjs b/skills/prospect-sequence/run.mjs new file mode 100644 index 000000000..7b33a7127 --- /dev/null +++ b/skills/prospect-sequence/run.mjs @@ -0,0 +1,274 @@ +#!/usr/bin/env node + +import { readFileSync } from "node:fs"; +import { createHash } from "node:crypto"; + +const input = readInput(); +const prospect = input.prospect ?? {}; +const icp = input.icp ?? {}; +const allowlist = Array.isArray(input.source_allowlist) ? input.source_allowlist : []; +const sources = Array.isArray(input.sources) ? input.sources : []; + +const output = decide(); +process.stdout.write(`${JSON.stringify(output, null, 2)}\n`); + +function decide() { + if (!prospect.company || !icp.offer) { + return refused("prospect.company and icp.offer are required"); + } + if (allowlist.length === 0) { + return refused("source_allowlist must contain at least one public host or URL prefix"); + } + if (sources.length === 0) { + return needsAgent("no public sources supplied; refusing to fabricate account facts"); + } + + const checked = []; + for (const source of sources) { + const check = checkSource(source); + checked.push(check); + if (check.decision !== "allowed") { + return policyDenied(check.reason, checked); + } + } + + const usedSources = checked.map((check, index) => ({ + id: `source-${index + 1}`, + url: check.url, + title: sources[index].title ?? check.host, + excerpt_digest: digest(sources[index].excerpt ?? ""), + citation: `[source-${index + 1}] ${sources[index].title ?? check.host} (${check.url})`, + })); + + const angle = [ + `${prospect.company} has public signals around ${icp.pain ?? "the stated operating pain"}.`, + `That maps to ${icp.offer}.`, + `Use ${usedSources.map((source) => source.id).join(", ")} as the evidence base; do not add unsourced claims.`, + ].join(" "); + + const sequence = [ + { + step: 1, + channel: "email", + subject: `Idea for ${prospect.company}'s exception workflow`, + body: `${prospect.contact ?? "Hi"} - I noticed ${summarizeSource(sources[0])}. It seems adjacent to ${icp.pain ?? "your operating priorities"}. Would it be useful to compare how governed agent workflows keep that motion auditable?`, + citations: [usedSources[0].id], + }, + { + step: 2, + channel: "email", + subject: `A governed follow-up for ${prospect.company}`, + body: `Following up with a narrower angle: ${icp.offer} can propose next actions while keeping sends behind approval. The public source trail is ${usedSources.map((source) => source.id).join(", ")}.`, + citations: usedSources.map((source) => source.id), + }, + { + step: 3, + channel: "linkedin", + subject: "Lightweight research note", + body: `Sharing a concise account note built only from public allowlisted sources: ${angle}`, + citations: usedSources.map((source) => source.id), + }, + ]; + + return { + decision: { + status: "sealed", + action: "propose_sequence", + reasons: [ + `${usedSources.length} allowlisted public source(s) checked`, + "sequence cites source ids and stops before sending", + ], + }, + research: { + prospect: { + company: prospect.company, + contact: prospect.contact ?? null, + }, + sources: usedSources, + angle, + allowlist_checked: allowlist, + fact_policy: "only cite facts present in supplied public sources", + }, + sequence, + send_proposal: { + effect: "send-as", + gated: true, + approval_required: true, + sends_directly: false, + send_class: "outreach", + principal_ref: input.principal_ref ?? "operator", + recipient_ref: prospect.contact ?? prospect.company, + content_digest: digest(JSON.stringify(sequence)), + source_citations: usedSources.map((source) => source.id), + }, + }; +} + +function refused(reason) { + return { + decision: { + status: "refused", + action: "refuse", + reasons: [reason], + }, + research: { + sources: [], + angle: null, + }, + sequence: [], + send_proposal: gatedNullProposal(reason), + }; +} + +function needsAgent(reason) { + return { + decision: { + status: "needs_agent", + action: "request_public_sources", + reasons: [reason], + }, + research: { + sources: [], + angle: null, + }, + sequence: [], + send_proposal: gatedNullProposal(reason), + }; +} + +function policyDenied(reason, checked) { + return { + decision: { + status: "policy_denied", + action: "refuse", + reasons: [reason], + }, + research: { + sources: checked, + angle: null, + }, + sequence: [], + send_proposal: gatedNullProposal(reason), + }; +} + +function gatedNullProposal(reason) { + return { + effect: "send-as", + gated: true, + approval_required: true, + sends_directly: false, + send_class: "outreach", + recipient_ref: prospect.contact ?? prospect.company ?? null, + content_digest: null, + reason, + }; +} + +function checkSource(source) { + let parsed; + try { + parsed = new URL(source.url); + } catch { + return { + decision: "denied", + url: source.url ?? null, + reason: "source url is not a valid absolute URL", + }; + } + + if (!["http:", "https:"].includes(parsed.protocol)) { + return { + decision: "denied", + url: parsed.href, + host: parsed.hostname, + reason: "source url must use http or https", + }; + } + + if (isPrivateHost(parsed.hostname)) { + return { + decision: "denied", + url: parsed.href, + host: parsed.hostname, + reason: "private-network host is not allowed", + }; + } + + const allowed = allowlist.some((entry) => matchesAllowlist(parsed, String(entry))); + if (!allowed) { + return { + decision: "denied", + url: parsed.href, + host: parsed.hostname, + reason: `host ${parsed.hostname} is outside source_allowlist`, + }; + } + + if (!source.excerpt || String(source.excerpt).trim().length < 20) { + return { + decision: "denied", + url: parsed.href, + host: parsed.hostname, + reason: "source excerpt is too thin to support an account fact", + }; + } + + return { + decision: "allowed", + url: parsed.href, + host: parsed.hostname, + allowlist_decision: "allowed", + }; +} + +function matchesAllowlist(parsed, entry) { + const normalized = entry.replace(/^https?:\/\//, "").replace(/\/$/, "").toLowerCase(); + const host = parsed.hostname.toLowerCase(); + return host === normalized || host.endsWith(`.${normalized}`) || parsed.href.toLowerCase().startsWith(entry.toLowerCase()); +} + +function isPrivateHost(host) { + const lower = host.toLowerCase(); + if (lower === "localhost" || lower.endsWith(".local")) return true; + if (/^\d+\.\d+\.\d+\.\d+$/.test(lower)) { + const [a, b] = lower.split(".").map(Number); + return a === 10 || a === 127 || (a === 172 && b >= 16 && b <= 31) || (a === 192 && b === 168) || a === 169; + } + return false; +} + +function summarizeSource(source) { + const excerpt = String(source.excerpt ?? "").trim(); + if (excerpt.length <= 120) return excerpt; + return `${excerpt.slice(0, 117)}...`; +} + +function digest(value) { + return `sha256:${createHash("sha256").update(String(value)).digest("hex")}`; +} + +function readInput() { + if (process.env.RUNX_INPUTS_PATH) { + return JSON.parse(readFileSync(process.env.RUNX_INPUTS_PATH, "utf8")); + } + if (process.env.RUNX_INPUTS_JSON) { + return JSON.parse(process.env.RUNX_INPUTS_JSON); + } + + const args = process.argv.slice(2); + const input = {}; + for (let i = 0; i < args.length; i += 1) { + if (args[i] === "--input-json") { + const [key, rawValue] = String(args[++i] ?? "").split(/=(.*)/s); + input[key] = JSON.parse(rawValue); + } + } + + if (Object.keys(input).length > 0) { + return input; + } + + const stdin = readFileSync(0, "utf8").trim(); + return stdin ? JSON.parse(stdin) : {}; +} diff --git a/skills/prospect-sequence/test.mjs b/skills/prospect-sequence/test.mjs new file mode 100644 index 000000000..e0f07d33d --- /dev/null +++ b/skills/prospect-sequence/test.mjs @@ -0,0 +1,87 @@ +#!/usr/bin/env node + +import assert from "node:assert/strict"; +import { spawnSync } from "node:child_process"; + +const happy = run({ + prospect: { + company: "Acme Logistics", + contact: "VP Operations", + }, + icp: { + offer: "governed agent workflows for operations teams", + pain: "manual exception handling across support and finance", + }, + source_allowlist: ["acme.example"], + sources: [ + { + url: "https://acme.example/blog/exception-ops", + title: "Exception operations update", + excerpt: "Acme describes new SLA pressure from invoice and shipment exceptions.", + }, + { + url: "https://acme.example/news/finance-automation", + title: "Finance automation note", + excerpt: "The finance team is consolidating manual approval queues this quarter.", + }, + ], +}); +assert.equal(happy.decision.status, "sealed"); +assert.equal(happy.research.sources.length, 2); +assert.match(happy.research.angle, /source-1/); +assert.equal(happy.sequence.length, 3); +assert.equal(happy.sequence[0].citations[0], "source-1"); +assert.equal(happy.send_proposal.effect, "send-as"); +assert.equal(happy.send_proposal.gated, true); +assert.equal(happy.send_proposal.sends_directly, false); + +const noSources = run({ + prospect: { company: "PrivateCo", contact: "Revenue Operations" }, + icp: { offer: "governed outreach planning", pain: "unverified account context" }, + source_allowlist: ["private.example"], + sources: [], +}); +assert.equal(noSources.decision.status, "needs_agent"); +assert.equal(noSources.sequence.length, 0); + +const offAllowlist = run({ + prospect: { company: "Acme Logistics", contact: "VP Operations" }, + icp: { offer: "governed workflows", pain: "manual queues" }, + source_allowlist: ["acme.example"], + sources: [ + { + url: "https://evil.example/post", + title: "Untrusted source", + excerpt: "This source should not be used because its host is outside the allowlist.", + }, + ], +}); +assert.equal(offAllowlist.decision.status, "policy_denied"); +assert.match(offAllowlist.decision.reasons[0], /outside source_allowlist/); + +const privateHost = run({ + prospect: { company: "LocalCo", contact: "Ops" }, + icp: { offer: "governed workflows", pain: "manual queues" }, + source_allowlist: ["localhost"], + sources: [ + { + url: "http://localhost/private", + title: "Private source", + excerpt: "This local source must be refused before any synthesis occurs.", + }, + ], +}); +assert.equal(privateHost.decision.status, "policy_denied"); +assert.match(privateHost.decision.reasons[0], /private-network/); + +console.log("prospect-sequence tests passed"); + +function run(input) { + const child = spawnSync(process.execPath, ["run.mjs"], { + cwd: new URL(".", import.meta.url), + input: JSON.stringify(input), + encoding: "utf8", + }); + assert.equal(child.status, 0, child.stderr); + return JSON.parse(child.stdout); +}