Goal

Goal Subsystem

Edge adaptation of the upstream same-session goal tracking system.

Upstream reference: Goal subsystem documentation

What Upstream Provides

The goal subsystem lets the model create a persistent objective for the current session and autonomously continue working across multiple turns until the objective is achieved or blocked. It consists of three server-side plugins and one client-side plugin:

• GoalService (ctx.goals) — state management: create, edit, pause, resume, complete, block, clear. All mutations commit as goal/change session events.
• ToolGoal — registers three model-facing tools (create_goal, get_goal, update_goal) and a system prompt policy section.
• GoalRoundDriver — listens for turn endings; when a goal is active and armed, injects a continuation prompt via agent.followup() to start a new turn automatically.
• dsh-client-ui-goal — renders the GoalBar in the input dock and goal change nodes in the conversation view.

All goal state is event-sourced: the goal/change events in the session log are the single source of truth. GoalService reconstructs its in-memory state by folding these events.

What Edge Changed

Direct Reuse — All goal plugins

All four goal plugins and the SessionProjectionCache are installed as-is. Model tools, system prompt injection, continuation logic, state management, GoalBar UI, and projection caching are entirely upstream code.

Transport Bridge — Goal projection push

GoalService registers a 'goal' projection in SessionProjectionRegistry. Edge captures changes via the generic onChanged bridge — which covers goal, title, and all future projection keys — and delivers them as WebSocket frames after flush.

Transport Bridge — GoalBar RPC routing

GoalBar's edit/pause/clear buttons send Typert RPC requests. Edge routes these through the generic TypertGatewayService which discovers GoalService's @Remote methods automatically.

What Edge Did NOT Change

• Goal lifecycle, tool definitions, system prompt policy, continuation logic
• GoalBar UI behavior, goal/change event format, authority checks
• Projection cache write timing, cleanup, and cold-snapshot restoration

Performance Characteristics

Goal projection push overhead

When the model calls create_goal or update_goal, GoalService appends a goal/change event. The projection registry's drive() computes the new goal value synchronously, and the onChanged callback buffers it. The buffered entry is drained and broadcast as a WebSocket frame after flush.

For non-goal events (the vast majority — assistant/chunk, tool/call, tool/result), the goal projection's apply() returns the same state reference (identity check), so onChanged does not fire. Net cost on non-goal events: zero.

GoalBar RPC latency

When the user clicks edit/pause/clear on the GoalBar, the request travels: browser → HTTP POST → handleTypertRpc → TypertGatewayService.invoke() → SRC reflection → GoalService.edit() → response. SRC reflection scans cordis services once per endpoint and caches the result. The actual GoalService method is a synchronous state mutation + session event append. Typical round-trip: single-digit milliseconds within the DO.

Cold-session goal restoration

Path	Trigger	Cost
Live agent snapshot	Session has active agent	O(1) — memory read
Cached snapshot	Cold session, cache exists	O(1) — synchronous domain read
Cold snapshot	Cold session, no cache	O(tail events) — persistence tail-read + refold

The upstream SessionProjectionCache handles write timing (throttled write-behind) and cleanup (session/disposed). Cache entries are stored via storageDomain and participate in the upstream domain lifecycle.

Architecture Summary

Component	Category	Edge Code
GoalService + ToolGoal + Driver + UI	Direct Reuse	Four ctx.plugin() calls
SessionProjectionCache	Direct Reuse	One ctx.plugin() call
Goal projection push	Transport Bridge	Generic projection bridge
GoalBar RPC routing	Transport Bridge	Generic Typert gateway

Key observation: Goal required zero business-logic code in Edge. Every Edge-owned line is generic transport infrastructure — projection delivery and RPC routing — that equally serves all other subsystems. The projection cache, lifecycle cleanup, and cold-session restoration are fully upstream.