@fatelabs/pi-estelle 0.0.0-stage → 0.0.18
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 +201 -0
- package/NOTICE +6 -0
- package/README.md +44 -2
- package/adapters/claude.mjs +17 -0
- package/adapters/codex.mjs +85 -0
- package/adapters/cursor.mjs +66 -0
- package/adapters/dsh-host.mjs +181 -0
- package/adapters/dsh-plugin.mjs +11 -0
- package/adapters/dsh.mjs +54 -0
- package/adapters/grok.mjs +63 -0
- package/adapters/host-bridge.mjs +85 -0
- package/adapters/kimi.mjs +135 -0
- package/adapters/opencode-mirror.mjs +103 -0
- package/adapters/opencode-plugin.mjs +143 -0
- package/adapters/opencode.mjs +15 -0
- package/adapters/pi-extension.mjs +107 -0
- package/adapters/pi.mjs +13 -0
- package/adapters/plugin-envelope.mjs +56 -0
- package/commands/cloud.md +28 -0
- package/commands/code.md +6 -0
- package/commands/handoff.md +25 -0
- package/commands/monitor.md +6 -0
- package/commands/resume.md +6 -0
- package/commands/review.md +6 -0
- package/commands/rooms.md +7 -0
- package/instructions.md +19 -0
- package/package.json +38 -4
- package/runtime/auth.mjs +27 -0
- package/runtime/checkpoint.mjs +208 -0
- package/runtime/claude-setup.mjs +130 -0
- package/runtime/cli.mjs +112 -0
- package/runtime/codex-trust.mjs +68 -0
- package/runtime/credential.mjs +341 -0
- package/runtime/dsh-session.mjs +91 -0
- package/runtime/dsh-telemetry.mjs +31 -0
- package/runtime/hooks.mjs +234 -0
- package/runtime/identity.mjs +20 -0
- package/runtime/io.mjs +155 -0
- package/runtime/key-check.mjs +51 -0
- package/runtime/kimi-history.mjs +163 -0
- package/runtime/mailbox.mjs +46 -0
- package/runtime/migration.mjs +118 -0
- package/runtime/move.mjs +443 -0
- package/runtime/native-export.mjs +204 -0
- package/runtime/native-index.mjs +77 -0
- package/runtime/native-tree.mjs +117 -0
- package/runtime/queued-context.mjs +152 -0
- package/runtime/redact.mjs +74 -0
- package/runtime/reindex.mjs +259 -0
- package/runtime/setup.mjs +174 -0
- package/runtime/stream.mjs +755 -0
- package/runtime/version.mjs +2 -0
- package/runtime/write-warning.mjs +67 -0
- package/skills/abstain-right/SKILL.md +19 -0
- package/skills/api-call-ground/SKILL.md +19 -0
- package/skills/bug-hunt/SKILL.md +20 -0
- package/skills/chain-of-verification/SKILL.md +19 -0
- package/skills/change-impact/SKILL.md +19 -0
- package/skills/coding-workflow/SKILL.md +20 -0
- package/skills/commit-guard/SKILL.md +20 -0
- package/skills/context-checkpoint/SKILL.md +19 -0
- package/skills/continuity-brief/SKILL.md +19 -0
- package/skills/dead-code-sweep/SKILL.md +19 -0
- package/skills/deep-search/SKILL.md +19 -0
- package/skills/diff-review/SKILL.md +19 -0
- package/skills/estelle/SKILL.md +119 -0
- package/skills/estelle-loop/SKILL.md +19 -0
- package/skills/estelle-monitor-install/SKILL.md +20 -0
- package/skills/evidence-traceability-audit/SKILL.md +19 -0
- package/skills/grounded-generate/SKILL.md +19 -0
- package/skills/incident-rca/SKILL.md +20 -0
- package/skills/mutation-test/SKILL.md +19 -0
- package/skills/program-repair/SKILL.md +20 -0
- package/skills/prompt-injection-defense/SKILL.md +19 -0
- package/skills/property-based-test/SKILL.md +19 -0
- package/skills/refactor-rfc/SKILL.md +19 -0
- package/skills/root-cause-loop/SKILL.md +19 -0
- package/skills/test-first/SKILL.md +19 -0
- package/skills/threat-model-stride/SKILL.md +19 -0
|
@@ -0,0 +1,107 @@
|
|
|
1
|
+
// Estelle for Pi: one extension. It registers the Estelle MCP server with Pi's built-in MCP support, the Estelle
|
|
2
|
+
// commands, and hands Pi's own events to the shared hook runner (adapters/host-bridge.mjs). Skills ship in the package
|
|
3
|
+
// manifest (`pi.skills`). Written against @earendil-works/pi-coding-agent 1.5.2 (docs/extensions.md, docs/mcp.md).
|
|
4
|
+
import { contextOf, END_TIMEOUT_MS, readCommands, readInstructions, runHook, SERVER_NAME, SERVER_URL, warningOf }
|
|
5
|
+
from './host-bridge.mjs';
|
|
6
|
+
|
|
7
|
+
const HOST = 'pi';
|
|
8
|
+
const MAX_TOOL_WARNINGS = 64;
|
|
9
|
+
// Tools declared to the model directly; the rest of Estelle's tools are found with Pi's `tool_search` when needed.
|
|
10
|
+
// `review` stays deferred: its input schema's root is a oneOf, which some providers refuse in a declaration (xAI
|
|
11
|
+
// answered 400 `invalid_client_tool_schema` for the whole request, measured 2026-11-18), so declaring it up front would
|
|
12
|
+
// break every turn on those providers instead of only the turn that asks for it.
|
|
13
|
+
export const DIRECT_TOOLS = Object.freeze(['estelle_resume', 'estelle_grep', 'verify', 'find_definition', 'find_usages',
|
|
14
|
+
'locate', 'memory_chat', 'estelle_move']);
|
|
15
|
+
|
|
16
|
+
const COMMAND = /^\/estelle:([a-z][a-z-]{0,40})(?:\s+([\s\S]*))?$/;
|
|
17
|
+
|
|
18
|
+
/** Offers `/estelle:<name>` while the person types it at the start of the editor; anything else goes to Pi's own. */
|
|
19
|
+
export function completer(current, byName) {
|
|
20
|
+
return {
|
|
21
|
+
triggerCharacters: current.triggerCharacters,
|
|
22
|
+
async getSuggestions(lines, cursorLine, cursorCol, options) {
|
|
23
|
+
const before = (lines[cursorLine] ?? '').slice(0, cursorCol);
|
|
24
|
+
const typed = cursorLine === 0 && /^\/e[a-z:-]*$/.test(before) ? before : null;
|
|
25
|
+
const items = typed ? [...byName.values()].map(item => ({ value: `/estelle:${item.name}`, label: `/estelle:${item.name}`,
|
|
26
|
+
description: item.description })).filter(item => item.value.startsWith(typed)) : [];
|
|
27
|
+
return items.length ? { prefix: typed, items } : current.getSuggestions(lines, cursorLine, cursorCol, options);
|
|
28
|
+
},
|
|
29
|
+
applyCompletion: (...args) => current.applyCompletion(...args),
|
|
30
|
+
shouldTriggerFileCompletion: (...args) => current.shouldTriggerFileCompletion?.(...args) ?? true };
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** The server entry this extension registers. Pure, so the test reads exactly what Pi is given. */
|
|
34
|
+
export function estelleServer(env = process.env) {
|
|
35
|
+
const key = env.ESTELLE_API_KEY;
|
|
36
|
+
// No key: Pi's own MCP OAuth signs in (`/mcp login Estelle`). An Authorization header would disable that.
|
|
37
|
+
return { url: SERVER_URL, description: 'Estelle: repository evidence, shared memory, review, Rooms, monitoring and cloud sessions',
|
|
38
|
+
exposure: 'deferred', toolExposure: Object.fromEntries(DIRECT_TOOLS.map(name => [name, 'direct'])),
|
|
39
|
+
...(key && !/[\r\n]/.test(key) ? { headers: { Authorization: `Bearer ${key}` } } : {}) };
|
|
40
|
+
}
|
|
41
|
+
|
|
42
|
+
/** Wire Estelle into one Pi extension runtime. `run` is injectable so tests drive the real handlers. */
|
|
43
|
+
export async function activate(pi, { env = process.env, run = runHook, commands, instructions } = {}) {
|
|
44
|
+
let context = '';
|
|
45
|
+
const warnings = new Map();
|
|
46
|
+
const sessionOf = ctx => ({ session_id: ctx.sessionManager.getSessionId(), cwd: ctx.cwd,
|
|
47
|
+
transcript_path: ctx.sessionManager.getSessionFile() ?? null });
|
|
48
|
+
const hook = (event, ctx, extra = {}, timeoutMs) => run(HOST, { hook_event_name: event, ...sessionOf(ctx), ...extra },
|
|
49
|
+
{ env, ...(timeoutMs ? { timeoutMs } : {}) });
|
|
50
|
+
const guide = instructions ?? await readInstructions();
|
|
51
|
+
|
|
52
|
+
try { pi.registerMcpServer(SERVER_NAME, estelleServer(env)); }
|
|
53
|
+
catch (error) { console.error(`Estelle could not register its MCP server with Pi: ${error.message}`); }
|
|
54
|
+
|
|
55
|
+
// `/estelle:<name> words` becomes the command's prompt before Pi expands templates, the way a prompt template would:
|
|
56
|
+
// the turn is the person's own, in every mode. A registered command's handler cannot start a turn that print and
|
|
57
|
+
// JSON modes wait for (measured on 1.5.2: the process exits with the handler, or hangs if the handler waits).
|
|
58
|
+
const byName = new Map((commands ?? await readCommands()).map(item => [item.name, item]));
|
|
59
|
+
pi.on('input', async event => {
|
|
60
|
+
const match = COMMAND.exec(typeof event.text === 'string' ? event.text.trim() : '');
|
|
61
|
+
const item = match && byName.get(match[1]);
|
|
62
|
+
if (!item) return { action: 'continue' };
|
|
63
|
+
return { action: 'transform', text: item.template.replaceAll('$ARGUMENTS', (match[2] ?? '').trim()) };
|
|
64
|
+
});
|
|
65
|
+
|
|
66
|
+
// SessionStart fires on startup, /new, /resume, /fork and reload, so the identity line is restated after each.
|
|
67
|
+
pi.on('session_start', async (_event, ctx) => {
|
|
68
|
+
if (ctx.hasUI && typeof ctx.ui.addAutocompleteProvider === 'function') ctx.ui.addAutocompleteProvider(current => completer(current, byName));
|
|
69
|
+
context = contextOf(await hook('session_start', ctx));
|
|
70
|
+
});
|
|
71
|
+
pi.on('before_agent_start', async (event, ctx) => {
|
|
72
|
+
// Instructions and this session's identity live in the system prompt, so a compaction never drops them.
|
|
73
|
+
const sections = event.systemPromptOptions?.sections;
|
|
74
|
+
if (sections && typeof sections === 'object') {
|
|
75
|
+
sections.estelle = guide;
|
|
76
|
+
if (context) sections.estelle_session = context;
|
|
77
|
+
}
|
|
78
|
+
if (event.messageType !== 'user' || typeof event.prompt !== 'string') return undefined;
|
|
79
|
+
const text = contextOf(await hook('before_agent_start', ctx, { prompt: event.prompt }));
|
|
80
|
+
// Recall travels as a session message the model reads; capture skips extension messages.
|
|
81
|
+
return text ? { message: { customType: 'estelle-recall', content: text, display: false } } : undefined;
|
|
82
|
+
});
|
|
83
|
+
pi.on('tool_call', async (event, ctx) => {
|
|
84
|
+
const warning = warningOf(await hook('tool_call', ctx, { tool_name: event.toolName, tool_input: event.input ?? {},
|
|
85
|
+
tool_use_id: event.toolCallId }));
|
|
86
|
+
if (!warning) return undefined;
|
|
87
|
+
warnings.set(event.toolCallId, warning);
|
|
88
|
+
if (warnings.size > MAX_TOOL_WARNINGS) warnings.delete(warnings.keys().next().value);
|
|
89
|
+
if (ctx.hasUI) ctx.ui.notify(warning, 'warning');
|
|
90
|
+
return undefined; // ⛔ A warning, never a block.
|
|
91
|
+
});
|
|
92
|
+
// Mail and room entries for this session arrive with the tool result the model is about to read.
|
|
93
|
+
pi.on('tool_result', async (event, ctx) => {
|
|
94
|
+
const output = (event.content ?? []).map(block => (block?.type === 'text' ? block.text : '')).join('\n').slice(0, 4_000);
|
|
95
|
+
const text = contextOf(await hook('tool_result', ctx, { tool_name: event.toolName, tool_input: event.input ?? {},
|
|
96
|
+
tool_use_id: event.toolCallId, tool_response: { output, is_error: event.isError === true } }));
|
|
97
|
+
const warning = warnings.get(event.toolCallId);
|
|
98
|
+
warnings.delete(event.toolCallId);
|
|
99
|
+
const extra = [warning, text].filter(Boolean).join('\n\n');
|
|
100
|
+
return extra ? { content: [...(event.content ?? []), { type: 'text', text: extra }] } : undefined;
|
|
101
|
+
});
|
|
102
|
+
pi.on('agent_settled', async (_event, ctx) => { await hook('agent_settled', ctx); });
|
|
103
|
+
pi.on('session_before_compact', async (_event, ctx) => { await hook('session_before_compact', ctx); return undefined; });
|
|
104
|
+
pi.on('session_shutdown', async (_event, ctx) => { await hook('session_shutdown', ctx, {}, END_TIMEOUT_MS); });
|
|
105
|
+
}
|
|
106
|
+
|
|
107
|
+
export default function estelle(pi) { return activate(pi); }
|
package/adapters/pi.mjs
ADDED
|
@@ -0,0 +1,13 @@
|
|
|
1
|
+
// Pi's extension events (docs/extensions.md in @earendil-works/pi-coding-agent 1.5.2), as adapters/pi-extension.mjs
|
|
2
|
+
// names them in the envelope.
|
|
3
|
+
import { envelopeAdapter } from './plugin-envelope.mjs';
|
|
4
|
+
|
|
5
|
+
export const { HOOK_EVENTS, normalize, formatContext } = envelopeAdapter({
|
|
6
|
+
host: 'pi',
|
|
7
|
+
events: Object.freeze({
|
|
8
|
+
session_start: 'SessionStart', before_agent_start: 'UserPromptSubmit', tool_call: 'PreToolUse',
|
|
9
|
+
tool_result: 'PostToolUse', agent_settled: 'Stop', session_before_compact: 'PreCompact', session_shutdown: 'SessionEnd',
|
|
10
|
+
}),
|
|
11
|
+
// Pi's built-in file tools: write {path, content} and edit {path, edits}.
|
|
12
|
+
tools: Object.freeze({ write: 'Write', edit: 'Edit' }),
|
|
13
|
+
});
|
|
@@ -0,0 +1,56 @@
|
|
|
1
|
+
import { isAbsolute } from 'node:path';
|
|
2
|
+
|
|
3
|
+
// OpenCode and Pi have no command-hook protocol: a hook there is a function inside the host's own process. Estelle's
|
|
4
|
+
// in-process plugin for each (adapters/opencode-plugin.mjs, adapters/pi-extension.mjs) writes this one envelope from
|
|
5
|
+
// the host's native event and hands it to `runtime/cli.mjs hook <host>`, so every field here is ours.
|
|
6
|
+
const SESSION_ID = /^[A-Za-z0-9_-]{1,200}$/;
|
|
7
|
+
const TOOL_EVENTS = new Set(['PreToolUse', 'PostToolUse']);
|
|
8
|
+
// Each plugin places this text with its host's own mechanism: a system-prompt section or a session message at the
|
|
9
|
+
// start and at a prompt, and the tool result the model is about to read at a tool boundary.
|
|
10
|
+
const CONTEXT_EVENTS = new Set(['SessionStart', 'SubagentStart', 'UserPromptSubmit', 'PostToolUse']);
|
|
11
|
+
|
|
12
|
+
const text = (host, value, name) => {
|
|
13
|
+
if (value != null && typeof value !== 'string') throw new TypeError(`${host} ${name} must be text`);
|
|
14
|
+
return value ?? null;
|
|
15
|
+
};
|
|
16
|
+
|
|
17
|
+
/** One adapter per host: `events` maps the host's native event names to Estelle's, `tools` maps file-writing tools
|
|
18
|
+
* to the names write-warning.mjs knows, so a key written by `write` gets the same warning as one written by `Write`. */
|
|
19
|
+
export function envelopeAdapter({ host, events, tools }) {
|
|
20
|
+
const nativeEvents = Object.freeze(Object.keys(events));
|
|
21
|
+
function normalize(payload) {
|
|
22
|
+
if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new TypeError(`${host} hook input must be an object`);
|
|
23
|
+
let event = events[payload.hook_event_name];
|
|
24
|
+
if (!event) throw new TypeError(`Unsupported ${host} hook event`);
|
|
25
|
+
if (typeof payload.session_id !== 'string' || !SESSION_ID.test(payload.session_id)) {
|
|
26
|
+
throw new TypeError(`Invalid ${host} session identity`);
|
|
27
|
+
}
|
|
28
|
+
if (typeof payload.cwd !== 'string' || payload.cwd.includes('\0') || !isAbsolute(payload.cwd)) {
|
|
29
|
+
throw new TypeError(`${host} hook cwd must be an absolute local path`);
|
|
30
|
+
}
|
|
31
|
+
const parent = text(host, payload.parent_session_id, 'parent_session_id');
|
|
32
|
+
if (parent !== null && !SESSION_ID.test(parent)) throw new TypeError(`Invalid ${host} parent session identity`);
|
|
33
|
+
if (parent && event === 'SessionStart') event = 'SubagentStart';
|
|
34
|
+
const toolName = text(host, payload.tool_name, 'tool_name');
|
|
35
|
+
if (TOOL_EVENTS.has(event) && !toolName) throw new TypeError(`${host} tool_name is required for tool events`);
|
|
36
|
+
return {
|
|
37
|
+
host, event, sessionId: payload.session_id, cwd: payload.cwd,
|
|
38
|
+
transcriptPath: text(host, payload.transcript_path, 'transcript_path'),
|
|
39
|
+
prompt: text(host, payload.prompt, 'prompt'),
|
|
40
|
+
toolName: toolName ? tools[toolName] ?? toolName : null,
|
|
41
|
+
toolInput: payload.tool_input ?? null,
|
|
42
|
+
toolResponse: payload.tool_response ?? null,
|
|
43
|
+
toolUseId: text(host, payload.tool_use_id, 'tool_use_id'),
|
|
44
|
+
// A child session's tool calls are not the main conversation's boundary for its mail (hooks.mjs reads agentId).
|
|
45
|
+
agentId: parent ? payload.session_id : null,
|
|
46
|
+
model: text(host, payload.model, 'model'),
|
|
47
|
+
raw: payload,
|
|
48
|
+
};
|
|
49
|
+
}
|
|
50
|
+
/** The plugin reads `additionalContext` and places it; null where its host has no place for it. */
|
|
51
|
+
function formatContext(value, event) {
|
|
52
|
+
if (typeof value !== 'string') throw new TypeError(`${host} hook context must be text`);
|
|
53
|
+
return CONTEXT_EVENTS.has(event) && value.trim() ? { additionalContext: value } : null;
|
|
54
|
+
}
|
|
55
|
+
return { HOOK_EVENTS: nativeEvents, normalize, formatContext };
|
|
56
|
+
}
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Start a new cloud session from a prompt and get a link to watch it.
|
|
3
|
+
---
|
|
4
|
+
Only act on this when the person typed the command themselves: it starts a billed machine.
|
|
5
|
+
The person asked to start a new cloud session. Their words: $ARGUMENTS
|
|
6
|
+
|
|
7
|
+
Do it now. Say nothing first, check nothing first, and ask nothing: this folder names the repository, and no repository
|
|
8
|
+
is fine. Do not call `estelle_resume`, `estelle_silo`, `session_message` or any other tool, and do not run git.
|
|
9
|
+
|
|
10
|
+
Run this once with your shell tool and pass their words on stdin exactly as written. In Claude Code the file is
|
|
11
|
+
`${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs`. Elsewhere it is `runtime/cli.mjs` at the root of the installed Estelle plugin: on Codex,
|
|
12
|
+
`../../runtime/cli.mjs` from this skill's own folder.
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
node "<Estelle cli.mjs>" move cloud <<'ESTELLE_MOVE'
|
|
16
|
+
$ARGUMENTS
|
|
17
|
+
ESTELLE_MOVE
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
PowerShell has no `<<`, so there pipe the same words in, with any `'` doubled: `'their words' | node "<Estelle cli.mjs>" move cloud`.
|
|
21
|
+
|
|
22
|
+
If it prints `ESTELLE_MCP_CALL` and a JSON line, this host signed in to Estelle with OAuth: call the MCP tool `estelle_move` once
|
|
23
|
+
with exactly that JSON as its arguments. Your whole reply is then any line starting `Starts from`, and one line more: the tool's
|
|
24
|
+
`last_message`, or otherwise the last line the command printed, as it is. It holds the link. If it says the move could not run, that is the answer: do not retry
|
|
25
|
+
and do not start a machine another way. Never say a session resumed unless that line says so.
|
|
26
|
+
|
|
27
|
+
After it starts, this session is a remote control: if the person keeps typing instructions for that work, send them with
|
|
28
|
+
`estelle_move` and `action: "steer"`, naming the session id it printed in the link.
|
package/commands/code.md
ADDED
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Implement a focused change using the repository's existing patterns and checks.
|
|
3
|
+
---
|
|
4
|
+
Use the coding-workflow skill for $ARGUMENTS. Read the actual flow and callers. Prefer a fitting
|
|
5
|
+
existing implementation or native feature, then the standard library, then a small complete change.
|
|
6
|
+
Keep trust boundaries and error handling. Test behavior, review the diff and state verification limits.
|
|
@@ -0,0 +1,25 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Continue this session in a cloud Silo and get a link to watch it.
|
|
3
|
+
---
|
|
4
|
+
Only act on this when the person typed the command themselves: it starts a billed machine.
|
|
5
|
+
The person asked to move this session to the cloud. Their words, which may be empty: $ARGUMENTS
|
|
6
|
+
|
|
7
|
+
Do it now. Say nothing first, check nothing first, and ask nothing: this folder names the repository. Do not call `estelle_resume`, `estelle_silo`, `session_message` or any other tool, and do not run git.
|
|
8
|
+
|
|
9
|
+
Empty words mean finish what this session is coding. Run this once with your shell tool and pass their words on stdin
|
|
10
|
+
exactly as written. In Claude Code the file is
|
|
11
|
+
`${CLAUDE_PLUGIN_ROOT}/runtime/cli.mjs`. Elsewhere it is `runtime/cli.mjs` at the root of the installed Estelle plugin: on Codex,
|
|
12
|
+
`../../runtime/cli.mjs` from this skill's own folder.
|
|
13
|
+
|
|
14
|
+
```sh
|
|
15
|
+
node "<Estelle cli.mjs>" move handoff <<'ESTELLE_MOVE'
|
|
16
|
+
$ARGUMENTS
|
|
17
|
+
ESTELLE_MOVE
|
|
18
|
+
```
|
|
19
|
+
|
|
20
|
+
PowerShell has no `<<`, so there pipe the same words in, with any `'` doubled: `'their words' | node "<Estelle cli.mjs>" move handoff`.
|
|
21
|
+
|
|
22
|
+
If it prints `ESTELLE_MCP_CALL` and a JSON line, this host signed in to Estelle with OAuth: call the MCP tool `estelle_move` once
|
|
23
|
+
with exactly that JSON as its arguments. Your whole reply is then any line starting `Starts from`, and one line more: the tool's
|
|
24
|
+
`last_message`, or otherwise the last line the command printed, as it is. It holds the link. If it says the move could not run, that is the answer: do not retry
|
|
25
|
+
and do not start a machine another way. Never say a session resumed unless that line says so.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Check production health in Estelle Monitor and investigate a reported issue.
|
|
3
|
+
---
|
|
4
|
+
Start with monitor_overview and inspect the issues, logs, alerts or uptime checks relevant to
|
|
5
|
+
$ARGUMENTS. Explain impact, evidence and next action plainly. Reading an alert does not send a page
|
|
6
|
+
or authorize a production change. Do not invent recipients, severity or a successful mitigation.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Continue earlier Estelle work with its decisions and file freshness.
|
|
3
|
+
---
|
|
4
|
+
Call estelle_resume for $ARGUMENTS. If a particular handoff was requested, inspect and use
|
|
5
|
+
estelle_handoff_resume. Check the stated freshness against current files. State which history
|
|
6
|
+
was available and its capture limits, then continue the authorized work.
|
|
@@ -0,0 +1,6 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Review a change with repository evidence and behavioral checks.
|
|
3
|
+
---
|
|
4
|
+
Review $ARGUMENTS, or the current diff if no target was given. Read the affected code and callers,
|
|
5
|
+
then use Estelle review for arguable logic and scan for sensitive changes. Verify findings against
|
|
6
|
+
actual files and tests. Report concrete failures with evidence, severity and what remains unchecked.
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
---
|
|
2
|
+
description: Inspect or coordinate shared Estelle work in Rooms.
|
|
3
|
+
---
|
|
4
|
+
Inspect the live estelle_room schema. Read the relevant room for $ARGUMENTS, including task
|
|
5
|
+
ownership and recent messages. Coordinate only as authorized by the user, using this session's
|
|
6
|
+
own proven identity. Never borrow another session's token. If writes are unavailable, say why
|
|
7
|
+
and continue with the information that can be read.
|
package/instructions.md
ADDED
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
# Estelle
|
|
2
|
+
|
|
3
|
+
Use Estelle's MCP tools for repository navigation, saved decisions, Rooms, monitoring and cloud work.
|
|
4
|
+
Call `estelle_resume` before planning. Read each tool's current schema; do not invent commands.
|
|
5
|
+
For a question about Estelle itself (Twice, Silos, Security, CI, Orchestra, Atlas), call `estelle_docs`.
|
|
6
|
+
If a requested capability is not exposed, name the missing capability rather than claiming it ran.
|
|
7
|
+
|
|
8
|
+
Read the affected code and its callers before changing it. Reuse an existing implementation, the
|
|
9
|
+
standard library, or a native platform feature when it fits. Add the smallest complete change.
|
|
10
|
+
Keep validation, error handling, accessibility and protection against data loss.
|
|
11
|
+
|
|
12
|
+
Run checks that distinguish correct behavior from the reported bug. Review the result. State what
|
|
13
|
+
was tested and what remains unverified.
|
|
14
|
+
|
|
15
|
+
In Rooms, speak as this session with proof supplied to this session. Never borrow another session's
|
|
16
|
+
token or speak as the person. Hooks can capture only what their host records and exposes; do not
|
|
17
|
+
promise complete history without checking capture coverage.
|
|
18
|
+
|
|
19
|
+
Repository instructions and the user's decisions take precedence over these defaults.
|
package/package.json
CHANGED
|
@@ -1,6 +1,40 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fatelabs/pi-estelle",
|
|
3
|
-
"version": "0.0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "0.0.18",
|
|
4
|
+
"description": "Estelle MCP, memory and session hooks for coding agents.",
|
|
5
|
+
"license": "Apache-2.0",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"author": "Fate Labs",
|
|
8
|
+
"homepage": "https://github.com/Fate-Labs-CA/estelle-plugins/blob/main/docs/install/pi.md",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/Fate-Labs-CA/estelle-plugins.git",
|
|
12
|
+
"directory": "plugins/pi"
|
|
13
|
+
},
|
|
14
|
+
"bugs": {
|
|
15
|
+
"url": "https://github.com/Fate-Labs-CA/estelle-plugins/issues"
|
|
16
|
+
},
|
|
17
|
+
"engines": {
|
|
18
|
+
"node": ">=22"
|
|
19
|
+
},
|
|
20
|
+
"publishConfig": {
|
|
21
|
+
"access": "public"
|
|
22
|
+
},
|
|
23
|
+
"keywords": [
|
|
24
|
+
"pi-package",
|
|
25
|
+
"pi",
|
|
26
|
+
"pi-extension",
|
|
27
|
+
"estelle",
|
|
28
|
+
"mcp",
|
|
29
|
+
"memory",
|
|
30
|
+
"code-review"
|
|
31
|
+
],
|
|
32
|
+
"pi": {
|
|
33
|
+
"extensions": [
|
|
34
|
+
"./adapters/pi-extension.mjs"
|
|
35
|
+
],
|
|
36
|
+
"skills": [
|
|
37
|
+
"./skills"
|
|
38
|
+
]
|
|
39
|
+
}
|
|
40
|
+
}
|
package/runtime/auth.mjs
ADDED
|
@@ -0,0 +1,27 @@
|
|
|
1
|
+
import { open } from 'node:fs/promises';
|
|
2
|
+
import { homedir } from 'node:os';
|
|
3
|
+
import { join } from 'node:path';
|
|
4
|
+
|
|
5
|
+
const usable = value => typeof value === 'string' && value.length > 0 && value.length <= 4096
|
|
6
|
+
&& /^[\x21-\x7e]+$/.test(value);
|
|
7
|
+
|
|
8
|
+
/** Migration helper only. Native hooks and MCP share the canonical inherited environment key. */
|
|
9
|
+
export async function launchCredential(env = process.env, home = homedir()) {
|
|
10
|
+
const inherited = env.ESTELLE_API_KEY || env.ESTELLE_KEY;
|
|
11
|
+
if (inherited) return usable(inherited) ? inherited : null;
|
|
12
|
+
const file = await open(join(home, '.estelle', 'auth.json'), 'r').catch(error => {
|
|
13
|
+
if (error.code === 'ENOENT') return null;
|
|
14
|
+
throw error;
|
|
15
|
+
});
|
|
16
|
+
if (!file) return null;
|
|
17
|
+
try {
|
|
18
|
+
const info = await file.stat();
|
|
19
|
+
if (!info.isFile() || info.size > 16_000 || (process.platform !== 'win32' && (info.mode & 0o077))) return null;
|
|
20
|
+
const buffer = Buffer.alloc(info.size + 1);
|
|
21
|
+
const { bytesRead } = await file.read(buffer, 0, buffer.length, 0);
|
|
22
|
+
if (bytesRead > info.size) return null;
|
|
23
|
+
const stored = JSON.parse(buffer.subarray(0, bytesRead).toString('utf8'));
|
|
24
|
+
return usable(stored.key) ? stored.key : null;
|
|
25
|
+
} catch { return null; }
|
|
26
|
+
finally { await file.close(); }
|
|
27
|
+
}
|
|
@@ -0,0 +1,208 @@
|
|
|
1
|
+
// Bounded conversation checkpoint client, ported from the public CLI contract.
|
|
2
|
+
import { open } from 'node:fs/promises';
|
|
3
|
+
import { redact, sanitize } from './redact.mjs';
|
|
4
|
+
import { cloudExecutionIdentity } from './identity.mjs';
|
|
5
|
+
import { safeSession, grokContentText } from './stream.mjs';
|
|
6
|
+
import { readKimiHistory } from './kimi-history.mjs';
|
|
7
|
+
|
|
8
|
+
export const CHECKPOINT_LIMITS = Object.freeze({
|
|
9
|
+
tailBytes: 32 * 1024 * 1024, headBytes: 64 * 1024,
|
|
10
|
+
records: 100_000, messages: 400, chars: 4_000, blocks: 1_000,
|
|
11
|
+
});
|
|
12
|
+
const HOSTS = { claude: 'claude-code', 'claude-code': 'claude-code', codex: 'codex', kimi: 'kimi-code', 'kimi-code': 'kimi-code',
|
|
13
|
+
grok: 'grok', cursor: 'cursor', dsh: 'deepseek-harness', 'deepseek-harness': 'deepseek-harness', opencode: 'opencode', pi: 'pi' };
|
|
14
|
+
const INJECTED = ['<environment_context', '<user_instructions', '# AGENTS.md instructions', '<skill', '<system-reminder', '<task-notification', '<command-', '<local-command', '<turn_aborted'];
|
|
15
|
+
const string = value => typeof value === 'string' ? value : '';
|
|
16
|
+
const shortened = text => Array.from(redact(text)).slice(0, CHECKPOINT_LIMITS.chars).join('');
|
|
17
|
+
|
|
18
|
+
async function readPart(file, start, bytes) {
|
|
19
|
+
const buffer = Buffer.alloc(bytes);
|
|
20
|
+
let used = 0;
|
|
21
|
+
const maxReads = 1024;
|
|
22
|
+
for (let attempt = 0; attempt < maxReads && used < bytes; attempt++) {
|
|
23
|
+
const { bytesRead } = await file.read(buffer, used, bytes - used, start + used);
|
|
24
|
+
if (!bytesRead) break;
|
|
25
|
+
used += bytesRead;
|
|
26
|
+
}
|
|
27
|
+
return buffer.subarray(0, used);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
async function transcriptWindows(path) {
|
|
31
|
+
const file = await open(path, 'r');
|
|
32
|
+
try {
|
|
33
|
+
const bytes = (await file.stat()).size;
|
|
34
|
+
if (bytes <= CHECKPOINT_LIMITS.tailBytes) {
|
|
35
|
+
const buffer = await readPart(file, 0, bytes);
|
|
36
|
+
return { windows: [buffer], bytes, read: buffer.length, partial: buffer.length < bytes };
|
|
37
|
+
}
|
|
38
|
+
const head = await readPart(file, 0, CHECKPOINT_LIMITS.headBytes);
|
|
39
|
+
const tailStart = Math.max(head.length, bytes - CHECKPOINT_LIMITS.tailBytes);
|
|
40
|
+
const tail = await readPart(file, tailStart, bytes - tailStart);
|
|
41
|
+
const first = tail.indexOf(10);
|
|
42
|
+
return { windows: [head.subarray(0, head.lastIndexOf(10) + 1), first < 0 ? Buffer.alloc(0) : tail.subarray(first + 1)],
|
|
43
|
+
bytes, read: head.length + tail.length, partial: true };
|
|
44
|
+
} finally { await file.close(); }
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function blockText(block) {
|
|
48
|
+
if (['text', 'input_text', 'output_text'].includes(block?.type)) return string(block.text);
|
|
49
|
+
if (['image', 'input_image', 'image_url'].includes(block?.type)) return '[image attached; image bytes omitted]';
|
|
50
|
+
if (block?.type === 'tool_use') return `[tool: ${string(block.name) || '?'}]`;
|
|
51
|
+
return ''; // Tool output, encrypted content, and reasoning do not belong in conversation checkpoints.
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
function messageOf(record, host, subagent) {
|
|
55
|
+
if (!record || typeof record !== 'object') return null;
|
|
56
|
+
// OpenCode's plugin mirror is written in Claude Code's line shape (adapters/opencode-mirror.mjs).
|
|
57
|
+
if (host === 'claude-code' || host === 'opencode') {
|
|
58
|
+
if (!['user', 'assistant'].includes(record.type) || record.isMeta || record.isCompactSummary || (record.isSidechain && !subagent)) return null;
|
|
59
|
+
return { role: record.type, ...record.message };
|
|
60
|
+
}
|
|
61
|
+
if (host === 'codex') {
|
|
62
|
+
const item = record.type === 'response_item' ? record.payload : record;
|
|
63
|
+
return item?.type === 'message' && ['user', 'assistant'].includes(item.role) ? item : null;
|
|
64
|
+
}
|
|
65
|
+
if (host === 'cursor') {
|
|
66
|
+
// Cursor lines: {"role":"user"|"assistant","message":{"content":[...]}}; role-less control lines carry no conversation.
|
|
67
|
+
return ['user', 'assistant'].includes(record.role) ? { role: record.role, content: record.message?.content ?? record.content } : null;
|
|
68
|
+
}
|
|
69
|
+
if (host === 'deepseek-harness') {
|
|
70
|
+
// The JSONL adapters/dsh-plugin.mjs writes from session/event. Only the person's own messages are "user":
|
|
71
|
+
// dsh also sends its runtime context and skill catalog as user-role messages with another source.
|
|
72
|
+
if (record.type === 'user/message') return record.data?.source?.kind === 'user' ? { role: 'user', content: record.data.content } : null;
|
|
73
|
+
return record.type === 'assistant/message' ? { role: 'assistant', content: record.data?.message?.content } : null;
|
|
74
|
+
}
|
|
75
|
+
if (host === 'pi') {
|
|
76
|
+
// Pi's session file: `message` entries. Extension messages (role `custom`) are not the conversation.
|
|
77
|
+
const message = record.type === 'message' ? record.message : null;
|
|
78
|
+
return ['user', 'assistant'].includes(message?.role) ? { role: message.role, content: message.content } : null;
|
|
79
|
+
}
|
|
80
|
+
if (host === 'grok') {
|
|
81
|
+
// Inferred dialect (not verified against a live session): ACP update lines become one message fragment
|
|
82
|
+
// per chunk; chat-history lines carry role/content directly. Tool output lines are not conversation.
|
|
83
|
+
const update = record.params?.update ?? record.update ?? (typeof record.sessionUpdate === 'string' ? record : null);
|
|
84
|
+
if (update && typeof update === 'object') {
|
|
85
|
+
const kind = update.sessionUpdate;
|
|
86
|
+
if (kind === 'user_message_chunk') return { role: 'user', content: grokContentText(update.content), chunk: true };
|
|
87
|
+
if (kind === 'agent_message_chunk') return { role: 'assistant', content: grokContentText(update.content), chunk: true };
|
|
88
|
+
return null;
|
|
89
|
+
}
|
|
90
|
+
return ['user', 'assistant'].includes(record.role) ? { role: record.role, content: record.content } : null;
|
|
91
|
+
}
|
|
92
|
+
return record.type === 'context.append_message' && ['user', 'assistant'].includes(record.message?.role) ? record.message : null;
|
|
93
|
+
}
|
|
94
|
+
|
|
95
|
+
function contextOf(record, host, context) {
|
|
96
|
+
const meta = host === 'codex' && record.type === 'session_meta' ? record.payload : record;
|
|
97
|
+
for (const [key, value] of Object.entries({ cwd: meta?.cwd, branch: meta?.gitBranch ?? meta?.git?.branch,
|
|
98
|
+
client_version: meta?.version ?? meta?.cli_version, model: record.message?.model, entrypoint: meta?.entrypoint })) {
|
|
99
|
+
if (context[key] === undefined && typeof value === 'string' && value) context[key] = shortened(value);
|
|
100
|
+
}
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
function checkpointText(message, counters) {
|
|
104
|
+
const blocks = message.content;
|
|
105
|
+
if (Array.isArray(blocks) && blocks.length > CHECKPOINT_LIMITS.blocks) counters.blocks_truncated++;
|
|
106
|
+
const text = (typeof blocks === 'string' ? blocks : Array.isArray(blocks)
|
|
107
|
+
? blocks.slice(0, CHECKPOINT_LIMITS.blocks).map(blockText).filter(Boolean).join('\n') : '');
|
|
108
|
+
// ACP chunk fragments split mid-word; trimming each fragment would corrupt the merged turn.
|
|
109
|
+
if (!text.trim() || (message.role === 'user' && INJECTED.some(prefix => text.trim().startsWith(prefix)))) return null;
|
|
110
|
+
const clean = redact(message.chunk ? text : text.trim());
|
|
111
|
+
if (Array.from(clean).length > CHECKPOINT_LIMITS.chars) counters.messages_truncated++;
|
|
112
|
+
return { role: message.role, content: shortened(clean), ...(message.chunk ? { chunk: true } : {}) };
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/** ACP chunk updates split one host message over many lines; merge consecutive same-role fragments. */
|
|
116
|
+
function mergeChunks(messages) {
|
|
117
|
+
const merged = [];
|
|
118
|
+
for (const message of messages) {
|
|
119
|
+
const last = merged.at(-1);
|
|
120
|
+
const fits = last && Array.from(last.content).length + Array.from(message.content).length <= CHECKPOINT_LIMITS.chars;
|
|
121
|
+
if (fits && last.role === message.role && (last.chunk || message.chunk)) last.content += message.content;
|
|
122
|
+
else merged.push(message);
|
|
123
|
+
delete merged.at(-1).chunk;
|
|
124
|
+
}
|
|
125
|
+
return merged;
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function parseWindow(buffer, host, subagent, messages, counters, context) {
|
|
129
|
+
let end = buffer.lastIndexOf(10);
|
|
130
|
+
if (end < buffer.length - 1) counters.partial_last_line = true;
|
|
131
|
+
for (; end >= 0 && counters.lines < CHECKPOINT_LIMITS.records;) {
|
|
132
|
+
const start = end === 0 ? 0 : buffer.lastIndexOf(10, end - 1) + 1;
|
|
133
|
+
const text = buffer.subarray(start, end).toString('utf8').trim();
|
|
134
|
+
end = start - 1;
|
|
135
|
+
if (!text) continue;
|
|
136
|
+
counters.lines++;
|
|
137
|
+
let record;
|
|
138
|
+
try { record = JSON.parse(text); } catch { counters.invalid_lines++; continue; }
|
|
139
|
+
if (!record || typeof record !== 'object' || Array.isArray(record)) { counters.unknown_lines++; continue; }
|
|
140
|
+
contextOf(record, host, context);
|
|
141
|
+
const message = messageOf(record, host, subagent);
|
|
142
|
+
if (!message) { counters.unknown_lines++; continue; }
|
|
143
|
+
counters.recognized_lines++;
|
|
144
|
+
const kept = checkpointText(message, counters);
|
|
145
|
+
if (!kept) continue;
|
|
146
|
+
if (messages.length < CHECKPOINT_LIMITS.messages) messages.push(kept);
|
|
147
|
+
else counters.turns_dropped++;
|
|
148
|
+
}
|
|
149
|
+
if (end >= 0) counters.record_limit_reached = true;
|
|
150
|
+
}
|
|
151
|
+
|
|
152
|
+
/** Read the most recent conversation, with a small head window for provenance, and disclose every cap. */
|
|
153
|
+
export async function readTranscriptMessages({ path, host, subagent = false }) {
|
|
154
|
+
const harness = HOSTS[host];
|
|
155
|
+
if (!harness) throw new Error('unsupported checkpoint host');
|
|
156
|
+
const bounded = await transcriptWindows(path);
|
|
157
|
+
const messages = [];
|
|
158
|
+
const counters = { lines: 0, recognized_lines: 0, unknown_lines: 0, invalid_lines: 0, turns_dropped: 0,
|
|
159
|
+
messages_truncated: 0, blocks_truncated: 0, record_limit_reached: false, partial_last_line: false };
|
|
160
|
+
const context = {};
|
|
161
|
+
// Reverse order makes message cap retain the most recent turns, while context keeps the latest fact.
|
|
162
|
+
for (const window of bounded.windows.toReversed()) parseWindow(window, harness, subagent, messages, counters, context);
|
|
163
|
+
messages.reverse();
|
|
164
|
+
const legacy = harness === 'kimi-code';
|
|
165
|
+
const inferred = harness === 'grok' || harness === 'cursor';
|
|
166
|
+
if (harness === 'grok') messages.splice(0, messages.length, ...mergeChunks(messages));
|
|
167
|
+
const partial = bounded.partial || legacy || inferred || counters.record_limit_reached || counters.partial_last_line || counters.turns_dropped > 0
|
|
168
|
+
|| counters.invalid_lines > 0 || counters.messages_truncated > 0 || counters.blocks_truncated > 0;
|
|
169
|
+
if (partial && messages.length) messages[0].content = shortened(
|
|
170
|
+
'[Estelle: this checkpoint is PARTIAL. Read bounds, omitted records, or text limits apply; this is not the complete session history.]\n' + messages[0].content);
|
|
171
|
+
return { messages, client: { name: harness, ...context, transcript_partial: partial, transcript_bytes: bounded.bytes,
|
|
172
|
+
transcript_read_bytes: bounded.read, ...(legacy ? { transcript_format: 'kimi-legacy-wire', newer_format_verified: false } : {}),
|
|
173
|
+
...(inferred ? { transcript_format: `${harness}-jsonl-inferred`, format_verified: false,
|
|
174
|
+
capture_note: 'Dialect inferred from third-party observations, not verified against a live host session.' } : {}),
|
|
175
|
+
...counters } };
|
|
176
|
+
}
|
|
177
|
+
|
|
178
|
+
/** SessionEnd is deliberately delegated to the caller's durable reference queue, without filesystem/network work. */
|
|
179
|
+
export async function checkpointSession({ payload, host, repo, stateDir, request }) {
|
|
180
|
+
if (cloudExecutionIdentity()) return { saved: false, unsupported: true,
|
|
181
|
+
reason: 'Cloud transcript checkpoints require a private owner-bound storage door; visible event streaming remains separate.' };
|
|
182
|
+
if (payload.hook_event_name === 'SessionEnd') return { saved: false, deferred: true };
|
|
183
|
+
if (!safeSession(payload.session_id)) throw new Error('invalid host session identity');
|
|
184
|
+
const child = payload.hook_event_name === 'SubagentStop';
|
|
185
|
+
const path = child && string(payload.agent_transcript_path).trim() ? payload.agent_transcript_path : payload.transcript_path;
|
|
186
|
+
if (!string(path).trim()) return { saved: false, reason: 'host did not supply a transcript path' };
|
|
187
|
+
let messages, client;
|
|
188
|
+
if (host === 'kimi' || host === 'kimi-code') {
|
|
189
|
+
const history = await readKimiHistory({ sessionId: payload.session_id, cwd: payload.cwd });
|
|
190
|
+
if (!history.available) return { saved: false, reason: history.coverage.reason, client: history.coverage };
|
|
191
|
+
const selected = history.messages.slice(-CHECKPOINT_LIMITS.messages);
|
|
192
|
+
messages = selected.map(message => ({ ...message, content: shortened(message.content) }));
|
|
193
|
+
const capped = selected.length < history.messages.length || selected.some(message => Array.from(message.content).length > CHECKPOINT_LIMITS.chars);
|
|
194
|
+
client = { name: 'kimi-code', transcript_format: history.format,
|
|
195
|
+
transcript_partial: !history.coverage.complete || capped, capture_coverage: history.coverage };
|
|
196
|
+
if (client.transcript_partial && messages.length) messages[0].content = shortened('[Estelle: this checkpoint is PARTIAL; inspect capture_coverage.]\n' + messages[0].content);
|
|
197
|
+
} else ({ messages, client } = await readTranscriptMessages({ path, host, subagent: child }));
|
|
198
|
+
if (!messages.length) return { saved: false, reason: 'no verified user or assistant messages in transcript', client };
|
|
199
|
+
const id = string(payload.agent_id);
|
|
200
|
+
if (child && /^[A-Za-z0-9][A-Za-z0-9_.-]{0,127}$/.test(id)) {
|
|
201
|
+
const kind = string(payload.agent_type).replace(/[\[\]\r\n]/g, ' ').trim() || id;
|
|
202
|
+
for (const message of messages) message.content = shortened(`[subagent: ${kind.slice(0, 100)} ${id}] ${message.content}`);
|
|
203
|
+
}
|
|
204
|
+
const body = { session_id: payload.session_id, messages,
|
|
205
|
+
client: sanitize({ ...client, event: payload.hook_event_name, cwd: client.cwd || payload.cwd || undefined, repo }) };
|
|
206
|
+
await request('/checkpoint', body);
|
|
207
|
+
return { saved: true, messages: messages.length, client: body.client };
|
|
208
|
+
}
|