agents-relay 2.0.249 → 2.0.251

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -5,6 +5,8 @@ Agents Relay is a TypeScript runtime for durable asynchronous agent Jobs driven
5
5
  V2 uses a read-only local SQLite Job Registry for discovery. The immutable jobId selects the Job Store even when prNumber is zero; lifecycle transitions are atomic across processes. GitHub is **audit-only**: its PR/head/publish events are persisted for reporting, never consulted to start, stop, or complete local Workflows. Local Git delivery and its confirmed merge receipt—not a remote PR MERGED fact—gate Graph completion. Job creation and local Task operations require no GitHub authentication or PR.
6
6
 
7
7
 
8
+ Agent frontmatter hints (`skills`, `model`, `reasoning`) are described in [Agent Definition Contract](skills/agents-relay/contracts/agent-contract.md). They are advisory only and do not alter Skill resolution or Router constraints.
9
+
8
10
  The canonical V2 architecture contract is
9
11
  [DESIGN-PRINCIPLES.md](DESIGN-PRINCIPLES.md). README sections below describe
10
12
  the runtime; they do not replace that contract.
@@ -17,6 +19,14 @@ Relay appends `--handoff-file`, optional `--on-needs-user-file`, and `--cwd`
17
19
  without using a shell. No Neo executable is assumed. Missing/failed executors
18
20
  produce `technical_failure` rather than silently resolving a blocker.
19
21
 
22
+ **Shortcut three-node L3 gate:** `npm run test:l3:shortcut` runs four isolated,
23
+ deterministic three-agent DAG scenarios: no review, sequential approvals,
24
+ Request Changes for a scripted node with a durable revision Worker, and
25
+ Request Changes for a model-only node with re-review. They exercise real
26
+ Shortcut CLI/SQLite/Git review identities and the real Reconciler with a
27
+ synthetic model adapter; no external model, iPhone, or production Job is used.
28
+ The gate is also included in `test:shortcut:dags` and `test:publish`.
29
+
20
30
  **Interactive Review:** Relay owns the generic
21
31
  `review.interactive.begin/wait/ready/fail/abort` lifecycle, immutable revision
22
32
  binding and decision correlation. The caller (e.g. Neo's Markcut MCP wrapper)
@@ -28,12 +28,11 @@ export async function beginInteractiveReview(store, jobId, taskId, executionId)
28
28
  reused = true; // Wrapper rejects a second compile for this pending request.
29
29
  }
30
30
  else if (!existing || (existing.executionId !== executionId &&
31
- (existing.status === 'changes_requested' || existing.status === 'awaiting_decision'))) {
32
- // A new authoritative RUNNING execution replaces a stale undelivered
33
- // invocation left behind by a crashed prior wrapper/worker. The old
34
- // execution cannot still be current by the Task execution guard above.
35
- // The prior decision remains in the durable decision ledger and Task
36
- // comments. A fresh execution may start the next preview revision.
31
+ (existing.status === 'changes_requested' || existing.status === 'awaiting_decision' || existing.status === 'approved'))) {
32
+ // A new authoritative execution can open the next Stage Preview after
33
+ // a prior approval, requested revision, or stale undelivered preview.
34
+ // The current execution guard prevents replacing an in-flight decision;
35
+ // historical decisions remain in the ledger and Task comments.
37
36
  invocationId = proposedId;
38
37
  task.interactiveInvocation = { invocationId, executionId, revision: `pending:${invocationId}`,
39
38
  status: 'awaiting_decision', boundAt: new Date().toISOString() };
@@ -54,7 +54,7 @@ export class Reconciler extends ReconcilerReviewBase {
54
54
  return;
55
55
  if (task.kind !== 'planner' && task.adapter !== 'orchestrator')
56
56
  await this.launch(job, task);
57
- }, context => `effect.launchTask:${context.jobId}:${context.taskId ?? 'task'}:${String(context.data?.attempt ?? 0)}`));
57
+ }, context => `effect.launchTask:${context.jobId}:${context.taskId ?? 'task'}:${String(context.data?.attempt ?? 0)}:${String(context.data?.reviewInvocationId ?? 'initial')}`));
58
58
  this.workflowEffects.register(new CallbackWorkflowEffectHandler('effect.launchShortcut', async (context) => launchShortcutEffect(this.store, this.options, context.jobId, context.taskId, event => this.emit(event)), context => `effect.launchShortcut:${context.jobId}:${context.taskId ?? 'task'}:${String(context.data?.attempt ?? 0)}`));
59
59
  this.workflowEffects.register(new CallbackWorkflowEffectHandler('effect.resumeShortcut', async (context) => resumeShortcutEffect(this.store, this.options, context.jobId, context.taskId, context.data, event => this.emit(event)), context => `effect.resumeShortcut:${context.jobId}:${context.taskId ?? 'task'}:${String(context.data?.executionId ?? '')}:${String(context.data?.nodeId ?? '')}:${String(context.data?.waitId ?? '')}`));
