@iiiokojiadbi/shift 0.0.0-stage → 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 iiiokojiadbi
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,13 @@
1
- # Temporary Holding Version
1
+ # shift for pi
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.
4
+
5
+ ```sh
6
+ pi install npm:@iiiokojiadbi/shift
7
+ ```
8
+
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 two commands: `/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
+
11
+ The records live in the project's `.shift/` folder and stay out of its git unless `commit = true` in `.shift/settings.toml`.
12
+
13
+ How it works and why: [github.com/iiiokojiadbi/shift](https://github.com/iiiokojiadbi/shift).
package/core/about.ts ADDED
@@ -0,0 +1,98 @@
1
+ // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
+ import { AFTER } from './layout'
3
+ import { bullets, formatK, frontmatter, isOneOf, sections } from './markdown'
4
+ import type { AboutMeta, ShiftAfter } from './types'
5
+
6
+ // about.md, a shift in brief with a strict structure: written once when the shift is accepted and again with its
7
+ // outcome, read by the history, by the message after a shift and by a fresh process for its base. One module writes
8
+ // and reads it, so the keys, the sections and the outcomes cannot drift between them.
9
+
10
+ // What became of a shift, as its `result:` line says it.
11
+ export const OUTCOME = {
12
+ pending: 'pending',
13
+ continuing: (shrank: string) => `shifted (${shrank}), continuing`,
14
+ waiting: (shrank: string, why: string) => `shifted (${shrank}), ${why}`,
15
+ notShifted: (why: string) => `not shifted: ${why}`,
16
+ unsettled: (why: string) => `let go, not settled: ${why}`,
17
+ }
18
+
19
+ export type About = {
20
+ description: string | null
21
+ after: ShiftAfter | null
22
+ result: string | null
23
+ session: string | null
24
+ // Whether the history was let go and settled.
25
+ shifted: boolean
26
+ // The fill right after the let-go; null when unknown.
27
+ tokensAfter: number | null
28
+ done: string[]
29
+ dropped: string[]
30
+ archived: string[]
31
+ open: string[]
32
+ }
33
+
34
+ export function renderAbout(meta: AboutMeta): string {
35
+ const list = (items: string[]) => (items.length === 0 ? ['none'] : items.map(item => `- ${item}`))
36
+ const tokens =
37
+ meta.tokensBefore === undefined
38
+ ? 'unknown'
39
+ : `${formatK(meta.tokensBefore)} → ${meta.tokensAfter === undefined ? '?' : formatK(meta.tokensAfter)}`
40
+
41
+ return [
42
+ '---',
43
+ `description: ${meta.about}`,
44
+ `at: ${new Date(meta.at).toISOString()}`,
45
+ `after: ${meta.after}`,
46
+ `result: ${meta.result}`,
47
+ `tokens: ${tokens}`,
48
+ `summary_chars: ${meta.summaryChars ?? 'unknown'}`,
49
+ `session: ${meta.sessionId}`,
50
+ '---',
51
+ '',
52
+ '## Done',
53
+ '',
54
+ ...list(meta.segment.done),
55
+ '',
56
+ '## Dropped',
57
+ '',
58
+ ...list(meta.segment.dropped),
59
+ '',
60
+ '## Archived',
61
+ '',
62
+ ...list(meta.segment.archived),
63
+ '',
64
+ '## Open',
65
+ '',
66
+ ...list(meta.segment.open),
67
+ '',
68
+ ].join('\n')
69
+ }
70
+
71
+ export function readAbout(text: string): About {
72
+ const meta = frontmatter(text)
73
+ const found = sections(text)
74
+ const after = meta.get('after') ?? meta.get('then') ?? null
75
+ const result = meta.get('result') ?? null
76
+ // `tokens: 300K → 20K`, a fill under 1000 printed as it is.
77
+ const fill = /→ (\d+)(K?)$/.exec(meta.get('tokens') ?? '')
78
+
79
+ return {
80
+ description: meta.get('description') ?? null,
81
+ after: isOneOf(AFTER, after) ? after : null,
82
+ result,
83
+ session: meta.get('session') ?? null,
84
+ shifted: result?.startsWith('shifted') ?? false,
85
+ tokensAfter: fill === null ? null : Number(fill[1]) * (fill[2] === 'K' ? 1000 : 1),
86
+ done: bullets(found.get('Done')),
87
+ dropped: bullets(found.get('Dropped')),
88
+ archived: bullets(found.get('Archived')),
89
+ open: bullets(found.get('Open')),
90
+ }
91
+ }
92
+
93
+ // The fill the stretch started from, if the shift was this session's and let the history go.
94
+ export function shiftFill(text: string, sessionId: string): number | null {
95
+ const about = readAbout(text)
96
+
97
+ return about.session === sessionId && about.shifted ? about.tokensAfter : null
98
+ }
@@ -0,0 +1,41 @@
1
+ // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
+ import { ARCHIVE, CLOSED, TASKS } from './layout'
3
+ import { itemsOf, quote, title } from './markdown'
4
+ import type { ArchiveInput, TaskFiles } from './types'
5
+
6
+ // What `task_archive` refuses: a task that is not there, or one marked done with open items.
7
+ export function checkArchive(input: ArchiveInput, task: TaskFiles, archived: boolean): string | null {
8
+ const where = `${TASKS}/${input.name}/`
9
+ if (archived) return `${ARCHIVE}/${input.name}/ already exists: pick another name for the task before archiving it.`
10
+ if (task.task === null) return `${where}task.md is missing: is "${input.name}" the task's folder name?`
11
+ if (title(task.task) === null) return `${where}task.md has no "# <title>" line.`
12
+ if (input.outcome === 'done') {
13
+ const open = itemsOf(task.track ?? '').filter(item => !CLOSED.has(item.status))
14
+ if (open.length > 0) {
15
+ return `Not every item is closed: ${quote(
16
+ open.map(i => i.line),
17
+ '; ',
18
+ )}. Close them as done or dropped, or archive the task as dropped.`
19
+ }
20
+ }
21
+
22
+ return null
23
+ }
24
+
25
+ // `continues` lists the archived tasks this one picked up, from its links in TASKS.md.
26
+ export function indexLine(input: ArchiveInput, task: string, continues: readonly string[]): string {
27
+ // An about that ends a sentence ends before the links: "tests pass; continues x", not "tests pass.; continues x".
28
+ const about = continues.length === 0 ? input.about : input.about.replace(/\.$/, '')
29
+ const tail = continues.length === 0 ? '' : `; continues ${continues.join(', ')}`
30
+
31
+ return `- [${input.outcome}] [${title(task) ?? input.name}](${input.name}/) — ${about}${tail}`
32
+ }
33
+
34
+ export function addToIndex(index: string | null, line: string): string {
35
+ const head =
36
+ index === null || index.trim() === ''
37
+ ? '# Archive\n\nOne line per archived task: outcome, title, what it was and how it ended.\n'
38
+ : `${index.trimEnd()}\n`
39
+
40
+ return `${head}${index === null || index.trim() === '' ? '\n' : ''}${line}\n`
41
+ }
@@ -0,0 +1,131 @@
1
+ // Generated from core/src by scripts/sync-core.ts — edit the source, not this copy.
2
+ import { docsAfterWrite } from './docs'
3
+ import { type ChangedBy, changedRecords, type Seen } from './flows'
4
+ import type { GaugeKeeper } from './hint'
5
+ import { MOD } from './layout'
6
+ import { type Loop, loopHint, waitingNote } from './loop'
7
+ import type { Project } from './project'
8
+ import { NOTE_KINDS, type NoteKind } from './texts/prompts'
9
+ import { TOLD } from './texts/rows'
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
13
+ // what comes back where its harness lets it; the kinds, their order, their one format and the owner's rows are here.
14
+ // Nothing is queued: every note is pulled at the slot it goes with.
15
+
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 }
19
+
20
+ export const FRESH_LOOKS: Looks = { seen: null, running: 0 }
21
+
22
+ export type Courier = {
23
+ loop: Loop
24
+ gauge: GaugeKeeper
25
+ project(): Promise<Project>
26
+ looks(): Promise<Looks>
27
+ // A change applied to the looks as they are then.
28
+ updateLooks(change: (current: Looks) => Looks): Promise<void>
29
+ }
30
+
31
+ // A note before it goes: its kind and what it says.
32
+ export type Note = { kind: NoteKind; body: string }
33
+
34
+ // How a tool of the main agent ended; null when it threw.
35
+ export type ToolEnd = {
36
+ // The mod's own tool: it writes the records validly, so what it wrote is only remembered.
37
+ own: boolean
38
+ // A tool that ran read-only changed nothing: no look after it.
39
+ readOnly: boolean
40
+ // The file it wrote, absolute, when it wrote one and did not fail: the docs follow it.
41
+ written?: string
42
+ }
43
+
44
+ // Before a tool of the main agent: what changed since the last look is someone else's — the owner's hand, another
45
+ // session — unless another tool runs now, whose own change it may be. The notes go with this tool's result.
46
+ export async function beforeTool(courier: Courier): Promise<Note[]> {
47
+ const { running } = await courier.looks()
48
+ const outside = running === 0 ? await look(courier, 'other') : null
49
+ await courier.updateLooks(current => ({ ...current, running: current.running + 1 }))
50
+
51
+ return outside === null ? [] : [{ kind: 'records', body: outside }]
52
+ }
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.
56
+ export async function afterTool(courier: Courier, before: readonly Note[], done: ToolEnd | null): Promise<string[]> {
57
+ await courier.updateLooks(current => ({ ...current, running: Math.max(0, current.running - 1) }))
58
+ if (done === null) return []
59
+ const notes = [...before]
60
+ const own = done.readOnly ? null : await look(courier, 'agent')
61
+ if (own !== null && !done.own) notes.push({ kind: 'records', body: own })
62
+ if (done.written !== undefined) notes.push(...(await docsNotes(courier, done.written)))
63
+ const hint = await loopHint(courier.loop, courier.gauge).catch(() => null)
64
+ if (hint !== null) notes.push({ kind: 'hint', body: hint })
65
+
66
+ return deliver(courier.loop, notes)
67
+ }
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))
72
+ }
73
+
74
+ // With the next prompt: what changed between turns, a hint, and after a wait the letter, last, when the owner speaks.
75
+ // The notes are told to the owner and the letter cleared only once `delivered` says the prompt went with them.
76
+ export async function atPrompt(
77
+ courier: Courier,
78
+ { runStarts, owner }: { runStarts: boolean; owner: boolean },
79
+ ): Promise<{ notes: string[]; delivered(): Promise<void> }> {
80
+ if (runStarts) await courier.updateLooks(current => ({ ...current, running: 0 }))
81
+ const notes: Note[] = []
82
+ const { running } = await courier.looks()
83
+ const outside = running === 0 ? await look(courier, 'other') : null
84
+ if (outside !== null) notes.push({ kind: 'records', body: outside })
85
+ const hint = await loopHint(courier.loop, courier.gauge).catch(() => null)
86
+ if (hint !== null) notes.push({ kind: 'hint', body: hint })
87
+ const letter = owner ? await waitingNote(courier.loop) : null
88
+
89
+ return {
90
+ notes: [...notes.map(wrap), ...(letter === null ? [] : [letter.context])],
91
+ delivered: async () => {
92
+ for (const note of notes) courier.loop.tell(TOLD(note.body), 'info')
93
+ await letter?.delivered()
94
+ },
95
+ }
96
+ }
97
+
98
+ // The run is over: no tool of it runs any more, whatever a process that ended mid-tool left counted.
99
+ export async function runEnded(courier: Courier): Promise<void> {
100
+ await courier.updateLooks(current => (current.running === 0 ? current : { ...current, running: 0 }))
101
+ }
102
+
103
+ // The records changed since the last look; the first look only remembers them. A look that fails says nothing: it
104
+ // must never stand between the agent and its tool.
105
+ async function look(courier: Courier, by: ChangedBy): Promise<string | null> {
106
+ try {
107
+ const changed = await changedRecords(await courier.project(), (await courier.looks()).seen, by)
108
+ await courier.updateLooks(current => ({ ...current, seen: changed.seen }))
109
+
110
+ return changed.body
111
+ } catch {
112
+ return null
113
+ }
114
+ }
115
+
116
+ async function docsNotes(courier: Courier, file: string): Promise<Note[]> {
117
+ const lines = await docsAfterWrite(await courier.project(), file).catch(() => [])
118
+
119
+ return lines.length === 0 ? [] : [{ kind: 'docs', body: lines.join('\n') }]
120
+ }
121
+
122
+ function deliver(loop: Loop, notes: readonly Note[]): string[] {
123
+ for (const note of notes) loop.tell(TOLD(note.body), 'info')
124
+
125
+ return notes.map(wrap)
126
+ }
127
+
128
+ // Every note in the mod's tag, by its kind: the agent tells it from what it came with.
129
+ export function wrap({ kind, body }: Note): string {
130
+ return `<${MOD} note="${NOTE_KINDS[kind]}">\n${body}\n</${MOD}>`
131
+ }