@iiiokojiadbi/shift 0.30.0 → 0.32.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,12 +1,15 @@
1
- # shift for pi
1
+ # shift for pi and opencode
2
2
 
3
- The agent decides by itself when to **shift**. At a stage boundary it updates its work board and task folders, writes a letter to itself, and has pi let the stretch's history go, with a direction of what to hold. Right after the shift it gets its letter, board and tasks in progress back whole and continues from where it stopped.
3
+ The agent decides by itself when to **shift**. At a stage boundary it updates its work board and task folders, writes a letter to itself, and has the harness let the stretch's history go, with a direction of what to hold. Right after the shift it gets its letter, board and tasks in progress back whole and continues from where it stopped.
4
+
5
+ One package for both harnesses: pi loads `index.ts`, opencode loads `server.ts`.
4
6
 
5
7
  ```sh
6
8
  pi install npm:@iiiokojiadbi/shift
9
+ opencode plugin add @iiiokojiadbi/shift
7
10
  ```
8
11
 
9
- The extension adds a "Shift" section to the system prompt, the `shift` tool with its companions (`shift_guide`, `shift_status`, `shift_history`, `shift_setup`, `task_open`, `task_track`, `task_archive`, `doc_outline`, `docs_mentioning`), and three commands: `/shift` asks the agent to shift now, `/shift-tasks` lists the open tasks, `/unshift` picks up the last shift in a fresh session. It hints a shift as the history grows.
12
+ It adds a "Shift" section to the system prompt, the `shift` tool with its companions (`shift_guide`, `shift_status`, `shift_history`, `shift_setup`, `task_open`, `task_track`, `task_archive`, `doc_outline`, `docs_mentioning`), and three commands: `/shift` asks the agent to shift now, `/shift-tasks` lists the open tasks, `/unshift` picks up the last shift in a fresh session. It hints a shift as the history grows.
10
13
 
11
14
  The records live in the project's `.shift/` folder and stay out of its git unless `commit = true` in `.shift/settings.toml`.
12
15
 
package/core/delivery.ts CHANGED
@@ -1,5 +1,5 @@
1
1
  // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
- import { docsAfterWrite } from './docs'
2
+ import { followWrite, settleDocs } from './docs'
3
3
  import { type ChangedBy, changedRecords, type Seen } from './flows'
4
4
  import type { GaugeKeeper } from './hint'
5
5
  import { MOD } from './layout'
@@ -8,14 +8,14 @@ import type { Project } from './project'
8
8
  import { NOTE_KINDS, type NoteKind } from './texts/prompts'
9
9
  import { TOLD } from './texts/rows'
10
10
 
11
- // Everything the mod tells the agent goes through here: a hint, the check of the records changed, the docs' remarks
12
- // after a write, the waiting letter. An adapter fills two slots — a tool's result and the next prompt — and puts
11
+ // Everything the mod tells the agent goes through here: a hint, the check of the records changed, the docs settled
12
+ // after a run, the waiting letter. An adapter fills two slots — a tool's result and the next prompt — and puts
13
13
  // what comes back where its harness lets it; the kinds, their order, their one format and the owner's rows are here.
14
14
  // Nothing is queued: every note is pulled at the slot it goes with.
15
15
 
16
16
  // What the mod last saw of the records and how many of the main agent's tools run now: a change seen while one runs
17
- // may be that tool's own.
18
- export type Looks = { seen: Seen | null; running: number }
17
+ // may be that tool's own. `written`: the files written since the docs were last settled, from the project's root.
18
+ export type Looks = { seen: Seen | null; running: number; written?: readonly string[] }
19
19
 
20
20
  export const FRESH_LOOKS: Looks = { seen: null, running: 0 }
21
21
 
@@ -37,7 +37,7 @@ export type ToolEnd = {
37
37
  own: boolean
38
38
  // A tool that ran read-only changed nothing: no look after it.
39
39
  readOnly: boolean
40
- // The file it wrote, absolute, when it wrote one and did not fail: the docs follow it.
40
+ // The file it wrote, absolute, when it wrote one and did not fail: the docs follow it, settled with the next prompt.
41
41
  written?: string
42
42
  }
43
43
 
@@ -51,27 +51,28 @@ export async function beforeTool(courier: Courier): Promise<Note[]> {
51
51
  return outside === null ? [] : [{ kind: 'records', body: outside }]
52
52
  }
53
53
 
54
- // After a tool of the main agent: the notes from before it, what it changed in the records, the docs after its write,
55
- // and a hint if the fill calls for one — wrapped, each told to the owner as it goes into the result.
54
+ // After a tool of the main agent: the notes from before it, what it changed in the records, and a hint if the fill
55
+ // calls for one — wrapped, each told to the owner as it goes into the result. A file it wrote is only followed.
56
56
  export async function afterTool(courier: Courier, before: readonly Note[], done: ToolEnd | null): Promise<string[]> {
57
57
  await courier.updateLooks(current => ({ ...current, running: Math.max(0, current.running - 1) }))
58
58
  if (done === null) return []
59
59
  const notes = [...before]
60
60
  const own = done.readOnly ? null : await look(courier, 'agent')
61
61
  if (own !== null && !done.own) notes.push({ kind: 'records', body: own })
62
- if (done.written !== undefined) notes.push(...(await docsNotes(courier, done.written)))
62
+ if (done.written !== undefined) await follow(courier, done.written)
63
63
  const hint = await loopHint(courier.loop, courier.gauge).catch(() => null)
64
64
  if (hint !== null) notes.push({ kind: 'hint', body: hint })
65
65
 
66
66
  return deliver(courier.loop, notes)
67
67
  }
