Files

-Puter 48205a5e19 chores

2026-08-03 18:13:45 +05:30

43 KiB

Raw Blame History

Zopu Intelligence & Delivery Runtime — Implementation Handoff

Continuation of: zopu-timeline-handoff.md
Status: implementation-planning handoff
Scope: project runtime setup, Convex workflows, timeline dispatch, one project-bound Flue conversation agent, AgentOS VM binding, exploration flow, issue flow, and artifact generation/publication.

0. How this document relates to the timeline handoff

The previous handoff defines the stable product model:

Project provides context.
Work owns the timeline.
Threads own bounded execution.
Events preserve history.
Artifacts communicate results.

This document adds the first intelligence and delivery runtime that operates on that model.

Where this document conflicts with the earlier onboarding implementation, this document wins for the first shipping slice.

Explicit simplifications that supersede earlier assumptions

The first slice supports one active Project per user/organization.
One Project owns one AgentOS VM.
One Project owns one Flue conversation agent instance.
Project setup does not attempt broad framework detection, application boot, or preview generation.
Environment values are optional and never block setup.
Only a root-level .env.example is inspected.
Project setup succeeds only when:
- the AgentOS VM exists
- the repository is shallow-cloned into it
- the repository can be read
Deep repository exploration happens after project.ready, through the conversation agent.
Multi-project routing, multiple VMs, autonomous coding, pull requests, and production previews are deferred.

Part I — Shipping goal

1. Demo promise

A user connects GitHub and selects a repository.

Zopu creates a dedicated AgentOS VM, shallow-clones the repository, scans the root .env.example, creates a project-bound Flue conversation agent, emits a durable project.ready event, and redirects the user to the global timeline.

The conversation agent receives the ready event, explores enough of the repository to onboard itself, stores a project summary, and posts a short coworker-style onboarding response plus a polished setup artifact.

The user can then ask for one of two supported kinds of work:

Explore or explain part of the repository.
Turn a request or finding into a well-formed issue.

The agent immediately acknowledges the request, creates Work and a first Thread when execution is required, performs the task inside the project VM, generates a polished static HTML artifact, stores it through Convex, and publishes its card into the appropriate timeline.

2. End-to-end loop

PROJECT ONBOARDING
GitHub connected
→ repository selected
→ Convex projectSetupWorkflow starts
→ AgentOS VM created for project
→ depth-1 repository clone
→ root .env.example scanned
→ project marked ready
→ project.ready event appended
→ project conversation agent registered
→ ready event dispatched to agent
→ agent performs onboarding exploration
→ summary.md stored as Project context
→ setup HTML artifact published
→ onboarding response appears in global timeline

NORMAL INTERACTION
User sends timeline message
→ message event stored first
→ timelineDispatchWorkflow starts
→ event sent to project conversation agent
→ agent posts short acknowledgement
→ agent decides: answer / explore / create issue
→ Work created or evolved when execution is needed
→ Thread created for specialist execution
→ specialist uses project VM
→ artifact generation loop runs
→ HTML uploaded through Convex
→ artifact card appears in timeline
→ agent posts concise final handoff

Part II — Runtime boundaries

3. Convex: durable control plane

Convex owns all user-visible and durable system state.

Responsibilities

Project records and setup state
global timeline and Work timelines
immutable Events and causal links
Work and Thread records
project runtime bindings
conversation agent registrations
dispatch records and workflow state
project context documents
artifact metadata and storage references
realtime client subscriptions
idempotency and retry state

Convex does not own

the live Flue model loop
shell execution
repository filesystem state
Pi execution sessions
static HTML rendering process
long-running delivery work

4. Hono + Flue: intelligence runtime

Hono exposes the runtime service. Flue models the persistent project conversation agent and the specialist execution flows.

Responsibilities

addressable conversation agent instances
receiving timeline and system events
coworker-style responses
deciding whether to answer, explore, or create an issue
starting and supervising specialist flows
mounting project context and tools
binding the agent to its AgentOS VM
publishing progress and results through typed tools
invoking the artifact generation loop

Agent identity

For the first slice:

one active Project
→ one ConversationAgent
→ one AgentOS VM

Suggested stable identity:

conversation:{organizationId}:{projectId}

The agent is project-bound even though it initially posts into the organization global timeline.

5. AgentOS VM: delivery environment

The VM is the agent's dedicated working environment for one Project.

Responsibilities

hold the shallow repository checkout
provide read access to code and configuration
run safe repository inspection commands
host optional Pi execution sessions
write generated working files and artifact drafts
retain Project-scoped runtime state according to AgentOS lifecycle

Initial constraints

one VM per Project
one repository per VM
one workspace root
read-oriented repository tools
no autonomous code mutation flow yet
no multi-VM routing

6. Pi sessions: optional deep workers

The conversation agent can inspect directly through sandbox tools for small tasks.

For deeper exploration, it may start or resume a Pi session inside the Project VM.

