@iiiokojiadbi/shift 0.36.1 → 0.38.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 +2 -2
- package/core/delivery.ts +73 -28
- package/core/docs.ts +26 -3
- package/core/flows.ts +82 -26
- package/core/hint.ts +42 -42
- package/core/index.ts +1 -0
- package/core/layout.ts +4 -0
- package/core/loop.ts +6 -2
- package/core/markdown.ts +8 -1
- package/core/records.ts +19 -9
- package/core/sizes.ts +77 -0
- package/core/texts/doctrine.ts +21 -34
- package/core/texts/prompts.ts +21 -7
- package/core/texts/tools.ts +16 -5
- package/core/tools.ts +15 -4
- package/core/track.ts +16 -9
- package/core/types.ts +13 -2
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -4,7 +4,7 @@
|
|
|
4
4
|
[](https://www.npmjs.com/package/@iiiokojiadbi/shift)
|
|
5
5
|
[](https://github.com/iiiokojiadbi/shift/blob/main/LICENSE)
|
|
6
6
|
|
|
7
|
-
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
|
|
7
|
+
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, open track items and recent closures back and continues from where it stopped.
|
|
8
8
|
|
|
9
9
|
One package for both harnesses: pi loads `index.ts`, opencode loads `server.ts`.
|
|
10
10
|
|
|
@@ -13,7 +13,7 @@ pi install npm:@iiiokojiadbi/shift
|
|
|
13
13
|
opencode plugin add @iiiokojiadbi/shift
|
|
14
14
|
```
|
|
15
15
|
|
|
16
|
-
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.
|
|
16
|
+
It adds a "Shift" section to the system prompt, the `shift` tool with its companions (`shift_guide`, `shift_status`, `shift_history`, `shift_setup`, `shift_sizes`, `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.
|
|
17
17
|
|
|
18
18
|
The records live in the project's `.shift/` folder and stay out of its git unless `commit = true` in `.shift/settings.toml`.
|
|
19
19
|
|
package/core/delivery.ts
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
// Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
|
|
2
2
|
import { docStamps, followWrite, refreshDocs, settleDocs } from './docs'
|
|
3
|
-
import { type ChangedBy, changedRecords, type Seen } from './flows'
|
|
3
|
+
import { type ChangedBy, type ConfirmedEdit, changedRecords, type Seen } from './flows'
|
|
4
4
|
import type { GaugeKeeper } from './hint'
|
|
5
|
-
import { MOD } from './layout'
|
|
5
|
+
import { DIR, MOD } from './layout'
|
|
6
6
|
import { type Loop, loopHint, loopOffer, waitingNote } from './loop'
|
|
7
7
|
import type { Project } from './project'
|
|
8
|
+
import { noteLinks } from './records'
|
|
9
|
+
import { readTask } from './store'
|
|
8
10
|
import { NOTE_KINDS, type NoteKind } from './texts/prompts'
|
|
9
11
|
import { TOLD } from './texts/rows'
|
|
10
12
|
|
|
@@ -16,19 +18,26 @@ import { TOLD } from './texts/rows'
|
|
|
16
18
|
// 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
19
|
// may be that tool's own. `written`: the files written since the docs were last settled, from the project's root.
|
|
18
20
|
// `docs`: the documents' stamps as the last prompt saw them, so one a script changed is settled like one written.
|
|
19
|
-
export type Looks = {
|
|
21
|
+
export type Looks = {
|
|
22
|
+
seen: Seen | null
|
|
23
|
+
running: number
|
|
24
|
+
pendingLinks?: readonly string[]
|
|
25
|
+
written?: readonly string[]
|
|
26
|
+
docs?: Record<string, string>
|
|
27
|
+
}
|
|
20
28
|
|
|
21
29
|
export const FRESH_LOOKS: Looks = { seen: null, running: 0 }
|
|
22
30
|
|
|
23
|
-
export type
|
|
24
|
-
|
|
25
|
-
gauge: GaugeKeeper
|
|
31
|
+
export type RecordCourier = {
|
|
32
|
+
confirmedEdit?: ConfirmedEdit
|
|
26
33
|
project(): Promise<Project>
|
|
27
34
|
looks(): Promise<Looks>
|
|
28
35
|
// A change applied to the looks as they are then.
|
|
29
36
|
updateLooks(change: (current: Looks) => Looks): Promise<void>
|
|
30
37
|
}
|
|
31
38
|
|
|
39
|
+
export type Courier = RecordCourier & { loop: Loop; gauge: GaugeKeeper }
|
|
40
|
+
|
|
32
41
|
// A note before it goes: its kind and what it says.
|
|
33
42
|
export type Note = { kind: NoteKind; body: string }
|
|
34
43
|
|
|
@@ -36,6 +45,8 @@ export type Note = { kind: NoteKind; body: string }
|
|
|
36
45
|
export type ToolEnd = {
|
|
37
46
|
// The mod's own tool: it writes the records validly, so what it wrote is only remembered.
|
|
38
47
|
own: boolean
|
|
48
|
+
// How the adapter attributes changes without a file receipt.
|
|
49
|
+
recordSource?: ChangedBy
|
|
39
50
|
// A tool that ran read-only changed nothing: no look after it.
|
|
40
51
|
readOnly: boolean
|
|
41
52
|
// The file it wrote, absolute, when it wrote one and did not fail: the docs follow it, settled with the next prompt.
|
|
@@ -47,7 +58,7 @@ export type ToolEnd = {
|
|
|
47
58
|
// Of tools started together only the first looks: the count is claimed in one change, so two never tell the same change.
|
|
48
59
|
// What it saw is kept at once: a tool that throws loses its note, which only a failing harness does, while a look kept
|
|
49
60
|
// open would let a sibling tool take the change as its own or put back what it saw.
|
|
50
|
-
export async function beforeTool(courier:
|
|
61
|
+
export async function beforeTool(courier: RecordCourier): Promise<Note[]> {
|
|
51
62
|
const claim: { first?: boolean } = {}
|
|
52
63
|
await courier.updateLooks(current => {
|
|
53
64
|
claim.first = current.running === 0
|
|
@@ -64,17 +75,23 @@ export async function beforeTool(courier: Courier): Promise<Note[]> {
|
|
|
64
75
|
// After a tool of the main agent: the notes from before it, what it changed in the records, and a hint if the fill
|
|
65
76
|
// calls for one — wrapped, each told to the owner as it goes into the result. A file it wrote is only followed.
|
|
66
77
|
export async function afterTool(courier: Courier, before: readonly Note[], done: ToolEnd | null): Promise<string[]> {
|
|
78
|
+
const notes = await afterToolRecords(courier, before, done)
|
|
79
|
+
if (done === null) return []
|
|
80
|
+
const hint = await loopHint(courier.loop, courier.gauge).catch(() => null)
|
|
81
|
+
if (hint !== null) notes.push({ kind: 'hint', body: hint })
|
|
82
|
+
|
|
83
|
+
return deliver(courier.loop, notes)
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
export async function afterToolRecords(courier: RecordCourier, before: readonly Note[], done: ToolEnd | null): Promise<Note[]> {
|
|
67
87
|
await courier.updateLooks(current => ({ ...current, running: Math.max(0, current.running - 1) }))
|
|
68
88
|
if (done === null) return []
|
|
69
89
|
const notes = [...before]
|
|
70
|
-
const own = done.readOnly ? null : await look(courier, 'agent')
|
|
90
|
+
const own = done.readOnly ? null : await look(courier, done.recordSource ?? 'agent')
|
|
71
91
|
if (own !== null) await remember(courier, own.seen)
|
|
72
92
|
if (own?.body != null && !done.own) notes.push({ kind: 'records', body: own.body })
|
|
73
93
|
if (done.written !== undefined) await follow(courier, done.written)
|
|
74
|
-
|
|
75
|
-
if (hint !== null) notes.push({ kind: 'hint', body: hint })
|
|
76
|
-
|
|
77
|
-
return deliver(courier.loop, notes)
|
|
94
|
+
return notes
|
|
78
95
|
}
|
|
79
96
|
|
|
80
97
|
// A file written by a subagent: the docs follow it, settled with the main agent's next prompt.
|
|
@@ -90,6 +107,24 @@ export async function atPrompt(
|
|
|
90
107
|
courier: Courier,
|
|
91
108
|
{ runStarts, owner }: { runStarts: boolean; owner: boolean },
|
|
92
109
|
): Promise<{ notes: string[]; delivered(): Promise<void> }> {
|
|
110
|
+
const records = await promptRecords(courier, runStarts)
|
|
111
|
+
const notes = records.notes
|
|
112
|
+
const hint = await loopOffer(courier.loop, courier.gauge).catch(() => null)
|
|
113
|
+
if (hint !== null) notes.push({ kind: 'hint', body: hint.text })
|
|
114
|
+
const letter = owner ? await waitingNote(courier.loop) : null
|
|
115
|
+
|
|
116
|
+
return {
|
|
117
|
+
notes: [...notes.map(wrap), ...(letter === null ? [] : [letter.context])],
|
|
118
|
+
delivered: async () => {
|
|
119
|
+
await records.delivered()
|
|
120
|
+
await hint?.take()
|
|
121
|
+
for (const note of notes) courier.loop.tell(TOLD(note.body), 'info')
|
|
122
|
+
await letter?.delivered()
|
|
123
|
+
},
|
|
124
|
+
}
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
export async function promptRecords(courier: RecordCourier, runStarts: boolean) {
|
|
93
128
|
if (runStarts) await courier.updateLooks(current => ({ ...current, running: 0 }))
|
|
94
129
|
const notes: Note[] = []
|
|
95
130
|
const { running } = await courier.looks()
|
|
@@ -97,16 +132,22 @@ export async function atPrompt(
|
|
|
97
132
|
const outside = running === 0 ? await look(courier, 'other') : null
|
|
98
133
|
if (outside?.body === null) await remember(courier, outside.seen)
|
|
99
134
|
if (outside?.body != null) notes.push({ kind: 'records', body: outside.body })
|
|
135
|
+
const pending = running === 0 ? ((await courier.looks()).pendingLinks ?? []) : []
|
|
136
|
+
if (pending.length) {
|
|
137
|
+
const project = await courier.project()
|
|
138
|
+
const problems = await Promise.all(pending.map(async name => noteLinks(await readTask(project.store, `${project.root}/${DIR}`, name))))
|
|
139
|
+
const body = problems.filter(Boolean).join('\n')
|
|
140
|
+
if (body) notes.push({ kind: 'records', body })
|
|
141
|
+
else await courier.updateLooks(now => ({ ...now, pendingLinks: now.pendingLinks?.filter(name => !pending.includes(name)) }))
|
|
142
|
+
}
|
|
100
143
|
if (running === 0) await scripted(courier)
|
|
101
144
|
const docs = running === 0 ? await settle(courier) : null
|
|
102
145
|
if (docs !== null) notes.push({ kind: 'docs', body: docs.body })
|
|
103
|
-
const hint = await loopOffer(courier.loop, courier.gauge).catch(() => null)
|
|
104
|
-
if (hint !== null) notes.push({ kind: 'hint', body: hint.text })
|
|
105
|
-
const letter = owner ? await waitingNote(courier.loop) : null
|
|
106
|
-
|
|
107
146
|
return {
|
|
108
|
-
notes
|
|
147
|
+
notes,
|
|
109
148
|
delivered: async () => {
|
|
149
|
+
if (pending.length)
|
|
150
|
+
await courier.updateLooks(now => ({ ...now, pendingLinks: now.pendingLinks?.filter(name => !pending.includes(name)) }))
|
|
110
151
|
// Kept unless a look since has kept newer records: putting back the older ones would tell their change again.
|
|
111
152
|
if (outside?.body != null)
|
|
112
153
|
await courier.updateLooks(current => (same(current.seen, seen) ? { ...current, seen: outside.seen } : current))
|
|
@@ -116,9 +157,6 @@ export async function atPrompt(
|
|
|
116
157
|
await forget(courier, settled)
|
|
117
158
|
await restamp(courier, settled)
|
|
118
159
|
}
|
|
119
|
-
await hint?.take()
|
|
120
|
-
for (const note of notes) courier.loop.tell(TOLD(note.body), 'info')
|
|
121
|
-
await letter?.delivered()
|
|
122
160
|
},
|
|
123
161
|
}
|
|
124
162
|
}
|
|
@@ -130,20 +168,25 @@ export async function runEnded(courier: Courier): Promise<void> {
|
|
|
130
168
|
|
|
131
169
|
// The records changed since the last look and what they are now, kept by `remember`; the first look finds nothing to
|
|
132
170
|
// tell. A look that fails says nothing: it must never stand between the agent and its tool.
|
|
133
|
-
async function look(courier:
|
|
171
|
+
async function look(courier: RecordCourier, by: ChangedBy): Promise<{ body: string | null; seen: Seen } | null> {
|
|
134
172
|
try {
|
|
135
|
-
|
|
173
|
+
const tasks = new Set<string>()
|
|
174
|
+
const result = await changedRecords(await courier.project(), (await courier.looks()).seen, by, courier.confirmedEdit, name =>
|
|
175
|
+
tasks.add(name),
|
|
176
|
+
)
|
|
177
|
+
if (tasks.size) await courier.updateLooks(now => ({ ...now, pendingLinks: [...new Set([...(now.pendingLinks ?? []), ...tasks])] }))
|
|
178
|
+
return result
|
|
136
179
|
} catch {
|
|
137
180
|
return null
|
|
138
181
|
}
|
|
139
182
|
}
|
|
140
183
|
|
|
141
|
-
async function remember(courier:
|
|
184
|
+
async function remember(courier: RecordCourier, seen: Seen): Promise<void> {
|
|
142
185
|
await courier.updateLooks(current => ({ ...current, seen }))
|
|
143
186
|
}
|
|
144
187
|
|
|
145
188
|
// A written file the docs follow is remembered for the next prompt; the map follows a document at once.
|
|
146
|
-
async function follow(courier:
|
|
189
|
+
async function follow(courier: RecordCourier, file: string): Promise<void> {
|
|
147
190
|
const path = await followWrite(await courier.project(), file).catch(() => null)
|
|
148
191
|
if (path === null) return
|
|
149
192
|
await courier.updateLooks(current =>
|
|
@@ -153,7 +196,9 @@ async function follow(courier: Courier, file: string): Promise<void> {
|
|
|
153
196
|
|
|
154
197
|
// The files written since the last settling, settled now and forgotten once told; a settling that fails says nothing.
|
|
155
198
|
// Nothing to tell is settled and forgotten at once: an adapter calls `delivered` only when a note goes.
|
|
156
|
-
async function settle(
|
|
199
|
+
async function settle(
|
|
200
|
+
courier: RecordCourier,
|
|
201
|
+
): Promise<{ body: string; paths: readonly string[]; write(): Promise<readonly string[]> } | null> {
|
|
157
202
|
const written = (await courier.looks()).written ?? []
|
|
158
203
|
if (written.length === 0) return null
|
|
159
204
|
const settled = await settleDocs(await courier.project(), written).catch(() => null)
|
|
@@ -168,7 +213,7 @@ async function settle(courier: Courier): Promise<{ body: string; paths: readonly
|
|
|
168
213
|
|
|
169
214
|
// The documents changed since the last prompt that no write of the agent's tools named — a script, a command — are
|
|
170
215
|
// taken as written, and the map follows them. The first look only remembers: there is nothing to compare with yet.
|
|
171
|
-
async function scripted(courier:
|
|
216
|
+
async function scripted(courier: RecordCourier): Promise<void> {
|
|
172
217
|
try {
|
|
173
218
|
const project = await courier.project()
|
|
174
219
|
const now = await docStamps(project)
|
|
@@ -190,7 +235,7 @@ async function scripted(courier: Courier): Promise<void> {
|
|
|
190
235
|
}
|
|
191
236
|
|
|
192
237
|
// A document settled is remembered as it is now, the toc the mod wrote included, so it is not taken for a script's change.
|
|
193
|
-
async function restamp(courier:
|
|
238
|
+
async function restamp(courier: RecordCourier, paths: readonly string[]): Promise<void> {
|
|
194
239
|
if (paths.length === 0) return
|
|
195
240
|
const now = await docStamps(await courier.project()).catch(() => null)
|
|
196
241
|
if (now === null) return
|
|
@@ -210,7 +255,7 @@ function same(a: Seen | null, b: Seen | null): boolean {
|
|
|
210
255
|
return JSON.stringify(a) === JSON.stringify(b)
|
|
211
256
|
}
|
|
212
257
|
|
|
213
|
-
async function forget(courier:
|
|
258
|
+
async function forget(courier: RecordCourier, paths: readonly string[]): Promise<void> {
|
|
214
259
|
await courier.updateLooks(current => ({ ...current, written: (current.written ?? []).filter(path => !paths.includes(path)) }))
|
|
215
260
|
}
|
|
216
261
|
|
package/core/docs.ts
CHANGED
|
@@ -400,8 +400,15 @@ export function withMap(shift: string | null, map: string): string {
|
|
|
400
400
|
if (shift === null) {
|
|
401
401
|
return `# Shift\n\nHow this project keeps its knowledge. The rules are written on the owner's word; the map below is the mod's.\n\n${map}\n`
|
|
402
402
|
}
|
|
403
|
-
// The markers on lines of their own, outside code fences: a sentence or an example that names them is the owner's.
|
|
404
403
|
const lines = shift.split('\n')
|
|
404
|
+
const { start, end } = mapBounds(lines)
|
|
405
|
+
if (end === -1) return `${shift.trimEnd()}\n\n${map}\n`
|
|
406
|
+
|
|
407
|
+
return [...lines.slice(0, start), map, ...lines.slice(end + 1)].join('\n')
|
|
408
|
+
}
|
|
409
|
+
|
|
410
|
+
export function mapBounds(lines: readonly string[]) {
|
|
411
|
+
// The markers on lines of their own, outside code fences: a sentence or an example that names them is the owner's.
|
|
405
412
|
// The opener as any version of the mod wrote it: one comment, the whole line, that starts as the mod's does.
|
|
406
413
|
const opener = `${MAP_START.slice(0, MAP_START.indexOf(' — '))} — `
|
|
407
414
|
const start = lineOutside(lines, line => {
|
|
@@ -409,9 +416,25 @@ export function withMap(shift: string | null, map: string): string {
|
|
|
409
416
|
return trimmed.startsWith(opener) && trimmed.indexOf('-->') === trimmed.length - 3
|
|
410
417
|
})
|
|
411
418
|
const end = start === -1 ? -1 : lineOutside(lines, line => line.trim() === MAP_END, start + 1)
|
|
412
|
-
|
|
419
|
+
return { start, end }
|
|
420
|
+
}
|
|
413
421
|
|
|
414
|
-
|
|
422
|
+
// Group the rendered map by its actual entries, including the sections and pins under each.
|
|
423
|
+
// A reduced map uses folder entries. Rules and map-level notices can be refreshed by path.
|
|
424
|
+
export function mapParts(text: string) {
|
|
425
|
+
const lines = text.split('\n')
|
|
426
|
+
const { start, end } = mapBounds(lines)
|
|
427
|
+
const entries = new Map<string, string>()
|
|
428
|
+
if (end < 0) return { other: '', entries }
|
|
429
|
+
const other: string[] = []
|
|
430
|
+
let key: string | undefined
|
|
431
|
+
for (const line of lines.slice(start + 1, end)) {
|
|
432
|
+
if (!line.trim() || line.startsWith('### ')) continue
|
|
433
|
+
if (!line.startsWith(' ')) key = /^- `([^`]+)`/.exec(line)?.[1]
|
|
434
|
+
if (!key) other.push(line)
|
|
435
|
+
else entries.set(key, entries.has(key) ? `${entries.get(key)}\n${line}` : line)
|
|
436
|
+
}
|
|
437
|
+
return { other: other.join('\n'), entries }
|
|
415
438
|
}
|
|
416
439
|
|
|
417
440
|
// Every document read once: its toc rewritten when the settings ask for one, then the map in SHIFT.md written when it
|
package/core/flows.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
// Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
|
|
2
2
|
import { OUTCOME, readAbout, renderAbout, shiftFill } from './about'
|
|
3
3
|
import { addToIndex, checkArchive, indexLine } from './archive'
|
|
4
|
-
import { docsReport, refreshDocs } from './docs'
|
|
4
|
+
import { docsReport, isDoc, refreshDocs, withMap, withToc } from './docs'
|
|
5
5
|
import { renderHistory, renderSummary, segment, shiftDir } from './history'
|
|
6
6
|
import {
|
|
7
7
|
ARCHIVE,
|
|
@@ -25,7 +25,7 @@ import {
|
|
|
25
25
|
TRACK_TOOL,
|
|
26
26
|
taskFile,
|
|
27
27
|
} from './layout'
|
|
28
|
-
import { formatItem, formatK, itemsOf, sections } from './markdown'
|
|
28
|
+
import { formatItem, formatK, itemsOf, sections, trackTimes } from './markdown'
|
|
29
29
|
import { basename, dirname, join, resolvePath } from './paths'
|
|
30
30
|
import type { Project } from './project'
|
|
31
31
|
import { checkLetter, checkTask, checkWork, checkWritten, listedTasks } from './records'
|
|
@@ -44,7 +44,19 @@ import {
|
|
|
44
44
|
} from './texts/prompts'
|
|
45
45
|
import { CONTINUING, NOT_MADE, renderTasks, type TaskView, UNSETTLED, WAITING } from './texts/rows'
|
|
46
46
|
import { numberTracks } from './track'
|
|
47
|
-
import type {
|
|
47
|
+
import type {
|
|
48
|
+
ArchiveInput,
|
|
49
|
+
HandedBack,
|
|
50
|
+
OpenInput,
|
|
51
|
+
PendingShift,
|
|
52
|
+
SessionFile,
|
|
53
|
+
Settled,
|
|
54
|
+
ShiftInput,
|
|
55
|
+
Stuck,
|
|
56
|
+
TaskFiles,
|
|
57
|
+
WaitNote,
|
|
58
|
+
Work,
|
|
59
|
+
} from './types'
|
|
48
60
|
|
|
49
61
|
// The flows that do not depend on the harness: an adapter hands them the loaded project and what only it knows.
|
|
50
62
|
|
|
@@ -60,15 +72,30 @@ export type ChangedBy = 'agent' | 'other'
|
|
|
60
72
|
|
|
61
73
|
// The records changed since the mod last looked, each checked by the checks of its file, so what the shift would refuse
|
|
62
74
|
// is told as it is written, not hundreds of K later. The agent's own change is told only when broken; someone else's
|
|
63
|
-
// is told always, so the agent reads it before writing over it. The first look only remembers
|
|
64
|
-
|
|
65
|
-
|
|
75
|
+
// is told always, so the agent reads it before writing over it. The first look only remembers. Generated map and toc changes have their own delivery slot.
|
|
76
|
+
export type ConfirmedEdit = (path: string, current: string | null, previous: string | undefined) => boolean
|
|
77
|
+
|
|
78
|
+
export function recordFingerprint(project: Project, path: string, text: string): string {
|
|
79
|
+
let observed = text
|
|
80
|
+
if (path === project.settings.files.shift) observed = withMap(text, '').trim()
|
|
81
|
+
else if (project.settings.docs.toc && isDoc(path, project.settings.docs.dirs)) observed = withToc(text) ?? text
|
|
82
|
+
return String(fingerprint(observed))
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
export async function changedRecords(
|
|
86
|
+
project: Project,
|
|
87
|
+
seen: Seen | null,
|
|
88
|
+
by: ChangedBy,
|
|
89
|
+
confirmed?: ConfirmedEdit,
|
|
90
|
+
deferLinks?: (name: string) => void,
|
|
91
|
+
): Promise<{ seen: Seen; body: string | null }> {
|
|
66
92
|
if (!project.settings.enabled) return { seen: seen ?? {}, body: null }
|
|
67
93
|
// A new stamp alone is not a change: a file rewritten with the same text, or edited and put back, says nothing.
|
|
68
|
-
const now: Seen =
|
|
94
|
+
const now: Seen = Object.create(null)
|
|
69
95
|
const changed: string[] = []
|
|
96
|
+
const external = new Set<string>()
|
|
70
97
|
for (const [path, stamp] of Object.entries(await recordStamps(project))) {
|
|
71
|
-
const was = seen
|
|
98
|
+
const was = seen && Object.hasOwn(seen, path) ? (seen[path] ?? '') : ''
|
|
72
99
|
const at = was.lastIndexOf('#')
|
|
73
100
|
if (at !== -1 && was.slice(0, at) === stamp) {
|
|
74
101
|
now[path] = was
|
|
@@ -76,19 +103,33 @@ export async function changedRecords(project: Project, seen: Seen | null, by: Ch
|
|
|
76
103
|
}
|
|
77
104
|
const text = await project.store.read(`${project.root}/${path}`)
|
|
78
105
|
if (text === null) continue
|
|
79
|
-
const hash =
|
|
106
|
+
const hash = recordFingerprint(project, path, text)
|
|
80
107
|
now[path] = `${stamp}#${hash}`
|
|
81
|
-
|
|
108
|
+
const generated = !was && path === project.settings.files.shift && withMap(text, '').trim() === withMap(null, '').trim()
|
|
109
|
+
if (seen !== null && was.slice(at + 1) !== hash && !generated) {
|
|
110
|
+
changed.push(path)
|
|
111
|
+
if (by === 'other' && !confirmed?.(path, text, was ? was.slice(at + 1) : undefined)) external.add(path)
|
|
112
|
+
}
|
|
113
|
+
}
|
|
114
|
+
const lines: string[] = []
|
|
115
|
+
if (by === 'other' && seen) {
|
|
116
|
+
for (const path of Object.keys(seen))
|
|
117
|
+
if (
|
|
118
|
+
!(path in now) &&
|
|
119
|
+
!(await project.store.exists(`${project.root}/${path}`)) &&
|
|
120
|
+
!confirmed?.(path, null, seen[path]?.split('#').pop())
|
|
121
|
+
)
|
|
122
|
+
lines.push(`\`${path}\` was removed outside your tools.`)
|
|
82
123
|
}
|
|
83
|
-
if (changed.length === 0) return { seen: now, body: null }
|
|
124
|
+
if (changed.length === 0) return { seen: now, body: lines.join('\n') || null }
|
|
84
125
|
|
|
85
126
|
const work = await readRecords(project)
|
|
86
|
-
const lines: string[] = []
|
|
87
127
|
let broken = false
|
|
88
128
|
for (const path of changed) {
|
|
89
|
-
const problem = path === LETTER ? await letterProblem(project) : work === null ? null : checkWritten(path, work, project)
|
|
129
|
+
const problem = path === LETTER ? await letterProblem(project) : work === null ? null : checkWritten(path, work, project, deferLinks)
|
|
90
130
|
broken ||= problem !== null
|
|
91
|
-
if (
|
|
131
|
+
if (external.has(path))
|
|
132
|
+
lines.push(`\`${path}\` changed outside your tools — by the owner or another session: read it before you write it.`)
|
|
92
133
|
if (problem !== null) lines.push(`\`${path}\`: ${problem}`)
|
|
93
134
|
}
|
|
94
135
|
if (broken) lines.push('The shift refuses until they are fixed; if you are still writing them, go on.')
|
|
@@ -102,15 +143,22 @@ async function recordStamps({ store, root, settings }: Project): Promise<Seen> {
|
|
|
102
143
|
const stamped = async (dir: string, only?: (name: string) => boolean): Promise<Seen> =>
|
|
103
144
|
Object.fromEntries(
|
|
104
145
|
Object.entries(await store.stamps(join(root, dir)))
|
|
105
|
-
.filter(([name]) => (name.endsWith('.md')
|
|
146
|
+
.filter(([name]) => (only ? only(name) : name.endsWith('.md')))
|
|
106
147
|
.map(([name, stamp]) => [join(dir, name), stamp]),
|
|
107
148
|
)
|
|
108
|
-
const own = new Set([
|
|
149
|
+
const own = new Set([
|
|
150
|
+
BOARD,
|
|
151
|
+
TASK_LIST,
|
|
152
|
+
LETTER,
|
|
153
|
+
SETTINGS,
|
|
154
|
+
settings.files.owner,
|
|
155
|
+
settings.files.glossary,
|
|
156
|
+
settings.files.shift,
|
|
157
|
+
...settings.files.always,
|
|
158
|
+
])
|
|
109
159
|
const tasks = await store.list(`${root}/${TASKS}`, 'dir')
|
|
110
160
|
const parts = await Promise.all([
|
|
111
|
-
...[...new Set([
|
|
112
|
-
stamped(dir, name => own.has(join(dir, name))),
|
|
113
|
-
),
|
|
161
|
+
...[...new Set([...own].map(dirname))].map(dir => stamped(dir, name => own.has(join(dir, name)))),
|
|
114
162
|
...tasks.flatMap(name => [
|
|
115
163
|
stamped(`${TASKS}/${name}`, file => file === NAMES.task || file === NAMES.track),
|
|
116
164
|
stamped(`${TASKS}/${name}/${NAMES.notes}`),
|
|
@@ -229,17 +277,22 @@ function knowledgeText(work: Work): string {
|
|
|
229
277
|
// Moves a finished or dropped task's folder to the archive and adds its line to the index.
|
|
230
278
|
// A task opened valid by construction: task.md by its sections, track.md with its first items, and its line with the
|
|
231
279
|
// links in TASKS.md — all checked before anything is written, so a refusal leaves the records as they were.
|
|
232
|
-
export async function openTask(
|
|
280
|
+
export async function openTask(
|
|
281
|
+
project: Project,
|
|
282
|
+
input: OpenInput,
|
|
283
|
+
now: number | null = null,
|
|
284
|
+
): Promise<{ deny: string } | { result: string }> {
|
|
233
285
|
const { store, root } = project
|
|
234
286
|
const folder = `${root}/${TASKS}/${input.name}`
|
|
235
287
|
if (await store.exists(folder)) return { deny: `${TASKS}/${input.name}/ already exists: set its status with ${TRACK_TOOL}.` }
|
|
236
288
|
const archived = await store.list(`${root}/${ARCHIVE}`, 'dir')
|
|
237
289
|
if (archived.includes(input.name))
|
|
238
290
|
return { deny: `${input.name} is archived: open a task under another name with continues: ${input.name}.` }
|
|
291
|
+
const initial = input.items.map((item, n) => formatItem('open', n + 1, item.name, item.note))
|
|
239
292
|
const task: TaskFiles = {
|
|
240
293
|
name: input.name,
|
|
241
294
|
task: renderTask(input),
|
|
242
|
-
track:
|
|
295
|
+
track: initial.map(line => `${line + trackTimes(now, null)}\n`).join(''),
|
|
243
296
|
notes: [],
|
|
244
297
|
}
|
|
245
298
|
const listPath = `${root}/${TASK_LIST}`
|
|
@@ -252,7 +305,7 @@ export async function openTask(project: Project, input: OpenInput): Promise<{ de
|
|
|
252
305
|
await store.write(`${folder}/${NAMES.track}`, task.track ?? '')
|
|
253
306
|
await store.write(listPath, list)
|
|
254
307
|
|
|
255
|
-
return { result: OPENED(input.name, formatTaskLine(input.status, input.name, input.name, input.about),
|
|
308
|
+
return { result: OPENED(input.name, formatTaskLine(input.status, input.name, input.name, input.about), initial.join('\n')) }
|
|
256
309
|
}
|
|
257
310
|
|
|
258
311
|
function renderTask(input: OpenInput): string {
|
|
@@ -385,10 +438,11 @@ async function recordFailure(project: Project, shift: PendingShift, about: strin
|
|
|
385
438
|
|
|
386
439
|
export type LetGo = {
|
|
387
440
|
shift: PendingShift
|
|
441
|
+
parkWait?(note: WaitNote): Promise<void>
|
|
388
442
|
// What the history was let go into, as the harness gives it back.
|
|
389
443
|
messages: readonly { role: string; text: string }[]
|
|
390
444
|
before: number | undefined
|
|
391
|
-
after: number
|
|
445
|
+
after: number | undefined
|
|
392
446
|
}
|
|
393
447
|
|
|
394
448
|
// After the let-go: the summary and the outcome on disk, then continue or wait, as the agent asked. `back` is what
|
|
@@ -398,7 +452,7 @@ export async function settleShift(project: Project, letGo: LetGo, back?: HandedB
|
|
|
398
452
|
const { shift, before, after } = letGo
|
|
399
453
|
const summary = renderSummary(letGo.messages)
|
|
400
454
|
await store.write(`${shift.dir}/${NAMES.summary}`, summary)
|
|
401
|
-
const shrank = `${formatK(before
|
|
455
|
+
const shrank = `${before === undefined ? '?' : formatK(before)} → ${after === undefined ? '?' : formatK(after)}`
|
|
402
456
|
const outcome = (result: string) =>
|
|
403
457
|
store.write(
|
|
404
458
|
`${shift.dir}/${NAMES.about}`,
|
|
@@ -415,8 +469,10 @@ export async function settleShift(project: Project, letGo: LetGo, back?: HandedB
|
|
|
415
469
|
return { after: 'continue', prompt, note: { context: prompt, dir: shift.dir, files }, row: CONTINUING(name, shrank, shift.dir) }
|
|
416
470
|
}
|
|
417
471
|
|
|
418
|
-
await outcome(OUTCOME.waiting(shrank, 'waiting for the owner'))
|
|
419
472
|
const note = { context: waitContext(shift.letter, handed), dir: shift.dir, files }
|
|
473
|
+
// Publish the waiting outcome only once a harness with durable thread history has parked the letter.
|
|
474
|
+
await letGo.parkWait?.(note)
|
|
475
|
+
await outcome(OUTCOME.waiting(shrank, 'waiting for the owner'))
|
|
420
476
|
|
|
421
477
|
return { after: 'wait', note, row: WAITING(name, shrank) }
|
|
422
478
|
}
|
|
@@ -461,7 +517,7 @@ export async function sessionFiles(project: Project, { refresh = true }: { refre
|
|
|
461
517
|
const { store, root, settings } = project
|
|
462
518
|
if (!settings.enabled || (await staleLayout(project)) !== null) return []
|
|
463
519
|
if (refresh) await refreshDocs(project)
|
|
464
|
-
const paths = [settings.files.shift, settings.files.owner, settings.files.glossary, TASK_LIST, ...settings.files.always]
|
|
520
|
+
const paths = [...new Set([settings.files.shift, settings.files.owner, settings.files.glossary, TASK_LIST, ...settings.files.always])]
|
|
465
521
|
const files = await Promise.all(paths.map(async path => ({ path, text: await store.read(`${root}/${path}`) })))
|
|
466
522
|
|
|
467
523
|
return files.filter((file): file is SessionFile => file.text !== null)
|
package/core/hint.ts
CHANGED
|
@@ -1,22 +1,28 @@
|
|
|
1
1
|
// Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
|
|
2
2
|
import { BOARD, TASK_LIST, TASKS, TOOL } from './layout'
|
|
3
3
|
import { formatK } from './markdown'
|
|
4
|
-
import type { Gauge, Reading } from './types'
|
|
4
|
+
import type { Gauge, HintTargets, Reading } from './types'
|
|
5
5
|
|
|
6
|
-
//
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
return
|
|
6
|
+
// A stretch needs enough new work to justify the cost of a voluntary shift.
|
|
7
|
+
function nextSoft(base: number, tokens: number, limit: number, targets: HintTargets): number | null {
|
|
8
|
+
if (targets.soft === null) return null
|
|
9
|
+
const at = Math.max(tokens, targets.soft, base + 200_000)
|
|
10
|
+
return at + Math.round(limit * 0.1) <= targets.final ? at : null
|
|
11
11
|
}
|
|
12
12
|
|
|
13
|
-
// The final hint comes at 80% of the limit, with room left to finish a stage, and again every 5% after it.
|
|
14
13
|
export function finalAt(limit: number): number {
|
|
15
|
-
return Math.round(limit * 0.
|
|
14
|
+
return Math.round(limit * 0.84)
|
|
16
15
|
}
|
|
17
16
|
|
|
18
|
-
|
|
19
|
-
return Math.round(limit
|
|
17
|
+
function hintTargets(limit: number, overrides?: HintTargets): HintTargets {
|
|
18
|
+
return overrides ?? { soft: Math.round(limit * 0.6), final: finalAt(limit) }
|
|
19
|
+
}
|
|
20
|
+
|
|
21
|
+
// Give a new stretch some room even when the previous shift left a full history.
|
|
22
|
+
function firstFinal(base: number, limit: number, final: number): number {
|
|
23
|
+
if (base < final) return final
|
|
24
|
+
const growth = Math.min(limit * 0.05, (limit - base) / 2)
|
|
25
|
+
return base + Math.max(1, Math.round(growth))
|
|
20
26
|
}
|
|
21
27
|
|
|
22
28
|
export const FRESH_GAUGE: Gauge = { base: null, hinted: null, unassisted: false, growth: {}, whole: false }
|
|
@@ -35,36 +41,33 @@ function rebased(gauge: Gauge, tokens: number): Gauge {
|
|
|
35
41
|
return gauge.base !== null && tokens < (gauge.hinted ?? gauge.base) ? { ...gauge, base: tokens, hinted: null, growth: {} } : gauge
|
|
36
42
|
}
|
|
37
43
|
|
|
38
|
-
//
|
|
39
|
-
export function shiftHint(
|
|
44
|
+
// A reading that crosses both milestones gives only the final hint.
|
|
45
|
+
export function shiftHint(
|
|
46
|
+
current: Gauge,
|
|
47
|
+
{ tokens, window, threshold, hintTargets: overrides }: Reading,
|
|
48
|
+
): { gauge: Gauge; text: string | null } {
|
|
40
49
|
if (tokens === undefined) return { gauge: current, text: null }
|
|
41
50
|
const gauge = rebased(current, tokens)
|
|
42
51
|
if (gauge.base === null) return { gauge: { ...gauge, base: tokens, unassisted: false }, text: gauge.unassisted ? UNASSISTED_HINT : null }
|
|
43
52
|
|
|
44
53
|
const limit = threshold ?? window
|
|
45
|
-
const
|
|
46
|
-
const grown = tokens - gauge.base
|
|
47
|
-
const since = tokens - (gauge.hinted ?? gauge.base)
|
|
54
|
+
const targets = hintTargets(limit, overrides)
|
|
48
55
|
const hinted = { ...gauge, hinted: tokens }
|
|
49
|
-
if (
|
|
56
|
+
if (tokens >= firstFinal(gauge.base, limit, targets.final) && (gauge.hinted === null || gauge.hinted < targets.final))
|
|
57
|
+
return { gauge: hinted, text: finalHint(tokens, limit, gauge.growth) }
|
|
50
58
|
|
|
51
|
-
if (tokens
|
|
52
|
-
|
|
53
|
-
return isFirst || since >= finalStep(limit) ? { gauge: hinted, text: finalHint(tokens, limit, gauge.growth) } : { gauge, text: null }
|
|
54
|
-
}
|
|
55
|
-
// No soft hint right before the final one: it would come twice in a row.
|
|
56
|
-
const step = softStep(limit)
|
|
57
|
-
if (since >= step && tokens + step / 2 <= final) return { gauge: hinted, text: softHint(grown, gauge.growth) }
|
|
59
|
+
if (gauge.hinted === null && nextSoft(gauge.base, tokens, limit, targets) === tokens)
|
|
60
|
+
return { gauge: hinted, text: softHint(tokens - gauge.base, gauge.growth) }
|
|
58
61
|
|
|
59
62
|
return { gauge, text: null }
|
|
60
63
|
}
|
|
61
64
|
|
|
62
65
|
function softHint(grown: number, growth: Record<string, number>): string {
|
|
63
|
-
return `Shift hint: the history has grown by ${formatK(grown)} since the last shift.${sources(growth)} This is not an alarm — running out of room gets a hint of its own. If you are at a stage boundary and the stretch's history is not needed whole any more, shift;
|
|
66
|
+
return `Shift hint: the history has grown by ${formatK(grown)} since the last shift.${sources(growth)} This is not an alarm — running out of room gets a hint of its own. If you are at a stage boundary and the stretch's history is not needed whole any more, shift; otherwise keep working.`
|
|
64
67
|
}
|
|
65
68
|
|
|
66
69
|
function finalHint(tokens: number, limit: number, growth: Record<string, number>): string {
|
|
67
|
-
return `Shift hint: ${formatK(tokens)} of ${formatK(limit)} used — close to the point where the harness lets the history go by itself, without your letter.${sources(growth)} Shift
|
|
70
|
+
return `Shift hint: ${formatK(tokens)} of ${formatK(limit)} used — close to the point where the harness lets the history go by itself, without your letter.${sources(growth)} Shift now. Check the records, write your letter and call \`${TOOL}\`.`
|
|
68
71
|
}
|
|
69
72
|
|
|
70
73
|
// Token counts per row are not known, so the growth is counted in characters and named by shares.
|
|
@@ -134,20 +137,21 @@ export function growthOf(messages: readonly { role: string; content: unknown }[]
|
|
|
134
137
|
}
|
|
135
138
|
|
|
136
139
|
// What the status tool answers: the fill, the limit, the growth since the last shift, when the next hints come, and what grew.
|
|
137
|
-
export function renderStatus(current: Gauge, { tokens, window, threshold }: Reading): string {
|
|
140
|
+
export function renderStatus(current: Gauge, { tokens, window, threshold, hintTargets: overrides }: Reading): string {
|
|
138
141
|
if (tokens === undefined) return 'No reading yet: the first response since the last let-go has not come back.'
|
|
139
142
|
const gauge = rebased(current, tokens)
|
|
140
143
|
const limit = threshold ?? window
|
|
141
|
-
const
|
|
144
|
+
const targets = hintTargets(limit, overrides)
|
|
145
|
+
const base = gauge.base ?? tokens
|
|
146
|
+
const final = firstFinal(base, limit, targets.final)
|
|
142
147
|
const lines = [
|
|
143
|
-
`Used: ${formatK(tokens)} of ${formatK(window)} window; ${threshold === undefined ? 'the
|
|
148
|
+
`Used: ${formatK(tokens)} of ${formatK(window)} window; ${threshold === undefined ? 'the automatic threshold is unknown' : `the harness lets the history go by itself at ${formatK(threshold)}`}.`,
|
|
144
149
|
]
|
|
145
150
|
if (gauge.base !== null) lines.push(`Since the last shift: +${formatK(Math.max(0, tokens - gauge.base))}.`)
|
|
146
|
-
if (tokens >= final) lines.push(`Past the final hint at ${formatK(final)}: shift
|
|
151
|
+
if (tokens >= final) lines.push(`Past the final hint at ${formatK(final)}: shift now.`)
|
|
147
152
|
else {
|
|
148
|
-
const
|
|
149
|
-
const
|
|
150
|
-
const next = soft + step / 2 <= final ? `next soft hint at ${formatK(soft)}` : 'no soft hint before the final'
|
|
153
|
+
const soft = gauge.hinted === null ? nextSoft(base, tokens, limit, targets) : null
|
|
154
|
+
const next = soft === null ? 'no soft hint before the final' : `next soft hint at ${formatK(soft)}`
|
|
151
155
|
lines.push(`Hints: ${next}; final at ${formatK(final)}.`)
|
|
152
156
|
}
|
|
153
157
|
const shares = growthShares(gauge.growth)
|
|
@@ -282,16 +286,12 @@ async function restore(keeper: GaugeKeeper): Promise<void> {
|
|
|
282
286
|
})
|
|
283
287
|
}
|
|
284
288
|
|
|
285
|
-
//
|
|
286
|
-
|
|
287
|
-
// placed below the real one would repeat it at once.
|
|
288
|
-
export function lastStep(base: number | null, { tokens, window, threshold }: Reading): number | null {
|
|
289
|
+
// On restore, infer the milestones already passed in this stretch.
|
|
290
|
+
export function lastStep(base: number | null, { tokens, window, threshold, hintTargets: overrides }: Reading): number | null {
|
|
289
291
|
if (base === null || tokens === undefined || tokens < base) return null
|
|
290
292
|
const limit = threshold ?? window
|
|
291
|
-
const
|
|
292
|
-
if (tokens >= final) return tokens
|
|
293
|
-
const
|
|
294
|
-
|
|
295
|
-
|
|
296
|
-
return passed > 0 ? base + passed * step : null
|
|
293
|
+
const targets = hintTargets(limit, overrides)
|
|
294
|
+
if (tokens >= firstFinal(base, limit, targets.final)) return tokens
|
|
295
|
+
const soft = nextSoft(base, base, limit, targets)
|
|
296
|
+
return soft !== null && tokens >= soft ? soft : null
|
|
297
297
|
}
|