60
60
  this.workflowEffects.register(new CallbackWorkflowEffectHandler('effect.cancelActiveTasks', async (context) => this.cancelActiveTasks(context.jobId, String(context.data?.reason ?? 'Job terminated'))));
@@ -83,7 +83,7 @@ export class Reconciler extends ReconcilerReviewBase {
83
83
  for (const task of dispatchable) {
84
84
  const shortcut = task.result?.data?.shortcut;
85
85
  await transitionTaskEvent(task, 'dispatch', { dispatchable: true, shortcutExecution: scheduled.executionMode === 'shortcut' && scheduled.contentOnly === true && shortcut?.workerFallback !== true && Boolean(task.agentGraph), shortcutFallback: shortcut?.workerFallback === true, shortcutHasGraph: Boolean(task.agentGraph) }, async (actionId) => {
86
- const outcomes = await this.workflowEffects.execute([actionId], { jobId: scheduled.id, taskId: task.id, transitionKey: `dispatch:${task.attempt}`, data: { attempt: task.attempt } });
86
+ const outcomes = await this.workflowEffects.execute([actionId], { jobId: scheduled.id, taskId: task.id, transitionKey: `dispatch:${task.attempt}`, data: { attempt: task.attempt, ...(task.interactiveInvocation?.decidedAt ? { reviewInvocationId: task.interactiveInvocation.invocationId } : {}) } });
87
87
  await this.applyTaskEffectOutcomes(scheduled, task, outcomes);
88
88
  }, async () => { await this.store.saveTask(task); });
89
89
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "agents-relay",
3
- "version": "2.0.249",
3
+ "version": "2.0.251",
4
4
  "description": "Durable async agent jobs coordinated through GitHub pull requests",
5
5
  "repository": {
6
6
  "type": "git",
@@ -16,8 +16,9 @@
16
16
  "test": "npm run test:full",
17
17
  "test:chatgpt-temp-quality": "AGENTS_RELAY_RUN_CHATGPT_TEMP_QUALITY=1 sh -c \"npm run build && node test/quality/run-temporary-chat.mjs\"",
18
18
  "dev": "tsx src/cli.ts",
19
- "test:publish": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 --test-force-exit test/*.test.js",
20
- "test:shortcut:dags": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/verification/shortcut-dag-matrix.test.mjs test/agent-shortcut.test.js",
19
+ "test:publish": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 --test-force-exit test/*.test.js test/verification/l3-shortcut-review.test.mjs",
20
+ "test:l3:shortcut": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/verification/l3-shortcut-review.test.mjs",
21
+ "test:shortcut:dags": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/verification/shortcut-dag-matrix.test.mjs test/verification/l3-shortcut-review.test.mjs test/agent-shortcut.test.js",
21
22
  "test:fast": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=2 test/workflow-lifecycle.test.js test/workflow-v2-lifecycle-parity.test.js test/workflow-effects.test.js test/relay-store.test.js test/local-authority.test.js test/local-jobid-routing.test.js test/interactive-request.test.js test/local-sqlite-jobid.test.js test/no-github.test.js test/reconcile-coordinator.test.js test/service-publication.test.js test/github-webhook.test.js test/verification/shortcut-dag-matrix.test.mjs",
22
23
  "test:full": "npm run build && node --import ./test/test-store-env.mjs --test --test-concurrency=1 test/*.test.js test/verification/shortcut-dag-matrix.test.mjs && npm run test:verification:l3",
23
24
  "test:verification:l1": "npm run build && node --test test/verification/harness.test.mjs test/verification/contract.test.mjs test/browser-worker-pool-graph.test.js test/verification/graph-inventory.test.mjs test/verification/dashboard-drilldown.test.mjs test/verification/evidence-matrix.test.mjs test/verification/task-resolution-classification.test.mjs test/verification/planner-contract.test.mjs test/verification/force-restate-validation.test.mjs test/planner-child-recovery.test.js",
@@ -31,7 +31,7 @@ Read `contracts/task-job-contract.md` before authoring or changing Jobs or Tasks
31
31
 
32
32
  Usually let `job create --initial-plan` establish the first Planner round; use `plan` for an existing create-only Job. Direct `task create` is for deliberately orchestrator-authored work. Tasks describe verifiable outcomes, **not shell commands**. Declare exactly one durable result (`task_pr` or `file`), meaningful dependencies, and `storySize`; Relay chooses worker/model routes unless the task truly needs a specific capability.
33
33
 
34
- Agent frontmatter `skills` suggests Worker skills; `model` and `reasoning` suggest a Router preference. None are mandatory.
34
+ Agent `skills` suggests Worker skills; `model`/`reasoning` suggest Router preferences. Neither is mandatory (see `contracts/agent-contract.md`).
35
35
 
36
36
  An assigned **execution Prompt** pins a specific Skill version and supplies Role, Bootstrap, Contracts, Contexts, and Task/Plan identity. Preserve these references. Resolve the matching CLI as `../../dist/cli.js` relative to the pinned Skill directory; do **not** substitute an unrelated globally installed CLI. Before acting, load the exact execution-bound context:
37
37
 
@@ -0,0 +1,64 @@
1
+ # Agents Relay Agent Definition Contract
2
+
3
+ This is the canonical contract for optional Agent frontmatter hints and their
4
+ effect on execution. It applies to project, shared, and Relay-built-in Agents,
5
+ including merged Agents. Agent role instructions, Task content, and Graph-owned
6
+ workflow/lifecycle behavior remain unchanged.
7
+
8
+ ## Optional frontmatter
9
+
10
+ Use simple top-level YAML scalar fields and inline comma-separated lists.
11
+ These fields are **advisory**, never requirements:
12
+
13
+ ```yaml
14
+ ---
15
+ name: vlog-editor
16
+ extends: shared/vlog-editor
17
+ skills: [markcut, shotcraft]
18
+ model: openai/gpt-6
19
+ reasoning: high
20
+ ---
21
+ ```
22
+
23
+ | Field | Consumer | Semantics |
24
+ | --- | --- | --- |
25
+ | `skills` | Worker User Assignment (including Planner) | Optional skill suggestions, e.g. `Suggested skills ...: markcut, shotcraft`. Only use relevant, available skills. |
26
+ | `model` | Unified Execution Router decision prompt | Preferred provider/model name, e.g. `openai/gpt-6`, for advisory ranking only. |
27
+ | `reasoning` | Unified Execution Router decision prompt | Preferred reasoning effort, e.g. `high`, for advisory ranking only. |
28
+
29
+ A field may be omitted. `reasoning` can be specified without `model`.
30
+ These optional hints do not auto-install/discover/select/require skills, do not
31
+ make a Task depend on a skill, do not create or enable model candidates, and do
32
+ not override the Task's explicit routing constraints, available routes, resource
33
+ or runtime gates, user routing instructions, or deterministic fallback.
34
+ Unknown/unavailable suggestions are not execution errors.
35
+
36
+ ## Resolution and precedence
37
+
38
+ The effective Agent inherits frontmatter metadata using the existing Agent
39
+ resolution and `extends` merge rules; a more specific override wins.
40
+ The selected Agent's `skills` hint appears in the Worker/Planner **user
41
+ prompt**, not as an enforced bootstrap/contract requirement. The selected
42
+ Agent's `model` and `reasoning` hints go to the Router **decision prompt**,
43
+ not to the Worker prompt.
44
+
45
+ User-authored Router `[routing-instruction]` guidance has priority over Agent
46
+ preferences, and authoritative hard constraints still apply before selection.
47
+ Only configured/default or explicitly listed `[choices]` routes are eligible;
48
+ the Agent hint does not widen that choice set. Existing Router selection,
49
+ fallback, review, and lifecycle behavior stays the same.
50
+
51
+ When a field is missing, Relay does not add the corresponding hint. If no safe,
52
+ read-only Agent path can be resolved for routing, Relay skips the optional
53
+ Router advice rather than preparing a Task worktree or blocking a valid route.
54
+ The frontmatter is not durable Job/Task state and does not change CLI or
55
+ SQLite schemas.
56
+
57
+ ## Related contracts
58
+
59
+ - [Task / Job Contract](task-job-contract.md) remains authoritative for durable
60
+ Task/Job inputs, dependencies, and lifecycle facts.
61
+ - [Prompt Builder](../../../docs/agent-prompt-builder.md) documents the actual
62
+ Worker User Assignment and the merged Agent snapshot.
63
+ - [Execution Router](../../../docs/worker-model-routers.md) documents choice
64
+ discovery, hard gates, decision priorities, and fallback.
@@ -17,6 +17,10 @@ When creating a new Job from an active discussion, the orchestrator must consoli
17
17
 
18
18
  Use `job create` with standalone objective Markdown. Existing PRs are not imported as Jobs. Use Relay CLI for subsequent Job reads and updates; do not infer Job state or objective from GitHub.
19
19
 
20
+ ## Agent definitions and advisory frontmatter
21
+
22
+ Agent frontmatter `skills`, `model`, and `reasoning` are optional **hints**, not Task requirements. See the canonical [Agent Definition Contract](agent-contract.md) for syntax, inheritance, the separate Worker/Router prompt consumers, and the unchanged hard-gate/Skill resolution semantics. Task producers must not turn those hints into durable Task routing constraints or required Skills.
23
+
20
24
  ## Task producers
21
25
 
22
26
  Any task producer — orchestrator, planner, or nested task-producing agent — must follow this contract.