Pi is an execution worker, not the owner of Work, Thread, Event, or Artifact state.

Work
└─ Thread
   └─ specialist flow
      └─ one or more Pi sessions

A Pi session may produce raw notes, Markdown, JSON, or files. Flue remains responsible for interpreting and publishing those outputs.

Part III — Core entities added by this slice

7. ProjectRuntime

Represents the Project-to-AgentOS binding.

interface ProjectRuntime {
  projectId: ProjectId
  organizationId: OrganizationId
  provider: "agentos"
  runtimeId?: string
  vmId?: string
  workspacePath: string
  repositoryPath: string
  status:
    | "requested"
    | "creating_vm"
    | "cloning"
    | "checking_repository"
    | "ready"
    | "failed"
  repositoryCommit?: string
  lastError?: RuntimeError
  createdAt: number
  updatedAt: number
}

Owns

runtime provider identifiers
workspace path
clone/readiness state
current repository commit
setup failures

Does not own

user-facing timeline state
agent conversational state
Work or Thread lifecycle

8. ConversationAgentBinding

Maps one Project to one Flue agent instance.

interface ConversationAgentBinding {
  id: AgentId
  organizationId: OrganizationId
  userId: string
  projectId: ProjectId
  runtimeId: string
  globalTimelineId: TimelineId
  status: "creating" | "ready" | "busy" | "error" | "disabled"
  flueConversationId?: string
  lastEventId?: EventId
  createdAt: number
  updatedAt: number
}

The binding is durable in Convex. Flue runtime state may be reconstructed from it and Project context.

9. AgentDispatch

One request to deliver one Event to one agent.

interface AgentDispatch {
  id: DispatchId
  sourceEventId: EventId
  organizationId: OrganizationId
  projectId: ProjectId
  agentId: AgentId
  workId?: WorkId
  threadId?: ThreadId
  status: "queued" | "sending" | "accepted" | "completed" | "failed"
  attempt: number
  handlerVersion: number
  idempotencyKey: string
  lastError?: string
  createdAt: number
  updatedAt: number
}

10. FlowRun

Represents an execution of a Flue specialist flow beneath a Thread.

interface FlowRun {
  id: FlowRunId
  flowType: "onboarding_explore" | "explore" | "issue"
  flowVersion: number
  projectId: ProjectId
  workId?: WorkId
  threadId?: ThreadId
  sourceEventId: EventId
  agentId: AgentId
  status:
    | "queued"
    | "running"
    | "waiting"
    | "generating_artifact"
    | "completed"
    | "failed"
    | "cancelled"
  state?: unknown
  attempt: number
  startedAt?: number
  finishedAt?: number
  updatedAt: number
}

11. ProjectContextDocument

Stores durable Project knowledge produced by onboarding and later work.

Initial context document:

summary.md

interface ProjectContextDocument {
  id: ContextDocumentId
  projectId: ProjectId
  kind: "repository_summary" | "environment_manifest" | "other"
  title: string
  contentType: "text/markdown" | "application/json"
  body?: string
  storageId?: string
  sourceFlowRunId?: FlowRunId
  revision: number
  status: "current" | "superseded" | "failed"
  createdAt: number
}

12. ArtifactBuild

Tracks the generation and publication of a static artifact.

interface ArtifactBuild {
  id: ArtifactBuildId
  projectId: ProjectId
  workId?: WorkId
  threadId?: ThreadId
  flowRunId: FlowRunId
  artifactKind: "project_setup" | "exploration" | "issue"
  status: "drafting" | "rendering" | "validating" | "uploading" | "published" | "failed"
  sourceManifest?: unknown
  outputStorageId?: string
  artifactId?: ArtifactId
  attempt: number
  lastError?: string
  createdAt: number
  updatedAt: number
}

Part IV — Project setup workflow

13. Entry point

The workflow starts immediately after the user connects GitHub and selects a repository.

Suggested client mutation:

projects.createFromRepository

Input:

interface CreateProjectInput {
  repositoryConnectionId: string
  repositoryOwner: string
  repositoryName: string
  repositoryUrl: string
  defaultBranch: string
}

The mutation should:

Validate user and organization ownership.
Create the Project record.
Create or reuse a ProjectRuntime record.
Start projectSetupWorkflow with an idempotency key.
Return the Project ID and setup status route.

14. `projectSetupWorkflow`

create_project_runtime
→ create_agentos_vm
→ shallow_clone_repository
→ verify_repository_readable
→ scan_root_env_example
→ register_project_agent
→ mark_project_ready
→ append_project_ready_event
→ trigger_timeline_dispatch

Step 1 — Create AgentOS VM

Required result:

{
  runtimeId: string
  vmId: string
  workspacePath: string
}

The step must be idempotent by projectId.

A retry must find and reuse an existing valid VM rather than creating duplicates.

Step 2 — Shallow clone

Clone only the selected branch and latest history:

