feat: Slice 1 polish - MiMo V2.5 model, visible reasoning, image attachments, mobile keyboard fix
- Switch conversation agent to xiaomi/mimo-v2.5 (multimodal: text + image) - Render native reasoning parts as live 'Thinking trace' (streaming open, collapsed after completion); inline <think> extraction for streaming models - Image attachments: picker (up to 4, 10MB each), base64 to Flue AgentPromptImage, authenticated blob-URL replay for historical images - Mobile keyboard viewport fix: visual-viewport hook, fixed shell, interactive-widget=resizes-content, header pinned, composer follows keyboard - Conversation to Signal to proposed Work: Convex persistence, Effect validation in @code/work-os, Work cards with exact source provenance - Streamdown markdown + Mermaid chart rendering in chat messages - Flue tool turns hidden, reasoning-containing turns remain visible - Frontend regression tests: keyboard viewport, responsive shell, attachment overflow, authenticated images, reasoning traces, transforms - .env.example updated to xiaomi/mimo-v2.5 config
This commit is contained in:
-Puter
328
docs/agent-context.md
Normal file
328
docs/agent-context.md
Normal file
@@ -0,0 +1,328 @@
|
||||
# Zopu Work OS — Agent Context
|
||||
|
||||
> **Purpose:** compact bootstrap context for Codex/OMP/OpenCode/FLUE workers contributing to Zopu.
|
||||
> **Usage:** read this first, then load only task-relevant documents and repository files.
|
||||
|
||||
## 1. Mission
|
||||
|
||||
Build Zopu: a Work OS that turns conversation and external Signals into durable, verified outcomes.
|
||||
|
||||
```text
|
||||
Signal → Work → Definition → Design → Vertical Slices
|
||||
→ Resolver → Attempts → Verification → Delivery → Result → Learning
|
||||
```
|
||||
|
||||
The product is not chat threads, an issue tracker, a harness UI, or an autonomous PR factory.
|
||||
|
||||
## 2. Source-of-truth order
|
||||
|
||||
```text
|
||||
1. current accepted Work/Question/Decision
|
||||
2. approved Work Definition
|
||||
3. approved Design Packet + current Slice
|
||||
4. repository tests/types/code
|
||||
5. product.md
|
||||
6. tech.md
|
||||
7. design.md
|
||||
8. dev-loop.md
|
||||
9. slices.md
|
||||
10. dev-plan.md
|
||||
11. glossary.md
|
||||
12. evaluation.md
|
||||
```
|
||||
|
||||
When sources conflict, report the conflict. Do not silently choose a convenient interpretation.
|
||||
|
||||
## 3. Current product target
|
||||
|
||||
Initial user:
|
||||
|
||||
```text
|
||||
technical founder / small engineering team
|
||||
one project + one Git repository
|
||||
web chat + Work cards
|
||||
manual merge
|
||||
```
|
||||
|
||||
Initial complete loop:
|
||||
|
||||
```text
|
||||
message
|
||||
→ Signal
|
||||
→ approved Work
|
||||
→ approved Design Packet
|
||||
→ one bounded coding slice
|
||||
→ independent verification
|
||||
→ exact verified commit
|
||||
→ real PR
|
||||
→ human intervention/resume
|
||||
```
|
||||
|
||||
## 4. Non-negotiable invariants
|
||||
|
||||
1. Work is a durable outcome, not a chat/session/issue/PR.
|
||||
2. Exact Signal provenance is preserved.
|
||||
3. State transitions are explicit commands/events.
|
||||
4. FLUE/model output is validated proposal data, not authority.
|
||||
5. Rivet actors own serialized lifecycle/recovery.
|
||||
6. Harnesses and runtimes are replaceable adapters.
|
||||
7. One mutating Attempt owns one isolated worktree.
|
||||
8. Every Attempt is bounded and terminally classified.
|
||||
9. Builder output remains candidate output until independent verification.
|
||||
10. Evidence binds to exact revision and environment.
|
||||
11. Published PR head equals verified integrated SHA.
|
||||
12. Human questions/approvals are durable objects.
|
||||
13. Retry/restart must not duplicate Work, commits, PRs, or deployments.
|
||||
14. Merge/deploy remain human-gated initially.
|
||||
15. Completion requires outcome evidence, not an agent’s “done.”
|
||||
|
||||
## 5. System ownership
|
||||
|
||||
```text
|
||||
Work OS durable intent/state/evidence/policy
|
||||
Rivet actors identity, serialization, timers, recovery
|
||||
FLUE domain agents/workflows and typed proposals
|
||||
Harness bounded coding/tool loop
|
||||
Sandbox filesystem/process/network isolation
|
||||
Git source history
|
||||
ArtifactStore durable output/evidence
|
||||
UI/Buzz interaction surfaces, not workflow truth
|
||||
```
|
||||
|
||||
## 6. Initial actor shape
|
||||
|
||||
```text
|
||||
ProjectActor
|
||||
├── project config + active Work index
|
||||
|
||||
WorkActor
|
||||
├── definition/design/slices
|
||||
├── resolver state
|
||||
├── questions/approvals
|
||||
├── artifacts/result
|
||||
|
||||
AttemptActor
|
||||
├── runtime lease
|
||||
├── harness session
|
||||
├── normalized events
|
||||
├── timeout/cancellation/outcome
|
||||
```
|
||||
|
||||
Add Verification/Integration/Result actors only when their lifecycles justify separation.
|
||||
|
||||
## 7. Initial adapters
|
||||
|
||||
Preferred first implementation:
|
||||
|
||||
```text
|
||||
FLUE definition/design/resolver support
|
||||
Rivet actors
|
||||
CubeSandbox full Linux runtime
|
||||
OMP first coding harness, replaceable
|
||||
Git forge branch/commit/PR
|
||||
Convex durable application data/projections where used
|
||||
Effect application ports/layers/errors/scopes/streams
|
||||
```
|
||||
|
||||
Do not import provider-specific types into domain modules.
|
||||
|
||||
## 8. Working protocol for every code task
|
||||
|
||||
### Before editing
|
||||
|
||||
1. Identify current vertical slice and acceptance criteria.
|
||||
2. Read relevant docs and repository rules.
|
||||
3. Inspect current architecture, tests, and existing abstractions.
|
||||
4. State impacted modules and risks.
|
||||
5. Produce/confirm a small implementation plan.
|
||||
6. Ask a Question only when ambiguity changes behavior, security, data, or architecture.
|
||||
|
||||
### During implementation
|
||||
|
||||
1. Stay within the current slice.
|
||||
2. Preserve dependency direction.
|
||||
3. Prefer existing patterns over parallel frameworks.
|
||||
4. Add typed boundaries and tagged errors.
|
||||
5. Make external effects idempotent.
|
||||
6. Add cancellation/timeouts for long-running operations.
|
||||
7. Record exact revisions/provider identifiers.
|
||||
8. Add tests with the implementation.
|
||||
9. Do not weaken unrelated tests or hide failures.
|
||||
10. Explain intentional Design Packet deviations.
|
||||
|
||||
### Before declaring candidate ready
|
||||
|
||||
Run task-relevant checks:
|
||||
|
||||
```text
|
||||
format/lint/typecheck
|
||||
focused unit/integration tests
|
||||
behavioral/live check
|
||||
security/secret check where relevant
|
||||
design-conformance review
|
||||
```
|
||||
|
||||
Report:
|
||||
|
||||
```text
|
||||
files changed
|
||||
behavior implemented
|
||||
checks run + results
|
||||
known risks/deviations
|
||||
artifacts/revision
|
||||
remaining blockers
|
||||
```
|
||||
|
||||
Never claim verified unless the independent verification path ran.
|
||||
|
||||
## 9. Code organization rule
|
||||
|
||||
Use logical separation:
|
||||
|
||||
```text
|
||||
domain/ pure types/state/invariants
|
||||
application/ use cases/commands
|
||||
ports/ Effect services
|
||||
adapters/ FLUE/Rivet/Cube/OMP/Git implementations
|
||||
```
|
||||
|
||||
Keep the initial package count practical. A folder boundary is enough until independent reuse/lifecycle exists.
|
||||
|
||||
## 10. State modeling rule
|
||||
|
||||
Prefer explicit state machines over booleans.
|
||||
|
||||
Bad:
|
||||
|
||||
```ts
|
||||
isRunning: boolean
|
||||
isDone: boolean
|
||||
hasError: boolean
|
||||
```
|
||||
|
||||
Good:
|
||||
|
||||
```ts
|
||||
type AttemptStatus =
|
||||
| "queued"
|
||||
| "running"
|
||||
| "succeeded"
|
||||
| "retryable_failure"
|
||||
| "needs_input"
|
||||
| "blocked"
|
||||
| "verification_failed"
|
||||
| "budget_exhausted"
|
||||
| "cancelled"
|
||||
| "permanent_failure"
|
||||
```
|
||||
|
||||
Transitions must validate current version/state.
|
||||
|
||||
## 11. Model/agent output rule
|
||||
|
||||
Agents return schemas such as:
|
||||
|
||||
```text
|
||||
SignalProposal
|
||||
WorkDefinitionProposal
|
||||
DesignPacketProposal
|
||||
ResolverDecisionProposal
|
||||
VerificationAssessment
|
||||
LearningProposal
|
||||
```
|
||||
|
||||
Application code decodes, authorizes, and executes commands. Agents do not directly mutate arbitrary state.
|
||||
|
||||
## 12. Quality rule
|
||||
|
||||
For every behavior, identify:
|
||||
|
||||
```text
|
||||
acceptance criterion
|
||||
implementation evidence
|
||||
independent check
|
||||
exact candidate revision
|
||||
review requirement
|
||||
```
|
||||
|
||||
Tests prove immediate behavior. Design review protects maintainability and future change cost. Both matter.
|
||||
|
||||
## 13. UI rule
|
||||
|
||||
Expose:
|
||||
|
||||
```text
|
||||
outcome
|
||||
phase
|
||||
latest meaningful update
|
||||
next action/blocker
|
||||
slice progress
|
||||
evidence
|
||||
delivery/result
|
||||
```
|
||||
|
||||
Hide low-level harness noise by default. Preserve raw logs in diagnostics.
|
||||
|
||||
## 14. Scope control
|
||||
|
||||
Do not implement unless required by the current slice:
|
||||
|
||||
- dynamic Kit Builder;
|
||||
- multiple harness providers;
|
||||
- large fleets;
|
||||
- autonomous merge/deploy;
|
||||
- universal workflows;
|
||||
- automatic canonical-memory mutation;
|
||||
- sophisticated multi-tenancy.
|
||||
|
||||
Design replaceable boundaries, then ship one path.
|
||||
|
||||
## 15. Task completion template
|
||||
|
||||
```md
|
||||
## Implemented
|
||||
- ...
|
||||
|
||||
## Behavior
|
||||
- ...
|
||||
|
||||
## Verification run
|
||||
- `command` — pass/fail
|
||||
- ...
|
||||
|
||||
## Evidence
|
||||
- candidate SHA/artifacts
|
||||
- ...
|
||||
|
||||
## Design deviations
|
||||
- none / ...
|
||||
|
||||
## Remaining risks or blockers
|
||||
- none / ...
|
||||
```
|
||||
|
||||
## 16. Required reading by task type
|
||||
|
||||
| Task | Read |
|
||||
|---|---|
|
||||
| product/domain | product.md, glossary.md |
|
||||
| UI | design.md, product.md |
|
||||
| actors/state | tech.md, glossary.md |
|
||||
| orchestration | dev-loop.md, tech.md |
|
||||
| current sequencing | slices.md, dev-plan.md |
|
||||
| verification/evals | evaluation.md, dev-loop.md |
|
||||
| provider adapter | tech.md plus provider docs |
|
||||
| broad feature | agent-context.md + all relevant sections |
|
||||
|
||||
## 17. Stop and escalate when
|
||||
|
||||
- accepted definition/design is missing or contradictory;
|
||||
- required permission is unavailable;
|
||||
- worktree/revision identity is uncertain;
|
||||
- a destructive action is outside policy;
|
||||
- verification cannot bind to exact candidate;
|
||||
- implementation requires expanding scope materially;
|
||||
- a retry would repeat a non-transient failure;
|
||||
- repository state suggests another active mutating owner.
|
||||
|
||||
Return a precise Question or blocker, not a guess.
|
||||
Reference in New Issue
Block a user