feat: add durable AgentOS slice execution
This commit is contained in:
-Puter
221
docs/TECH.md
221
docs/TECH.md
@@ -18,29 +18,28 @@ Convex application backend
|
||||
├── normalized product data
|
||||
├── conversation turn queue
|
||||
└── reactive client projections
|
||||
│ service-authenticated dispatch
|
||||
│ durable Workflow steps + service-authenticated dispatch
|
||||
▼
|
||||
FLUE orchestration service
|
||||
├── model calls
|
||||
├── typed tools
|
||||
└── canonical Flue persistence in Convex
|
||||
│ later execution commands
|
||||
Private agent backend
|
||||
├── FLUE product agents and typed tools
|
||||
├── AgentOS execution environments
|
||||
├── Codex implementation harness
|
||||
└── canonical events/results returned to Convex
|
||||
│ optional attached full sandbox
|
||||
▼
|
||||
Rivet Engine + AgentOS (post-Slice 1)
|
||||
└── sandboxes, harnesses, and durable execution
|
||||
Cube/E2B-compatible runtime (later)
|
||||
```
|
||||
|
||||
Clients MUST communicate only with Convex. FLUE and future Rivet/AgentOS
|
||||
services are private workers: Convex admits durable commands, invokes the
|
||||
worker, and stores the product-facing result before clients observe it.
|
||||
Clients MUST communicate only with Convex. FLUE and future Rivet/AgentOS services are private workers: Convex admits durable commands, invokes the worker, and stores the product-facing result before clients observe it.
|
||||
|
||||
### Ownership
|
||||
|
||||
| Layer | Owns |
|
||||
|---|---|
|
||||
| --- | --- |
|
||||
| Convex | authentication, normalized product records, command admission, reactive reads |
|
||||
| FLUE | private programmable orchestration and domain-specific agents |
|
||||
| Rivet actors (later) | serialized execution ownership, recovery, timers, leases |
|
||||
| Convex Workflow | durable sequencing, retries, cancellation, scheduling, and completion callbacks |
|
||||
| Agent backend | private programmable agents and execution adapters |
|
||||
| Rivet Engine + runners | placement, routing, sleep/wake, and execution ownership for AgentOS workspaces |
|
||||
| Harness | bounded coding/tool loop |
|
||||
| Sandbox/runtime | filesystem, processes, network, isolation |
|
||||
| Git | source revision history |
|
||||
@@ -63,11 +62,7 @@ signals ──< signalWorkAttachments >── works
|
||||
works ──< workEvents
|
||||
```
|
||||
|
||||
Convex mutations provide atomic transactions and optimistic serializability.
|
||||
Foreign-key integrity and uniqueness are enforced in the owning mutations;
|
||||
composite indexes back every identity and relation lookup. Flue's adapter
|
||||
tables remain isolated infrastructure persistence and are not product-domain
|
||||
relations.
|
||||
Convex mutations provide atomic transactions and optimistic serializability. Foreign-key integrity and uniqueness are enforced in the owning mutations; composite indexes back every identity and relation lookup. Flue's adapter tables remain isolated infrastructure persistence and are not product-domain relations.
|
||||
|
||||
## 2. Domain boundaries
|
||||
|
||||
@@ -106,93 +101,93 @@ Avoid package proliferation in v0; logical boundaries may begin as folders.
|
||||
Minimal durable model:
|
||||
|
||||
```ts
|
||||
type Id = string
|
||||
type Id = string;
|
||||
|
||||
interface Message {
|
||||
id: Id
|
||||
projectId: Id
|
||||
content: string
|
||||
createdAt: number
|
||||
id: Id;
|
||||
projectId: Id;
|
||||
content: string;
|
||||
createdAt: number;
|
||||
}
|
||||
|
||||
interface Signal {
|
||||
id: Id
|
||||
projectId: Id
|
||||
sourceType: string
|
||||
sourceId: string
|
||||
sourcePayloadRef?: string
|
||||
summary: string
|
||||
fingerprint: string
|
||||
status: "candidate" | "accepted" | "dismissed"
|
||||
id: Id;
|
||||
projectId: Id;
|
||||
sourceType: string;
|
||||
sourceId: string;
|
||||
sourcePayloadRef?: string;
|
||||
summary: string;
|
||||
fingerprint: string;
|
||||
status: "candidate" | "accepted" | "dismissed";
|
||||
}
|
||||
|
||||
interface Work {
|
||||
id: Id
|
||||
projectId: Id
|
||||
title: string
|
||||
objective: string
|
||||
risk: "low" | "medium" | "high"
|
||||
status: WorkStatus
|
||||
definitionVersion?: number
|
||||
designVersion?: number
|
||||
createdAt: number
|
||||
updatedAt: number
|
||||
id: Id;
|
||||
projectId: Id;
|
||||
title: string;
|
||||
objective: string;
|
||||
risk: "low" | "medium" | "high";
|
||||
status: WorkStatus;
|
||||
definitionVersion?: number;
|
||||
designVersion?: number;
|
||||
createdAt: number;
|
||||
updatedAt: number;
|
||||
}
|
||||
|
||||
interface Step {
|
||||
id: Id
|
||||
workId: Id
|
||||
sliceId?: Id
|
||||
kind: "design" | "implement" | "verify" | "integrate" | "publish" | "observe"
|
||||
objective: string
|
||||
dependsOn: readonly Id[]
|
||||
status: StepStatus
|
||||
id: Id;
|
||||
workId: Id;
|
||||
sliceId?: Id;
|
||||
kind: "design" | "implement" | "verify" | "integrate" | "publish" | "observe";
|
||||
objective: string;
|
||||
dependsOn: readonly Id[];
|
||||
status: StepStatus;
|
||||
}
|
||||
|
||||
interface Run {
|
||||
id: Id
|
||||
workId: Id
|
||||
stepId: Id
|
||||
kitVersion: string
|
||||
status: RunStatus
|
||||
id: Id;
|
||||
workId: Id;
|
||||
stepId: Id;
|
||||
kitVersion: string;
|
||||
status: RunStatus;
|
||||
}
|
||||
|
||||
interface Attempt {
|
||||
id: Id
|
||||
runId: Id
|
||||
number: number
|
||||
harness: string
|
||||
runtime: string
|
||||
sourceRevision: string
|
||||
status: AttemptStatus
|
||||
startedAt?: number
|
||||
endedAt?: number
|
||||
id: Id;
|
||||
runId: Id;
|
||||
number: number;
|
||||
harness: string;
|
||||
runtime: string;
|
||||
sourceRevision: string;
|
||||
status: AttemptStatus;
|
||||
startedAt?: number;
|
||||
endedAt?: number;
|
||||
}
|
||||
|
||||
interface Artifact {
|
||||
id: Id
|
||||
workId: Id
|
||||
stepId?: Id
|
||||
runId?: Id
|
||||
attemptId?: Id
|
||||
type: string
|
||||
uri?: string
|
||||
contentHash?: string
|
||||
sourceRevision?: string
|
||||
environmentId?: string
|
||||
metadata: unknown
|
||||
id: Id;
|
||||
workId: Id;
|
||||
stepId?: Id;
|
||||
runId?: Id;
|
||||
attemptId?: Id;
|
||||
type: string;
|
||||
uri?: string;
|
||||
contentHash?: string;
|
||||
sourceRevision?: string;
|
||||
environmentId?: string;
|
||||
metadata: unknown;
|
||||
}
|
||||
|
||||
interface Question {
|
||||
id: Id
|
||||
workId: Id
|
||||
stepId?: Id
|
||||
attemptId?: Id
|
||||
prompt: string
|
||||
recommendation?: string
|
||||
alternatives: readonly string[]
|
||||
status: "open" | "answered" | "withdrawn"
|
||||
answer?: string
|
||||
id: Id;
|
||||
workId: Id;
|
||||
stepId?: Id;
|
||||
attemptId?: Id;
|
||||
prompt: string;
|
||||
recommendation?: string;
|
||||
alternatives: readonly string[];
|
||||
status: "open" | "answered" | "withdrawn";
|
||||
answer?: string;
|
||||
}
|
||||
```
|
||||
|
||||
@@ -337,35 +332,49 @@ Keep domain/application code provider-neutral.
|
||||
|
||||
```ts
|
||||
interface HarnessRuntime {
|
||||
open(input: OpenHarnessInput): Effect.Effect<HarnessSession, HarnessError>
|
||||
prompt(id: string, content: string): Effect.Effect<void, HarnessError>
|
||||
events(id: string): Stream.Stream<HarnessEvent, HarnessError>
|
||||
approve(input: PermissionDecision): Effect.Effect<void, HarnessError>
|
||||
abort(id: string): Effect.Effect<void, HarnessError>
|
||||
close(id: string): Effect.Effect<void, HarnessError>
|
||||
open(input: OpenHarnessInput): Effect.Effect<HarnessSession, HarnessError>;
|
||||
prompt(id: string, content: string): Effect.Effect<void, HarnessError>;
|
||||
events(id: string): Stream.Stream<HarnessEvent, HarnessError>;
|
||||
approve(input: PermissionDecision): Effect.Effect<void, HarnessError>;
|
||||
abort(id: string): Effect.Effect<void, HarnessError>;
|
||||
close(id: string): Effect.Effect<void, HarnessError>;
|
||||
}
|
||||
|
||||
interface SandboxRuntime {
|
||||
create(spec: SandboxSpec): Effect.Effect<SandboxLease, SandboxError>
|
||||
exec(lease: SandboxLease, cmd: Command): Effect.Effect<CommandResult, SandboxError>
|
||||
readFile(lease: SandboxLease, path: string): Effect.Effect<Uint8Array, SandboxError>
|
||||
writeFile(lease: SandboxLease, path: string, body: Uint8Array): Effect.Effect<void, SandboxError>
|
||||
pause(lease: SandboxLease): Effect.Effect<void, SandboxError>
|
||||
resume(id: string): Effect.Effect<SandboxLease, SandboxError>
|
||||
terminate(lease: SandboxLease): Effect.Effect<void, SandboxError>
|
||||
create(spec: SandboxSpec): Effect.Effect<SandboxLease, SandboxError>;
|
||||
exec(
|
||||
lease: SandboxLease,
|
||||
cmd: Command
|
||||
): Effect.Effect<CommandResult, SandboxError>;
|
||||
readFile(
|
||||
lease: SandboxLease,
|
||||
path: string
|
||||
): Effect.Effect<Uint8Array, SandboxError>;
|
||||
writeFile(
|
||||
lease: SandboxLease,
|
||||
path: string,
|
||||
body: Uint8Array
|
||||
): Effect.Effect<void, SandboxError>;
|
||||
pause(lease: SandboxLease): Effect.Effect<void, SandboxError>;
|
||||
resume(id: string): Effect.Effect<SandboxLease, SandboxError>;
|
||||
terminate(lease: SandboxLease): Effect.Effect<void, SandboxError>;
|
||||
}
|
||||
|
||||
interface SourceControl {
|
||||
prepareWorktree(input: WorktreeInput): Effect.Effect<Worktree, GitError>
|
||||
diff(worktree: Worktree): Effect.Effect<DiffArtifact, GitError>
|
||||
commit(input: CommitInput): Effect.Effect<CommitArtifact, GitError>
|
||||
push(input: PushInput): Effect.Effect<BranchArtifact, GitError>
|
||||
createPullRequest(input: PullRequestInput): Effect.Effect<PullRequestArtifact, GitError>
|
||||
prepareWorktree(input: WorktreeInput): Effect.Effect<Worktree, GitError>;
|
||||
diff(worktree: Worktree): Effect.Effect<DiffArtifact, GitError>;
|
||||
commit(input: CommitInput): Effect.Effect<CommitArtifact, GitError>;
|
||||
push(input: PushInput): Effect.Effect<BranchArtifact, GitError>;
|
||||
createPullRequest(
|
||||
input: PullRequestInput
|
||||
): Effect.Effect<PullRequestArtifact, GitError>;
|
||||
}
|
||||
|
||||
interface VerificationRuntime {
|
||||
execute(plan: VerificationPlan, env: EnvironmentRef):
|
||||
Effect.Effect<VerificationResult, VerificationError>
|
||||
execute(
|
||||
plan: VerificationPlan,
|
||||
env: EnvironmentRef
|
||||
): Effect.Effect<VerificationResult, VerificationError>;
|
||||
}
|
||||
```
|
||||
|
||||
@@ -420,6 +429,10 @@ Zopu owns Work, branches, worktrees, budgets, approvals, artifacts, and completi
|
||||
|
||||
## 10. Runtime strategy
|
||||
|
||||
### Convex orchestration
|
||||
|
||||
Slice 5 uses the Convex Workflow component as the durable product orchestration layer. Workflow steps call private agent-backend actions, while all user-visible state, events, artifacts, idempotency keys, and cancellation remain canonical in Convex.
|
||||
|
||||
### CubeSandbox
|
||||
|
||||
Best for full Linux execution:
|
||||
@@ -443,7 +456,7 @@ Best for:
|
||||
- actor-adjacent orchestration;
|
||||
- context/files/networking that fit runtime limits.
|
||||
|
||||
Use an attached full sandbox when native/heavy tooling is needed.
|
||||
Slice 5 starts here with one Codex-backed AgentOS actor and one authenticated repository checkout per project. Convex Workflow owns product orchestration; Rivet Engine coordinates placement while a normal runner executes the actor. Use an attached full sandbox through the E2B-compatible boundary when native/heavy tooling is needed.
|
||||
|
||||
### Persistent project machine
|
||||
|
||||
|
||||
@@ -211,16 +211,18 @@ Zopu implements one approved slice in an isolated repository environment and str
|
||||
Initial adapter choice:
|
||||
|
||||
```text
|
||||
SandboxRuntime = CubeSandboxLive
|
||||
HarnessRuntime = OmpHarnessLive (or one chosen harness)
|
||||
SandboxRuntime = AgentOsSandboxLive
|
||||
HarnessRuntime = CodexHarnessLive
|
||||
Durable orchestration = Convex Workflow
|
||||
```
|
||||
|
||||
Flow:
|
||||
|
||||
```text
|
||||
prepare worktree
|
||||
→ create sandbox
|
||||
→ clone/mount repo
|
||||
load the project's authenticated Git connection
|
||||
→ start durable Convex workflow
|
||||
→ create AgentOS execution environment
|
||||
→ clone the single configured repo
|
||||
→ inject context
|
||||
→ run one slice
|
||||
→ normalize events
|
||||
@@ -230,14 +232,15 @@ prepare worktree
|
||||
|
||||
Security:
|
||||
|
||||
- scoped Git/model tokens;
|
||||
- GitHub OAuth or self-hosted Gitea PAT, scoped to one project;
|
||||
- scoped Git/model tokens passed only to private execution;
|
||||
- isolated HOME/worktree;
|
||||
- one mutating attempt per worktree;
|
||||
- timeout/cancel cleanup.
|
||||
|
||||
### Frontend
|
||||
|
||||
Current activity, changed files, artifact links, expandable raw logs.
|
||||
Project selector/settings, Git connection status, current activity, changed files, artifact links, expandable raw logs, cancel/retry, and manual Git delivery controls.
|
||||
|
||||
### Acceptance
|
||||
|
||||
@@ -247,6 +250,8 @@ Current activity, changed files, artifact links, expandable raw logs.
|
||||
- provider failure becomes classified attempt outcome;
|
||||
- exact base/candidate revision recorded.
|
||||
|
||||
Rivet Engine coordinates AgentOS actor placement through a normal runner, but does not own product orchestration; Convex Workflow remains canonical for the Run lifecycle. Cube/Kubernetes sandbox support remains behind `SandboxRuntime` and can be mounted through AgentOS incrementally.
|
||||
|
||||
---
|
||||
|
||||
## Slice 6 — Independent verification and repair
|
||||
@@ -490,4 +495,4 @@ browser-tester integration-coordinator
|
||||
1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → 9 → 10 → 11 → 12
|
||||
```
|
||||
|
||||
Parallel engineering is allowed *within* a slice after contracts land, but product release order remains sequential.
|
||||
Parallel engineering is allowed _within_ a slice after contracts land, but product release order remains sequential.
|
||||
|
||||
Reference in New Issue
Block a user