git clone --depth=1 --single-branch --branch "$BRANCH" "$REPOSITORY_URL" "$REPOSITORY_PATH"

Repository credentials are handled by the AgentOS/runtime adapter. They are never exposed to the model or written into Events.

The clone step is idempotent:

if the repository directory is absent, clone
if it contains the expected repository, verify it
if it is corrupt or mismatched, mark the runtime failed and require repair/retry

Step 3 — Verify readability

Minimum checks:

repository path exists
git rev-parse HEAD succeeds
root directory can be listed
at least one tracked file can be read

The current commit SHA is stored on ProjectRuntime.

Step 4 — Scan `.env.example`

Narrow rule:

only inspect <repository-root>/.env.example

If the file does not exist:

environment manifest = empty
environment status = none_detected

If it exists:

parse variable names
preserve example/default text where safe
never treat example values as secrets
never require the user to complete them before proceeding
present them later as optional Project configuration

No recursive env scanning, framework inference, or required/optional classification in this slice.

Step 5 — Register conversation agent

Create one project-bound agent identity and associate it with the VM.

The registration must be idempotent by:

organizationId + projectId + agentType

Step 6 — Mark Project ready

Project setup is ready only when:

VM exists
AND repository is cloned
AND repository is readable

Environment configuration is not part of the readiness predicate.

Step 7 — Emit `project.ready`

The workflow appends an immutable system Event:

{
  type: "project.ready",
  scope: "global",
  actor: { kind: "system", service: "project-setup" },
  projectId,
  payload: {
    agentId,
    runtimeId,
    repositoryCommit,
    environmentVariableNames
  }
}

This event is the durable trigger for the onboarding conversation.

Step 8 — Dispatch the ready event

Create an AgentDispatch for the Project conversation agent and start the normal timeline dispatch workflow.

The setup workflow itself does not fabricate the onboarding response.

The conversation agent produces it.

15. Setup failure behavior

Setup fails and onboarding remains blocked when any of these fail terminally:

VM cannot be created
repository cannot be cloned
repository cannot be read

Behavior:

project.status = setup_failed
projectRuntime.status = failed
setup page shows an actionable error card
user is not redirected as ready
project.ready is not emitted

The user can retry after fixing the connection or runtime problem.

Environment variables do not cause setup failure.

16. Deferred from Project setup

Do not implement these in this workflow yet:

application boot
preview creation
package-manager detection beyond what exploration may report
framework-specific environment inference
dependency installation
test execution
deep architecture summary
multi-repository Project

Part V — Timeline dispatch workflow

17. User message entry point

The client sends a message through a Convex mutation.

Suggested mutation:

timeline.sendMessage

It must atomically:

authenticate the user
validate timeline scope
append the user Event
create the AgentDispatch
start timelineDispatchWorkflow
return the Event ID immediately

The client optimistically renders the message, but Convex is authoritative.

18. `timelineDispatchWorkflow`

load_source_event
→ resolve_project_agent
→ create_or_reuse_dispatch
→ send_event_to_flue
→ record_acceptance
→ wait_for_or_observe_completion
→ complete_dispatch

Dispatch input

interface ConversationEventInput {
  dispatchId: DispatchId
  sourceEvent: EventEnvelope
  agentId: AgentId
  organizationId: OrganizationId
  projectId: ProjectId
  globalTimelineId: TimelineId
  workId?: WorkId
  threadId?: ThreadId
}

Delivery contract

The Hono/Flue service must accept the Event using a service-authenticated endpoint.

Suggested logical route:

POST /internal/agents/:agentId/events

The request must be idempotent by dispatchId.

A repeated Convex workflow step must not cause the agent to process the same source Event twice.

19. Agent-to-timeline tool

The conversation agent receives a constrained tool for publishing user-visible output.

Do not give the model direct database credentials or arbitrary Convex mutations.

Suggested tool surface:

interface TimelineTool {
  postMessage(input: {
    text: string
    replyToEventId?: EventId
    workId?: WorkId
    importance?: "normal" | "high"
    idempotencyKey: string
  }): Promise<{ eventId: EventId }>

  postUpdate(input: {
    text: string
    workId: WorkId
    threadId?: ThreadId
    status?: "working" | "blocked" | "waiting" | "done"
    idempotencyKey: string
  }): Promise<{ eventId: EventId }>

  publishArtifact(input: {
    artifactId: ArtifactId
    workId?: WorkId
    threadId?: ThreadId
    text?: string
    idempotencyKey: string
  }): Promise<{ eventId: EventId }>
}

The implementation can call a Hono control endpoint that validates the agent binding and writes through Convex.

The agent can use this tool to:

acknowledge a request
publish a meaningful intermediate update
ask a blocking question
publish an artifact card
post its final handoff

It should not post every internal tool call.

Part VI — Conversation agent

20. Product behavior

The conversation agent behaves like an effective coworker who already understands the Project.

It should:

