-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathimplementation-notes.html
More file actions
143 lines (141 loc) · 11.2 KB
/
Copy pathimplementation-notes.html
File metadata and controls
143 lines (141 loc) · 11.2 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>ACM Implementation Notes</title>
<style>
:root { color-scheme: light dark; font-family: system-ui, sans-serif; line-height: 1.5; }
body { max-width: 72rem; margin: 0 auto; padding: 2rem; }
table { border-collapse: collapse; width: 100%; }
th, td { border: 1px solid #8888; padding: .6rem; text-align: left; vertical-align: top; }
th { background: #8882; }
code { background: #8882; padding: .1rem .25rem; border-radius: .2rem; }
.meta { color: #666; }
</style>
</head>
<body>
<h1>ACM Implementation Notes</h1>
<p class="meta">Current implementation decisions, updated 2026-07-15. Superseded cross-repository synchronization decisions were removed when omp-context became independently maintained.</p>
<h2>Decision Record</h2>
<table>
<thead>
<tr><th>Provenance</th><th>Decision</th><th>Rationale and constraint</th></tr>
</thead>
<tbody>
<tr>
<td>user-decided</td>
<td>Maintain <code>omp-context</code> as an independent repository.</td>
<td>The repository no longer owns or synchronizes another product repository. Product documentation, verification, release state, and host compatibility are local concerns only.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Track the exact locally installed OMP host through a pre-commit contract gate.</td>
<td>Every commit detects the local coding-agent, agent-core, and pi-ai versions. A changed version is validated in an isolated cold candidate before package metadata, the adapter constant, and locks are updated. Failed candidates leave the repository version untouched.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Remain extension-only and synchronize live AgentSession state through one capability-probed adapter.</td>
<td><code>branchWithSummary()</code> remains the persistent tree mutation. After a definitively successful travel, the adapter rebuilds the active branch and calls <code>agent.replaceMessages()</code> at the matching <code>tool_execution_end</code>. Runtime availability must depend on observed capabilities rather than a hard-coded OMP version, so a locally updated but compatible host remains usable.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Isolate OMP internals behind one narrow Host Bridge.</td>
<td>All guarded SessionManager mutations live at this seam. Domain logic and agent-facing tools consume typed structural results rather than casting host internals directly.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Verify runtime behavior with the real SessionManager and AgentSession.</td>
<td>The isolated fixture uses the exact declared OMP packages without a model or API key and proves resolver origin, mutation behavior, context reconstruction, compaction lifecycle, live replacement, repeated travel, resume, and session isolation.</td>
</tr>
<tr>
<td>user-decided</td>
<td>The ACM Skill package is the sole guidance authority.</td>
<td>Canonical CORE owns the normal path. Generated system-prompt text, tool descriptions, cues, and recovery fragments are derived artifacts rather than editable behavioral sources.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Retain one model-invoked advanced Skill and the fixed seven-slot handoff.</td>
<td>Advanced guidance loads only for ambiguous target selection, interleaved fronts, archive round trips, or exceptional recovery. Every handoff contains <code>Goal</code>, <code>State</code>, <code>Evidence</code>, <code>External</code>, <code>Exclusions</code>, <code>Recover</code>, and <code>NEXT</code>.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Use hard structural invariants and soft semantic criteria.</td>
<td>Runtime validates observable shape and mutation state. Boundary quality, cold start, recoverability sufficiency, and whether <code>NEXT</code> is genuinely executable remain agent completion criteria.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Use one strict timeline view discriminator.</td>
<td>The public views are <code>active</code>, <code>checkpoints</code>, <code>search</code>, and <code>tree</code>. Legacy booleans, unknown keys, blank queries, and view-incompatible fields are rejected.</td>
</tr>
<tr>
<td>agent-resolved</td>
<td>Model host mutations as explicit transaction outcomes.</td>
<td>Mutation ports return <code>not_applied</code>, <code>applied</code>, or <code>indeterminate</code> after observing the real journal and leaf. Compensation uses an operation-scoped token; applied or indeterminate branch changes create a context-refresh obligation.</td>
</tr>
<tr>
<td>agent-resolved</td>
<td>Use a capability-probed, identity-scoped live AgentSession adapter.</td>
<td>The adapter installs one descriptor-safe idempotent wrapper at <code>AgentSession.getContextUsage()</code>, associates <code>SessionManager → WeakRef<AgentSession></code> by object identity, keeps the complete tool-call ticket atomically inside the shared adapter, and validates the retained message sequence after <code>replaceMessages()</code>. Exact dependency versions remain verification targets only.</td>
</tr>
<tr>
<td>agent-resolved</td>
<td>Preserve persistent recovery when live synchronization is unavailable or fails.</td>
<td>Unsupported host shape, missing association, stale work, build failure, or replacement failure never rolls back an otherwise valid travel. The summary branch and backup checkpoint remain authoritative, and public context rebuild continues.</td>
</tr>
<tr>
<td>agent-resolved</td>
<td>Port Pi 2026-07-15 robustness and safety changes into OMP extension form.</td>
<td>Host Bridge snapshots and observes mutation state before/after each append and rollback; branch verification requires an observable leaf change; reserved target names are rejected before mutation; travel refuses mixed assistant tool batches. Pi-only TUI renderers, prompt metadata, and the <code>src/context.ts</code> command surface have no OMP equivalent, so terminal-control neutralization is applied to plain-text tool results instead.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Add semantic rebase as a normal-path agent transition, not a new tool.</td>
<td>A rebase carries all surviving state in one authoritative snapshot to the earliest safe base, with root as the ideal candidate rather than a default. <code>acm_travel</code> remains the only mutation primitive.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Use cold start as the hard rebase gate.</td>
<td>A fresh agent must be able to execute <code>NEXT</code> from the snapshot and direct evidence pointers without reading archived summaries. Context pressure triggers the check but never lowers it.</td>
</tr>
<tr>
<td>agent-resolved</td>
<td>Expose summary-depth evidence without runtime safety verdicts.</td>
<td>Timeline counts active <code>branch_summary</code> handoff layers separately from native compaction, exposes root as a structural candidate, and projects post-travel depth. Travel reports before/after/delta plus target/root facts and explains that a root rebase replaces prior layers while appending one new handoff, so resulting depth is normally target depth + 1 rather than zero; it never labels a candidate safe.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Refine rebase without weakening checkpoint, local-fold, failed-direction, or task-end behavior.</td>
<td>The always-on CORE retains every normal transition and a complete local-fold example. Rebase adds a structural-reset criterion alongside cold start rather than replacing the existing fold gate.</td>
</tr>
<tr>
<td>agent-resolved</td>
<td>Use one advanced reference at a time and reroute when the observable condition changes.</td>
<td>This preserves progressive disclosure without trapping archive recovery inside the wrong playbook after a failure. Recovery references now distinguish backup-label rollback from indeterminate branch mutation and use factual refresh/live-sync lifecycle states.</td>
</tr>
<tr>
<td>agent-resolved</td>
<td>Deliver 30/50/70 context reminders through OMP-native tool and terminal paths.</td>
<td>The <code>context</code> event observes usage. A pending reminder is sent as a hidden <code>steer</code> on <code>tool_result</code>. For a normally settled main session without a tool result, <code>session_stop</code> only records terminal eligibility and always returns <code>undefined</code>; the following <code>agent_end</code> sends a hidden <code>nextTurn</code> message with <code>triggerTurn: true</code>. This preserves other stop-hook results and metadata. OMP does not emit <code>session_stop</code> for subagents, so their fallback guarantee is intentionally limited to the tool-result path.</td>
</tr>
<tr>
<td>agent-resolved</td>
<td>Use a persisted baseline-only cycle after travel and native compaction.</td>
<td>A successful <code>acm_travel</code> or <code>session_compact</code> suppresses threshold delivery until the first real post-transition <code>turn_end</code> establishes a baseline. The baseline is stored in a non-context custom entry; hidden reminder custom messages record delivered tiers. Start, switch, branch, and tree events rebuild the current cycle from the active branch so reload and resume do not duplicate reminders.</td>
</tr>
<tr>
<td>agent-resolved</td>
<td>Preserve strict per-view timeline validation after the OMP 16.4.8 Zod 4 host promotion.</td>
<td>The host-compatible root schema remains one object, while a Zod refinement enforces the documented discriminated-view contract: search requires a non-blank query, and fields scoped to active/checkpoints/search are rejected on other views. This restores the existing public contract without reintroducing a root union that conflicts with the host registration surface.</td>
</tr>
<tr>
<td>user-decided</td>
<td>Classify ACM reminders against a working budget capped at 400K tokens while preserving hard-window usage as a separate metric.</td>
<td><code>workingBudgetTokens = min(contextWindow, 400000)</code>: models at or below 400K retain their actual-window 30% / 50% / 70% behavior, while larger windows use 400K and therefore trigger at 120K / 200K / 280K active tokens. Existing persisted levels remain compatible; reminder details, baseline state, and the timeline dashboard expose both hard usage and ACM pressure rather than redefining <code>usagePercent</code>. OMP-native delivery and lifecycle recovery paths remain unchanged.</td>
</tr>
</tbody>
</table>
<h2>Open Decisions</h2>
<p>None. A failed local-host cold candidate or a new official OMP navigation API must reopen the capability seam decision.</p>
</body>
</html>