Agent-first pivot + workflow-system hardening (docs/spec/ADR — Phase 1 not started)#5
Merged
Conversation
…25/0026) Record the Option-A pivot from workflow-first to agent-first + workflow: a conversational AgentSession becomes a first-class engine entry point alongside WorkflowEngine, reusing the ToolRegistry + @relavium/llm seam + event bus, with a chat → workflow export (the "graduation" continuum). - ADR-0024: AgentSession as a second engine entry point (session:* namespace, history.db persistence, resumable, one agent + fallback chain per session). - ADR-0025: refine ADR-0007's desktop scope — a conversational chat panel is an agent capability (allowed), distinct from an IDE shell (editor/file-tree/terminal, still forbidden); Chat & Canvas co-equal tabs, neutral default landing. - ADR-0026: session → .relavium.yaml export as a reviewed linear-chain scaffold. - Append-only amendments to ADR-0007/0009/0011 (dated notes; decisions intact). - New canonical contract reference/contracts/agent-session-spec.md and the architecture home architecture/agent-sessions.md (cites shared-core-engine). - decisions/README index rows for ADR-0024..0029. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…DR-0027/0028/0029) A pre-Phase-1 hardening pass over the workflow specs (validated against the specs; 8 of 27 candidate findings dropped as misframed/already-handled). - ADR-0027: expression sandbox for condition/transform/merge_fn — QuickJS-wasm via the WebAssembly global from embedded bytes (no node:fs/fetch/DOM, no new Function), deterministic (no wall-clock/RNG), CPU/mem/time-capped; expression_type is js-only in v1.0 (jmespath/jsonlogic reserved). - ADR-0028: workflow resource governance — pre-egress budget cap + run timeout + parallel concurrency cap; pause_for_approval reuses the human-gate seam; BYOK-first-class, distinct from ADR-0014 managed billing. - ADR-0029: tool-policy hardening — exact-match allowedCommands, node tools narrow-only, secret-no-interpolation, and one SSRF primitive across provider base URLs + http_request + MCP server URLs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…nonical specs - sse-event-schema: session:* namespace + SessionEvent; budget:warning/paused + run:timeout + run:paused (multi-gate aggregate) in the RunEvent union; reserved steering/iteration events; ErrorCode taxonomy; attemptNumber; forward-compat rule; decidedBy 'timeout' (escalate reserved). - database-schema: agent_sessions + session_messages (history.db; bound to sessions, distinct from the run messages table). - config-spec: [chat] block referencing [defaults].fs_scope + allowedCommands (no fork). - ipc-contract: session commands + resume_budget. - workflow-yaml-spec + node-types: expression_type js-only; budget block; condition strict-equality; eager-once context; escalate reserved; parse-time model resolution; edge data_mapping reserved; inputs.validation; output_schema; tool-policy tightenings. - agent-yaml-spec: expose output_schema/input_schema. Index rows + canonical-home line. Refs ADR-0024/0026/0027/0028/0029. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
shared-core-engine now owns the unified-substrate narrative: WorkflowEngine and AgentSession are co-equal entry points on one substrate (AgentRunner, ToolRegistry, @relavium/llm seam, RunEventBus, Checkpointer), hardened once by ADR-0027/0028/0029. overview + execution-model add the second entry point and scope notes; state-management marks sessions DB-first (no sixth store). agent-sessions.md cites this file. Refs ADR-0024/0027/0028/0029. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- CLI: relavium chat REPL + chat-resume/list/export + agent run + gate list; exit code 4; new cli/chat-session.md. - Desktop: /chat + /chat/:sessionId, Chat/Canvas co-equal tabs with a neutral default landing (ADR-0025); Export-to-Canvas; agent-capability-vs-IDE-shell line intact. - VS Code: full chat-assistant panel + openChat/exportChatSession + chat events. Refs ADR-0024/0025/0026. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…1/M2 spine inversion
- Phase 1: agent-first sub-spine 1.V–1.AA (parallel, not on the M2 critical path) +
1.AB expression sandbox (on the critical path, folds into 1.P) + 1.AC resource
governor; mermaid + milestone table updated (M1/M2 definitions kept).
- Phase 2: relavium chat (2.M–2.Q) + agent run + gate list; exit code 4 in the map.
- Phase 3: insert chat 3.N + export 3.O after 3.M; rename sign-off 3.N → 3.P across
mermaid, heading, the M4 milestone cell, risk rows, and the global spine.
- Phase 4: workstreams 4.L/4.M; in-phase milestones renamed 4.M* → P4.M* (collision).
- Fix a pre-existing global-spine bug: roadmap/README had M1 ('core engine') and M2
('LLM seam') inverted relative to phase-1 — a dependency inversion (M1's AgentRunner
+ retry need the seam M2 delivered). Aligned to phase-1: M1 = LLM seam proven,
M2 = engine end-to-end (critical-path). current.md updated to match.
- Reserve human-gate escalate consistently (decidedBy 'timeout' across phases).
Refs ADR-0024/0026/0027/0028.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…ials, analysis - Positioning: tagline → "Start as an agent. Ship the workflow. Own every run."; vision/uvp reframed to two co-equal entry points (chat + workflow); product-constraints keeps the no-editor/file-tree/terminal line, adds conversation-mode (ADR-0025); README/docs/README/project-structure/deployment-models updated. - Governance: CLAUDE.md #7 + AGENTS.md #6 refined to agent-capability vs IDE-shell; AGENTS.md status corrected to Phase-0-complete. - Standards: architectural-principles 4a (conversational agent is a first-class entry point); security-review adds the chat secret boundary, the three-pronged SSRF policy (base URL + http_request + MCP, one primitive), and the ADR-0027 sandbox rules. - Glossary: AgentSession / mode / chat-to-workflow terms + SessionEvent; tagline + unit-of-value softened; escalate reserved. - Tutorials: chat-first entry + new start-a-chat-session (planned). - New dated competitive-landscape-2026-06-05 (two-entry-point thesis); 06-03 frozen. Refs ADR-0024/0025/0026/0027/0029. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Reviewer's GuideDocs-only PR that pivots Relavium from workflow-first to agent-first+workflow, introducing AgentSession as a second engine entry point alongside WorkflowEngine, defining its contracts and surfaces, and simultaneously hardening the workflow system around tool policy, expression sandboxing, resource governance, and roadmap alignment — all without touching packages/apps code. Sequence diagram for chat-to-workflow export via AgentSessionsequenceDiagram
actor User
participant CLI as CLI_relavium
participant AgentSession
participant HistoryDB as history_db
participant WorkflowEngine
User->>CLI: relavium chat
CLI->>AgentSession: start(agentRef, context)
AgentSession->>HistoryDB: insert agent_session
loop per_turn
User->>CLI: message text
CLI->>AgentSession: sendMessage(sessionId, text)
AgentSession->>HistoryDB: append session_message
end
User->>CLI: relavium chat-export sessionId
CLI->>AgentSession: exportToWorkflow(sessionId)
AgentSession->>HistoryDB: read agent_session + session_messages
AgentSession->>WorkflowEngine: createWorkflowScaffold(transcript)
WorkflowEngine-->>CLI: workflowPath
CLI-->>User: open .relavium.yaml scaffold
Entity-relationship diagram for new agent session persistence tableserDiagram
agents {
TEXT id PK
TEXT slug
}
agent_sessions {
TEXT id PK
TEXT agent_id FK
TEXT agent_slug
TEXT agent_snapshot
TEXT title
TEXT model_id
TEXT working_dir
TEXT git_ref
TEXT fs_scope_tier
TEXT status
TEXT context_json
INTEGER total_input_tokens
INTEGER total_output_tokens
INTEGER total_cost_microcents
TEXT exported_workflow_path
INTEGER created_at
INTEGER updated_at
}
session_messages {
TEXT id PK
TEXT session_id FK
INTEGER sequence_number
TEXT role
TEXT content
TEXT content_parts
TEXT tool_calls
TEXT tool_call_id
TEXT name
TEXT finish_reason
INTEGER input_tokens
INTEGER output_tokens
INTEGER cost_microcents
INTEGER created_at
}
agents ||--o{ agent_sessions : "configured_by"
agent_sessions ||--o{ session_messages : "has_messages"
File-Level Changes
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (2)
📝 WalkthroughWalkthroughThis PR updates documentation and ADRs to pivot Relavium to an agent-first + workflow platform: introduces AgentSession as a co-equal engine entry point, defines session persistence/export contracts, tightens sandboxing/tool/security policies, and integrates session behavior across CLI, desktop, VS Code, contracts, and the roadmap. ChangesAgent-First Platform Pivot
Estimated code review effort 🎯 3 (Moderate) | ⏱️ ~25 minutes Possibly related PRs:
✨ Finishing Touches🧪 Generate unit tests (beta)
|
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
![gemini-code-assist[bot]](https://avatars.githubusercontent.com/in/956858?s=60&v=4){kind=small}
There was a problem hiding this comment.
Code Review
This pull request establishes the "agent-first + workflow" pivot for the Relavium platform, introducing conversational AgentSessions as a first-class engine entry point alongside the WorkflowEngine. It adds specifications and architectural designs for persistent, resumable chat sessions, a chat-to-workflow export continuum, a QuickJS-wasm expression sandbox, pre-egress budget governance, and tightened tool policies. The review comments are highly constructive and should all be kept, as they identify important improvement opportunities: tracking fallback models in the database and message contracts, propagating errors in session events, refining budget estimation when max_tokens is omitted, and strictly validating transitive secret interpolation to prevent prompt leaks.
Important
The consumer version of Gemini Code Assist on GitHub is being sunset. Starting June 18, 2026, new organization installations will be blocked, and all code review activity will officially cease on July 17, 2026.
For more details on the timeline and next steps, please review the Help Documentation.
Comment on lines
+360
to
+375
| | Column | Type | Constraints | | ||
| |--------|------|-------------| | ||
| | `id` | TEXT | PRIMARY KEY (UUID) | | ||
| | `session_id` | TEXT | NOT NULL REFERENCES `agent_sessions(id)` ON DELETE CASCADE | | ||
| | `sequence_number` | INTEGER | NOT NULL — monotonic per session (append-only) | | ||
| | `role` | TEXT | NOT NULL (`system`, `user`, `assistant`, `tool`) | | ||
| | `content` | TEXT | NULL | | ||
| | `content_parts` | TEXT (JSON) | NULL — multimodal/structured parts | | ||
| | `tool_calls` | TEXT (JSON) | NULL | | ||
| | `tool_call_id` | TEXT | NULL | | ||
| | `name` | TEXT | NULL | | ||
| | `finish_reason` | TEXT | NULL | | ||
| | `input_tokens` | INTEGER | NOT NULL DEFAULT 0 | | ||
| | `output_tokens` | INTEGER | NOT NULL DEFAULT 0 | | ||
| | `cost_microcents` | INTEGER | NOT NULL DEFAULT 0 | | ||
| | `created_at` | INTEGER | NOT NULL | |
There was a problem hiding this comment.
Since an AgentSession can use fallback models (as described in the specs), the session_messages table should store the actual model used for each turn. Without a model_id column, the UI cannot correctly display which model generated a specific response in the history transcript once the session is reloaded.
Comment on lines
+88
to
+95
| interface SessionMessage { | ||
| id: string; | ||
| sessionId: string; | ||
| sequenceNumber: number; // monotonic per session | ||
| role: 'system' | 'user' | 'assistant' | 'tool'; | ||
| content: ContentPart[]; // text | tool_call | tool_result parts | ||
| timestamp: string; // ISO 8601 | ||
| } |
There was a problem hiding this comment.
To support fallback model tracking in the conversation transcript, the SessionMessage interface should include an optional modelId field. This ensures the runtime representation matches the database schema and allows the UI to display the correct model for each turn.
Suggested change
| interface SessionMessage { | |
| id: string; | |
| sessionId: string; | |
| sequenceNumber: number; // monotonic per session | |
| role: 'system' | 'user' | 'assistant' | 'tool'; | |
| content: ContentPart[]; // text | tool_call | tool_result parts | |
| timestamp: string; // ISO 8601 | |
| } | |
| interface SessionMessage { | |
| id: string; | |
| sessionId: string; | |
| sequenceNumber: number; // monotonic per session | |
| role: 'system' | 'user' | 'assistant' | 'tool'; | |
| modelId?: string; // the model that generated this message (null for user/system/tool) | |
| content: ContentPart[]; // text | tool_call | tool_result parts | |
| timestamp: string; // ISO 8601 | |
| } |
Comment on lines
+185
to
+191
| export type SessionEvent = | ||
| | SessionStartedEvent // 'session:started' — { agentRef, model, context } | ||
| | SessionTurnStartedEvent // 'session:turn_started' — a user message began an assistant turn | ||
| | SessionTurnCompletedEvent // 'session:turn_completed' — { stopReason, tokensUsed } | ||
| | SessionCancelledEvent // 'session:cancelled' — the in-flight turn was aborted | ||
| | SessionExportedEvent; // 'session:exported' — { workflowPath } (chat-to-workflow export) | ||
| ``` |
There was a problem hiding this comment.
If a session turn fails (e.g., due to a provider error or rate limit), the event stream needs to convey the error details so the UI can display a helpful error message. Adding an optional error field to SessionTurnCompletedEvent ensures proper error propagation.
Suggested change
| export type SessionEvent = | |
| | SessionStartedEvent // 'session:started' — { agentRef, model, context } | |
| | SessionTurnStartedEvent // 'session:turn_started' — a user message began an assistant turn | |
| | SessionTurnCompletedEvent // 'session:turn_completed' — { stopReason, tokensUsed } | |
| | SessionCancelledEvent // 'session:cancelled' — the in-flight turn was aborted | |
| | SessionExportedEvent; // 'session:exported' — { workflowPath } (chat-to-workflow export) | |
| ``` | |
| export type SessionEvent = | |
| | SessionStartedEvent // 'session:started' — { agentRef, model, context } | |
| | SessionTurnStartedEvent // 'session:turn_started' — a user message began an assistant turn | |
| | SessionTurnCompletedEvent // 'session:turn_completed' — { stopReason, tokensUsed, error?: { code: ErrorCode, message: string } } | |
| | SessionCancelledEvent // 'session:cancelled' — the in-flight turn was aborted | |
| | SessionExportedEvent; // 'session:exported' — { workflowPath } (chat-to-workflow export) |
|
|
||
| ### Negative | ||
|
|
||
| - `worstCaseNextEstimate` is an estimate (it uses `maxTokens`), so the cap is conservative — it may |
There was a problem hiding this comment.
When max_tokens is omitted on a node, using the model's absolute maximum output limit for worstCaseNextEstimate can result in extremely conservative estimates that prematurely block runs (e.g., blocking on the first turn of a small budget). Consider specifying a fallback default or requiring max_tokens on nodes when a budget is defined.
| - **(b) Node tools narrow-only.** A node's `tools:` may only **intersect** (narrow) the agent's | ||
| granted tools; it can never add a tool the agent lacks. Enforced by the parser | ||
| ([ADR-0023](0023-strict-authored-yaml-validation.md)). | ||
| - **(c) No secret interpolation into agent text.** `secret`-typed inputs are **rejected at parse** |
There was a problem hiding this comment.
The parser must also strictly validate transitive interpolation (e.g., assigning a secret input to a context variable and then interpolating that variable into a prompt) to prevent bypassing the secret-interpolation rejection rule.
|
Caution Failed to replace (edit) comment. This is likely due to insufficient permissions or the comment being deleted. Error details |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (1)
CLAUDE.md (1)
38-39:⚠️ Potential issue | 🟡 Minor | ⚡ Quick winFix malformed ADR range link separator.
The
ADR-0012..ADR-0015reference currently uses..directly between two links, which reads as a formatting typo and can confuse readers. Use a clear separator (to,–, or comma-separated links).Suggested edit
- engine is identical across all three. See [ADR-0012](docs/decisions/0012-managed-inference-dual-mode.md)..[ADR-0015](docs/decisions/0015-managed-mode-data-handling-and-compliance.md) + engine is identical across all three. See [ADR-0012](docs/decisions/0012-managed-inference-dual-mode.md) to [ADR-0015](docs/decisions/0015-managed-mode-data-handling-and-compliance.md)🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@CLAUDE.md` around lines 38 - 39, The ADR link range uses a malformed separator ("..") between two markdown links; edit the sentence containing the ADR references (ADR-0012 and ADR-0015) to replace the ".." with a clear separator such as "to" or an en-dash (e.g., "ADR-0012 to ADR-0015" or "ADR-0012–ADR-0015") or list the links comma-separated so the links read clearly (update the fragment that currently reads "ADR-0012](... )..[ADR-0015](... )" to use the chosen separator).
🧹 Nitpick comments (3)
docs/standards/security-review.md (1)
145-179: ⚡ Quick winMove concrete tool-policy rule definitions to
docs/reference/and keep this section as a checklist/link hub.This section currently defines detailed normative behavior (exact-match semantics, parse-time rejection, narrowing validation) in
docs/standards/, which risks divergence from canonical specs. Keep brief security requirements here and link to the authoritative reference contract sections for exact rule text.As per coding guidelines, “Concrete specs … must live only in docs/reference/; other files must link to these definitions, never restate them.”
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/standards/security-review.md` around lines 145 - 179, The "Sandbox and tool policy (`run_command`, node tools, secret inputs)" section contains concrete normative rules (exact-match semantics for allowedCommands, allowedCommandGlobs, node `tools:` narrowing, `secret`-typed input parse-time rejection, etc. and citations like ADR-0029/ADR-0023) that must be moved to the canonical reference; edit this section to remove the detailed rule text and replace it with a short checklist and direct links to the authoritative specs in docs/reference (e.g. point to built-in-tools.md, workflow-yaml-spec.md and ADR-0029/ADR-0023), keeping only high-level requirements and link anchors and ensuring mentions of symbols like run_command, allowedCommands, allowedCommandGlobs, tools:, and secret-typed inputs remain as pointers rather than normative definitions.docs/roadmap/phases/phase-2-cli.md (1)
120-123: ⚡ Quick winAvoid duplicating CLI process-contract constants in the phase roadmap.
The exact exit-code table and
/exitbehavior are concrete command-spec details; this file should referencedocs/reference/cli/commands.mdrather than restating numeric mappings.As per coding guidelines: “Concrete specs … must live only in docs/reference/; other files must link to these definitions, never restate them.”
Also applies to: 131-132, 410-421
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/roadmap/phases/phase-2-cli.md` around lines 120 - 123, This file duplicates CLI process-contract constants (exit codes and `/exit` behavior); remove the numeric mappings and the `/exit` specification from phase-2-cli.md and replace them with a single reference to the canonical definitions in docs/reference/cli/commands.md (the same link already mentioned in the text). Specifically, delete the explicit exit code text (exit 3 for gate-paused, exit 4 for chat session ended) and instead insert a short pointer like “See docs/reference/cli/commands.md for exit-code and /exit behavior” so the phase roadmap references the authoritative symbols maintained in commands.md.docs/roadmap/phases/phase-1-engine-and-llm.md (1)
483-488: ⚡ Quick winPrefer linking to canonical spec instead of restating behavior details here.
This section duplicates concrete contract semantics (
timeout_action/on_timeout, aggregate pause semantics, pre-egress budget formula) that should stay canonical indocs/reference/**. Keep this phase doc at milestone/task level and link to the contract anchors.As per coding guidelines: “Concrete specs … must live only in docs/reference/; other files must link to these definitions, never restate them.”
Also applies to: 582-590
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/roadmap/phases/phase-1-engine-and-llm.md` around lines 483 - 488, This section restates concrete contract semantics (timeout_action / on_timeout mapping, run:paused aggregate behavior, pre-egress budget formula) that must live only in the canonical reference; remove the detailed semantics text and replace each restatement with a short milestone-level sentence plus a link to the authoritative anchors (referencing the human_gate-node anchor in the workflow-yaml-spec and the relevant pre-egress budget anchor in docs/reference), leaving only task/milestone descriptions and links; ensure the duplicate passages at the later block (the one mentioned for lines 582-590) are updated the same way and keep the symbols timeout_action, on_timeout and run:paused as plain references only.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/analysis/competitive-landscape-2026-06-05.md`:
- Around line 36-38: In the sentence under "The workflow is a git-committable
file" containing the phrase ".relavium.yaml", replace the misspelled word
"revertable" with the correct word "reversible" so the line reads
"...reviewable, diffable, reversible, and shareable..." (update the markdown in
the file that contains that paragraph).
In `@docs/reference/shared-core/node-types.md`:
- Around line 128-130: The blockquote containing "The authored YAML uses
friendlier field names..." and the following "Expression languages (condition /
transform)." paragraph has an empty quoted line that triggers MD028; remove that
blank quoted separator so the two quoted paragraphs form one continuous
blockquote (i.e., join the quoted lines so there is no blank quoted line between
the YAML paragraph and the Expression languages paragraph).
In `@docs/vision.md`:
- Line 81: The docs row currently marks `relavium chat` as "(Phase 2)" but
elsewhere `AgentSession` and CLI chat are described as current functionality;
update this table cell to consistently reflect `relavium chat` as a Phase 1 /
current first-class `AgentSession` entry point (or change the other docs to
Phase 2 if you intend to delay it). Specifically, replace the "(Phase 2)"
qualifier after `relavium chat` with the matching phrase used in other docs
(e.g., "current" or "Phase 1") so references to `relavium chat` and
`AgentSession` are consistent across the documentation.
---
Outside diff comments:
In `@CLAUDE.md`:
- Around line 38-39: The ADR link range uses a malformed separator ("..")
between two markdown links; edit the sentence containing the ADR references
(ADR-0012 and ADR-0015) to replace the ".." with a clear separator such as "to"
or an en-dash (e.g., "ADR-0012 to ADR-0015" or "ADR-0012–ADR-0015") or list the
links comma-separated so the links read clearly (update the fragment that
currently reads "ADR-0012](... )..[ADR-0015](... )" to use the chosen
separator).
---
Nitpick comments:
In `@docs/roadmap/phases/phase-1-engine-and-llm.md`:
- Around line 483-488: This section restates concrete contract semantics
(timeout_action / on_timeout mapping, run:paused aggregate behavior, pre-egress
budget formula) that must live only in the canonical reference; remove the
detailed semantics text and replace each restatement with a short
milestone-level sentence plus a link to the authoritative anchors (referencing
the human_gate-node anchor in the workflow-yaml-spec and the relevant pre-egress
budget anchor in docs/reference), leaving only task/milestone descriptions and
links; ensure the duplicate passages at the later block (the one mentioned for
lines 582-590) are updated the same way and keep the symbols timeout_action,
on_timeout and run:paused as plain references only.
In `@docs/roadmap/phases/phase-2-cli.md`:
- Around line 120-123: This file duplicates CLI process-contract constants (exit
codes and `/exit` behavior); remove the numeric mappings and the `/exit`
specification from phase-2-cli.md and replace them with a single reference to
the canonical definitions in docs/reference/cli/commands.md (the same link
already mentioned in the text). Specifically, delete the explicit exit code text
(exit 3 for gate-paused, exit 4 for chat session ended) and instead insert a
short pointer like “See docs/reference/cli/commands.md for exit-code and /exit
behavior” so the phase roadmap references the authoritative symbols maintained
in commands.md.
In `@docs/standards/security-review.md`:
- Around line 145-179: The "Sandbox and tool policy (`run_command`, node tools,
secret inputs)" section contains concrete normative rules (exact-match semantics
for allowedCommands, allowedCommandGlobs, node `tools:` narrowing,
`secret`-typed input parse-time rejection, etc. and citations like
ADR-0029/ADR-0023) that must be moved to the canonical reference; edit this
section to remove the detailed rule text and replace it with a short checklist
and direct links to the authoritative specs in docs/reference (e.g. point to
built-in-tools.md, workflow-yaml-spec.md and ADR-0029/ADR-0023), keeping only
high-level requirements and link anchors and ensuring mentions of symbols like
run_command, allowedCommands, allowedCommandGlobs, tools:, and secret-typed
inputs remain as pointers rather than normative definitions.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 8d1abb4d-201a-440d-a6cb-436abc1cc140
📒 Files selected for processing (57)
AGENTS.mdCLAUDE.mdREADME.mddocs/README.mddocs/analysis/README.mddocs/analysis/competitive-landscape-2026-06-05.mddocs/architecture/agent-sessions.mddocs/architecture/execution-model.mddocs/architecture/overview.mddocs/architecture/shared-core-engine.mddocs/architecture/state-management.mddocs/decisions/0007-desktop-is-not-an-ide.mddocs/decisions/0009-git-native-workflow-yaml.mddocs/decisions/0011-internal-llm-abstraction.mddocs/decisions/0024-agent-first-entry-point-agentsession.mddocs/decisions/0025-agent-surface-refines-desktop-scope.mddocs/decisions/0026-session-export-to-workflow.mddocs/decisions/0027-expression-sandbox.mddocs/decisions/0028-workflow-resource-governance.mddocs/decisions/0029-tool-policy-hardening.mddocs/decisions/README.mddocs/deployment-models.mddocs/glossary.mddocs/product-constraints.mddocs/project-structure.mddocs/reference/README.mddocs/reference/cli/README.mddocs/reference/cli/chat-session.mddocs/reference/cli/commands.mddocs/reference/contracts/README.mddocs/reference/contracts/agent-session-spec.mddocs/reference/contracts/agent-yaml-spec.mddocs/reference/contracts/config-spec.mddocs/reference/contracts/ipc-contract.mddocs/reference/contracts/sse-event-schema.mddocs/reference/contracts/workflow-yaml-spec.mddocs/reference/desktop/README.mddocs/reference/desktop/database-schema.mddocs/reference/desktop/routes-and-screens.mddocs/reference/shared-core/node-types.mddocs/reference/shared-core/store-shapes.mddocs/reference/vscode/README.mddocs/reference/vscode/extension-api.mddocs/roadmap/README.mddocs/roadmap/current.mddocs/roadmap/phases/phase-1-engine-and-llm.mddocs/roadmap/phases/phase-2-cli.mddocs/roadmap/phases/phase-3-desktop.mddocs/roadmap/phases/phase-4-vscode.mddocs/roadmap/phases/phase-6-cloud-execution-portal.mddocs/standards/architectural-principles.mddocs/standards/documentation-style.mddocs/standards/security-review.mddocs/tutorials/README.mddocs/tutorials/cli/start-a-chat-session.mddocs/uvp.mddocs/vision.md
Verified each finding against the docs; fixed the still-valid ones, skipped the rest. Fixed: - competitive-landscape: "revertable" → "reversible". - node-types: MD028 — join the two adjacent blockquotes (engine-config note + expression-languages note) into one continuous quote. - CLAUDE.md: malformed ".." between ADR-0012/ADR-0015 links → "to". - Session model tracking: add session_messages.model_id + SessionMessage.modelId? (fallback-aware — transcript shows which model answered each turn). - Session error propagation: session:turn_completed gains optional error? (ErrorCode taxonomy) so a failed turn is conveyed, not a silent stall. - ADR-0028: when a node omits maxTokens, the pre-egress estimate uses a configured per-call default (not the model's absolute max, which would over-block). - ADR-0029(c): secret-no-interpolation is transitive (taint-tracked through context entries / derived values), mirrored in workflow-yaml-spec + security-review. - phase-1 1.AC: drop the restated budget formula; point to ADR-0028 (one canonical home). Skipped (with reason): - vision `relavium chat` "(Phase 2)" — correct: it is the Phase-2 CLI workstream (2.M); the AgentSession engine is Phase 1 but the CLI command is Phase 2; no doc calls it current. - phase-2 exit-code map — kept: §2.A is the CLI process-contract workstream, already names commands.md as canonical, and the maintainer's review explicitly asked to reflect exit-4 here. - security-review §sandbox-and-tool-policy — kept: it is the binding security standard; stating normative rules is its role (ADR-0029 names it the binding home). Field defs are cited. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
…+ fix consistency defects Verified each finding from the two review passes; fixed the clear consistency/completeness defects (design/business calls deferred to the maintainer). - tech-stack.md: add the QuickJS-wasm row ADR-0027 says lives here (the engine's first runtime dependency was unrecorded — non-negotiable #2/#8). - built-in-tools.md: propagate ADR-0029 — run_command exact-match, http_request HTTPS-only + exact-FQDN allowedDomains + deny-all-when-empty + SSRF range-block (the promised pointer home). - mcp-integration.md: add the MCP-URL SSRF pointer; note the localhost example needs a local-endpoint opt-in (it was a config the new rule would reject). - sse-event-schema.md: resolve the envelope contradiction — BaseEvent carries runId? | sessionId? (exactly one), so reused agent:*/cost:* events ride a session legitimately; document the full typed session stream (5 session:* + agent:*/cost:* on sessionId) a chat --json consumer sees. - store-shapes.md: runStore token buffer is now per-node (Record<NodeId,string>) — a single global buffer corrupts parallel-node streaming, per state-management.md. - extension-api.md: drop the forked .relavium/permissions.yaml allowlist; the VS Code prompt appends to the canonical workflow.tools.allowedCommands (ADR-0029) — one allowlist home across surfaces. - workflow-yaml-spec.md: top-level tools summary now matches the detail (allowedDomains required to use http_request, deny-all-when-empty); add a durable workflow.metadata field. - transcript durability: session export preserves the transcript in workflow.metadata (a schema field that survives round-trips), not fragile YAML comments (agent-session-spec + ADR-0026). - current.md: scope "adds no work to M1/M2" to the agent sub-spine; the sandbox 1.AB is new M2-critical-path work that raises 1.m4. - budget resume cross-surface: add `relavium budget resume` (CLI) + relavium.resumeBudget (VS Code) so ADR-0028's budget:paused has an operator path beyond desktop IPC. Refs ADR-0026/0027/0028/0029. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Maintainer-approved resolutions to the genuine design/strategy questions the two reviews surfaced. - D1 — cross-surface session persistence: history.db is the canonical store (the resume-anywhere differentiator). Phase-4 4.M now persists to history.db (not extension state); the VS Code/CLI Node hosts open the SQLCipher DB via a wasm SQLite build (no native module → respects ADR-0003), documented as a "Cross-host access" note in database-schema.md. Resolves the agent-sessions/extension-api ↔ 4.M contradiction. - D2 — file_patch is now a canonical event: add `agent:file_patch_proposed` to the RunEvent union + table (gated; no write until accepted); extension-api references it instead of inventing `filePatchProposed`. One canonical home. - D3 — chat-session budget: ADR-0028's governor now applies to sessions via a per-session `[chat].max_cost_microcents` + `on_exceed` (config-spec + agent-session-spec), so "both entry points inherit resource governance" (ADR-0024) is literally true and open-ended chat fails safe. - D4 — phase disambiguation + CLI-chat milestone: `relavium chat` is a Product-Phase-1 surface built in build phase 2 (not Product Phase 2 / cloud). Fixed the misleading "(Phase 2)" tags in vision/project-structure/tutorials, qualified the "Killer Features (Phase 1)" engine-vs-surface distinction, and firmed the phase-2 in-phase milestone as the first user-facing AgentSession surface (a committed build-phase-2 deliverable). - D5 — positioning: added an explicit risk/caveat to the competitive analysis — chat is the most contested surface; the moat is the chat→workflow continuum + git-native artifact + local-first, not conversational parity. Made the bet with eyes open. Refs ADR-0024/0026/0028/0029. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 1
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/reference/contracts/sse-event-schema.md`:
- Around line 29-36: The docs and shared schema diverge:
BaseEventSchema/baseFields currently require runId and lack sessionId while the
doc states exactly one of runId/sessionId is present and sequenceNumber is
monotonic per run OR per session; update the shared schema in
packages/shared/src/run-event.ts to match the spec by making runId optional,
adding sessionId?: string, and model the envelope as a union or
runtime-validated shape that enforces "exactly one of runId or sessionId" (e.g.,
two interfaces RunEnvelope { runId: string; sessionId?: undefined } and
SessionEnvelope { sessionId: string; runId?: undefined } and export type
BaseEvent = RunEnvelope | SessionEnvelope), then audit any usages of
BaseEventSchema/baseFields and functions that assumed runId to handle the
sessionId branch, and confirm documentation text about sequenceNumber
monotonicity matches the behavior (per-run or per-session) or adjust the doc
instead if you prefer the code’s current semantics.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: f68fb29b-01fe-4d1a-9375-e8e875628271
📒 Files selected for processing (21)
docs/analysis/competitive-landscape-2026-06-05.mddocs/decisions/0026-session-export-to-workflow.mddocs/decisions/0028-workflow-resource-governance.mddocs/project-structure.mddocs/reference/cli/commands.mddocs/reference/contracts/agent-session-spec.mddocs/reference/contracts/config-spec.mddocs/reference/contracts/sse-event-schema.mddocs/reference/contracts/workflow-yaml-spec.mddocs/reference/desktop/database-schema.mddocs/reference/shared-core/built-in-tools.mddocs/reference/shared-core/mcp-integration.mddocs/reference/shared-core/store-shapes.mddocs/reference/vscode/extension-api.mddocs/roadmap/current.mddocs/roadmap/phases/phase-2-cli.mddocs/roadmap/phases/phase-4-vscode.mddocs/tech-stack.mddocs/tutorials/README.mddocs/tutorials/cli/start-a-chat-session.mddocs/vision.md
✅ Files skipped from review due to trivial changes (13)
- docs/reference/shared-core/mcp-integration.md
- docs/tech-stack.md
- docs/tutorials/cli/start-a-chat-session.md
- docs/tutorials/README.md
- docs/project-structure.md
- docs/roadmap/phases/phase-4-vscode.md
- docs/roadmap/phases/phase-2-cli.md
- docs/decisions/0026-session-export-to-workflow.md
- docs/roadmap/current.md
- docs/reference/contracts/config-spec.md
- docs/analysis/competitive-landscape-2026-06-05.md
- docs/decisions/0028-workflow-resource-governance.md
- docs/reference/contracts/agent-session-spec.md
🚧 Files skipped from review as they are similar to previous changes (4)
- docs/reference/cli/commands.md
- docs/reference/desktop/database-schema.md
- docs/vision.md
- docs/reference/contracts/workflow-yaml-spec.md
Comment on lines
+29
to
+36
| runId?: string; // correlation key on a workflow RUN (omitted on a session) | ||
| sessionId?: string; // correlation key on an agent SESSION (omitted on a run) | ||
| timestamp: string; // ISO 8601 | ||
| sequenceNumber: number; // monotonically increasing per run | ||
| sequenceNumber: number; // monotonic per run OR per session | ||
| } | ||
| ``` | ||
|
|
||
| > **Correlation key.** Exactly one of `runId` / `sessionId` is present — `runId` on a workflow run, `sessionId` on an agent session. The reused `agent:token` / `agent:tool_call` / `agent:tool_result` / `cost:updated` events carry `runId` on a run and `sessionId` on a session; consumers route on whichever is present. |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Check BaseEvent schema and related session/run envelope fields"
fd run-event.ts | xargs -I{} sh -c 'echo "== {} =="; sed -n "1,120p" "{}"'
echo
echo "Find required runId/sessionId usage in shared event schemas"
rg -n -C3 "runId|sessionId|sequenceNumber|BaseEventSchema" packages/shared/srcRepository: HodeTech/Relavium
Length of output: 9913
Fix spec/schema drift in SSE base envelope (runId/sessionId) and sequenceNumber monotonicity.
docs/reference/contracts/sse-event-schema.md (lines 29–36) claims “exactly one of runId / sessionId is present” and that sequenceNumber is “monotonic per run OR per session”, but packages/shared/src/run-event.ts defines the base envelope with runId required (BaseEventSchema/baseFields) and provides no sessionId; it also documents the stream as “Every run produces one ordered stream” (so sequenceNumber is per run). Reconcile the doc with the shared schema (or update the shared schema to include sessionId).
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/reference/contracts/sse-event-schema.md` around lines 29 - 36, The docs
and shared schema diverge: BaseEventSchema/baseFields currently require runId
and lack sessionId while the doc states exactly one of runId/sessionId is
present and sequenceNumber is monotonic per run OR per session; update the
shared schema in packages/shared/src/run-event.ts to match the spec by making
runId optional, adding sessionId?: string, and model the envelope as a union or
runtime-validated shape that enforces "exactly one of runId or sessionId" (e.g.,
two interfaces RunEnvelope { runId: string; sessionId?: undefined } and
SessionEnvelope { sessionId: string; runId?: undefined } and export type
BaseEvent = RunEnvelope | SessionEnvelope), then audit any usages of
BaseEventSchema/baseFields and functions that assumed runId to handle the
sessionId branch, and confirm documentation text about sequenceNumber
monotonicity matches the behavior (per-run or per-session) or adjust the doc
instead if you prefer the code’s current semantics.
…o DoD/deps/exit/risks + 2 specs The pivot added workstreams 1.V–1.AC to the Phase-1 work-breakdown + milestones, but the Definition-of-Done, Dependencies, Exit-criteria, and Risks sections were never updated to match — leaving Phase 1 internally inconsistent at its go/no-go gate. This closes that, plus two small open specs the readiness analysis surfaced. Phase-1 doc (consistency): - DoD: now includes the QuickJS-wasm sandbox (1.AB) + pre-egress budget governor (1.AC) and the agent-first sub-spine proven by its own 1.AA harness. - Dependencies: mermaid shows CORE incl. 1.AB/1.AC + the parallel sub-spine → 1.AA → Phase 2; bullets add the agent-session contract, [chat] defaults, the pivot/hardening ADRs (0024/0026/ 0027/0028/0029), and the QuickJS-wasm runtime dependency. - Exit criteria: add #6 sandbox proven, #7 budget governor blocks before egress, #8 sub-spine passes the 1.AA harness (additive — does not gate M2). - Risks: add expression-sandbox perf/determinism and the new session-lifecycle/persistence rows. Open specs closed: - B5 — QuickJS-wasm package: name the candidate (quickjs-emscripten) and make a perf spike 1.AB's first task; recorded in tech-stack.md. - B6 — pre-egress estimate default: give it a canonical home, [defaults].max_tokens_estimate (config-spec), referenced from ADR-0028 (so 1.AC is deterministic to implement). - B7 — agent_sessions.model_id is the configured primary model; the fallback-aware per-turn model is session_messages.model_id. (The schema-migration drift gate for the new session tables was already noted in 1.X.) Refs ADR-0024/0026/0027/0028/0029. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
A multi-agent Phase-1 readiness review (6 dimensions, adversarially verified: 27 confirmed) found
Phase 1 is go-with-fixes — the root cause being that @relavium/shared (frozen 2026-06-04) drifted from
the contracts the pivot hardened the next day. These are the doc/plan fixes that close the gate; the
actual schema reconciliation is now an explicit first Phase-1 workstream (1.L.0), not silent drift.
Must-fix:
- 1.L.0 (new, do-first): reconcile @relavium/shared to the 2026-06-05 contract — authored-YAML fields
(metadata/budget/timeout_ms/max_parallel/system_prompt_append/output_schema/allowedCommandGlobs/
input.validation), the 5 missing run-events + SessionEvent union with an exactly-one-of
runId|sessionId envelope (discriminated RunEnvelope|SessionEnvelope + baseFields usage audit),
attemptNumber on 3 events, the closed ErrorCode enum + retryable on run:failed, [defaults].max_tokens_
estimate + [chat], RUN_EVENT_TYPES + the count-pinned test. (Also resolves the inline review comment
on the run-event envelope.)
- 1.L2 (new): the {{…}} interpolation/templating engine (resolver + pipe filters + eager-once frozen
context + transitive parse-time secret taint, ADR-0029c) — previously unowned.
- Expression-sandbox scope object defined once in ADR-0027 (inputs/ctx/run.outputs keyed by node id,
secrets excluded; {{…}} is separate templating); node-types bare `output` example fixed to run.outputs.
- Checkpointer is event-sourced from step_executions + run_events (+ messages) — no checkpoint table;
reconciled across execution-model, shared-core-engine, database-schema, and the 1.R pointer.
- Canonical supported-model matrix + prices home is packages/llm/src/pricing.ts (seeded into the empty
model_catalog); 1.B and multi-llm-providers repointed at it.
- README global spine reconciled: M1 = seam + 3 adapters (fallback/cost are 1.m2), M2 includes the
sandbox (1.AB) + budget governor (1.AC) + the parallel sub-spine (1.m5).
- Work-breakdown DAG: T->O (registry before the AgentRunner tool loop), Q->AC (gate seam for
pause_for_approval), P->U; 1.U/1.AB acceptance no longer over-claims the 3-node harness exercises the
sandbox.
In-phase fixes folded in: DoD rescope, 1.Z WorkflowDefinition->YAML emitter made explicit, milestone
1.m3 includes 1.L.0/1.L2, sub-spine label 1.V–1.AA, QuickJS "pinned by the 1.AB spike", expression
syntax-error surfaces at the sandbox not parse. Deferred (low, genuinely in-phase): J->K edge relaxation
and critical-path tag consistency.
Refs the phase-1 readiness review; ADR-0023/0026/0027/0028/0029.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Nitpick comments (1)
docs/roadmap/phases/phase-1-engine-and-llm.md (1)
395-416: ⚡ Quick winReduce schema restatement in roadmap; link to canonical contracts instead.
This section now embeds detailed field-by-field contract requirements (event variants/envelopes/config enums), which is likely to drift from
docs/reference/contracts/*. Keep roadmap text outcome-focused and link to the canonical specs for exact shapes.As per coding guidelines, “Use relative links in documentation and avoid restating canonical specs; link to specs in
docs/reference/instead”.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@docs/roadmap/phases/phase-1-engine-and-llm.md` around lines 395 - 416, The roadmap currently restates detailed contract shapes (e.g., RunEnvelope/SessionEnvelope, BaseEventSchema, ErrorCode enum, ProjectConfigSchema, RUN_EVENT_TYPES, run-event.test.ts) — remove the field-by-field specs and replace with concise outcome-focused text that refers readers to the canonical contract files under docs/reference/contracts (use relative links) for exact schemas and enums; keep a short bulleted list of what will change (e.g., add five run/session variants, discriminated envelope, add attemptNumber and retryable, update RUN_EVENT_TYPES) and update the comment about decidedBy, but do not duplicate schema details in phase-1-engine-and-llm.md.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@docs/architecture/multi-llm-providers.md`:
- Around line 146-152: Clarify that pricing.ts is the single source-of-truth for
canonical model ids, context windows, and per-token pricing, and that
model_catalog is only a seeded projection/read-model used for UI display via
providerStore; explicitly state that adapters and CostTracker read pricing data
from pricing.ts (not model_catalog) and that model_catalog must not be treated
as the authoritative pricing contract to avoid drift.
In `@docs/roadmap/phases/phase-1-engine-and-llm.md`:
- Around line 710-712: The roadmap bullet that references database-schema.md as
the model-pricing catalog is inconsistent with the phase plan which designates
packages/llm/src/pricing.ts as the source of truth; update the dependency bullet
to reference packages/llm/src/pricing.ts (or explicitly state that
database-schema.md mirrors the definitions in packages/llm/src/pricing.ts) so
the pricing-source is unambiguous and consistent with the phase definition.
---
Nitpick comments:
In `@docs/roadmap/phases/phase-1-engine-and-llm.md`:
- Around line 395-416: The roadmap currently restates detailed contract shapes
(e.g., RunEnvelope/SessionEnvelope, BaseEventSchema, ErrorCode enum,
ProjectConfigSchema, RUN_EVENT_TYPES, run-event.test.ts) — remove the
field-by-field specs and replace with concise outcome-focused text that refers
readers to the canonical contract files under docs/reference/contracts (use
relative links) for exact schemas and enums; keep a short bulleted list of what
will change (e.g., add five run/session variants, discriminated envelope, add
attemptNumber and retryable, update RUN_EVENT_TYPES) and update the comment
about decidedBy, but do not duplicate schema details in
phase-1-engine-and-llm.md.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 304d92ef-55b7-4acf-a725-09ed1e911912
📒 Files selected for processing (11)
docs/architecture/execution-model.mddocs/architecture/multi-llm-providers.mddocs/architecture/shared-core-engine.mddocs/decisions/0027-expression-sandbox.mddocs/decisions/0028-workflow-resource-governance.mddocs/reference/contracts/config-spec.mddocs/reference/desktop/database-schema.mddocs/reference/shared-core/node-types.mddocs/roadmap/README.mddocs/roadmap/phases/phase-1-engine-and-llm.mddocs/tech-stack.md
✅ Files skipped from review due to trivial changes (4)
- docs/tech-stack.md
- docs/decisions/0027-expression-sandbox.md
- docs/reference/shared-core/node-types.md
- docs/decisions/0028-workflow-resource-governance.md
🚧 Files skipped from review as they are similar to previous changes (4)
- docs/reference/contracts/config-spec.md
- docs/architecture/execution-model.md
- docs/roadmap/README.md
- docs/architecture/shared-core-engine.md
Resolve review feedback on the model-pricing canonical home. Three spots implied database-schema.md / model_catalog was the authoritative pricing catalog, contradicting pricing.ts as the in-code source of truth: - multi-llm-providers.md header callout said the catalog "is canonical in database-schema.md" — now names packages/llm/src/pricing.ts, seeded into the model_catalog display projection. - phase-1 frozen-contracts bullet called database-schema.md "the model-pricing catalog" — now the model_catalog table seeded from pricing.ts (the source of truth for ids, context windows, pricing). Also trim the inline run/session envelope type definition in 1.L.0 to an outcome + spec link, per the one-canonical-home rule (sse-event-schema.md owns the shape). Skipped the already-addressed pricing clarification at multi-llm-providers.md:146-152. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
7 tasks
cemililik
added a commit
that referenced
this pull request
Jun 25, 2026
… status, defer log, concurrency) Five review findings on the CLI media surface (all low/nit): - #12 (nit, 3-lens): wireSaveToPort called mkdirSync on every write (blocking sync I/O in an async port) while the JSDoc implied once-only. Switch to await mkdir (node:fs/promises) — matches the FilesystemMediaStore.put pattern, keeps the port non-blocking — and reword the JSDoc to "every write". - #13 (nit): TERMINAL_RUN_STATUSES typed Set<RunStatus> (was Set<string>), so a misspelled status is a compile error and .has() narrows the closed union. - #7 (low): createWorkflowModelCatalog deferred silently on a CapabilityFlagsSchema.safeParse failure — indistinguishable from "model absent". Add an optional, per-model-deduped, secret-free warn sink (model id + Zod issue messages) threaded from run/gate via io.writeErr, so a future schema evolution that invalidates previously-valid rows is observable. Still fail-open (FallbackChain backstop). - #6 (low): document the grace-window soft-delete→unlink resurrection gap (within ADR-0042 §3 best-effort) so a future graceMs shortening triggers a re-verify-before-delete. - #5 companion (low, PERF-CONCURRENCY-2): the grace-reclaim and orphan-sweep CAS deletes ran one await at a time on the exit path — fan them out with Promise.all (independent unlinks). Refs: ADR-0042 Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What & why
Pivots Relavium from workflow-first to agent-first + workflow (the maintainer's Option-A decision), and folds in a validated workflow-system hardening pass. Phase 0/M0 is complete and Phase 1 has not started, so this lands entirely at the docs / spec / ADR layer — there is no
packages/*orapps/*code here. The point is to settle the design before any engine code is written.A conversational
AgentSessionbecomes a first-class engine entry point alongsideWorkflowEngine— reusing the sameToolRegistry, the@relavium/llmseam, and the event bus — with a one-way chat → workflow export so Relavium sits at both the start (chat) and the destination (committed workflow).Highlights
6 new ADRs (0024–0029)
.relavium.yamlexport (reviewed linear-chain scaffold)http_request+ MCP)New canonical artifacts:
reference/contracts/agent-session-spec.md,architecture/agent-sessions.md,reference/cli/chat-session.md,tutorials/cli/start-a-chat-session.md,analysis/competitive-landscape-2026-06-05.md.Roadmap: agent-first sub-spine
1.V–1.AA(parallel, off the M2 critical path) +1.ABsandbox (on the critical path, folds into 1.P) +1.ACbudget; CLI2.M–2.Q; desktop chat3.N/3.O(sign-off renumbered3.N→3.P); VS Code4.L/4.M(milestones4.M*→P4.M*).Pre-existing bug fixed:
roadmap/READMEhad M1/M2 inverted vsphase-1(a dependency inversion — M1'sAgentRunner+retry needed the seam M2 delivered). Aligned the global spine tophase-1: M1 = LLM seam proven, M2 = engine end-to-end.Conformance checklist
shared-core-engine, not a new file;[chat]referencesfs_scope/allowedCommands, doesn't fork them)@relavium/llmseam (SessionMessagemaps toLlmMessage, never copied)WebAssemblyglobal, notisolated-vm)secret-typed inputs rejected from prompts (ADR-0029)Scope: explicitly NOT in this PR
best_of_n/ jmespath / jsonlogic (all reserved; a future loops/expression ADR owns them).🤖 Generated with Claude Code
Summary by Sourcery
Pivot the product design to an agent-first model by introducing AgentSession as a co-equal engine entry point alongside WorkflowEngine, and harden the workflow and tool security model through new ADRs and documentation updates.
New Features:
Bug Fixes:
Enhancements:
Documentation:
Summary by CodeRabbit
New Features
Documentation