reply quickly
use short, natural messages
begin work without reheating the entire context
create or evolve Work when a real responsibility appears
dispatch specialist execution
send only meaningful progress updates
return depth through artifacts rather than chat walls
remain available after a specialist finishes

21. Initial supported decisions

For the first slice, the agent chooses among four actions:

1. respond directly
2. ask one necessary clarification
3. start exploration
4. start issue creation

No broad autonomous planner is required yet.

22. Conversation style contract

Default response size

one to three short sentences
usually under 50 words
no long status essays
no raw chain-of-thought
no giant Markdown reports in the timeline

Good acknowledgement examples

Got it — I’m tracing that part of the repo now. I’ll bring back the relevant code path and the risky edges.

Yep. I’m turning this into a concrete issue and checking the repository evidence before I lock the scope.

I found the likely entry point. I’m checking the surrounding dependencies before I package the result.

Final response examples

The exploration is ready. The main path starts in `packages/server`, with two coupling risks worth handling first.

I’ve drafted the issue with scope, acceptance criteria, and the files most likely involved.

The detailed result is linked through the artifact card.

23. Unsupported requests

The first runtime is read-oriented and does not yet implement autonomous code delivery.

The agent should not bluntly deny every writing request.

Instead it can:

inspect and scope the request
create Work
produce an issue artifact
explain the next delivery step
preserve the request for a later implementation flow

It must not falsely claim that code was changed, tested, or shipped.

24. Context mounted for every turn

The agent should receive or be able to retrieve:

Project identity and repository metadata
summary.md Project context when available
environment variable names, never secret values by default
recent global timeline Events
current Work timeline Events when the source Event belongs to Work
active Work and Thread summaries
recent Artifact cards and references
direct access to the project-bound VM tools

Convex remains the source of durable truth. Flue persistent state is useful for conversational continuity, but it must be recoverable from durable records.

Part VII — Flow loop

25. Definition

The flow loop is the event-driven supervisor around the conversation agent and specialist flows.

It is not a permanent while(true) process.

It advances when one of these Events occurs:

user message
project.ready
specialist started
specialist progress worth surfacing
specialist completed
specialist failed
artifact published
user clarification
user cancellation

26. Loop behavior

receive event
→ restore agent/project/work context
→ decide next conversational action
→ publish acknowledgement when needed
→ start or resume one specialist flow
→ persist run/thread state
→ return control

specialist later emits event
→ conversation agent receives it
→ publishes concise update or final response
→ starts next flow only if required

27. Work and Thread creation

A casual response does not require Work.

When the agent starts exploration or issue creation for a user goal:

create or resolve Work
→ create first Thread beneath Work
→ attach source Event causally
→ start specialist FlowRun under Thread

Work

Represents the broader desired outcome or responsibility.

It may begin vague and evolve as more context and Threads accumulate.

Thread

Represents one bounded execution path.

Initial Thread types:

exploration
issue-definition
onboarding-exploration

A Thread can close while its Work remains active.

28. Supervision rules

one source Event creates at most one initial specialist run per handler version
a run must have a stable flowRunId
a specialist completion is emitted as an Event
a failed run is visible and retryable
the conversation agent never marks Work complete merely because one Thread completed
important outputs are artifacts, not hidden runtime state

Part VIII — Initial specialist flows

29. Onboarding exploration flow

Triggered by:

project.ready

Purpose:

let the agent onboard itself to the repository
seed durable Project context
create the first system-authored onboarding message and Project setup artifact

Inputs

interface OnboardingExploreInput {
  projectId: ProjectId
  runtimeId: string
  repositoryPath: string
  repositoryCommit: string
  environmentVariableNames: string[]
  sourceEventId: EventId
}

Allowed actions

list repository tree
read important manifests and entry points
search filenames and code
inspect root documentation
run safe read-only commands
optionally start a Pi exploration session
write generated notes under the Zopu artifact/context directory

Outputs

summary.md Project context document.
Project setup artifact manifest.
Static HTML Project setup artifact.
Short onboarding timeline response.

Suggested `summary.md` contents

Project purpose
Detected stack
Repository shape
Primary entry points
Important packages/directories
Likely run/build/test commands, clearly marked as inferred or verified
Root .env.example variable names
Known constraints
Useful starting areas
Repository commit inspected

Do not invent repository facts. Mark assumptions explicitly.

30. Exploration specialist flow

Triggered by a user request such as:

Explore the auth flow.
How does the event timeline work?
Find where previews are started.
Why is this package coupled to Convex?

Responsibilities

turn the request into a focused repository question
inspect only relevant code and context
collect code evidence with file paths
identify the current behavior
identify risks, unknowns, and boundaries
produce an exploration artifact
return a concise result to the conversation agent

Recommended stages

frame_question
→ inspect_project_context
→ inspect_repository
→ verify_findings
→ create_exploration_manifest
→ generate_artifact
→ publish_result

