diff --git a/.github/workflows/pr.yml b/.github/workflows/pr.yml index 578dcdd68d9..dcd636f84fe 100644 --- a/.github/workflows/pr.yml +++ b/.github/workflows/pr.yml @@ -485,6 +485,10 @@ jobs: if: needs.code_paths.outputs.static_analysis == 'true' run: node config/scripts/plugin-authoring/rpc-catalog/generate-rpc-params-catalog.mjs --check + - name: Check orchestration parity declarations + if: needs.code_paths.outputs.static_analysis == 'true' + run: node config/scripts/static-analysis/orchestration-parity/check-orchestration-parity-declarations.mjs + - name: Verify the generated ACP protocol schema if: needs.code_paths.outputs.static_analysis == 'true' run: node config/scripts/acp/generate-protocol.mjs --check diff --git a/config/ast-grep/rule-tests/orchestration-agent-kind-branch-test.yml b/config/ast-grep/rule-tests/orchestration-agent-kind-branch-test.yml new file mode 100644 index 00000000000..cfa0617bd35 --- /dev/null +++ b/config/ast-grep/rule-tests/orchestration-agent-kind-branch-test.yml @@ -0,0 +1,11 @@ +id: orchestration-agent-kind-branch +valid: + - const party = resolveOrchestrationParty(address, db) + - if (party.terminalHandle === undefined) { return } + - const local = target.startsWith('run:') +invalid: + - if (to.startsWith(ORCA_SESSION_ADDRESS_PREFIX)) { return } + - const session = parseOrcaSessionAddress(to) + - if (party.orcaSessionId !== null) { notify() } + - if (agent.kind === 'structured') { inject() } + - const chat = !isTuiAgent(agent) diff --git a/config/ast-grep/rules/orchestration-agent-kind-branch.yml b/config/ast-grep/rules/orchestration-agent-kind-branch.yml new file mode 100644 index 00000000000..a8a5500f2c4 --- /dev/null +++ b/config/ast-grep/rules/orchestration-agent-kind-branch.yml @@ -0,0 +1,39 @@ +# Ratcheted by config/scripts/static-analysis/ratchets/orchestration/check-orchestration-agent-kind-ratchet.mjs; +# info severity keeps `pnpm lint:ast-grep` quiet about the grandfathered baseline. +# The addressing owners resolve an address or caller to its party; everything else should use that party. +id: orchestration-agent-kind-branch +language: typescript +severity: info +message: Branching on agent kind (terminal or chat) in an orchestration command splits their behaviour per command. Use the party the addressing owners resolve, and declare any per-kind refusal in src/main/runtime/orchestration/orchestration-parity.md. +note: 'A deliberate exception takes `// ast-grep-ignore: orchestration-agent-kind-branch -- ` above the line.' +files: + - src/main/runtime/rpc/methods/orchestration/** + - src/main/runtime/orchestration/** + - src/main/runtime/rpc/orchestration-*.ts + - src/cli/handlers/orchestration/** +ignores: + - '**/*.test.*' + - '**/*test-support*' + - '**/*test-fixture*' + - src/main/runtime/orchestration/addressing/** + - src/main/runtime/rpc/orchestration-session-caller.ts +rule: + any: + # Address shape + - pattern: $X.startsWith(ORCA_SESSION_ADDRESS_PREFIX) + - pattern: $X.startsWith('orca_session_id:') + - pattern: isOrcaSessionId($$$) + - pattern: parseOrcaSessionAddress($$$) + - pattern: mayNameSession($$$) + # Party shape + - pattern: $P.orcaSessionId !== null + - pattern: $P.orcaSessionId === null + - pattern: $P.terminalHandle === null + - pattern: $P.terminalHandle !== null + # Kind and mode literals + - pattern: $K.kind === 'structured' + - pattern: $K.mode === 'structured' + - pattern: isTuiAgent($$$) + # Caller kind read from the environment + - pattern: readInjectedAgentSessionId($$$) + - pattern: hasStructuredSessionMarker($$$) diff --git a/config/orchestration-agent-kind-baseline.txt b/config/orchestration-agent-kind-baseline.txt new file mode 100644 index 00000000000..b4b00f20efc --- /dev/null +++ b/config/orchestration-agent-kind-baseline.txt @@ -0,0 +1,37 @@ +# Agent-kind branches per file (config/ast-grep/rules/orchestration-agent-kind-branch.yml). +# This is a RATCHET: counts may only go DOWN. Prune after a fix: +# pnpm check:orchestration-agent-kind-ratchet --prune +2 src/cli/handlers/orchestration/message-send-handler.ts +4 src/cli/handlers/orchestration/terminal-identity.ts +1 src/main/runtime/orchestration/crew/crew-parent-inputs.ts +4 src/main/runtime/orchestration/crew/crew-parties.ts +2 src/main/runtime/orchestration/crew/crew-party-snapshot.ts +1 src/main/runtime/orchestration/crew/crew-recipient-owner-queries.ts +3 src/main/runtime/orchestration/db/dispatch-context/worker-follow-up-lineage.ts +1 src/main/runtime/orchestration/db/runs/run-lookup.ts +1 src/main/runtime/orchestration/db/schema/structured-worker-orca-session-backfill.ts +1 src/main/runtime/orchestration/mailbox/routing/structured-session-mail-address.ts +3 src/main/runtime/orchestration/mailbox/routing/structured-session-mail-target.ts +1 src/main/runtime/orchestration/mailbox/senders/agent-message-sender.ts +2 src/main/runtime/orchestration/terminal-authority/structured-sessions/structured-worker-authority.ts +1 src/main/runtime/orchestration/terminal-authority/structured-sessions/structured-worker-custody.ts +1 src/main/runtime/orchestration/terminal-authority/structured-sessions/structured-worker-identity.ts +1 src/main/runtime/orchestration/terminal-authority/write-orchestration-pointer-pty.ts +2 src/main/runtime/orchestration/workers/launch/configured-worker-agent-selector.ts +1 src/main/runtime/orchestration/workers/launch/orchestration-cli-command.ts +1 src/main/runtime/orchestration/workers/launch/worker-dispatch-preamble.ts +1 src/main/runtime/orchestration/workers/launch/worker-launch-observation.ts +1 src/main/runtime/orchestration/workers/lifecycle/chat-assignee.ts +1 src/main/runtime/orchestration/workers/turn-stops/chat-worker-error-escalation.ts +1 src/main/runtime/rpc/methods/orchestration/caller-show.ts +1 src/main/runtime/rpc/methods/orchestration/federation/federated-worker-start.ts +3 src/main/runtime/rpc/methods/orchestration/messaging/recipient-routing.ts +1 src/main/runtime/rpc/methods/orchestration/messaging/send-methods.ts +6 src/main/runtime/rpc/methods/orchestration/messaging/session-recipient.ts +1 src/main/runtime/rpc/methods/orchestration/messaging/settled-worker-follow-through.ts +1 src/main/runtime/rpc/methods/orchestration/runs/dispatch-creator.ts +1 src/main/runtime/rpc/methods/orchestration/worker/deliver-worker-dispatch-preamble.ts +1 src/main/runtime/rpc/methods/orchestration/worker/worker-configured-agent-preflight.ts +1 src/main/runtime/rpc/methods/orchestration/worker/worker-earlier-work.ts +1 src/main/runtime/rpc/methods/orchestration/worker/worker-follow-up-placement.ts +1 src/main/runtime/rpc/methods/orchestration/worker/worker-start-validation.ts diff --git a/config/scripts/preflight/changed-checks/run-lint.mjs b/config/scripts/preflight/changed-checks/run-lint.mjs index 0a2bbe3c723..8e4ff92bcde 100644 --- a/config/scripts/preflight/changed-checks/run-lint.mjs +++ b/config/scripts/preflight/changed-checks/run-lint.mjs @@ -33,6 +33,7 @@ export const LINT_STEPS = [ 'check:legacy-relay-fence-ratchet', 'check:runtime-electron-ratchet', 'verify:rpc-params-catalog', + 'check:orchestration-parity', 'check:repo-host-read-ratchet', 'test:ast-grep', 'check:max-lines-ratchet', diff --git a/config/scripts/static-analysis/orchestration-parity/check-orchestration-parity-declarations.mjs b/config/scripts/static-analysis/orchestration-parity/check-orchestration-parity-declarations.mjs new file mode 100644 index 00000000000..619c0e73706 --- /dev/null +++ b/config/scripts/static-analysis/orchestration-parity/check-orchestration-parity-declarations.mjs @@ -0,0 +1,107 @@ +import { readFileSync } from 'node:fs' +import path from 'node:path' +import process from 'node:process' +import { pathToFileURL } from 'node:url' +import { readTrackedSources } from '../ratchet-baseline/ratchet-baseline.mjs' + +// Every orchestration method declares what each agent kind gets in each location (terminal and chat parity). + +const DECLARATION = 'src/main/runtime/orchestration/orchestration-parity.md' +// Generated from the RPC registry and checked fresh in CI, so it lists every registered method. +const CATALOG = 'src/shared/rpc-contract/rpc-params-catalog.generated.ts' +const LABELS = [ + 'Terminal · Local', + 'Chat · Local', + 'Terminal · Paired', + 'Chat · Paired', + 'Terminal · SSH/WSL', + 'Chat · SSH/WSL' +] +const CELL = /^(?:supported(?:: .+)?|refused `([a-z_]+)`: .+|n\/a: .+)$/ + +// Both catalog lists are generated from the registry: methods with shared params, then those without. +export function registeredMethods(catalogText) { + return new Set( + [...catalogText.matchAll(/^\s*'(orchestration\.[A-Za-z]+)'[:,\n]/gm)].map((m) => m[1]) + ) +} + +/** Each `## \`orchestration.x\`` section, as its `-