specrails-core 5.2.2 → 5.3.0

package/integration-contract.json

@@ -147,14 +147,14 @@
     "file": ".specrails/install-config.yaml",
     "version": 1,
     "fields": {
-      "version": "number \u2014 schema version, currently 1",
-      "provider": "string \u2014 claude | codex | gemini | kimi",
+      "version": "number — schema version, currently 1",
+      "provider": "string — claude | codex | gemini | kimi",
       "tier": "Deprecated legacy string, tolerated and ignored; all installs use deterministic placement.",
-      "agents.selected": "string[] \u2014 unique lowercase kebab-case agent ids to install (1-64 characters)",
-      "agents.excluded": "string[] \u2014 unique lowercase kebab-case agent ids to skip; must not overlap agents.selected",
-      "models.preset": "string \u2014 balanced | budget | max; resolved within the selected provider catalog",
-      "models.defaults.model": "string \u2014 exact provider model id or configured alias (overrides preset; Kimi: 1-128 characters matching [A-Za-z0-9][A-Za-z0-9._/:-]*; default: k3)",
-      "models.overrides": "Record<safe-agent-id, string> \u2014 exact per-agent provider model ids or configured aliases with the same provider-specific validation (highest priority)"
+      "agents.selected": "string[] — unique lowercase kebab-case agent ids to install (1-64 characters)",
+      "agents.excluded": "string[] — unique lowercase kebab-case agent ids to skip; must not overlap agents.selected",
+      "models.preset": "string — balanced | budget | max; resolved within the selected provider catalog",
+      "models.defaults.model": "string — exact provider model id or configured alias (overrides preset; Kimi: 1-128 characters matching [A-Za-z0-9][A-Za-z0-9._/:-]*; default: k3)",
+      "models.overrides": "Record<safe-agent-id, string> — exact per-agent provider model ids or configured aliases with the same provider-specific validation (highest priority)"
     }
   },
   "checkpoints": {
@@ -249,6 +249,78 @@
       "--lite"
     ]
   },