Output contract

interface ExplorationResult {
  question: string
  summary: string
  findings: Array<{
    title: string
    detail: string
    evidence: Array<{
      path: string
      lineRange?: string
      note: string
    }>
  }>
  systemMap?: Array<{
    from: string
    to: string
    relationship: string
  }>
  risks: string[]
  unknowns: string[]
  suggestedNextActions: string[]
  generatedFiles: string[]
}

Exploration artifact visual sections

concise answer
visual system/code path
key files
current behavior
evidence cards
risks and unknowns
recommended next actions
inspected commit and scope

31. Issue specialist flow

Purpose:

Turn a user request or exploration result into a concrete, implementation-ready issue.

Inputs

source user Event
Project context
relevant exploration artifacts
repository evidence when needed
current Work goal

Recommended stages

understand_request
→ gather_repository_evidence
→ define_current_world
→ define_desired_world
→ bound_scope
→ write_acceptance_criteria
→ review_issue_quality
→ generate_artifact
→ publish_result

Output contract

interface IssueResult {
  title: string
  summary: string
  currentWorld: string
  desiredWorld: string
  scope: string[]
  nonGoals: string[]
  acceptanceCriteria: string[]
  evidence: Array<{
    path?: string
    note: string
  }>
  risks: string[]
  openQuestions: string[]
  suggestedImplementationShape?: string[]
  generatedFiles: string[]
}

Issue artifact visual sections

issue title and status
current world → desired world transition
scope and non-goals
acceptance checklist
repository evidence
affected areas
risks and open questions
next action

GitHub publication boundary

Keep issue drafting and GitHub publication as separate operations.

The first slice must at minimum generate the issue artifact.

A later or optional explicit action can call github.issue.create using the final artifact. This avoids coupling artifact quality to a side-effecting integration call.

Part IX — Artifact generation loop

32. Purpose

Specialist output is not automatically user-facing quality.

The artifact generation loop turns structured findings and generated files into a polished, durable static HTML artifact plus a compact timeline card.

33. Pipeline

specialist result
→ normalize artifact manifest
→ select artifact kit
→ render static HTML
→ visual/content review
→ sanitize and validate
→ upload to Convex storage
→ create Artifact revision
→ append artifact.published Event
→ conversation agent posts short handoff

34. Artifact manifest

Every specialist must produce a typed manifest before HTML generation.

interface ArtifactManifest {
  kind: "project_setup" | "exploration" | "issue"
  title: string
  summary: string
  projectId: ProjectId
  workId?: WorkId
  threadId?: ThreadId
  flowRunId: FlowRunId
  sourceEventIds: EventId[]
  card: {
    label: string
    facts: Array<{ label: string; value: string }>
    actions?: Array<{
      id: string
      label: string
      eventType: "client.action"
      style?: "primary" | "secondary"
    }>
  }
  sections: unknown[]
  evidence: Array<{
    path?: string
    note: string
  }>
  generatedFiles: string[]
}

35. Artifact kits

Use a small curated component/template system rather than asking the model to invent an entire design language every time.

Initial kits:

project-setup
repository-exploration
issue-definition

Each kit should provide:

responsive page shell
typography and spacing
status and fact cards
ownership/system diagrams
file/evidence cards
current-world/desired-world visual
checklist component
action/footer block
light and dark compatibility if practical

The model supplies structured content and chooses components. The renderer supplies visual quality and safety.

36. Artifact output path

Suggested VM working path:

<workspace>/.zopu/artifacts/<artifactBuildId>/
├─ manifest.json
├─ index.html
└─ optional generated supporting files

The publisher uploads index.html and allowed supporting files to Convex Storage or the chosen artifact storage behind Convex metadata.

37. Validation

Before publication:

HTML parses successfully
required title and summary are present
no raw secrets are included
no repository credentials are included
no unsupported external scripts or remote dependencies
links are safe and expected
artifact stays within configured size limits
card payload conforms to the UI registry contract
source Event, FlowRun, Work, Thread, and Project links are valid

38. Review loop

Keep it bounded.

render
→ inspect against artifact checklist
→ repair once if necessary
→ publish or fail visibly

Do not let the artifact agent redesign indefinitely.

39. Artifact revision

New evidence or a user revision request creates a new immutable Artifact revision.

Old revisions remain inspectable and are marked superseded.

Part X — Initial tool surface

40. Conversation/control tools

timeline.postMessage
timeline.postUpdate
timeline.publishArtifact
work.createOrResolve
work.update
thread.create
thread.update
flow.start
flow.inspect
flow.cancel
projectContext.get
artifact.get

41. AgentOS sandbox tools

Read-oriented first slice:

sandbox.describe
sandbox.listFiles
sandbox.readFile
sandbox.search
sandbox.execSafe
sandbox.writeGeneratedFile

execSafe should use a narrow policy and deny destructive commands.

Generated-file writes are allowed only under controlled directories such as:

