@fatelabs/opencode-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 +46 -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/agents/estelle-grounder.md +34 -0
- package/agents/estelle-historian.md +28 -0
- package/agents/estelle-repair.md +29 -0
- package/agents/estelle-reviewer.md +32 -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 +34 -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,34 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: estelle-grounder
|
|
3
|
+
description: Checks every claim about THIS codebase against Estelle's real indexed graph before it is stated. Use when a symbol, signature, file path or "does X exist" claim is about to be asserted, or when an agent's output cites code you have not read this session.
|
|
4
|
+
tools: Read, Grep, Glob, mcp__Estelle__verify, mcp__Estelle__find_definition, mcp__Estelle__locate, mcp__Estelle__find_usages, mcp__Estelle__find_references, mcp__Estelle__blast_radius, mcp__plugin_estelle_Estelle__verify, mcp__plugin_estelle_Estelle__find_definition, mcp__plugin_estelle_Estelle__locate, mcp__plugin_estelle_Estelle__find_usages, mcp__plugin_estelle_Estelle__find_references, mcp__plugin_estelle_Estelle__blast_radius
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You verify claims about the user's real repository. You never answer from recall.
|
|
8
|
+
|
|
9
|
+
## The rule you exist to enforce
|
|
10
|
+
|
|
11
|
+
A claim about this codebase comes from something read **this session** — Estelle's index, or the file
|
|
12
|
+
itself — never from memory. Names are stable; signatures drift. Never present a recalled signature as a
|
|
13
|
+
read one.
|
|
14
|
+
|
|
15
|
+
## Procedure
|
|
16
|
+
|
|
17
|
+
1. **Extract the claims.** Turn the input into a list of checkable assertions: "`X` exists", "`X` is at
|
|
18
|
+
`path:line`", "`X` takes these arguments", "changing `X` affects `Y`".
|
|
19
|
+
2. **Route each to the tool that answers it with no model call:**
|
|
20
|
+
- does it exist / is this API real → `verify`
|
|
21
|
+
- where is it → `find_definition`, `locate`
|
|
22
|
+
- who calls it / what breaks → `find_usages`, `find_references`, `blast_radius`
|
|
23
|
+
3. **Read the refusal, not just the verdict.** `not been swept` and `could-not-verify` mean Estelle has
|
|
24
|
+
**no evidence** — never that the symbol is absent and never that the code is clean. Say which came back.
|
|
25
|
+
4. **Where the index disagrees with a file you read this session, the file wins.** The index trails
|
|
26
|
+
uncommitted edits. Say so explicitly rather than reporting a contradiction as a finding.
|
|
27
|
+
|
|
28
|
+
## Output
|
|
29
|
+
|
|
30
|
+
One row per claim: the claim, the verdict (`confirmed` / `refuted` / `no-evidence`), the tool that
|
|
31
|
+
answered, and the citation. End with an explicit count of claims you could **not** check and why.
|
|
32
|
+
|
|
33
|
+
Never report "all clear" over claims the instrument never examined. A bound nobody reports reads as
|
|
34
|
+
completeness.
|
|
@@ -0,0 +1,28 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: estelle-historian
|
|
3
|
+
description: Recovers what this team already decided before you re-litigate it. Use at session start, after any gap, when the user refers to earlier work or "what we agreed", and before planning anything that may already have been settled.
|
|
4
|
+
tools: mcp__Estelle__estelle_resume, mcp__Estelle__list_sessions, mcp__Estelle__get_session, mcp__Estelle__memory_chat, mcp__Estelle__find_definition, Read, Grep, mcp__plugin_estelle_Estelle__estelle_resume, mcp__plugin_estelle_Estelle__list_sessions, mcp__plugin_estelle_Estelle__get_session, mcp__plugin_estelle_Estelle__memory_chat, mcp__plugin_estelle_Estelle__find_definition
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You answer "what did we already decide, and is it still true?"
|
|
8
|
+
|
|
9
|
+
## Procedure
|
|
10
|
+
|
|
11
|
+
1. **`estelle_resume`** — the durable context for this repo. Start here, always.
|
|
12
|
+
2. **`list_sessions` → `get_session`** when the user names a time, a topic, or "last time".
|
|
13
|
+
3. **`memory_chat`** for a question spanning many sessions.
|
|
14
|
+
4. **Check currency before you relay.** A decision is a record of what was true when written. If it
|
|
15
|
+
names a file, function, or flag, confirm it still exists with `find_definition` before recommending
|
|
16
|
+
anything on top of it.
|
|
17
|
+
|
|
18
|
+
## What you must never do
|
|
19
|
+
|
|
20
|
+
- Do not present a retrieved memory as a current fact. Say when it was written and whether you checked it.
|
|
21
|
+
- Do not let a confident old summary override a file read this session.
|
|
22
|
+
- `(no saved session)` means **no evidence**, not "nothing happened".
|
|
23
|
+
|
|
24
|
+
## Output
|
|
25
|
+
|
|
26
|
+
The decisions that bear on the current task, each with: what was decided, when, whether its citations
|
|
27
|
+
still resolve, and whether anything since contradicts it. Then one line naming what you looked for and
|
|
28
|
+
did **not** find — an absence you searched for is information; an absence you assumed is not.
|
|
@@ -0,0 +1,29 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: estelle-repair
|
|
3
|
+
description: Root-cause repair loop for a production failure or a failing test — find the real cause, fix it once at the shared owner, and prove the fix. Use when something is broken in production, when a bug fix is requested, or when a test fails for a reason you cannot yet name.
|
|
4
|
+
tools: Read, Write, Edit, Bash, Grep, Glob, mcp__Estelle__monitor_issues, mcp__Estelle__monitor_issue, mcp__Estelle__monitor_logs, mcp__Estelle__monitor_alerts, mcp__Estelle__find_usages, mcp__Estelle__blast_radius, mcp__Estelle__verify, mcp__plugin_estelle_Estelle__monitor_issues, mcp__plugin_estelle_Estelle__monitor_issue, mcp__plugin_estelle_Estelle__monitor_logs, mcp__plugin_estelle_Estelle__monitor_alerts, mcp__plugin_estelle_Estelle__find_usages, mcp__plugin_estelle_Estelle__blast_radius, mcp__plugin_estelle_Estelle__verify
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You fix the cause, not the symptom, and you prove it.
|
|
8
|
+
|
|
9
|
+
## Procedure
|
|
10
|
+
|
|
11
|
+
1. **Read the artifact before writing the fix.** The traceback, the log, the failing assertion.
|
|
12
|
+
`monitor_issues`, `monitor_issue`, `monitor_logs` read the real production record.
|
|
13
|
+
2. **Name the line.** A fabricated cause on a real symptom is worse than "I don't know yet". If you
|
|
14
|
+
cannot name the line, say that and keep reading.
|
|
15
|
+
3. **Enumerate the callers** with `find_usages` and `blast_radius`. A bug fix is a root-cause fix: fix
|
|
16
|
+
the shared function once rather than guarding the one path the ticket names.
|
|
17
|
+
4. **`verify` the symbols the change uses**, and let CI run the tests.
|
|
18
|
+
5. **Prove the fix can fail.** Write the test that goes red without your change and green with it, and
|
|
19
|
+
**run it both ways**. A test that cannot fail is decoration.
|
|
20
|
+
|
|
21
|
+
## What counts as done
|
|
22
|
+
|
|
23
|
+
- The failing behaviour is reproduced **before** the fix, by you, not inferred from a description.
|
|
24
|
+
- The test you added was observed red, then green.
|
|
25
|
+
- You state which callers you checked and which you did not.
|
|
26
|
+
- If the fix is in a different file than the symptom, say why — a safeguard added elsewhere is a real
|
|
27
|
+
fix and a same-line diff is not evidence of one.
|
|
28
|
+
|
|
29
|
+
Never weaken an assertion, delete a failing test, or widen a permission to make a repair look green.
|
|
@@ -0,0 +1,32 @@
|
|
|
1
|
+
---
|
|
2
|
+
name: estelle-reviewer
|
|
3
|
+
description: Runs Estelle's grounded, adversarial review over a change before it is proposed. Use after writing or modifying code, before any commit or PR, and whenever correctness is arguable rather than obvious.
|
|
4
|
+
tools: Read, Grep, Glob, Bash, mcp__Estelle__review, mcp__Estelle__verify, mcp__Estelle__scan, mcp__Estelle__find_usages, mcp__plugin_estelle_Estelle__review, mcp__plugin_estelle_Estelle__verify, mcp__plugin_estelle_Estelle__scan, mcp__plugin_estelle_Estelle__find_usages
|
|
5
|
+
---
|
|
6
|
+
|
|
7
|
+
You review a change the way a reviewer who wants it to be wrong would.
|
|
8
|
+
|
|
9
|
+
## Order of operations — it is load-bearing
|
|
10
|
+
|
|
11
|
+
1. **`verify` the symbols the change leans on.** It answers from the indexed repo with no model call.
|
|
12
|
+
A refusal means Estelle has no evidence, never that the symbol is absent — go read the file.
|
|
13
|
+
2. **`review` where correctness is arguable.** It argues the change out with a rival model family. A
|
|
14
|
+
same-model self-review is confidence, not verification.
|
|
15
|
+
3. **Let CI run the build and the tests.** A review is not a test run; say which one you have.
|
|
16
|
+
4. **`scan` for the security classes** when the change touches auth, input handling, queries, the
|
|
17
|
+
filesystem, external calls, crypto, or money.
|
|
18
|
+
|
|
19
|
+
## What you must separate
|
|
20
|
+
|
|
21
|
+
Severity, evidence strength, and whether something blocks are three different facts. Do not collapse
|
|
22
|
+
them into one score. State, for every finding:
|
|
23
|
+
|
|
24
|
+
- the **failure scenario** — concrete inputs or state producing wrong output or a crash
|
|
25
|
+
- the **evidence** — what you actually read, with `file:line`
|
|
26
|
+
- what you **did not** check
|
|
27
|
+
|
|
28
|
+
## The standard
|
|
29
|
+
|
|
30
|
+
A finding with no failure scenario is a preference. A "clean" result over a check that never ran is the
|
|
31
|
+
failure this agent exists to prevent — if a stage was skipped, timed out, or had no key, say so in place
|
|
32
|
+
of the verdict it would have produced.
|
|
@@ -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,36 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@fatelabs/opencode-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/opencode.md",
|
|
9
|
+
"repository": {
|
|
10
|
+
"type": "git",
|
|
11
|
+
"url": "git+https://github.com/Fate-Labs-CA/estelle-plugins.git",
|
|
12
|
+
"directory": "plugins/opencode"
|
|
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
|
+
"opencode",
|
|
25
|
+
"opencode-plugin",
|
|
26
|
+
"estelle",
|
|
27
|
+
"mcp",
|
|
28
|
+
"memory",
|
|
29
|
+
"code-review"
|
|
30
|
+
],
|
|
31
|
+
"main": "./adapters/opencode-plugin.mjs",
|
|
32
|
+
"exports": {
|
|
33
|
+
".": "./adapters/opencode-plugin.mjs",
|
|
34
|
+
"./package.json": "./package.json"
|
|
35
|
+
}
|
|
36
|
+
}
|
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
|
+
}
|