Introducing Focusa: a local-first autonomy substrate for agents and applications that need mission, scope, proof, prediction, learning, and continuation beyond one session
I’ve been working on Focusa in one form or another for about a year.
The repo is younger than that. The problem is not.
Before Focusa had a name, I kept watching the same failure repeat across AI coding sessions.
The agent did not necessarily crash.
It did not always refuse the task.
It did not even have to produce obviously bad code.
It would keep moving after it had lost the shape of the work.
The original mission would blur into the current prompt. A test result would disappear into transcript history. A model switch would turn a real project into a summary of a project. A new session would inherit prose instead of authority. An agent would report that something was finished because the conversation felt finished, even when the proof was incomplete.
That is a more dangerous failure than simply stopping.
The agent still looks productive.
It is just no longer reliably attached to the same project, mission, evidence, constraints, or definition of done.
This is the problem Focusa started with.
But as the codebase has developed, the shape of Focusa has become clearer. It is not merely a memory layer. It is not a prompt manager. It is not another coding assistant, IDE, or model wrapper.
Focusa is becoming a local-first autonomy runtime and substrate that agents, interfaces, coding harnesses, and other applications can build on.
Continuity is still at the center. But continuity alone is not enough.
An autonomous system also needs to know:
- which project it is operating on;
- which workstream is active;
- what the durable direction is;
- what the immediate next action is;
- which statements are observations and which are canonical truth;
- what evidence supports the work;
- which action is authorized;
- what the system predicted would happen;
- what actually happened;
- which lessons deserve to be reused;
- and how much autonomy the agent has actually earned.
A transcript cannot carry all of that safely.
The transcript was never meant to be the runtime.
Cursor showed the spark.
Focusa is building the wiring.
The first problem was continuity
The earliest Focusa idea was simple:
The next agent should not have to reconstruct the project from transcript memory.
Experienced developers do not hold a project as one giant stream of dialogue.
They carry multiple layers at once:
project identity
long-term direction
current milestone
immediate task
active files and objects
constraints
decisions
known risks
proof already collected
unfinished work
next safe action
A chat transcript mixes those layers together.
It contains useful information, but it also contains abandoned ideas, outdated assumptions, repeated tool output, intermediate mistakes, operator corrections, irrelevant branches, and stale summaries.
A longer context window delays the problem. It does not solve it.
Eventually the session compacts. A provider truncates history. A model changes. An agent forks. A developer takes over. A second machine joins. An application needs to inspect the state without replaying the conversation.
At that point, the system needs something more durable than the tail of a chat.
This is where Focusa began: preserve the work itself, not just the conversation about the work.
Reusable project state may be the reusable rocket of AI coding
Code generation is getting cheaper.
The expensive part is increasingly everything that has to be rebuilt around it:
What repository is this?
What are we actually trying to accomplish?
Which branch of work is current?
What has already been tried?
Which result was verified?
What failed?
What must not change?
What should happen next?
Every time that state has to be reconstructed from a transcript, the workflow pays the launch cost again.
That is why I keep returning to this analogy:
Reusable project state may be the reusable rocket of AI coding.
Not “memory” as an unlimited bag of old text.
Reusable scoped, proof-backed project state.
The useful part is not remembering everything. The useful part is preserving the right state, under the right project, with the right authority, so a new agent can continue without pretending to know more than it does.
What Focusa is today
Focusa currently runs as a local Rust daemon beside the agent.
The main runtime surfaces are:
focusa-core reducer, state, Workpoints, Evidence, scope, persistence
focusa-api local typed HTTP API
focusa-cli operator and agent command surface
focusa-tui terminal Mission Deck
Pi extension deep coding-agent integration
menubar preview operator cockpit
The broader shape looks like this:
Agent / coding harness / application / operator interface
|
CLI | HTTP API | Pi tools | capability index
|
Focusa daemon
|
Project scope | Trajectory | Workpoints | Evidence
Predictions | Metacognition | Autonomy | Work Loop
|
Reducer | scoped state | local persistence
The daemon owns runtime state.
The API exposes typed reads and controlled writes.
The CLI gives operators and agents a practical interface.
The TUI turns the current project, Workpoint, trajectory, proof state, health, and next safe action into a terminal cockpit.
The Pi extension allows the coding agent to use Focusa directly instead of inventing a separate memory system inside every prompt.
Focusa also exposes a machine-readable capabilities endpoint:
GET /v1/agent/capabilities
That endpoint describes operations using fields such as:
operation id
family
HTTP method and path
request and response schema
side-effect profile
permissions
confirmation requirements
idempotency requirements
budget profile
documentation reference
The separate tool-contract registry currently contains 105 contracts. Each contract connects a tool to its API route, CLI command, ontology action, side-effect profile, scope requirements, authority requirements, documentation, and verification path.
That is an important part of the transition from “tool” to “substrate.”
An application should not have to scrape CLI help or guess which operation is safe. It should be able to discover what Focusa can do and what authority a particular operation requires.
The repo also includes a deliberately minimal MCP JSON-RPC bridge. It currently exposes safe health discovery rather than routing project-bound operations around Focusa’s scope checks.
That restraint is intentional.
Integration should not become a shortcut around authority.
Scope has to come before memory
One of the most important changes in the current runtime is that Focusa is becoming explicitly scoped.
A continuity ID alone is not enough.
Two repositories could both contain a workstream called checkout-fix. Two agents could use the same session name. A process could start from a home directory, root directory, shared server folder, or stale working directory.
Focusa now models scope using typed structures similar to:
{
"root_scope": {
"scope_kind": "project",
"scope_id": "project:9b4c...",
"root_path": "/srv/projects/storefront",
"canonical_name": "storefront",
"fingerprint": "sha256:..."
},
"continuity_id": "checkout-recovery"
}
The runtime separates:
ScopeRef — what verified project or host boundary owns the state
ProjectRootKey — canonical project-root identity
WorkstreamKey — root scope plus continuity ID
AttachmentKey — workstream plus instance, session, and attachment identity
The rule in the code is blunt:
Canonical state must be partitioned by verified root scope first
and workstream second.
Continuity never establishes root authority.
That means checkout-recovery does not become trusted merely because an agent remembers that name.
The project root must also be verified.
The fingerprint must match.
The continuity ID must belong to that project.
Unsafe project roots are rejected.
This matters because an autonomy runtime cannot afford vague ownership. Before an agent remembers, predicts, learns, resumes, or mutates anything, the system has to know whose state it is touching.
The core authority boundary is:
project_root + continuity_id
A session ID is useful temporal metadata.
It is not project authority.
A transcript is useful history.
It is never authority.
Direction lives in Trajectory
Knowing the project is not enough. The agent also needs direction.
Focusa uses a Trajectory hierarchy:
HLT — High-Level Trajectory
MLG — Mid-Level Goal
STG — Short-Term Goal
Waypoints — proof-bearing progress markers
The HLT is the durable north star.
For example:
HLT:
Make checkout reliable across every supported payment provider
without regressing refunds, subscriptions, or auditability.
A mid-level goal might be:
MLG:
Remove provider-specific response ambiguity from the payment adapter layer.
A short-term goal might be:
STG:
Repair Stripe decline normalization and prove it against the targeted fixture suite.
Waypoints might include:
- failing case reproduced
- provider response mapped
- adapter patched
- targeted test passed
- regression suite passed
- browser checkout flow verified
This hierarchy matters because “fix checkout” is not enough context for long-running agent work.
The current task has to remain attached to the larger direction.
Focusa does not treat any generic project description as an authoritative trajectory. Missing, stale, inferred, and canonical direction are different states.
The runtime is designed to say that direction is missing rather than silently manufacture a north star from the repository name or current prompt.
Workpoints are the current center of continuation
The strongest practical center of Focusa is the Workpoint.
A Workpoint is a typed continuation contract.
It is not a transcript summary.
It records the bounded state needed to continue the current work:
verified project scope
continuity ID
mission
active object references
action intent
verification records
blockers
next slice
evidence references
confidence
canonical or degraded posture
A basic checkpoint looks like this:
focusa workpoint checkpoint \
--project-root "$PWD" \
--continuity-id checkout-recovery \
--mission "Repair checkout decline handling without regressing refunds" \
--next-action "Patch response normalization and run targeted tests" \
--json
Evidence can then be attached:
focusa workpoint evidence-link \
--target-ref crates/payments/src/provider_adapter.rs \
--result "Targeted checkout tests passed" \
--evidence-ref "test:cargo test checkout_decline_normalization" \
--json
A later session can resume it:
focusa workpoint resume \
--project-root "$PWD" \
--continuity-id checkout-recovery \
--copy-prompt
The result is a bounded packet carrying the mission, exact scope, proof handles, and next action.
If the project root is unsafe or the requested continuity belongs to another scope, Focusa is supposed to block or degrade the packet instead of pretending it is canonical.
That distinction is critical.
A continuation packet that confidently resumes the wrong project is worse than no packet at all.
Workpoints are bounded on purpose
A Workpoint is not supposed to contain the whole repository.
It does not need the entire chat.
It does not need every diagnostic line, source file, test log, browser event, and rejected idea.
It needs enough to continue safely.
Large artifacts belong behind handles.
Detailed evidence should remain rehydratable without being copied into every prompt.
This is part of the role of Bloatgaurd, Focusa’s context-pressure and output-control layer.
The governing idea is:
Hot context:
- current mission
- verified scope
- active Workpoint
- current trajectory
- blockers
- proof handles
- next safe action
Cold but rehydratable context:
- full command output
- screenshots
- long diagnostics
- complete artifacts
- prior detailed reflections
- older evidence payloads
Rich context should live in indexed handles, evidence stores, compact packets, and rehydration references—not repeatedly dumped into the hottest part of the prompt.
Recent Focusa work has also moved compaction closer to the runtime itself: measuring session pressure, preserving typed scope during rollover, carrying Workpoint and Trajectory state through compaction, and restoring automatic compaction controls in the Pi integration.
The goal is not merely to make a session smaller.
The goal is to make it recoverable without turning the compacted summary into a new source of authority.
Evidence has to survive the handoff
AI coding workflows often treat evidence as disposable output.
A command runs.
A test passes.
A screenshot appears.
The agent says “done.”
Then the transcript compacts and the proof disappears.
Focusa treats evidence as a first-class reference that can remain attached to the active work.
Evidence may refer to:
tests
files
routes
screenshots
browser diagnostics
command output
release checks
build artifacts
public sources
verification reports
The important point is not that Focusa stores every byte inside the Workpoint.
It preserves the relationship:
this proof
supports this result
for this Workpoint
inside this project and workstream
That relationship can survive a model switch or handoff.
It can also be inspected by an operator, another agent, a UI, or a future application.
This is the beginning of a more useful definition of memory:
Memory is not merely what the agent once saw.
Memory is what the system can still place, scope, retrieve, and verify.
Drift checking turns “stay focused” into a runtime operation
Most coding-agent instructions contain some version of:
Stay on task.
Do not change unrelated files.
Do not drift from the request.
Those are useful instructions, but they are still prose.
Focusa makes drift a typed operation.
A drift check can compare:
latest action
expected action type
active objects
do-not-drift boundaries
current Workpoint
The result can classify whether drift occurred, how severe it is, why it happened, and what recovery action should follow.
That allows an agent or application to ask something more concrete than “Am I still focused?”
It can ask:
Does the action I just took still belong to the active Workpoint?
Did I touch an object outside the accepted scope?
Did I replace the next action with an adjacent task?
Should I checkpoint, recover, or ask the operator?
Focusa is not trying to eliminate exploration.
It is trying to make the difference between exploration and canonical progress visible.
Context Authority governs risky mutation
Autonomy without an authority boundary is just speed with fewer brakes.
Focusa includes a Context Authority preflight path for risky operations.
For example:
focusa action preflight \
--current-ask "install Focusa locally" \
--kind binary_replace \
--target /usr/local/bin/focusa \
--source github_release_asset \
--install-role live_build_host \
--project-root "$PWD" \
--json
The current authority model recognizes outcomes such as:
allow
block
ask_operator
verify_first
diagnosis_only
planning_only
This applies to actions such as:
deploys
release publication
git push
binary replacement
destructive file operations
database migrations
broad refactors
cross-project edits
secret or configuration changes
live service actions
install and update ambiguity
The point is not to make every edit bureaucratic.
The point is to distinguish:
I can describe this action.
I can recommend this action.
I am allowed to perform this action.
I performed this action.
I have evidence that it succeeded.
Those are not the same statement.
A useful autonomy substrate must keep them separate.
The reducer separates observation from truth
Focusa’s reducer is one of the most important pieces of the runtime.
It is designed as a deterministic, replayable, side-effect-free state machine.
Its job is to decide which events change canonical state.
One of the current reducer rules is conceptually this simple:
if is_observation {
return Ok(ReductionResult {
new_state: state,
emitted_events: vec![event],
});
}
The observation is recorded.
The canonical state does not change.
That distinction allows Focusa to represent:
an agent noticed something
a remote machine proposed something
a browser tool produced a result
a background model inferred something
an operator approved something
the reducer accepted something as canonical
Without that boundary, every model output can quietly become truth.
The reducer also enforces writer ownership for canonical thread mutation. A non-owner can observe or propose. It cannot silently overwrite the canonical Focus State owned by another writer.
That is how Focusa starts to support multiple agents and applications without letting them all become competing sources of truth.
The system can accept many observers.
It should still know who is allowed to write.
Typed scoped state is becoming the reusable substrate
The current runtime does not rely only on one global bag of JSON state.
Focusa now has typed scoped records that carry:
workstream scope
record ID
actor ID
vector clock
Lamport timestamp
updated time
tombstone state
typed value
A simplified record shape looks like this:
{
"scope": {
"root_scope": {
"scope_kind": "project",
"root_path": "/srv/projects/storefront",
"fingerprint": "sha256:..."
},
"continuity_id": "checkout-recovery"
},
"record_id": "prediction-019...",
"actor_id": "agent-a",
"vector_clock": {
"agent-a": 4,
"agent-b": 2
},
"lamport_ts": 8,
"tombstone": false,
"value": {}
}
Reconciliation rejects records from different workstreams.
Concurrent records are resolved deterministically using vector clocks, Lamport ordering, timestamps, actor identity, and payload hashes.
This is more than persistence.
It is a foundation for agents and applications that need to share state without flattening different projects, workstreams, writers, and observations into one global memory.
The response layer also carries both machine and human posture:
{
"scope": {},
"authority": {
"status": "canonical",
"why": "The record belongs to the exact verified workstream."
},
"human": {
"status": "recorded",
"summary": "Prediction recorded.",
"next_action": "Evaluate it when proof arrives.",
"warnings": []
},
"data": {}
}
Applications can consume the typed data.
Humans can understand why the result was accepted.
Ontology gives the runtime a working world
Continuity tells the agent where it left off.
Ontology tells it what kind of world it is operating in.
Focusa’s ontology layer models software work using typed objects, relations, actions, status, provenance, verification, freshness, affordances, and working sets.
The central idea is that an agent should not receive only a pile of remembered prose.
It should receive a bounded working world that can answer:
What exists?
How are these things related?
Which actions are valid?
What currently matters?
What has been verified?
What is still uncertain?
What can this agent actually do here?
The ontology API currently includes surfaces for:
primitives
contracts
world projections
bounded slices
tool contracts
tool choreography
actions
adjacency
working sets
communities
context
affordances
retrieval governance
tool-result proposals
execution criticism
reflection synthesis
memory pipelines
intelligence dashboards
Ontology does not replace the runtime.
It gives the runtime shared semantics.
The division is roughly:
Ontology:
- object identity
- types
- relations
- valid actions
- provenance
- verification
- status and freshness
Runtime:
- continuity
- active focus
- salience
- reducer authority
- persistence
- replay
- recovery
- enforcement
The architectural rule is:
Deterministic systems classify structure.
Models classify ambiguity.
Only the reducer canonizes truth.
That lets models remain useful without making every inference authoritative.
Predictions turn guesses into evaluated records
Agents make predictions constantly, even when they do not call them predictions.
They implicitly estimate:
This file probably contains the bug.
This command is likely to pass.
This migration should be reversible.
This browser failure is probably caused by authentication.
This patch will not affect refunds.
This tool is the best next route.
Usually those expectations disappear after the action.
The agent does not compare them to the outcome.
The next session cannot tell whether the strategy has been reliable.
Focusa now treats prediction as a scoped runtime family.
A prediction includes:
typed workstream scope
prediction type
context references
ontology context
predicted outcome
confidence
recommended action
reasoning summary
trajectory context
An agent can record one from the CLI:
focusa predict record \
--project-root "$PWD" \
--continuity-id checkout-recovery \
--prediction-type next_action_success \
--predicted-outcome "targeted checkout tests pass" \
--confidence 0.72 \
--recommended-action "patch provider response normalization and rerun targeted tests" \
--why "the observed failure is isolated to decline-code mapping"
Once evidence arrives, the prediction can be evaluated:
focusa predict evaluate <prediction-id> \
--project-root "$PWD" \
--continuity-id checkout-recovery \
--actual-outcome "targeted checkout tests passed" \
--score 1.0
Focusa can then calculate scoped accuracy and calibration statistics:
focusa predict stats \
--project-root "$PWD" \
--continuity-id checkout-recovery
The important word is scoped.
Prediction records are partitioned by the exact typed workstream. The runtime does not fall back to a global prediction bag when it cannot find the requested project.
A prediction about checkout in one repository cannot quietly become evidence for a similarly named workstream in another.
Predictions also remain advisory until evaluated.
They never override operator steering.
Predictions and metacognition form a learning flywheel
Prediction becomes more useful when it feeds learning.
The current Focusa direction is:
Focusa signals
→ prediction
→ action
→ evidence and outcome
→ evaluation
→ metacognition
→ promoted learning
→ next prediction
Before a risky or familiar action, an agent can retrieve related lessons and record what it expects to happen.
After the action, it can evaluate the result against evidence.
A successful prediction evaluation can create a scoped metacognition capture.
A successful metacognition evaluation can promote that lesson and create a follow-up prediction for the next similar action.
This turns “the agent learned something” from a vague claim into a visible sequence of records.
Metacognition is not a journal of everything the model thought
Focusa’s metacognition layer currently supports:
capture
retrieve
reflect
adjust
evaluate
promote
inspect recent reflections
inspect recent adjustments
inspect recent evaluations
A capture can record a reusable lesson:
focusa metacognition capture \
--kind recovery_pattern \
--content "When the checkout UI succeeds but the API reports an unknown decline, inspect provider normalization before changing form state." \
--rationale "The browser and API evidence separated the UI path from the adapter failure." \
--confidence 0.88 \
--strategy-class payment_adapter_recovery
A later agent can retrieve relevant lessons:
focusa metacognition retrieve \
--current-ask "Repair checkout without regressing refunds" \
--scope-tag checkout \
--scope-tag payments \
--k 5
Retrieval is bounded.
The default path uses a compact hot index and summary-first results. Full records remain rehydratable by ID.
This avoids turning every prior lesson into hot prompt context.
The metacognition loop is more structured than “write a reflection”:
capture a signal
retrieve related lessons
reflect on a turn range or failure class
select a strategy adjustment
evaluate observed outcome changes
promote only when the result supports it
The CLI can execute that compound flow through:
focusa metacognition loop run
Promotion is not automatic because a strategy sounded intelligent.
An evaluated outcome has to support it.
When a metacognition evaluation crosses the promotion threshold, Focusa can:
- create a promoted learning capture;
- attach its trajectory and exact workstream;
- make it available to later retrieval;
- create a follow-up prediction of type
metacog_learning_transfer; - ask the next agent to test whether the lesson actually transfers.
That final step matters.
Even promoted learning should remain testable.
Autonomy should be earned, scoped, and revocable
The word “autonomy” is often used to mean that the agent can keep running for a long time.
That is not enough.
An agent can run for a long time while being wrong.
Focusa models autonomy as evidence-based trust calibration.
The current autonomy layer tracks six dimensions:
correctness
stability
efficiency
trust
grounding
recovery
These roll into an Agent Reliability Index, or ARI, from 0 to 100.
Focusa defines six autonomy levels:
AL0 → AL1 → AL2 → AL3 → AL4 → AL5
The highest end represents long-horizon autonomy.
But the core rule is more important than the score:
Focusa never self-escalates autonomy.
The runtime may recommend a higher level after enough evidence and sufficient ARI performance.
A human still has to grant it.
The grant can carry:
autonomy level
allowed scope
expiration time
reason
supporting evidence
The autonomy API can expose:
GET /v1/autonomy
GET /v1/autonomy/history
The response includes the current level, ARI score, dimensions, sample count, granted scope, grant TTL, promotion recommendation, and history.
This means an application can ask:
How reliable has this agent actually been?
In which dimensions?
Over how many observations?
Under what scope?
Has the grant expired?
Is the runtime recommending promotion, or has a human approved it?
That is a more useful model than an “autonomous mode” checkbox.
The Work Loop is bounded orchestration, not unchecked control
Focusa also has a Work Loop for governed continuous execution.
The Work Loop can manage:
ready-work selection
current task
writer ownership
driver lifecycle
Pi RPC attachment
pause and resume
checkpoints
heartbeats
delegation
blocked or degraded states
operator stop
But the work loop does not automatically become cognitive authority.
Its current authority posture explicitly says:
authority plane: bounded orchestration
canonical: false
Focus State authority: false
writer ownership required: true
Operator controls include:
pause
resume
stop
preflight
approval for sensitive actions
The promotion boundary is also explicit:
The Work Loop may select and execute bounded work,
but it must checkpoint, attach evidence, and pass promotion
before canonical cognition changes.
This is an important part of the substrate design.
Focusa can help an agent continue working without declaring that every action the loop takes is automatically correct.
Execution and truth remain separate.
Project Cards create bounded orientation for agents and applications
Focusa can also produce an advisory Project Card.
The card fuses bounded information from several runtime families:
ProjectIdentity
ontology counts
Trajectory hierarchy
Workpoint and Evidence status
prior decisions and results
prediction statistics
recent outcomes
timing and token efficiency
waypoint status
metacognition retrieval prompts
This is useful for cold starts and reorientation.
An agent or application can get a compact view of the project without dumping the full runtime into its context.
But the Project Card remains advisory.
It does not replace the Workpoint.
It does not become a hidden source of task authority.
This recurring separation—useful intelligence versus canonical authority—is one of the most important principles in Focusa.
UIAI Engine gives the runtime eyes and proof in the browser
Focusa is not the only piece of this system.
UIAI Engine is the companion browser and proof runtime.
It gives agents persistent browser sessions, selector and @ref actions, screenshots, page reads, diagnostics, public-source research, visual artifacts, and stable evidence handles.
Its current FPV cockpit allows an operator to see the browser from the agent’s perspective and send audited steering actions back into the active Pi workflow.
The product boundary is deliberate:
UIAI Engine owns:
- browser execution
- browser sessions
- search and public-source research
- screenshots and visual artifacts
- console and network diagnostics
- operator FPV
- stable browser evidence handles
Focusa owns:
- ProjectIdentity
- Trajectory
- Workpoints
- evidence linkage
- predictions
- metacognition
- recovery
- authority
- continuation
Together, the flow can look like this:
Focusa Workpoint
|
v
UIAI Engine browser session
|
+-- page state
+-- screenshots
+-- console errors
+-- failed requests
+-- source research
+-- operator steering
|
v
stable evidence handles
|
v
Focusa Evidence linkage
|
+-- evaluate prediction
+-- update Workpoint
+-- capture metacognition
+-- choose next safe action
This solves a common problem in browser-based agent work.
Without a proof layer, the result is:
“The agent clicked around and said it worked.”
With UIAI Engine and Focusa, the target is closer to:
The agent inspected these pages,
performed these actions,
observed these diagnostics,
captured these screenshots,
linked this proof to this Workpoint,
and Focusa knows what should happen next.
UIAI Engine gives the agent eyes.
Focusa gives those eyes a mission, continuity, and learning loop.
A practical example: repairing checkout without losing the mission
Consider an agent asked to repair an intermittent checkout failure.
The visible task sounds simple:
Fix checkout.
But the real engineering mission is larger:
Restore reliable checkout without regressing refunds,
subscriptions, provider auditability, or existing payment flows.
A Focusa-backed workflow might proceed like this.
1. Verify the project
focusa project discover --max-depth 2 --json
Focusa establishes the verified project root and fingerprint.
2. Load the direction
The agent loads the current Trajectory:
HLT: reliable multi-provider payment execution
MLG: normalize provider behavior behind one adapter boundary
STG: repair decline handling
3. Resume or create the Workpoint
focusa workpoint checkpoint \
--project-root "$PWD" \
--continuity-id checkout-recovery \
--mission "Repair checkout decline handling without regressing refunds" \
--next-action "Reproduce the failing browser and API paths" \
--json
4. Retrieve prior lessons
focusa metacognition retrieve \
--current-ask "Reproduce intermittent checkout failure" \
--scope-tag checkout \
--scope-tag payments \
--k 5
The agent may learn that a similar failure previously came from provider normalization rather than form state.
5. Record a prediction
focusa predict record \
--project-root "$PWD" \
--continuity-id checkout-recovery \
--prediction-type failure_source \
--predicted-outcome "the UI submits successfully and the adapter misclassifies the decline response" \
--confidence 0.68 \
--recommended-action "capture browser network and API evidence before changing UI code" \
--why "prior scoped learning points to provider normalization"
6. Use UIAI Engine to observe the real browser flow
UIAI Engine opens a persistent browser session.
The agent and operator can inspect:
form submission
request payload
response body
console output
failed requests
screenshots
current URL and page state
7. Link the proof
The browser diagnostics show that the UI submitted correctly but the provider adapter mapped an expected decline code into an unknown error.
That evidence is linked to the Workpoint.
8. Run Context Authority preflight
Before touching provider-wide adapter code, Focusa checks whether the mutation matches the active ask and verified project.
9. Patch and verify
The agent changes only the normalization path, runs targeted tests, then runs the broader payment regression suite.
10. Evaluate the prediction
The actual outcome matches the forecast.
The prediction is scored.
A successful result feeds a scoped metacognition capture.
11. Promote the useful lesson carefully
The lesson is not:
“All checkout errors are adapter errors.”
It is something bounded:
When browser submission succeeds and the API returns an unknown
decline after a valid provider response, inspect normalization
before changing UI state.
That lesson remains attached to the payments workstream and can be tested again later.
12. Checkpoint the next action
The Workpoint now carries:
mission
patched object
tests passed
browser evidence
prediction result
promoted lesson
remaining regression checks
next safe action
A new agent can resume from that state without replaying the entire session.
That is the kind of workflow Focusa is being built to support.
What makes this a substrate instead of another agent
Focusa is not trying to become the coding model.
Models will change.
Editors will change.
Harnesses will change.
Applications will use different combinations of local models, hosted models, browser runtimes, coding agents, CI workers, and operator interfaces.
Focusa is trying to provide a reusable layer underneath them:
scope
authority
trajectory
continuation
evidence
prediction
learning
autonomy calibration
orchestration
recovery
The value of that layer increases when more than one agent or application needs to understand the work.
A coding agent may checkpoint a Workpoint.
A TUI may display it.
A browser runtime may attach evidence.
A project dashboard may render the trajectory.
A CI worker may add test proof.
A second agent may retrieve a promoted lesson.
An operator interface may approve a risky action.
A future application may inspect the capabilities registry and use only the operations it is authorized to call.
The substrate should let those surfaces cooperate without giving each one permission to redefine canonical truth.
Try the current core loop
Focusa is still early, but the local runtime and core continuity loop are usable.
Install the evaluation build:
curl -fsS https://install.focusa.dev/focusa | bash -s -- --eval
focusa start
focusa setup wizard --dry-run
focusa doctor
Run the non-destructive five-minute proof inside a project:
focusa project discover --max-depth 2 --json
focusa first-mission \
--project-root "$PWD" \
--dry-run \
--json
focusa workpoint checkpoint \
--project-root "$PWD" \
--continuity-id demo-continuity \
--mission "First Focusa proof" \
--next-action "Resume from the Workpoint packet" \
--json
focusa workpoint evidence-link \
--target-ref tests \
--result "cargo test passed" \
--evidence-ref "test:cargo test" \
--json
focusa workpoint resume \
--project-root "$PWD" \
--continuity-id demo-continuity \
--copy-prompt
The expected result is a typed continuation packet with:
mission
verified scope
proof handle
next safe action
authority posture
Unsafe or unclear scope should return a blocked or degraded result rather than a false canonical packet.
The Mission Deck can also be inspected from the terminal:
focusa deck --headless-self-test --json
Or opened interactively:
focusa tui
What is current, and what is still early
Focusa is not finished.
The current center of the product is:
local Rust daemon
typed HTTP API
CLI
terminal Mission Deck
ProjectIdentity
Trajectory
Workpoints
Evidence
Context Authority
scope-aware reducer paths
Pi integration
prediction records and evaluation
scoped metacognition
autonomy calibration
bounded Work Loop
tool-contract and capability discovery
The Pi integration is currently the deepest agent harness path.
The menubar remains a preview surface.
The MCP bridge is intentionally minimal today rather than a broad escape hatch around project scope enforcement.
Predictions and metacognition now operate inside typed workstreams, but the larger learning experience will continue to evolve.
The autonomy layer measures and recommends. It does not give itself more authority.
Longer-horizon work-loop behavior is governed and actively being hardened.
Focusa Receipt surfaces are being consolidated into a clearer proof ledger across Workpoints, evidence, outcomes, closure, and handoffs.
That is the honest state.
The repo is young.
The system is already much larger than a weekend prototype.
And the underlying problem is older than the repo.
The direction from here
The first wave of AI coding made code easier to generate.
The next wave has to make work harder to lose.
That means agents need more than context.
They need a working world.
They need to know where they are, what they are doing, what they predicted, what happened, what was proven, what was learned, and what they are actually allowed to do next.
They need state that survives the model.
They need proof that survives the session.
They need learning that remains scoped.
They need autonomy that is earned rather than assumed.
Focusa is my attempt to build that layer.
Not another agent.
Not another editor.
Not a larger transcript.
A local-first runtime underneath agentic work—one that agents and applications can build upon without making the conversation itself the source of truth.
The transcript should carry the conversation.
Focusa should carry the work.
Sources and code referenced
- Focusa README and current operator workflow
- Current authority model
- Current Golden Workflow
- Typed scoped state and CRDT reconciliation
- Core reducer
- Workpoint API routes
- Ontology overview
- Current ontology and prediction API inventory
- Prediction and metacognition signal substrate
- Scoped prediction implementation
- Prediction CLI
- Metacognition implementation
- Metacognition CLI
- Autonomy calibration
- Governed Work Loop
- Agent capabilities endpoint
- Current Focusa tool-contract registry
- Minimal scope-preserving MCP bridge
- UIAI Engine browser and proof runtime