<workspace>/.zopu/

42. Optional Pi tools

pi.startSession
pi.prompt
pi.followUp
pi.status
pi.abort
pi.listGeneratedFiles

The conversation agent need not use Pi for every task.

43. Artifact tools

artifact.beginBuild
artifact.writeManifest
artifact.render
artifact.validate
artifact.publish

44. Tool ownership rule

Tools emit typed proposals or commands that are validated by the runtime boundary.

The model must not receive arbitrary database mutation access, runtime credentials, or tenant routing control.

Part XI — Convex persistence additions

45. Tables/components to add

The earlier handoff already defines Projects, Works, Threads, Events, Artifacts, ProjectSetups, and DispatchJobs.

Add or refine:

projectRuntimes
conversationAgents
agentDispatches
flowRuns
projectContextDocuments
artifactBuilds

46. `projectRuntimes`

Suggested indexes:

by_project
by_organization_status
by_runtime_id

47. `conversationAgents`

Suggested indexes:

by_project
by_user_project
by_status

Enforce one active conversation agent per Project in the first slice.

48. `agentDispatches`

Suggested indexes:

by_source_event_handler_version
by_agent_status
by_status_updated_at

Unique semantic key:

sourceEventId + agentId + handlerVersion

49. `flowRuns`

Suggested indexes:

by_thread
by_work_status
by_agent_status
by_source_event

50. `projectContextDocuments`

Suggested indexes:

by_project_kind_status
by_project_created_at

Only one current document per Project and kind.

51. `artifactBuilds`

Suggested indexes:

by_flow_run
by_status_updated_at
by_project_created_at

Part XII — Convex functions and workflows

52. Public mutations

projects.createFromRepository
timeline.sendMessage
timeline.sendAction
projectEnvironment.setOptionalValue
projectSetup.retry
flow.cancel

53. Public queries

projectSetup.getStatus
projects.getCurrent
timeline.getGlobal
timeline.getWork
works.get
threads.listForWork
artifacts.get
projectContext.getCurrentSummary

54. Internal mutations

projectRuntime.markCreating
projectRuntime.markCloning
projectRuntime.markReady
projectRuntime.markFailed
projectEnvironment.replaceDetectedManifest
conversationAgent.register
conversationAgent.markStatus
events.appendSystemEvent
events.appendAgentEvent
agentDispatch.create
agentDispatch.markSending
agentDispatch.markAccepted
agentDispatch.markCompleted
agentDispatch.markFailed
flowRun.create
flowRun.update
projectContext.publishRevision
artifactBuild.create
artifactBuild.update
artifacts.publishRevision

55. Workflows

Initial durable workflows:

projectSetupWorkflow
timelineDispatchWorkflow

Do not put the full Flue specialist execution inside Convex.

Convex workflows coordinate durable external calls and state transitions. Flue runs the agent logic and specialists.

Part XIII — Events added by this slice

56. Project/runtime Events

project.setup.started
project.runtime.created
project.repository.cloned
project.environment.scanned
project.ready
project.setup.failed

Most setup progress remains hidden or setup-page-only. project.ready is the main global-timeline trigger.

57. Conversation Events

agent.acknowledged
agent.message
agent.blocked
agent.final

58. Flow Events

flow.started
flow.progress
flow.completed
flow.failed
flow.cancelled

Only meaningful flow progress should be user-visible.

59. Artifact Events

artifact.build.started
artifact.published
artifact.failed
artifact.superseded

60. Causality

Every agent, flow, and artifact Event must carry:

causationId = the Event that directly caused it
correlationId = the broader interaction/work chain
projectId
workId when applicable
threadId when applicable
flowRunId when applicable

Part XIV — Security and policy

61. Repository credentials

GitHub credentials are resolved by the runtime adapter.
They are not sent to the model.
They are not written to Events, artifacts, summaries, or generated files.

62. Environment values

.env.example names may enter Project context.
user-provided secret values must stay in a secret store or protected runtime configuration.
raw values must never appear in the timeline or generated artifact.
environment values are optional for this slice.

63. Service authentication

Hono/Flue and Convex communicate using service credentials and explicit tenant/project IDs.

Every agent timeline write validates:

agent belongs to Project
Project belongs to Organization
requested timeline belongs to Organization/Work
Artifact belongs to the same Project/Work boundary

64. Sandbox policy

The first slice allows:

reads anywhere inside the Project workspace
safe search/list commands
generated writes only under .zopu/

It does not allow autonomous destructive repository changes.

Part XV — Reliability

65. Idempotency keys

Use stable keys for every external or repeatable operation.

VM creation       project:<projectId>:vm:v1
repository clone  project:<projectId>:clone:<commit-or-branch>:v1
project ready     project:<projectId>:ready:<setupRevision>
agent dispatch    event:<eventId>:agent:<agentId>:handler:<version>
agent post        dispatch:<dispatchId>:message:<logicalStep>
flow run          event:<eventId>:flow:<flowType>:version:<version>
artifact build    flow:<flowRunId>:artifact:<kind>:revision:<revision>

