@iiiokojiadbi/shift 0.31.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/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
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,6 +1,6 @@
1
1
  {
2
2
  "name": "@iiiokojiadbi/shift",
3
- "version": "0.31.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",
package/server.ts CHANGED
@@ -64,7 +64,7 @@ type Session = {
64
64
  letGo: ((end: { text: string } | { error: string }) => void) | undefined
65
65
  // The doctrine and the session's files as the session started or last let go: a block read anew every
66
66
  // request would show records the history has not reached yet and break the prompt's cache on every write.
67
- block: string[] | undefined
67
+ block: { doctrine: string; files: string | null } | undefined
68
68
  }
69
69
 
70
70
  type Ended = { sessionID: string; text?: string; error?: unknown; tokens?: { input?: number } }
@@ -77,7 +77,7 @@ const plugin: Definition = {
77
77
  if (!start.enabled) return
78
78
 
79
79
  const sessions = new Map<string, Session>()
80
- const children = new Map<string, boolean>()
80
+ const parents = new Map<string, string | null>()
81
81
  const windows = new Map<string, { window: number; threshold: number | undefined }>()
82
82
  const outside = new Map<string, Note[]>()
83
83
  let stopped = false
@@ -104,15 +104,26 @@ const plugin: Definition = {
104
104
 
105
105
  // A subagent runs in a child session: only the main agent shifts and is told.
106
106
  async function child(sessionID: string): Promise<boolean> {
107
- const known = children.get(sessionID)
107
+ return (await parentOf(sessionID)) !== null
108
+ }
109
+
110
+ async function parentOf(sessionID: string): Promise<string | null> {
111
+ const known = parents.get(sessionID)
108
112
  if (known !== undefined) return known
109
113
  const info = await ctx.session.get({ sessionID }).catch(() => undefined)
110
- const parent = info?.parentID !== undefined
111
- children.set(sessionID, parent)
114
+ const parent = info?.parentID ?? null
115
+ parents.set(sessionID, parent)
112
116
 
113
117
  return parent
114
118
  }
115
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
+
116
127
  // A row for the owner: a synthetic message the owner sees by its description; the agent reads it with the next one.
117
128
  async function tell(sessionID: string, row: string, _level: Level): Promise<void> {
118
129
  await ctx.session.synthetic({ sessionID, text: row, description: row, resume: false }).catch(() => {})
@@ -216,9 +227,10 @@ const plugin: Definition = {
216
227
  if (session.block === undefined) {
217
228
  const project = await projectAt(root)
218
229
  const files = renderSessionFiles(await sessionFiles(project))
219
- session.block = [sessionDoctrine(project.settings).doctrine, ...(files === null ? [] : [files])]
230
+ session.block = { doctrine: sessionDoctrine(project.settings).doctrine, files }
220
231
  }
221
- for (const text of session.block) event.system.push({ type: 'text', text })
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 })
222
234
  })
223
235
 
224
236
  // A compaction the agent asked for holds what its letter says; any other gets the summarizer's instructions.
@@ -254,13 +266,14 @@ const plugin: Definition = {
254
266
  const path = done !== null && WRITING.has(event.tool) ? (event.input as { path?: unknown }).path : undefined
255
267
  const written = typeof path === 'string' ? resolve(root, path) : undefined
256
268
  if (done !== null) await countGrowth(keeperOf(sessionID), event.tool, contentChars(done.content))
257
- let added: string[]
258
- if (!(await child(sessionID))) {
259
- const before = outside.get(event.id) ?? []
260
- outside.delete(event.id)
261
- const end = done === null ? null : { own: OURS.has(event.tool), readOnly: READING.has(event.tool), written }
262
- added = await afterTool(courierOf(sessionID), before, end)
263
- } else added = written === undefined ? [] : await afterWrite(courierOf(sessionID), written)
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)
264
277
  if (done === null || added.length === 0) return
265
278
  const blocks = added.map(text => ({ type: 'text' as const, text }))
266
279
  const content = typeof done.content === 'string' ? [{ type: 'text' as const, text: done.content }] : (done.content ?? [])
@@ -282,8 +295,8 @@ const plugin: Definition = {
282
295
  now: async () => Date.now(),
283
296
  subagent: await child(call.sessionID),
284
297
  loop: loopOf(call.sessionID),
285
- // The session's files are read anew before every request, so this copy is never older than them.
286
- loaded: async () => null,
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,
287
300
  status: () => gaugeStatus(keeperOf(call.sessionID)),
288
301
  cannotLetGo: async () => null,
289
302
  })