specrails-core 6.3.0 → 6.5.0

package/dist/shared/specrails-home.d.ts

@@ -0,0 +1,21 @@
+/**
+ * The user-level Specrails home. Registry, framework store, workspaces and
+ * agent session journals all live under `<home>/.specrails`, never inside a
+ * project repository.
+ *
+ * `SPECRAILS_REGISTRY_HOME` overrides the base directory so tests (and
+ * isolated installs) redirect every user-level artifact together.
+ */
+export declare function userHome(home?: string): string;
+/** Absolute path to `<home>/.specrails`. */
+export declare function specrailsHome(home?: string): string;
+/** Scope used by session hosts that are not bound to a project. */
+export declare const GLOBAL_SESSION_SCOPE = "global";
+/** True when `scope` is a valid session scope key (a project slug or `global`). */
+export declare function isSessionScopeKey(scope: string): boolean;
+/**
+ * Directory that holds every agent session journal of one scope:
+ * `<home>/.specrails/sessions/<scope>/`. Sessions are grouped per project so a
+ * project's history can be inspected, backed up or removed as one unit.
+ */
+export declare function sessionsRoot(scope: string, home?: string): string;

package/dist/shared/specrails-home.js

@@ -0,0 +1,36 @@
+import os from 'node:os';
+import path from 'node:path';
+/**
+ * The user-level Specrails home. Registry, framework store, workspaces and
+ * agent session journals all live under `<home>/.specrails`, never inside a
+ * project repository.
+ *
+ * `SPECRAILS_REGISTRY_HOME` overrides the base directory so tests (and
+ * isolated installs) redirect every user-level artifact together.
+ */
+export function userHome(home) {
+    return home ?? process.env.SPECRAILS_REGISTRY_HOME ?? os.homedir();
+}
+/** Absolute path to `<home>/.specrails`. */
+export function specrailsHome(home) {
+    return path.join(userHome(home), '.specrails');
+}
+/** Scope used by session hosts that are not bound to a project. */
+export const GLOBAL_SESSION_SCOPE = 'global';
+/** Same alphabet the registry uses for project slugs, bounded for file names. */
+const SCOPE_KEY = /^[a-z0-9](?:[a-z0-9-]{0,126}[a-z0-9])?$/;
+/** True when `scope` is a valid session scope key (a project slug or `global`). */
+export function isSessionScopeKey(scope) {
+    return SCOPE_KEY.test(scope);
+}
+/**
+ * Directory that holds every agent session journal of one scope:
+ * `<home>/.specrails/sessions/<scope>/`. Sessions are grouped per project so a
+ * project's history can be inspected, backed up or removed as one unit.
+ */
+export function sessionsRoot(scope, home) {
+    if (!isSessionScopeKey(scope)) {
+        throw new Error(`Invalid session scope "${scope}": use a project slug (a-z, 0-9, "-") or "${GLOBAL_SESSION_SCOPE}"`);
+    }
+    return path.join(specrailsHome(home), 'sessions', scope);
+}

package/integration-contract.json

@@ -241,7 +241,8 @@
       "workflows",
       "fork",
       "signal",
-      "cancel"
+      "cancel",
+      "host"
     ],
     "cliPresentationOperations": [
       "help"
@@ -293,7 +294,7 @@
     "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": "13",
+    "instructionsVersion": "14",
     "workflowVersion": "7",
     "engines": [
       1,
@@ -373,6 +374,46 @@
     "workflowAgentSteps": {
       "version": 1,
       "ownership": "Host-defined roles, schemas and gates; Core provides scoped artifact contracts and verified candidate guards"
+    },
+    "sessions": {
+      "version": 1,
+      "protocolVersions": [
+        1
+      ],
+      "capability": "sessions",
+      "cliOperation": "host",
+      "cliCommand": "specrails-core runtime host --stdio --scope <projectKey|global>",
+      "transport": "JSON-RPC 2.0 over newline-delimited stdio; one host per scope",
+      "journalRoot": "~/.specrails/sessions/<scope>/sessions.sqlite",
+      "moduleExport": "./agent-runtime/session",
+      "documentation": "docs/agent-sessions/protocol.md",
+      "eventTypes": [
+        "session.opened",
+        "session.phase",
+        "session.process",
+        "session.provider-ref",
+        "session.updated",
+        "session.closed",
+        "input.accepted",
+        "input.state",
+        "turn.started",
+        "turn.output",
+        "turn.tool",
+        "turn.completed",
+        "subagent.started",
+        "subagent.phase",
+        "subagent.output",
+        "subagent.usage",
+        "subagent.result",
+        "subagents.settled",
+        "output.truncated",
+        "notice.interruption",
+        "provider.diagnostic"
+      ],
+      "capabilities": [
+        "sessions",
+        "delegation"
+      ]
     }
   },
   "execution": {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "6.3.0",
+  "version": "6.5.0",
   "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code and Codex",
   "type": "module",
   "exports": {
@@ -14,6 +14,16 @@
       "import": "./dist/agent-runtime/engine/index.js",
       "default": "./dist/agent-runtime/engine/index.js"
     },
+    "./agent-runtime/session": {
+      "types": "./dist/agent-runtime/session/index.d.ts",
+      "import": "./dist/agent-runtime/session/index.js",
+      "default": "./dist/agent-runtime/session/index.js"
+    },
+    "./agent-runtime/session/testing": {
+      "types": "./dist/agent-runtime/session/testing/index.d.ts",
+      "import": "./dist/agent-runtime/session/testing/index.js",
+      "default": "./dist/agent-runtime/session/testing/index.js"
+    },
     "./package.json": "./package.json",
     "./integration-contract.json": "./integration-contract.json",
     "./schemas/agent-runtime.schema.json": "./schemas/agent-runtime.schema.json",

package/schemas/agent-runtime.schema.json

@@ -134,13 +134,8 @@
       "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": {
-      "key": { "$ref": "#/definitions/id" }, "label": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "\\S" }, "policy": { "$ref": "#/definitions/checkPolicy" },
-      "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" }
-    } } },
+    "verification": { "type": "array", "items": { "$ref": "#/definitions/checkCommand" } },
+    "setup": { "type": "array", "description": "Idempotent commands the verify piece runs sequentially in the admitted workspace before each verification plan; a failing setup command blocks the run instead of starting a correction round.", "items": { "$ref": "#/definitions/checkCommand" } },
     "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" },
@@ -154,6 +149,13 @@
     } }
   },
   "definitions": {
+    "checkCommand": { "type": "object", "additionalProperties": false, "required": ["repositoryId", "command", "args"], "properties": {
+      "key": { "$ref": "#/definitions/id" }, "label": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "\\S" }, "policy": { "$ref": "#/definitions/checkPolicy" },
+      "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" }
+    } },
     "effort": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$" },
     "inputList": { "type": "array", "maxItems": 256, "items": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "\\S" } },
     "checkPolicy": { "type": "object", "additionalProperties": false, "properties": {