66. Retry rules

Project setup

retry VM and network failures with bounded backoff
reuse existing runtime resources
never emit project.ready twice for the same setup revision

Timeline dispatch

retry delivery until accepted or terminally failed
the Flue endpoint deduplicates by dispatchId

Agent timeline writes

deduplicate by tool-call idempotency key
repeated model turns cannot duplicate visible messages or artifacts

Artifact generation

one bounded repair attempt
failure publishes a visible failure Event and retains the specialist result

67. Recovery

The system should be able to restart Hono/Flue and reconstruct the active state from:

Project runtime binding
conversation agent binding
Events
Work/Thread status
FlowRun status
Project context
ArtifactBuild state

No critical product state may exist only inside one model process or Pi session.

Part XVI — Frontend behavior added by this slice

68. Project setup screen

Show only a thin state progression:

Creating workspace
→ Cloning repository
→ Checking repository
→ Ready

Show detected .env.example keys as optional configuration.

On blocking failure, show:

concise failure reason
retry action
repository connection repair action when relevant

Do not redirect until Project readiness succeeds.

69. Redirect to global timeline

After project.ready:

redirect immediately or as soon as the workflow marks ready
global timeline subscribes normally
onboarding response may arrive live after redirect
show a small agent-working indicator while the first onboarding exploration runs

Do not fake a completed onboarding artifact before it exists.

70. Initial onboarding presentation

First agent message example:

The repository is connected and I’m getting familiar with the important paths now. I’ll leave the project map here as soon as it’s ready.

Then publish the Project setup artifact card.

71. Normal request presentation

user message appears immediately
→ short agent acknowledgement
→ Work card/link appears when Work is created
→ subtle running indicator
→ artifact card appears
→ concise final message

The full exploration or issue output lives in the artifact, not the chat message.

Part XVII — Implementation order

72. Slice A — Project runtime foundation

Add projectRuntimes schema.
Add AgentOS runtime adapter in Hono/Effect.
Implement idempotent VM creation.
Implement depth-1 clone.
Implement readability verification.
Implement root .env.example parser.
Implement projectSetupWorkflow.
Build setup-state UI and retry.

Exit condition

A repository can reliably become a ready Project with one VM and one readable clone.

73. Slice B — Agent registration and dispatch

Add conversationAgents and agentDispatches.
Register one Flue agent per Project.
Implement project.ready Event.
Implement timelineDispatchWorkflow.
Implement Hono/Flue event endpoint.
Implement agent timeline tool.
Have the agent post deterministic onboarding text.

Exit condition

project.ready causes a real agent-authored message to appear in the global timeline.

74. Slice C — Onboarding exploration

Mount the Project VM as the agent sandbox.
Add read/list/search/safe-exec tools.
Implement onboarding exploration flow.
Generate and store summary.md.
Add Project context retrieval.

Exit condition

The agent can onboard itself and persist a useful Project summary.

75. Slice D — Artifact generation

Add artifactBuilds.
Define typed artifact manifest.
Build the first static HTML kit.
Validate and upload through Convex.
Publish artifact card Event.
Render artifact detail in the existing frontend.

Exit condition

Onboarding exploration produces a polished Project setup HTML artifact visible from the global timeline.

76. Slice E — Exploration Work

Add conversation decision for exploration.
Create/evolve Work.
Create exploration Thread.
Run exploration specialist.
Generate exploration artifact.
Return concise final message.

Exit condition

A user can ask a repository question and receive an evidence-backed exploration artifact.

77. Slice F — Issue Work

Add issue intent decision.
Reuse relevant exploration context.
Create issue-definition Thread.
Generate issue result and artifact.
Add optional card action for later GitHub publication.

Exit condition

A user request can become a clear implementation-ready issue artifact.

Part XVIII — Acceptance scenarios

78. First-time setup

Given a connected GitHub repository
When the user selects it
Then one AgentOS VM is created
And the selected branch is cloned with depth 1
And the repository can be read
And root .env.example names are stored when present
And missing env values do not block readiness
And one project conversation agent is registered
And project.ready is emitted exactly once

79. Setup failure

Given VM creation or repository clone fails
Then the Project remains not ready
And the user remains on setup
And a retryable error is shown
And no onboarding agent event is dispatched

80. Onboarding response

Given project.ready exists
When the dispatch workflow delivers it
Then the project agent posts a short acknowledgement
And explores the repository
And stores summary.md
And publishes a Project setup HTML artifact
And posts its card into the global timeline

81. Exploration request

Given the Project agent is ready
When the user asks to explore a code path
Then the message is stored before execution
And the agent acknowledges quickly
And Work plus an exploration Thread are created
And repository evidence is collected inside the Project VM
And an exploration HTML artifact is published
And the final timeline response remains concise