+  "agentRuntime": {
+    "apiVersion": 1,
+    "configSchemaVersion": 1,
+    "workflowStateSchemaVersion": 2,
+    "checkpointEnvelopeFormat": 2,
+    "checkpointEnvelope": "checkpoint.json holds {format: 2, checksum, state, graph}: the host ledger (state) and the LangGraph checkpoint history (graph) written atomically together",
+    "moduleExport": "specrails-core/agent-runtime",
+    "modulePath": "dist/agent-runtime/index.js",
+    "typesPath": "dist/agent-runtime/index.d.ts",
+    "cliPath": "dist/agent-runtime/cli.js",
+    "cliCommand": "runtime",
+    "cliOperations": [
+      "api",
+      "validate",
+      "run",
+      "status",
+      "resume"
+    ],
+    "apiOperation": "runtime api emits {type: runtime-api, apiVersion, coreVersion}; does not invoke providers",
+    "validationTransport": "runtime validate --stdin accepts UTF-8 configuration JSON up to 2 MiB, mutually exclusive with --config",
+    "compactStatus": "runtime status --compact omits workflow history, events and outputs, frozen pipeline context and verification command output; retains identities (runId, traceId), phase statuses and visits, pendingApproval, pendingQuestion, usage, completion, acceptance summary and verification metadata",
+    "interrupts": "A paused run (exit 2) carries pendingApproval (resume --approve <step>) or pendingQuestion (resume --answer <text>, nonempty, at most 20000 characters); the architect asks only after one autonomous investigation pass unless architect.onLowConfidence is proceed",
+    "eventStream": "run/resume emit JSON lines typed workflow-event, agent-event, verification-output, span ({traceId, spanId, name, stepId, attempt, visit, startedAt, endedAt, status, usage?, error?}) and a final runtime-result",
+    "reviewGate": "review.minScore and review.aspects may only tighten Core's own gate (minScore 70, security 75, other aspects 60); the pipeline journal enforces the floor",
+    "acceptance": "The reviewer certifies every frozen acceptance criterion by specId and criterionIndex; Core records the verification commands it ran as required checks and binds the report to the exact candidate before the reviewer verdict",
+    "configSchemaPath": "schemas/agent-runtime.schema.json",
+    "configSchemaExport": "specrails-core/schemas/agent-runtime.schema.json",
+    "projectConfigPath": ".specrails/agent-runtime.json",
+    "minimumNode": "20.19.0",
+    "platforms": [
+      "darwin",
+      "win32"
+    ],
+    "cliProviders": [
+      "claude",
+      "codex",
+      "gemini",
+      "kimi"
+    ],
+    "providerKinds": [
+      "cli",
+      "openai-compatible"
+    ],
+    "programmaticRegistration": "ExecutorRegistry.register(id, executor); custom executors implement AgentExecutor.execute(request)",
+    "phases": [
+      "architect",
+      "developer",
+      "verify",
+      "reviewer",
+      "archive"
+    ],
+    "contextSchema": "execution.context; ownership.git must be host",
+    "statePath": "<backlogRoot>/.specrails/pipeline/<runId>/agent-workflow/<runId>/checkpoint.json",
+    "requestPath": "<backlogRoot>/.specrails/pipeline/<runId>/agent-runtime-request.json",
+    "exitCodes": {
+      "succeeded": 0,
+      "paused": 2,
+      "failedBlockedOrCancelled": 1
+    },
+    "recovery": "Explicit resume uses frozen configuration and revalidates Core evidence; interrupted writes require named recovery; grants persist until evidence invalidation.",
+    "delivery": "Core implements through archive; the host owns worktrees, commits, pushes, PRs and backlog delivery. A standalone continuation does not restart Desktop delivery.",
+    "specificationFormat": "Architect specs contain complete main-spec replacements, including unchanged requirements; archive does not merge partial delta snippets.",
+    "compatibility": "Additive to integration schema 4 and execution context schema 1. Legacy workflows and profile v1 remain supported. Hosts must check RUNTIME_API_VERSION, not infer runtime support from Core major version.",
+    "documentation": "docs/agent-runtime.md",
+    "instructionsVersion": "3",
+    "workflowVersion": "3",
+    "developerTools": "The developer role runs with each CLI's autonomous edit+shell mode (claude --tools default --dangerously-skip-permissions with Agent/Task/Skill disallowed; codex workspace-write; gemini --yolo; kimi print mode). Architect and reviewer stay read-only. Claude roles load project settings only (--setting-sources project,local).",
+    "verificationPolicy": "Configured commands are optional. The architect proposes commands for repositories without one; repositories with no automated check are admitted and recorded in the receipt as unverifiedRepositories. Unchecked tasks return to the developer as feedback instead of failing the run.",
+    "sessionReuse": "Developer correction passes resume the previous provider session (claude --resume, codex exec resume, gemini --resume, kimi --session) with a short correction prompt; an unavailable session falls back to a fresh full turn. Structured roles get one repair turn in-session when their JSON is unusable.",
+    "structuredOutput": "Claude receives --json-schema and Codex --output-schema for architect/reviewer replies; other providers are parsed leniently.",
+    "resumeBudget": "An explicit resume resets the transition ceiling and grants the developer a fresh maxAttempts budget."
+  },
   "execution": {
     "schemaVersion": 1,
     "contextEnv": "SPECRAILS_EXECUTION_CONTEXT",

package/package.json

@@ -1,8 +1,18 @@
 {
   "name": "specrails-core",
-  "version": "5.2.2",
+  "version": "5.3.0",
   "description": "Provider-independent AI agent workflow system for Claude Code, Codex, Gemini CLI, and Kimi Code",
   "type": "module",
+  "exports": {
+    "./agent-runtime": {
+      "types": "./dist/agent-runtime/index.d.ts",
+      "import": "./dist/agent-runtime/index.js",
+      "default": "./dist/agent-runtime/index.js"
+    },
+    "./package.json": "./package.json",
+    "./integration-contract.json": "./integration-contract.json",
+    "./schemas/agent-runtime.schema.json": "./schemas/agent-runtime.schema.json"
+  },
   "bin": {
     "specrails-core": "bin/specrails-core.mjs"
   },
@@ -68,11 +78,16 @@
   },
   "dependencies": {
     "@inquirer/prompts": "^7.0.0",
+    "@langchain/core": "1.2.10",
+    "@langchain/langgraph": "1.4.14",
+    "@langchain/langgraph-checkpoint": "1.1.5",
     "ajv": "^8.18.0",
+    "cross-spawn": "7.0.6",
     "js-yaml": "^4.1.0",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {
+    "@types/cross-spawn": "6.0.6",
     "@types/js-yaml": "^4.0.9",
     "@types/node": "^22.10.2",
     "@vitest/coverage-v8": "^4.1.5",

package/schemas/agent-runtime.schema.json

@@ -0,0 +1,55 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://specrails.dev/schemas/agent-runtime.schema.json",
+  "title": "Specrails programmatic agent runtime",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schemaVersion", "enabled", "providers", "agents", "verification"],
+  "properties": {
+    "schemaVersion": { "const": 1 },
+    "enabled": { "type": "boolean" },
+    "providers": { "type": "array", "items": { "oneOf": [
+      { "type": "object", "additionalProperties": false, "required": ["id", "kind", "cli"], "properties": {
+        "id": { "$ref": "#/definitions/id" }, "kind": { "const": "cli" }, "cli": { "enum": ["claude", "codex", "gemini", "kimi"] }
+      } },
+      { "type": "object", "additionalProperties": false, "required": ["id", "kind", "baseUrl"], "properties": {
+        "id": { "$ref": "#/definitions/id" }, "kind": { "const": "openai-compatible" },
+        "baseUrl": { "type": "string", "pattern": "^https?://[^/?#@]+(?:/[^?#]*)?$" },
+        "apiKeyEnv": { "type": "string", "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }
+      } }
+    ] } },
+    "agents": { "type": "object", "additionalProperties": false, "required": ["architect", "developer", "reviewer"], "properties": {
+      "architect": { "$ref": "#/definitions/agent" }, "developer": { "$ref": "#/definitions/agent" }, "reviewer": { "$ref": "#/definitions/agent" }
+    } },
+    "limits": { "type": "object", "additionalProperties": false, "properties": {
+      "maxAttempts": { "$ref": "#/definitions/positiveInteger" }, "maxTokens": { "$ref": "#/definitions/positiveInteger" },
+      "maxCostUsd": { "type": "number", "exclusiveMinimum": 0 }, "timeoutMs": { "$ref": "#/definitions/positiveInteger" }
+    } },
+    "verification": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["repositoryId", "command", "args"], "properties": {
+      "repositoryId": { "$ref": "#/definitions/id" }, "command": { "type": "string", "minLength": 1 },
+      "args": { "type": "array", "items": { "type": "string" } }, "cwd": { "type": "string", "minLength": 1 },
+      "env": { "type": "object", "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "additionalProperties": { "type": "string" } },
+      "timeoutMs": { "$ref": "#/definitions/positiveInteger" }
+    } } },
+    "approvalBeforeArchive": { "type": "boolean" },
+    "review": { "type": "object", "additionalProperties": false, "description": "Review gate thresholds; unset fields keep Core's defaults (score 70, security 75, other aspects 60).", "properties": {
+      "minScore": { "$ref": "#/definitions/score" },
+      "aspects": { "type": "object", "additionalProperties": false, "properties": {
+        "type_correctness": { "$ref": "#/definitions/score" }, "pattern_adherence": { "$ref": "#/definitions/score" }, "test_coverage": { "$ref": "#/definitions/score" },
+        "security": { "$ref": "#/definitions/score" }, "architectural_alignment": { "$ref": "#/definitions/score" }
+      } }
+    } },
+    "architect": { "type": "object", "additionalProperties": false, "properties": {
+      "onLowConfidence": { "enum": ["ask", "proceed"], "description": "After one autonomous investigation pass, a still-low design either pauses with its question (ask, default) or proceeds on stated assumptions (proceed)." }
+    } }
+  },
+  "definitions": {
+    "id": { "type": "string", "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$" },
+    "positiveInteger": { "type": "integer", "minimum": 1 },
+    "score": { "type": "number", "minimum": 0, "maximum": 100 },
+    "agent": { "type": "object", "additionalProperties": false, "required": ["provider"], "properties": {
+      "provider": { "$ref": "#/definitions/id" }, "model": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "^[^-\\r\\n\\u0000][^\\r\\n\\u0000]*$" },
+      "maxTurns": { "$ref": "#/definitions/positiveInteger" }
+    } }
+  }
+}

package/templates/runtime/provider-pipeline.md

@@ -48,6 +48,22 @@ Run verification through `verify --request <absolute-json-file>` with
 `{kind:"full"|"scoped",commands:[{repositoryId,command,args,cwd?,env?}]}`. The helper
 records actual exits and candidate fingerprints. Reuse only a current valid full
 receipt reported by `status`; semantic acceptance review remains mandatory.
+Checks run without the runtime's known agent session/launcher metadata. Changing
+that metadata between developer, reviewer and host does not invalidate a receipt.
+Application inputs (including PATH, NODE_OPTIONS, npm configuration and custom
+variables) remain verified. If a check needs session metadata as an input, declare
+it explicitly in the command's `env`; the override is bound without storing its
+value. Older environment-policy receipts require one fresh full verification;
+never edit a receipt to make it current. Keep notes and temporary verification
+requests under `stateDir`, outside the candidate source tree.
+For an environment mismatch, retain the runtime's added/removed key names in
+the failure report; values are deliberately not printed. When only recorded
+values differ, the aggregate hash cannot identify the individual variable.
+Do not work around recurring handoff failures by repeatedly refreshing the same
+checks until one process accepts them; report the mismatch for diagnosis.
+Automatic untracked files under known provider `agent-memory/` directories are
+runtime notes, not candidate inputs. Tracked memory, provider settings and skills
+remain candidate inputs and changing them requires fresh verification.
 Missing/low design confidence, unchecked tasks, missing/failed review and stale
 verification block success. Record reviewer done after semantic review, then run
 `archive-check`. ONLY a successful gate authorizes reviewer archive-only execution.