68
68
 
69
- // A file written by a subagent: the docs follow it, and their remarks go with its result.
70
- export async function afterWrite(courier: Courier, file: string): Promise<string[]> {
71
- return deliver(courier.loop, await docsNotes(courier, file))
69
+ // A file written by a subagent: the docs follow it, settled with the main agent's next prompt.
70
+ export async function afterWrite(courier: Courier, file: string): Promise<void> {
71
+ await follow(courier, file)
72
72
  }
73
73
 
74
- // With the next prompt: what changed between turns, a hint, and after a wait the letter, last, when the owner speaks.
74
+ // With the next prompt: what changed between turns, the docs written in the run settled, a hint, and after a wait the
75
+ // letter, last, when the owner speaks. With a tool running — a message queued mid-run — the docs wait: it may be an edit.
75
76
  // The notes are told to the owner and the letter cleared only once `delivered` says the prompt went with them.
76
77
  export async function atPrompt(
77
78
  courier: Courier,
@@ -82,6 +83,8 @@ export async function atPrompt(
82
83
  const { running } = await courier.looks()
83
84
  const outside = running === 0 ? await look(courier, 'other') : null
84
85
  if (outside !== null) notes.push({ kind: 'records', body: outside })
86
+ const docs = running === 0 ? await settle(courier) : null
87
+ if (docs !== null) notes.push({ kind: 'docs', body: docs })
85
88
  const hint = await loopHint(courier.loop, courier.gauge).catch(() => null)
86
89
  if (hint !== null) notes.push({ kind: 'hint', body: hint })
87
90
  const letter = owner ? await waitingNote(courier.loop) : null
@@ -113,10 +116,23 @@ async function look(courier: Courier, by: ChangedBy): Promise<string | null> {
113
116
  }
114
117
  }
115
118
 
116
- async function docsNotes(courier: Courier, file: string): Promise<Note[]> {
117
- const lines = await docsAfterWrite(await courier.project(), file).catch(() => [])
119
+ // A written file the docs follow is remembered for the next prompt; the map follows a document at once.
120
+ async function follow(courier: Courier, file: string): Promise<void> {
121
+ const path = await followWrite(await courier.project(), file).catch(() => null)
122
+ if (path === null) return
123
+ await courier.updateLooks(current =>
124
+ current.written?.includes(path) ? current : { ...current, written: [...(current.written ?? []), path] },
125
+ )
126
+ }
127
+
128
+ // The files written since the last settling, settled now and forgotten; a settling that fails says nothing.
129
+ async function settle(courier: Courier): Promise<string | null> {
130
+ const written = (await courier.looks()).written ?? []
131
+ if (written.length === 0) return null
132
+ await courier.updateLooks(current => ({ ...current, written: (current.written ?? []).filter(path => !written.includes(path)) }))
133
+ const lines = await settleDocs(await courier.project(), written).catch(() => [])
118
134
 
119
- return lines.length === 0 ? [] : [{ kind: 'docs', body: lines.join('\n') }]
135
+ return lines.length === 0 ? null : lines.join('\n')
120
136
  }
121
137
 
122
138
  function deliver(loop: Loop, notes: readonly Note[]): string[] {
package/core/docs.ts CHANGED
@@ -86,37 +86,63 @@ export async function brokenLinks(store: Store, root: string, path: string, text
86
86
  return missing
87
87
  }
88
88
 
89
- // After the agent wrote a file: a document gets its toc rewritten and the map follows it; a document's remarks and any
90
- // file's broken links come back as lines of one note. None when all is well: a check that speaks on every edit is noise.
91
- export async function docsAfterWrite(project: Project, file: string): Promise<string[]> {
92
- const { store, root, settings } = project
93
- const docs = settings.docs
94
- if (!settings.enabled || docs.dirs.length === 0 || !file.startsWith(`${root}/`)) return []
89
+ // After the agent wrote a file: a document puts the map in step at once; the file itself is settled by `settleDocs`
90
+ // once the run is over. The file's path from the root, or null when the docs do not follow it.
91
+ export async function followWrite(project: Project, file: string): Promise<string | null> {
92
+ const { root, settings } = project
93
+ if (!settings.enabled || settings.docs.dirs.length === 0 || !file.startsWith(`${root}/`)) return null
95
94
  const path = file.slice(root.length + 1)
96
- if (path.startsWith(`${DIR}/`)) return []
97
- let text = await store.read(file)
98
- if (text === null) return []
95
+ if (path.startsWith(`${DIR}/`)) return null
96
+ if (isDoc(path, settings.docs.dirs)) await refreshDocs(project, { tocs: false })
99
97
 
100
- const lines: string[] = []
101
- const doc = isDoc(path, docs.dirs)
102
- if (doc && docs.toc) {
103
- const next = withToc(text)
104
- if (next !== null && next !== text) {
105
- await store.write(file, next)
106
- text = next
107
- lines.push(`The mod rewrote the toc of \`${path}\`: read the file before editing it again.`)
98
+ return path
99
+ }
100
+
101
+ // The files written in a run, once it is over: each document gets its toc written, and the remarks — a document's own,
102
+ // any file's links still not there — come back as lines of one note. Not after each write: a document written before
103
+ // the one it links to has no remark to make, and a toc written mid-run would make the agent read the file again before
104
+ // each next edit. None when all is well: a check that speaks on every run is noise.
105
+ export async function settleDocs(project: Project, paths: readonly string[]): Promise<string[]> {
106
+ const { store, root, settings } = project
107
+ const docs = settings.docs
108
+ if (!settings.enabled || docs.dirs.length === 0) return []
109
+ const rewritten: string[] = []
110
+ const remarked: string[] = []
111
+ let pins = false
112
+ for (const path of paths) {
113
+ let text = await store.read(`${root}/${path}`)
114
+ if (text === null) continue
115
+ const doc = isDoc(path, docs.dirs)
116
+ if (doc && docs.toc) {
117
+ const next = withToc(text)
118
+ if (next !== null && next !== text) {
119
+ await store.write(`${root}/${path}`, next)
120
+ text = next
121
+ rewritten.push(path)
122
+ }
108
123
  }
124
+ if (doc && pinned(text).length > 0) pins = true
125
+ const remarks = [
126
+ ...(doc ? docRemarks(text, docs) : []),
127
+ ...(await brokenLinks(store, root, path, text, docs.dirs)).map(link => `a link to \`${link}\` that is not there`),
128
+ ]
129
+ if (remarks.length > 0) remarked.push(`\`${path}\`: ${remarks.join('; ')}.`)
109
130
  }
110
- // Pinned blocks past the limit are told when the document written has some: the write may be what passed it.
111
- const over = doc ? pinnedOver(await refreshDocs(project), docs) : null
112
- if (over !== null && pinned(text).length > 0) lines.push(over)
113
- const remarks = [
114
- ...(doc ? docRemarks(text, docs) : []),
115
- ...(await brokenLinks(store, root, path, text, docs.dirs)).map(link => `a link to \`${link}\` that is not there`),
116
- ]
117
- if (remarks.length > 0) lines.push(`\`${path}\`: ${remarks.join('; ')}.`)
131
+ const named = rewritten.map(path => `\`${path}\``).join(', ')
132
+ // Pinned blocks past the limit are told when a document written has some: the write may be what passed it.
133
+ const over = pins ? pinnedOver(await refreshDocs(project, { tocs: false }), docs) : null
118
134
 
119
- return lines
135
+ return [
136
+ ...(rewritten.length === 0
137
+ ? []
138
+ : [
139
+ rewritten.length === 1
140
+ ? `The mod wrote the toc of ${named}: read the file before editing it again.`
141
+ : `The mod wrote the tocs of ${named}: read each before editing it again.`,
142
+ ]),
143
+ ...(over === null ? [] : [over]),
144
+ ...remarked,
145
+ ]
120
146
  }
121
147
 
122
148
  // The documents with remarks and the root's Markdown files with a broken link, short enough to read after a shift:
@@ -334,14 +360,15 @@ export function withMap(shift: string | null, map: string): string {
334
360
  }
335
361
 
336
362
  // Every document read once: its toc rewritten when the settings ask for one, then the map in SHIFT.md written when it
337
- // changed — nothing when there are no documents and no SHIFT.md yet. At the session's start, a shift and a write.
338
- export async function refreshDocs(project: Project): Promise<Doc[]> {
363
+ // changed — nothing when there are no documents and no SHIFT.md yet. At the session's start and a shift; after a write
364
+ // mid-run only the map, `tocs: false`: a toc the agent is not told of would fail its next edit.
365
+ export async function refreshDocs(project: Project, { tocs = true }: { tocs?: boolean } = {}): Promise<Doc[]> {
339
366
  const { store, root } = project
340
367
  const settings = project.settings.docs
341
368
  const docs: Doc[] = []
342
369
  for (const path of await docPaths(store, root, settings.dirs)) {
343
370
  let text = (await store.read(`${root}/${path}`)) ?? ''
344
- const next = settings.toc ? withToc(text) : null
371
+ const next = tocs && settings.toc ? withToc(text) : null
345
372
  if (next !== null && next !== text) {
346
373
  await store.write(`${root}/${path}`, next)
347
374
  text = next
@@ -133,7 +133,7 @@ const SHIFT_RULES = `\`${SHIFT_FILE}\` is how this project keeps its knowledge:
133
133
 
134
134
  A \`> [!IMPORTANT]\` block in one of those documents is pinned: the map shows it under its document with its section, so it is in front of you in every session without opening the document. Pin only what you would get wrong in any task without it, in a line or two; change it in the document, never in the map. Nothing is pinned until you pin it. Past \`[docs] max_pinned\` the map says so and still shows every block — unpin what is not needed in every task.
135
135
 
136
- Those documents the mod keeps as you write them. After an Edit or a Write the map follows at once; with \`[docs] toc = true\` each document carries a toc between \`${TOC_START}\` and \`${TOC_END}\` under its \`# \` title, written by the mod from its \`##\` and \`###\` and the \`> \` line under a heading — never edit it by hand, and read the file again when the mod says it rewrote it. Remarks come once, in the tool's result: no description, a description or a file over the limits the settings set, a link to a document that is not there. Silence means all is well. The documents with remarks also come after a shift.`
136
+ Those documents the mod keeps as you write them. After an Edit or a Write the map follows at once; with \`[docs] toc = true\` each document carries a toc between \`${TOC_START}\` and \`${TOC_END}\` under its \`# \` title, written by the mod from its \`##\` and \`###\` and the \`> \` line under a heading — never edit it by hand. The rest waits until the run is over, so a set of documents can be written in any order: with the next message the mod writes the tocs of the files you wrote and checks them, in one note — the tocs it wrote, so read such a file again before editing it, and the remarks: no description, a description or a file over the limits the settings set, a link to a document that is not there. Silence means all is well. The documents with remarks also come after a shift.`
137
137
 
138
138
  // The section's text without its tag, for a harness that wraps a prompt section in a tag of its own; the tools are the
139
139
  // ones shown in this project, in the order given.
@@ -33,7 +33,7 @@ import type { HandedBack, PendingShift, Recent, SessionFile, ShiftAfter, Stuck,
33
33
  export const NOTE_KINDS = {
34
34
  hint: 'a hint from the mod, not part of what it came with',
35
35
  records: "the mod's check of the records just changed",
36
- docs: "the mod's check of the file just written",
36
+ docs: "the mod's check of the files written in the last run",
37
37
  } as const
38
38
 
39
39
  export type NoteKind = keyof typeof NOTE_KINDS
@@ -181,7 +181,7 @@ function shiftMessage(opening: string, letter: string, back: HandedBack, closing
181
181
  `<${MOD} folder="${dir}/">`,
182
182
  opening,
183
183
  '',
184
- 'The board, the tasks in progress and the map of knowledge, as they are now; SHIFT.md, OWNER.md, GLOSSARY.md and TASKS.md are in your session block, read again after this shift:',
184
+ 'The board, the tasks in progress and the map of knowledge, as they are now; the files of your session block were read again after this shift:',
185
185
  '',
186
186
  renderWork(work, back.knowledge, back.owner),
187
187
  '',
@@ -209,7 +209,7 @@ export function continuePrompt(letter: string, back: HandedBack): string {
209
209
  }
210
210
 
211
211
  export function waitContext(letter: string, back: HandedBack): string {
212
- return shiftMessage("You shifted and waited for the owner; the owner's message is above.", letter, back, [GUIDE_KNOWN])
212
+ return shiftMessage("You shifted and waited for the owner; the owner's message comes with this one.", letter, back, [GUIDE_KNOWN])
213
213
  }
214
214
 
215
215
  export function resumePrompt(letter: string, back: HandedBack): string {
package/index.ts CHANGED
@@ -179,12 +179,13 @@ export default function shift(pi: ExtensionAPI): void {
179
179
  if (!enabled) return
180
180
  const path = (event.toolName === 'edit' || event.toolName === 'write') && !event.isError ? event.input.path : undefined
181
181
  const written = typeof path === 'string' ? resolve(ctx.cwd, path) : undefined
182
- let added: string[]
183
- if (event.parentToolCallId === undefined) {
184
- const before = outside.get(event.toolCallId) ?? []
185
- outside.delete(event.toolCallId)
186
- added = await afterTool(courierOf(ctx), before, { own: OURS.has(event.toolName), readOnly: READING.has(event.toolName), written })
187
- } else added = written === undefined ? [] : await afterWrite(courierOf(ctx), written)
182
+ if (event.parentToolCallId !== undefined) {
183
+ if (written !== undefined) await afterWrite(courierOf(ctx), written)
184
+ return
185
+ }
186
+ const before = outside.get(event.toolCallId) ?? []
187
+ outside.delete(event.toolCallId)
188
+ const added = await afterTool(courierOf(ctx), before, { own: OURS.has(event.toolName), readOnly: READING.has(event.toolName), written })
188
189
  if (added.length === 0) return
189
190
 
190
191
  return {
package/package.json CHANGED
@@ -1,24 +1,30 @@
1
1
  {
2
2
  "name": "@iiiokojiadbi/shift",
3
- "version": "0.30.0",
3
+ "version": "0.32.0",
4
4
  "description": "The agent decides by itself when to shift: it keeps a work board and task folders, writes a letter to itself, and continues from where it stopped.",
5
5
  "license": "MIT",
6
6
  "type": "module",
7
7
  "repository": {
8
8
  "type": "git",
9
9
  "url": "git+https://github.com/iiiokojiadbi/shift.git",
10
- "directory": "adapters/pi"
10
+ "directory": "adapters/npm"
11
11
  },
12
12
  "keywords": [
13
- "pi-package"
13
+ "pi-package",
14
+ "opencode-plugin"
14
15
  ],
15
16
  "files": [
16
17
  "index.ts",
18
+ "server.ts",
17
19
  "store.ts",
18
20
  "core",
19
21
  "README.md",
20
22
  "LICENSE"
21
23
  ],
24
+ "exports": {
25
+ "./server": "./server.ts",
26
+ "./package.json": "./package.json"
27
+ },
22
28
  "pi": {
23
29
  "extensions": [
24
30
  "./index.ts"
@@ -27,5 +33,13 @@
27
33
  "peerDependencies": {
28
34
  "@earendil-works/pi-coding-agent": "*",
29
35
  "typebox": "*"
36
+ },
37
+ "peerDependenciesMeta": {
38
+ "@earendil-works/pi-coding-agent": {
39
+ "optional": true
40
+ },
41
+ "typebox": {
42
+ "optional": true
43
+ }
30
44
  }
31
45
  }
package/server.ts ADDED
@@ -0,0 +1,431 @@
1
+ import { resolve } from 'node:path'
2
+ import type { Plugin } from '@opencode/plugin'
3
+ import type { Courier, Gauge, GaugeKeeper, LetGoHarness, Level, Looks, Loop, LoopState, Note, WaitNote } from './core/index'
4
+ import {
5
+ addGrowth,
6
+ afterTool,
7
+ afterTurn,
8
+ afterWrite,
9
+ atPrompt,
10
+ beforeTool,
11
+ contentChars,
12
+ countGrowth,
13
+ FRESH_GAUGE,
14
+ FRESH_LOOKS,
15
+ FRESH_LOOP,
16
+ gaugeStatus,
17
+ letGoGauge,
18
+ MOD,
19
+ RESUME_COMMAND,
20
+ RESUME_DESCRIPTION,
21
+ renderSessionFiles,
22
+ resumeShift,
23
+ SHIFT_COMMAND,
24
+ SHIFT_NOW,
25
+ SHIFT_NOW_DESCRIPTION,
26
+ SOURCES,
27
+ sessionDoctrine,
28
+ sessionFiles,
29
+ shiftBase,
30
+ startSession,
31
+ TASKS_COMMAND,
32
+ TASKS_DESCRIPTION,
33
+ TOOLS,
34
+ tasksView,
35
+ unassistedInstructions,
36
+ } from './core/index'
37
+ import { projectAt } from './store'
38
+
39
+ type Definition = Plugin.Plugin
40
+
41
+ const OURS: ReadonlySet<string> = new Set(TOOLS.map(tool => tool.name))
42
+ // opencode's tools that only read, and those that write one file by `path`.
43
+ const READING: ReadonlySet<string> = new Set(['read', 'glob', 'grep'])
44
+ const WRITING: ReadonlySet<string> = new Set(['edit', 'write'])
45
+ // opencode keeps this much of the latest history whole beside the digest, unless its config says otherwise.
46
+ const KEPT_TOKENS = 15_000
47
+ // A token is about four characters: the step's tokens stand for the response's text, which the event does not carry.
48
+ const CHARS_PER_TOKEN = 4
49
+ // The rows the owner sees above what the mod sends the agent.
50
+ const CONTINUED = `${MOD}: the letter and the records`
51
+ const NOTES = `${MOD}: notes to the agent`
52
+
53
+ // What the plugin keeps of one session; the plugin is one per project, shared by its sessions.
54
+ type Session = {
55
+ loop: LoopState
56
+ gauge: Gauge
57
+ looks: Looks
58
+ // The last step's prompt size: the history as the model read it.
59
+ fill: number | undefined
60
+ // A run is going on; set when it starts, cleared at idle.
61
+ busy: boolean
62
+ // The Hold of the shift being let go, and what its let-go ended in.
63
+ hold: string | undefined
64
+ letGo: ((end: { text: string } | { error: string }) => void) | undefined
65
+ // The doctrine and the session's files as the session started or last let go: a block read anew every
66
+ // request would show records the history has not reached yet and break the prompt's cache on every write.
67
+ block: { doctrine: string; files: string | null } | undefined
68
+ }
69
+
70
+ type Ended = { sessionID: string; text?: string; error?: unknown; tokens?: { input?: number } }
71
+
72
+ const plugin: Definition = {
73
+ id: MOD,
74
+ async setup(ctx) {
75
+ const root = ctx.location.directory
76
+ const start = await startSession(await projectAt(root))
77
+ if (!start.enabled) return
78
+
79
+ const sessions = new Map<string, Session>()
80
+ const parents = new Map<string, string | null>()
81
+ const windows = new Map<string, { window: number; threshold: number | undefined }>()
82
+ const outside = new Map<string, Note[]>()
83
+ let stopped = false
84
+
85
+ // A session's state, its waiting letter read back from the plugin's storage the first time: it outlives a restart.
86
+ async function state(sessionID: string): Promise<Session> {
87
+ const known = sessions.get(sessionID)
88
+ if (known !== undefined) return known
89
+ const note = ((await ctx.storage.get(waitKey(sessionID))) ?? null) as WaitNote | null
90
+ const fresh: Session = {
91
+ loop: { ...FRESH_LOOP, note },
92
+ gauge: FRESH_GAUGE,
93
+ looks: FRESH_LOOKS,
94
+ fill: undefined,
95
+ busy: false,
96
+ hold: undefined,
97
+ letGo: undefined,
98
+ block: undefined,
99
+ }
100
+ sessions.set(sessionID, sessions.get(sessionID) ?? fresh)
101
+
102
+ return sessions.get(sessionID) ?? fresh
103
+ }
104
+
105
+ // A subagent runs in a child session: only the main agent shifts and is told.
106
+ async function child(sessionID: string): Promise<boolean> {
107
+ return (await parentOf(sessionID)) !== null
108
+ }
109
+
110
+ async function parentOf(sessionID: string): Promise<string | null> {
111
+ const known = parents.get(sessionID)
112
+ if (known !== undefined) return known
113
+ const info = await ctx.session.get({ sessionID }).catch(() => undefined)
114
+ const parent = info?.parentID ?? null
115
+ parents.set(sessionID, parent)
116
+
117
+ return parent
118
+ }
119
+
120
+ // The main session a subagent's session runs under, through any depth.
121
+ async function mainOf(sessionID: string): Promise<string> {
122
+ const parent = await parentOf(sessionID)
123
+
124
+ return parent === null ? sessionID : mainOf(parent)
125
+ }
126
+
127
+ // A row for the owner: a synthetic message the owner sees by its description; the agent reads it with the next one.
128
+ async function tell(sessionID: string, row: string, _level: Level): Promise<void> {
129
+ await ctx.session.synthetic({ sessionID, text: row, description: row, resume: false }).catch(() => {})
130
+ }
131
+
132
+ function loopOf(sessionID: string): Loop {
133
+ return {
134
+ read: async () => (await state(sessionID)).loop,
135
+ update: async change => {
136
+ const session = await state(sessionID)
137
+ const before = session.loop.note
138
+ session.loop = change(session.loop)
139
+ const { note } = session.loop
140
+ if (note === before) return
141
+ if (note === null) await ctx.storage.remove(waitKey(sessionID))
142
+ else await ctx.storage.set(waitKey(sessionID), note)
143
+ },
144
+ tell: (row, level) => void tell(sessionID, row, level),
145
+ }
146
+ }
147
+
148
+ function courierOf(sessionID: string): Courier {
149
+ return {
150
+ loop: loopOf(sessionID),
151
+ gauge: keeperOf(sessionID),
152
+ project: () => projectAt(root),
153
+ looks: async () => (await state(sessionID)).looks,
154
+ updateLooks: async change => {
155
+ const session = await state(sessionID)
156
+ session.looks = change(session.looks)
157
+ },
158
+ }
159
+ }
160
+
161
+ // The gauge in the plugin's memory; the history and the base read from the session.
162
+ function keeperOf(sessionID: string): GaugeKeeper {
163
+ return {
164
+ read: async () => (await state(sessionID)).gauge,
165
+ update: async change => {
166
+ const session = await state(sessionID)
167
+ session.gauge = change(session.gauge)
168
+ },
169
+ history: async () => growthIn(await ctx.session.context({ sessionID })),
170
+ base: async () => shiftBase(await projectAt(root), sessionID),
171
+ reading: async () => ({ tokens: (await state(sessionID)).fill, ...(await limits(sessionID)) }),
172
+ }
173
+ }
174
+
175
+ // The model's window and where opencode lets the history go by itself: the window less max(15%, 16K), its default.
176
+ async function limits(sessionID: string): Promise<{ window: number; threshold: number | undefined }> {
177
+ const known = windows.get(sessionID)
178
+ if (known !== undefined) return known
179
+ const info = await ctx.session.get({ sessionID }).catch(() => undefined)
180
+ const models = info?.model === undefined ? [] : ((await ctx.model.list().catch(() => undefined))?.data ?? [])
181
+ const model = models.find(each => each.id === info?.model?.id && each.providerID === info?.model?.providerID)
182
+ const window = model?.limit.input || model?.limit.context || 0
183
+ if (window === 0) return { window: 0, threshold: undefined }
184
+ const buffer =
185
+ typeof ctx.options.buffer === 'number' ? ctx.options.buffer : Math.max(Math.floor(window * 0.15), window >= 32_000 ? 16_000 : 0)
186
+ const found = { window, threshold: window - buffer }
187
+ windows.set(sessionID, found)
188
+
189
+ return found
190
+ }
191
+
192
+ // opencode lets go through a compaction the runner takes once the session is idle; the Hold rides on its hook.
193
+ function letGoOf(sessionID: string): LetGoHarness {
194
+ return {
195
+ fill: async () => (await state(sessionID)).fill,
196
+ letGo: async instructions => {
197
+ const session = await state(sessionID)
198
+ const before = session.fill
199
+ const ended = new Promise<{ text: string } | { error: string }>(done => {
200
+ session.letGo = done
201
+ })
202
+ session.hold = instructions
203
+ try {
204
+ await ctx.session.compact({ sessionID, delivery: 'queue' })
205
+ const end = await ended
206
+ if ('error' in end) return { skip: end.error }
207
+ await ctx.session.wait({ sessionID })
208
+ // The next step measures it; until then the digest and the kept tail stand for it.
209
+ const after = Math.round(end.text.length / CHARS_PER_TOKEN) + Math.min(before ?? 0, KEPT_TOKENS)
210
+
211
+ return { messages: [{ role: 'digest', text: end.text }], before, after }
212
+ } finally {
213
+ session.hold = undefined
214
+ session.letGo = undefined
215
+ }
216
+ },
217
+ continueWith: async prompt => {
218
+ await ctx.session.synthetic({ sessionID, text: prompt, description: CONTINUED })
219
+ },
220
+ }
221
+ }
222
+
223
+ // The doctrine and the session's files, read at the session's first request and again after each let-go.
224
+ await ctx.session.hook('context', async event => {
225
+ if (await child(event.sessionID)) return
226
+ const session = await state(event.sessionID)
227
+ if (session.block === undefined) {
228
+ const project = await projectAt(root)
229
+ const files = renderSessionFiles(await sessionFiles(project))
230
+ session.block = { doctrine: sessionDoctrine(project.settings).doctrine, files }
231
+ }
232
+ event.system.push({ type: 'text', text: session.block.doctrine })
233
+ if (session.block.files !== null) event.system.push({ type: 'text', text: session.block.files })
234
+ })
235
+
236
+ // A compaction the agent asked for holds what its letter says; any other gets the summarizer's instructions.
237
+ await ctx.session.hook('compaction', async event => {
238
+ const hold = sessions.get(event.sessionID)?.hold
239
+ const text = hold ?? unassistedInstructions((await projectAt(root)).settings.files)
240
+ event.system.push({ type: 'text', text })
241
+ })
242
+
243
+ // The owner's message: what changed between turns, a hint, and after a wait the letter go with it.
244
+ await ctx.session.hook('prompt', async event => {
245
+ if (await child(event.sessionID)) return
246
+ const { sessionID } = event
247
+ await countGrowth(keeperOf(sessionID), SOURCES.owner, event.prompt.text.length)
248
+ const told = await atPrompt(courierOf(sessionID), { runStarts: !(await state(sessionID)).busy, owner: true })
249
+ if (told.notes.length === 0) return
250
+ const text = told.notes.join('\n\n')
251
+ await ctx.session.synthetic({ sessionID, text, description: NOTES, resume: false })
252
+ await countGrowth(keeperOf(sessionID), SOURCES.attachments, text.length)
253
+ await told.delivered()
254
+ })
255
+
256
+ // Every note to the agent mid-run goes with a tool's result: what changed in the records around a tool of the agent,
257
+ // the docs after a write, a hint. A subagent's write gets only the docs.
258
+ await ctx.tool.hook('execute.before', async event => {
259
+ if (await child(event.sessionID)) return
260
+ outside.set(event.id, await beforeTool(courierOf(event.sessionID)))
261
+ })
262
+
263
+ await ctx.tool.hook('execute.after', async event => {
264
+ const { sessionID } = event
265
+ const done = event.status === 'completed' ? event.result : null
266
+ const path = done !== null && WRITING.has(event.tool) ? (event.input as { path?: unknown }).path : undefined
267
+ const written = typeof path === 'string' ? resolve(root, path) : undefined
268
+ if (done !== null) await countGrowth(keeperOf(sessionID), event.tool, contentChars(done.content))
269
+ if (await child(sessionID)) {
270
+ if (written !== undefined) await afterWrite(courierOf(await mainOf(sessionID)), written)
271
+ return
272
+ }
273
+ const before = outside.get(event.id) ?? []
274
+ outside.delete(event.id)
275
+ const end = done === null ? null : { own: OURS.has(event.tool), readOnly: READING.has(event.tool), written }
276
+ const added = await afterTool(courierOf(sessionID), before, end)
277
+ if (done === null || added.length === 0) return
278
+ const blocks = added.map(text => ({ type: 'text' as const, text }))
279
+ const content = typeof done.content === 'string' ? [{ type: 'text' as const, text: done.content }] : (done.content ?? [])
280
+ if (event.status === 'completed') event.result = { ...done, content: [...content, ...blocks] }
281
+ })
282
+
283
+ await ctx.tool.transform(tools => {
284
+ for (const tool of start.tools) {
285
+ tools.add({
286
+ name: tool.name,
287
+ description: tool.description,
288
+ input: tool.schema,
289
+ // Called by its name, not through the code-mode tool.
290
+ options: { codemode: false },
291
+ execute: async (input, call) => {
292
+ const done = await tool.run(input as Record<string, unknown>, {
293
+ project: () => projectAt(root),
294
+ sessionId: async () => call.sessionID,
295
+ now: async () => Date.now(),
296
+ subagent: await child(call.sessionID),
297
+ loop: loopOf(call.sessionID),
298
+ // The session's files as this session read them: shift_setup tells which changed since.
299
+ loaded: async () => (await state(call.sessionID)).block?.files ?? null,
300
+ status: () => gaugeStatus(keeperOf(call.sessionID)),
301
+ cannotLetGo: async () => null,
302
+ })
303
+ if ('deny' in done) throw new Error(done.deny)
304
+
305
+ return { content: done.result }
306
+ },
307
+ })
308
+ }
309
+ })
310
+
311
+ await ctx.command.transform(commands => {
312
+ // The owner's word to shift: once the run going on is over, a turn of its own.
313
+ commands.add({
314
+ name: SHIFT_COMMAND,
315
+ description: SHIFT_NOW_DESCRIPTION,
316
+ execute: async ({ sessionID, prompt }) => {
317
+ await ctx.session.synthetic({
318
+ sessionID,
319
+ text: SHIFT_NOW(prompt.text.trim()),
320
+ description: `/${SHIFT_COMMAND}`,
321
+ delivery: 'queue',
322
+ })
323
+ },
324
+ })
325
+ // The letter first; the owner's words typed with the command come after it as their own message.
326
+ commands.add({
327
+ name: RESUME_COMMAND,
328
+ description: RESUME_DESCRIPTION,
329
+ execute: async ({ sessionID, prompt }) => {
330
+ const resumed = await resumeShift(await projectAt(root))
331
+ const words = prompt.text.trim()
332
+ if (resumed.prompt === undefined) return tell(sessionID, resumed.text, 'info')
333
+ await ctx.session.synthetic({ sessionID, text: resumed.prompt, description: resumed.text, resume: words === '' })
334
+ if (words !== '') await ctx.session.prompt({ sessionID, text: words })
335
+ },
336
+ })
337
+ // For the owner: it asks the agent nothing; the agent reads it with the next message.
338
+ commands.add({
339
+ name: TASKS_COMMAND,
340
+ description: TASKS_DESCRIPTION,
341
+ execute: async ({ sessionID }) => tell(sessionID, await tasksView(await projectAt(root)), 'info'),
342
+ })
343
+ })
344
+
345
+ // The runs and the let-gos, by the server's events; a let-go is awaited outside the loop that reads its end.
346
+ async function onEvent(event: { type: string; data?: unknown }): Promise<void> {
347
+ const data = (event.data ?? {}) as Ended & { tokens?: Tokens; reason?: string }
348
+ if (typeof data.sessionID !== 'string' || (await child(data.sessionID))) return
349
+ const session = await state(data.sessionID)
350
+ switch (event.type) {
351
+ case 'session.execution.started':
352
+ session.busy = true
353
+ return
354
+ case 'session.step.ended': {
355
+ const tokens = data.tokens as Tokens | undefined
356
+ if (tokens === undefined) return
357
+ session.fill = (tokens.input ?? 0) + (tokens.cache?.read ?? 0) + (tokens.cache?.write ?? 0)
358
+ const said = ((tokens.output ?? 0) + (tokens.reasoning ?? 0)) * CHARS_PER_TOKEN
359
+ await countGrowth(keeperOf(data.sessionID), SOURCES.responses, said)
360
+ return
361
+ }
362
+ case 'session.compaction.ended':
363
+ session.gauge = letGoGauge(data.reason === 'auto')
364
+ session.fill = undefined
365
+ session.block = undefined
366
+ session.letGo?.({ text: data.text ?? '' })
367
+ return
368
+ case 'session.compaction.failed':
369
+ session.letGo?.({ error: `the compaction failed: ${errorText(data.error)}` })
370
+ return
371
+ // A run is over, whichever way it ended: a shift held in it lets go now, unless the owner interrupted it.
372
+ case 'session.execution.succeeded':
373
+ case 'session.execution.failed':
374
+ case 'session.execution.interrupted': {
375
+ session.busy = false
376
+ const courier = courierOf(data.sessionID)
377
+ await courier.updateLooks(current => (current.running === 0 ? current : { ...current, running: 0 }))
378
+ if (session.loop.pending === null) return
379
+ const aborted = event.type === 'session.execution.interrupted'
380
+ void afterTurn(await projectAt(root), loopOf(data.sessionID), letGoOf(data.sessionID), aborted)
381
+ return
382
+ }
383
+ }
384
+ }
385
+
386
+ void (async () => {
387
+ for await (const event of ctx.event.subscribe()) {
388
+ if (stopped) return
389
+ await onEvent(event as { type: string; data?: unknown }).catch(() => {})
390
+ }
391
+ })()
392
+
393
+ return () => {
394
+ stopped = true
395
+ }
396
+ },
397
+ }
398
+
399
+ export default plugin
400
+
401
+ type Tokens = { input?: number; output?: number; reasoning?: number; cache?: { read?: number; write?: number } }
402
+
403
+ // The waiting letter of a session, in the plugin's storage.
404
+ function waitKey(sessionID: string): string {
405
+ return `wait:${sessionID}`
406
+ }
407
+
408
+ function errorText(error: unknown): string {
409
+ if (typeof error === 'string') return error
410
+ if (typeof error === 'object' && error !== null && 'message' in error) return String(error.message)
411
+
412
+ return JSON.stringify(error)
413
+ }
414
+
415
+ // The growth of the history since the last let-go, counted the way rows are counted as they come.
416
+ function growthIn(messages: readonly unknown[]): Record<string, number> {
417
+ let gauge = FRESH_GAUGE
418
+ for (const message of messages as { type: string; text?: string; content?: unknown }[]) {
419
+ if (message.type === 'compaction') gauge = FRESH_GAUGE
420
+ else if (message.type === 'user') gauge = addGrowth(gauge, SOURCES.owner, message.text?.length ?? 0)
421
+ else if (message.type === 'synthetic') gauge = addGrowth(gauge, SOURCES.attachments, message.text?.length ?? 0)
422
+ else if (message.type === 'assistant' && Array.isArray(message.content)) {
423
+ for (const block of message.content as { type: string; name?: string; state?: { content?: unknown } }[]) {
424
+ if (block.type === 'tool') gauge = addGrowth(gauge, block.name ?? SOURCES.tools, contentChars(block.state?.content))
425
+ else gauge = addGrowth(gauge, SOURCES.responses, contentChars(block))
426
+ }
427
+ }
428
+ }
429
+
430
+ return gauge.growth
431
+ }
package/store.ts CHANGED
@@ -3,7 +3,8 @@ import { access, mkdir, readdir, readFile, rename, stat, writeFile } from 'node:
3
3
  import { dirname } from 'node:path'
4
4
  import { loadProject, type Project, type Store } from './core/index'
5
5
 
6
- // The core's store over node's files and processes: an extension runs inside pi's own node process.
6
+ // The core's store over node's files and processes: pi runs an extension in its own node process, opencode a plugin
7
+ // in its server under Bun.
7
8
  export const nodeStore: Store = {
8
9
  read: path => readFile(path, 'utf8').catch(() => null),
9
10
  list: async (path, kind) => {