82. Issue request

Given a user request or exploration finding
When the agent starts issue creation
Then an issue-definition Thread is created
And the result includes current world, desired world, scope, non-goals, acceptance criteria, evidence, risks, and questions
And a polished issue artifact is published

83. Duplicate delivery

Given Convex retries a dispatch
When the same dispatchId reaches Flue again
Then no duplicate agent response, Work, Thread, FlowRun, or Artifact is created

Part XIX — Explicitly deferred

Do not add these while shipping this slice:

one global agent routing across many Projects
many active Projects per user
multiple VMs per Project or Thread
automatic VM escalation
code implementation specialist
PR creation or review specialist
autonomous repository mutation
broad build-system detection
application boot and preview lifecycle
required/optional env intelligence
recursive env scanning
full RLM over all organization history
long-term memory/knowledge graph
dynamic agent-generated agent definitions
actor migration or dynamic Rivet registry
arbitrary unvalidated generated UI
complex artifact collaboration/editor

Preserve interfaces so these can be added later, but do not implement them now.

Part XX — Technical planning choices that do not block the model

The implementation agent may choose these after inspecting the repository and installed library versions:

Whether the Flue process executes inside the Project VM or controls the VM through the AgentOS sandbox adapter. The product contract is one project-bound agent with direct access to one project-bound VM.
Exact Flue v2 APIs for registry, hooks, persistent state, sandbox mounting, and workflow execution.
Exact Convex Workflow component syntax and retry configuration.
Artifact renderer implementation, provided it consumes typed manifests and produces safe static HTML.
Whether GitHub issue publication is included immediately or added after issue artifact generation works.

These choices must not change the durable contracts in this document.

Part XXI — Final mental model

CONVEX
Owns durable truth:
Projects · Events · Timelines · Work · Threads · Agents · Runs · Context · Artifacts

FLUE / HONO
Owns intelligence:
conversation · decisions · specialist orchestration · supervision · artifact loop

AGENTOS VM
Owns project execution environment:
repo clone · filesystem · safe commands · generated files · optional Pi sessions

The first shipping contract is:

Repository selected
→ Project VM and clone become ready
→ project.ready wakes one project conversation agent
→ agent talks briefly and works deeply
→ exploration and issue flows run beneath Work Threads
→ every meaningful result becomes a polished artifact
→ Convex publishes the result back into the timeline

43 KiB Raw Blame History Unescape Escape

Zopu Intelligence & Delivery Runtime — Implementation Handoff

0. How this document relates to the timeline handoff

Explicit simplifications that supersede earlier assumptions

Part I — Shipping goal

1. Demo promise

2. End-to-end loop

Part II — Runtime boundaries

3. Convex: durable control plane

Responsibilities

Convex does not own

4. Hono + Flue: intelligence runtime

Responsibilities

Agent identity

5. AgentOS VM: delivery environment

Responsibilities

Initial constraints

6. Pi sessions: optional deep workers

Part III — Core entities added by this slice

7. ProjectRuntime

Owns

Does not own

8. ConversationAgentBinding

9. AgentDispatch

10. FlowRun

11. ProjectContextDocument

12. ArtifactBuild

Part IV — Project setup workflow

13. Entry point

14. projectSetupWorkflow

Step 1 — Create AgentOS VM

Step 2 — Shallow clone

Step 3 — Verify readability

Step 4 — Scan .env.example

Step 5 — Register conversation agent

Step 6 — Mark Project ready

Step 7 — Emit project.ready

Step 8 — Dispatch the ready event

15. Setup failure behavior

16. Deferred from Project setup

Part V — Timeline dispatch workflow

17. User message entry point

18. timelineDispatchWorkflow

Dispatch input

Delivery contract

19. Agent-to-timeline tool

Part VI — Conversation agent

20. Product behavior

21. Initial supported decisions

22. Conversation style contract

Default response size

Good acknowledgement examples

Final response examples

23. Unsupported requests

24. Context mounted for every turn

Part VII — Flow loop

25. Definition

26. Loop behavior

27. Work and Thread creation

Work

Thread

28. Supervision rules

Part VIII — Initial specialist flows

29. Onboarding exploration flow

Inputs

Allowed actions

Outputs

Suggested summary.md contents

30. Exploration specialist flow

Responsibilities

Recommended stages

Output contract

Exploration artifact visual sections

31. Issue specialist flow

Inputs

Recommended stages

Output contract

Issue artifact visual sections

GitHub publication boundary

Part IX — Artifact generation loop

43 KiB

Raw Blame History

14. `projectSetupWorkflow`

Step 4 — Scan `.env.example`

Step 7 — Emit `project.ready`

18. `timelineDispatchWorkflow`

Suggested `summary.md` contents

46. `projectRuntimes`

47. `conversationAgents`

48. `agentDispatches`

49. `flowRuns`

50. `projectContextDocuments`

51. `artifactBuilds`