@kolisachint/hoocode-agent 0.5.26 → 0.5.27

package/dist/extensions/core/self-knowledge.js

@@ -0,0 +1,199 @@
+/**
+ * SearchHooCode — retrieval over hoocode's own docs and the capabilities this
+ * session actually has.
+ *
+ * The system prompt already lists every shipped doc with a one-line summary
+ * (see `core/self-docs.ts`), which answers "which file covers extensions?".
+ * What it cannot answer is anything *inside* a file: `extensions.md` alone is
+ * over a thousand lines, and reading it whole to find one heading costs more
+ * context than the rest of the prompt put together. This indexes docs at the
+ * heading level so a question lands on a section and a line number.
+ *
+ * It also registers the capability kinds the registry has always declared but
+ * nobody ever filled — `skill`, `command`, `agent`, `plugin-installed`
+ * (registry.ts notes §6.4 left them eager). Those are eager in the prompt, so
+ * indexing them is not about reachability; it is about "what can you do?"
+ * having one place that answers it rather than the model reciting whichever
+ * list happens to be in front of it.
+ *
+ * `mcp-tool` is deliberately out of scope: ResolveMcpTools owns that kind
+ * because finding an MCP tool and making it callable are the same action
+ * there, and a second searcher that returns un-resolvable names would be a
+ * worse answer, not an extra one.
+ */
+import { Type } from "typebox";
+import { ensureDenseIndex } from "../../core/capabilities/dense.js";
+import { getCapabilities, registerCapabilities } from "../../core/capabilities/registry.js";
+import { resetCapabilitySearch, searchCapabilities } from "../../core/capabilities/search.js";
+import { listSelfDocSections, sectionLabel } from "../../core/self-docs.js";
+const SEARCH_HOOCODE_TOOL_NAME = "SearchHooCode";
+/** Kinds this tool searches. `mcp-tool` belongs to ResolveMcpTools. */
+const SEARCHABLE = ["doc", "skill", "command", "agent", "plugin-installed"];
+const DEFAULT_LIMIT = 8;
+const MAX_LIMIT = 25;
+/** Registered once per process; the docs are read-only install content. */
+let docsRegistered = false;
+/**
+ * Index the shipped docs, the first time anyone asks.
+ *
+ * Lazy because it reads thirty files and produces roughly a thousand sections.
+ * A session that never asks hoocode about itself should not pay for that at
+ * startup, and the cost is invisible once paid — `listSelfDocSections` caches.
+ */
+function ensureDocsRegistered() {
+    if (docsRegistered)
+        return;
+    docsRegistered = true;
+    const sections = listSelfDocSections();
+    if (sections.length === 0)
+        return;
+    registerCapabilities("doc", sections.map((section) => ({
+        id: `doc:${section.id}`,
+        kind: "doc",
+        name: sectionLabel(section),
+        description: section.excerpt,
+        source: section.path,
+        // The body is withheld until the model reads the file, which is
+        // exactly the condition this flag records.
+        deferred: true,
+    })));
+    resetCapabilitySearch();
+}
+/** Line-number lookup for rendering a hit, keyed by the id we registered under. */
+function sectionIndex() {
+    const index = new Map();
+    for (const section of listSelfDocSections()) {
+        index.set(`doc:${section.id}`, { path: section.path, line: section.line });
+    }
+    return index;
+}
+/**
+ * Mirror the session's skills, commands, and subagents into the registry.
+ *
+ * Driven from `before_agent_start` because that is where the assembled
+ * `systemPromptOptions` carries the skills and agents the session actually
+ * loaded — re-discovering them from disk here would risk disagreeing with what
+ * the model was told. Guarded by a signature so a steady session registers once
+ * instead of dropping the lexical index on every turn.
+ */
+let lastSignature = "";
+function registerSessionCapabilities(event, pi) {
+    const skills = event.systemPromptOptions.skills ?? [];
+    const agents = event.systemPromptOptions.agents ?? [];
+    let commands = [];
+    try {
+        commands = pi.getCommands();
+    }
+    catch {
+        // Commands are an interactive-mode concern; a headless session may not
+        // have them. Missing commands is not a reason to skip skills and agents.
+        commands = [];
+    }
+    const signature = [
+        skills.map((s) => s.name).join(","),
+        agents.map((a) => a.name).join(","),
+        commands.map((c) => c.name).join(","),
+    ].join("|");
+    if (signature === lastSignature)
+        return;
+    lastSignature = signature;
+    registerCapabilities("skill", skills.map((skill) => ({
+        id: `skill:${skill.name}`,
+        kind: "skill",
+        name: skill.name,
+        description: skill.description ?? "",
+        source: skill.filePath,
+        // Eager: the prompt already lists these, so a hit is a convenience.
+        deferred: false,
+    })));
+    registerCapabilities("agent", agents.map((agent) => ({
+        id: `agent:${agent.name}`,
+        kind: "agent",
+        name: agent.name,
+        description: agent.description ?? "",
+        deferred: false,
+    })));
+    registerCapabilities("command", commands.map((command) => ({
+        id: `command:${command.name}`,
+        kind: "command",
+        name: `/${command.name}`,
+        description: command.description ?? "",
+        deferred: false,
+    })));
+    resetCapabilitySearch();
+}
+function describeHit(doc, sections) {
+    if (doc.kind === "doc") {
+        const where = sections.get(doc.id);
+        const location = where ? `${where.path}:${where.line}` : (doc.source ?? "");
+        return `- [doc] ${doc.name}\n  read ${location}\n  ${doc.description}`;
+    }
+    const summary = doc.description ? ` — ${doc.description}` : "";
+    return `- [${doc.kind}] ${doc.name}${summary}`;
+}
+export function setupSelfKnowledge(pi) {
+    pi.on("before_agent_start", (event) => {
+        registerSessionCapabilities(event, pi);
+    });
+    const params = Type.Object({
+        query: Type.String({
+            description: "What you want to know about hoocode, in your own words — 'how do I write an extension', " +
+                "'where are sessions stored', 'can it run subagents'.",
+        }),
+        limit: Type.Optional(Type.Number({ description: `Maximum results. Default ${DEFAULT_LIMIT}.` })),
+    }, { additionalProperties: false });
+    pi.registerTool({
+        name: SEARCH_HOOCODE_TOOL_NAME,
+        label: SEARCH_HOOCODE_TOOL_NAME,
+        description: "Search hoocode's own documentation and the capabilities loaded in this session (skills, slash " +
+            "commands, subagents, installed plugins). Use it when the user asks what hoocode can do, how one of " +
+            "its features works, or how to configure or extend it. Doc results come back as a file path and line " +
+            "number — read that range for the answer rather than replying from the excerpt alone. " +
+            "MCP tools are not covered here; find those with ResolveMcpTools.",
+        promptSnippet: "Search hoocode's own docs and this session's capabilities by describing what you need.",
+        promptGuidelines: [
+            "For questions about hoocode itself — its features, configuration, or how to extend it — use SearchHooCode and read the section it points at instead of answering from memory.",
+        ],
+        parameters: params,
+        executionMode: "parallel",
+        async execute(_toolCallId, args) {
+            const query = args.query?.trim();
+            if (!query) {
+                return { content: [{ type: "text", text: "Provide a query." }], details: undefined };
+            }
+            ensureDocsRegistered();
+            const limit = Math.min(Math.max(1, Math.trunc(args.limit ?? DEFAULT_LIMIT)), MAX_LIMIT);
+            // Fire-and-forget over everything registered, not just the docs: the
+            // dense store is shared, so indexing a subset here would evict whatever
+            // the MCP resolver indexed. The lexical leg answers this call either way.
+            void ensureDenseIndex(getCapabilities()).catch(() => { });
+            const { hits, legs } = await searchCapabilities(query, { kinds: [...SEARCHABLE], limit });
+            if (hits.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `Nothing matched "${query}". The docs are listed in the system prompt under "About hoocode itself" — read the most likely file directly.`,
+                        },
+                    ],
+                    details: undefined,
+                };
+            }
+            const sections = sectionIndex();
+            const body = hits.map((hit) => describeHit(hit.doc, sections)).join("\n");
+            // Say which legs answered: lexical-only on a conceptual query is a
+            // weaker result, and the caller should be able to see that.
+            const note = legs.includes("dense") ? "" : "\n(Lexical match only — try naming the feature if this missed.)";
+            return {
+                content: [{ type: "text", text: `Results for "${query}":\n${body}${note}` }],
+                details: undefined,
+            };
+        },
+    });
+}
+/** Tests, and anything that relocates the package root mid-process. */
+export function resetSelfKnowledge() {
+    docsRegistered = false;
+    lastSignature = "";
+}
+//# sourceMappingURL=self-knowledge.js.map

package/dist/extensions/core/self-knowledge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"self-knowledge.js","sourceRoot":"","sources":["../../../src/extensions/core/self-knowledge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,SAAS,CAAC;AAC/B,OAAO,EAAE,gBAAgB,EAAE,MAAM,kCAAkC,CAAC;AACpE,OAAO,EAAsB,eAAe,EAAE,oBAAoB,EAAE,MAAM,qCAAqC,CAAC;AAChH,OAAO,EAAE,qBAAqB,EAAE,kBAAkB,EAAE,MAAM,mCAAmC,CAAC;AAE9F,OAAO,EAAE,mBAAmB,EAAE,YAAY,EAAE,MAAM,yBAAyB,CAAC;AAE5E,MAAM,wBAAwB,GAAG,eAAe,CAAC;AAEjD,uEAAuE;AACvE,MAAM,UAAU,GAAG,CAAC,KAAK,EAAE,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,kBAAkB,CAAU,CAAC;AAErF,MAAM,aAAa,GAAG,CAAC,CAAC;AACxB,MAAM,SAAS,GAAG,EAAE,CAAC;AAErB,2EAA2E;AAC3E,IAAI,cAAc,GAAG,KAAK,CAAC;AAE3B;;;;;;GAMG;AACH,SAAS,oBAAoB,GAAS;IACrC,IAAI,cAAc;QAAE,OAAO;IAC3B,cAAc,GAAG,IAAI,CAAC;IAEtB,MAAM,QAAQ,GAAG,mBAAmB,EAAE,CAAC;IACvC,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAElC,oBAAoB,CACnB,KAAK,EACL,QAAQ,CAAC,GAAG,CACX,CAAC,OAAO,EAAiB,EAAE,CAAC,CAAC;QAC5B,EAAE,EAAE,OAAO,OAAO,CAAC,EAAE,EAAE;QACvB,IAAI,EAAE,KAAK;QACX,IAAI,EAAE,YAAY,CAAC,OAAO,CAAC;QAC3B,WAAW,EAAE,OAAO,CAAC,OAAO;QAC5B,MAAM,EAAE,OAAO,CAAC,IAAI;QACpB,gEAAgE;QAChE,2CAA2C;QAC3C,QAAQ,EAAE,IAAI;KACd,CAAC,CACF,CACD,CAAC;IACF,qBAAqB,EAAE,CAAC;AAAA,CACxB;AAED,mFAAmF;AACnF,SAAS,YAAY,GAAgD;IACpE,MAAM,KAAK,GAAG,IAAI,GAAG,EAA0C,CAAC;IAChE,KAAK,MAAM,OAAO,IAAI,mBAAmB,EAAE,EAAE,CAAC;QAC7C,KAAK,CAAC,GAAG,CAAC,OAAO,OAAO,CAAC,EAAE,EAAE,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE,CAAC,CAAC;IAC5E,CAAC;IACD,OAAO,KAAK,CAAC;AAAA,CACb;AAED;;;;;;;;GAQG;AACH,IAAI,aAAa,GAAG,EAAE,CAAC;AAEvB,SAAS,2BAA2B,CAAC,KAA4B,EAAE,EAAgB,EAAQ;IAC1F,MAAM,MAAM,GAAG,KAAK,CAAC,mBAAmB,CAAC,MAAM,IAAI,EAAE,CAAC;IACtD,MAAM,MAAM,GAAG,KAAK,CAAC,mBAAmB,CAAC,MAAM,IAAI,EAAE,CAAC;IACtD,IAAI,QAAQ,GAAkD,EAAE,CAAC;IACjE,IAAI,CAAC;QACJ,QAAQ,GAAG,EAAE,CAAC,WAAW,EAAE,CAAC;IAC7B,CAAC;IAAC,MAAM,CAAC;QACR,uEAAuE;QACvE,yEAAyE;QACzE,QAAQ,GAAG,EAAE,CAAC;IACf,CAAC;IAED,MAAM,SAAS,GAAG;QACjB,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QACnC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;QACnC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC;KACrC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;IACZ,IAAI,SAAS,KAAK,aAAa;QAAE,OAAO;IACxC,aAAa,GAAG,SAAS,CAAC;IAE1B,oBAAoB,CACnB,OAAO,EACP,MAAM,CAAC,GAAG,CACT,CAAC,KAAK,EAAiB,EAAE,CAAC,CAAC;QAC1B,EAAE,EAAE,SAAS,KAAK,CAAC,IAAI,EAAE;QACzB,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;QACpC,MAAM,EAAE,KAAK,CAAC,QAAQ;QACtB,oEAAoE;QACpE,QAAQ,EAAE,KAAK;KACf,CAAC,CACF,CACD,CAAC;IACF,oBAAoB,CACnB,OAAO,EACP,MAAM,CAAC,GAAG,CACT,CAAC,KAAK,EAAiB,EAAE,CAAC,CAAC;QAC1B,EAAE,EAAE,SAAS,KAAK,CAAC,IAAI,EAAE;QACzB,IAAI,EAAE,OAAO;QACb,IAAI,EAAE,KAAK,CAAC,IAAI;QAChB,WAAW,EAAE,KAAK,CAAC,WAAW,IAAI,EAAE;QACpC,QAAQ,EAAE,KAAK;KACf,CAAC,CACF,CACD,CAAC;IACF,oBAAoB,CACnB,SAAS,EACT,QAAQ,CAAC,GAAG,CACX,CAAC,OAAO,EAAiB,EAAE,CAAC,CAAC;QAC5B,EAAE,EAAE,WAAW,OAAO,CAAC,IAAI,EAAE;QAC7B,IAAI,EAAE,SAAS;QACf,IAAI,EAAE,IAAI,OAAO,CAAC,IAAI,EAAE;QACxB,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,EAAE;QACtC,QAAQ,EAAE,KAAK;KACf,CAAC,CACF,CACD,CAAC;IACF,qBAAqB,EAAE,CAAC;AAAA,CACxB;AAED,SAAS,WAAW,CAAC,GAAkB,EAAE,QAAqD,EAAU;IACvG,IAAI,GAAG,CAAC,IAAI,KAAK,KAAK,EAAE,CAAC;QACxB,MAAM,KAAK,GAAG,QAAQ,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;QACnC,MAAM,QAAQ,GAAG,KAAK,CAAC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,IAAI,EAAE,CAAC,CAAC;QAC5E,OAAO,WAAW,GAAG,CAAC,IAAI,YAAY,QAAQ,OAAO,GAAG,CAAC,WAAW,EAAE,CAAC;IACxE,CAAC;IACD,MAAM,OAAO,GAAG,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC,QAAM,GAAG,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAC/D,OAAO,MAAM,GAAG,CAAC,IAAI,KAAK,GAAG,CAAC,IAAI,GAAG,OAAO,EAAE,CAAC;AAAA,CAC/C;AAED,MAAM,UAAU,kBAAkB,CAAC,EAAgB,EAAQ;IAC1D,EAAE,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,KAA4B,EAAE,EAAE,CAAC;QAC7D,2BAA2B,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;IAAA,CACvC,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CACzB;QACC,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC;YAClB,WAAW,EACV,4FAA0F;gBAC1F,sDAAsD;SACvD,CAAC;QACF,KAAK,EAAE,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,EAAE,4BAA4B,aAAa,GAAG,EAAE,CAAC,CAAC;KAChG,EACD,EAAE,oBAAoB,EAAE,KAAK,EAAE,CAC/B,CAAC;IAEF,EAAE,CAAC,YAAY,CAAC;QACf,IAAI,EAAE,wBAAwB;QAC9B,KAAK,EAAE,wBAAwB;QAC/B,WAAW,EACV,gGAAgG;YAChG,qGAAqG;YACrG,sGAAsG;YACtG,yFAAuF;YACvF,kEAAkE;QACnE,aAAa,EAAE,wFAAwF;QACvG,gBAAgB,EAAE;YACjB,mLAA+K;SAC/K;QACD,UAAU,EAAE,MAAM;QAClB,aAAa,EAAE,UAAU;QACzB,KAAK,CAAC,OAAO,CAAC,WAAmB,EAAE,IAA2B,EAAE;YAC/D,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,EAAE,CAAC;gBACZ,OAAO,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,kBAAkB,EAAE,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;YAC/F,CAAC;YAED,oBAAoB,EAAE,CAAC;YACvB,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,IAAI,aAAa,CAAC,CAAC,EAAE,SAAS,CAAC,CAAC;YAExF,qEAAqE;YACrE,wEAAwE;YACxE,0EAA0E;YAC1E,KAAK,gBAAgB,CAAC,eAAe,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,EAAE,CAAC,EAAC,CAAC,CAAC,CAAC;YAEzD,MAAM,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,MAAM,kBAAkB,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,UAAU,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC;YAC1F,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;gBACvB,OAAO;oBACN,OAAO,EAAE;wBACR;4BACC,IAAI,EAAE,MAAe;4BACrB,IAAI,EAAE,oBAAoB,KAAK,kHAAgH;yBAC/I;qBACD;oBACD,OAAO,EAAE,SAAS;iBAClB,CAAC;YACH,CAAC;YAED,MAAM,QAAQ,GAAG,YAAY,EAAE,CAAC;YAChC,MAAM,IAAI,GAAG,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,WAAW,CAAC,GAAG,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAC1E,mEAAmE;YACnE,4DAA4D;YAC5D,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,mEAAiE,CAAC;YAC7G,OAAO;gBACN,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAe,EAAE,IAAI,EAAE,gBAAgB,KAAK,OAAO,IAAI,GAAG,IAAI,EAAE,EAAE,CAAC;gBACrF,OAAO,EAAE,SAAS;aAClB,CAAC;QAAA,CACF;KACiB,CAAC,CAAC;AAAA,CACrB;AAED,uEAAuE;AACvE,MAAM,UAAU,kBAAkB,GAAS;IAC1C,cAAc,GAAG,KAAK,CAAC;IACvB,aAAa,GAAG,EAAE,CAAC;AAAA,CACnB","sourcesContent":["/**\n * SearchHooCode — retrieval over hoocode's own docs and the capabilities this\n * session actually has.\n *\n * The system prompt already lists every shipped doc with a one-line summary\n * (see `core/self-docs.ts`), which answers \"which file covers extensions?\".\n * What it cannot answer is anything *inside* a file: `extensions.md` alone is\n * over a thousand lines, and reading it whole to find one heading costs more\n * context than the rest of the prompt put together. This indexes docs at the\n * heading level so a question lands on a section and a line number.\n *\n * It also registers the capability kinds the registry has always declared but\n * nobody ever filled — `skill`, `command`, `agent`, `plugin-installed`\n * (registry.ts notes §6.4 left them eager). Those are eager in the prompt, so\n * indexing them is not about reachability; it is about \"what can you do?\"\n * having one place that answers it rather than the model reciting whichever\n * list happens to be in front of it.\n *\n * `mcp-tool` is deliberately out of scope: ResolveMcpTools owns that kind\n * because finding an MCP tool and making it callable are the same action\n * there, and a second searcher that returns un-resolvable names would be a\n * worse answer, not an extra one.\n */\n\nimport type { Static } from \"typebox\";\nimport { Type } from \"typebox\";\nimport { ensureDenseIndex } from \"../../core/capabilities/dense.js\";\nimport { type CapabilityDoc, getCapabilities, registerCapabilities } from \"../../core/capabilities/registry.js\";\nimport { resetCapabilitySearch, searchCapabilities } from \"../../core/capabilities/search.js\";\nimport type { BeforeAgentStartEvent, ExtensionAPI, ToolDefinition } from \"../../core/extensions/types.js\";\nimport { listSelfDocSections, sectionLabel } from \"../../core/self-docs.js\";\n\nconst SEARCH_HOOCODE_TOOL_NAME = \"SearchHooCode\";\n\n/** Kinds this tool searches. `mcp-tool` belongs to ResolveMcpTools. */\nconst SEARCHABLE = [\"doc\", \"skill\", \"command\", \"agent\", \"plugin-installed\"] as const;\n\nconst DEFAULT_LIMIT = 8;\nconst MAX_LIMIT = 25;\n\n/** Registered once per process; the docs are read-only install content. */\nlet docsRegistered = false;\n\n/**\n * Index the shipped docs, the first time anyone asks.\n *\n * Lazy because it reads thirty files and produces roughly a thousand sections.\n * A session that never asks hoocode about itself should not pay for that at\n * startup, and the cost is invisible once paid — `listSelfDocSections` caches.\n */\nfunction ensureDocsRegistered(): void {\n\tif (docsRegistered) return;\n\tdocsRegistered = true;\n\n\tconst sections = listSelfDocSections();\n\tif (sections.length === 0) return;\n\n\tregisterCapabilities(\n\t\t\"doc\",\n\t\tsections.map(\n\t\t\t(section): CapabilityDoc => ({\n\t\t\t\tid: `doc:${section.id}`,\n\t\t\t\tkind: \"doc\",\n\t\t\t\tname: sectionLabel(section),\n\t\t\t\tdescription: section.excerpt,\n\t\t\t\tsource: section.path,\n\t\t\t\t// The body is withheld until the model reads the file, which is\n\t\t\t\t// exactly the condition this flag records.\n\t\t\t\tdeferred: true,\n\t\t\t}),\n\t\t),\n\t);\n\tresetCapabilitySearch();\n}\n\n/** Line-number lookup for rendering a hit, keyed by the id we registered under. */\nfunction sectionIndex(): Map<string, { path: string; line: number }> {\n\tconst index = new Map<string, { path: string; line: number }>();\n\tfor (const section of listSelfDocSections()) {\n\t\tindex.set(`doc:${section.id}`, { path: section.path, line: section.line });\n\t}\n\treturn index;\n}\n\n/**\n * Mirror the session's skills, commands, and subagents into the registry.\n *\n * Driven from `before_agent_start` because that is where the assembled\n * `systemPromptOptions` carries the skills and agents the session actually\n * loaded — re-discovering them from disk here would risk disagreeing with what\n * the model was told. Guarded by a signature so a steady session registers once\n * instead of dropping the lexical index on every turn.\n */\nlet lastSignature = \"\";\n\nfunction registerSessionCapabilities(event: BeforeAgentStartEvent, pi: ExtensionAPI): void {\n\tconst skills = event.systemPromptOptions.skills ?? [];\n\tconst agents = event.systemPromptOptions.agents ?? [];\n\tlet commands: Array<{ name: string; description?: string }> = [];\n\ttry {\n\t\tcommands = pi.getCommands();\n\t} catch {\n\t\t// Commands are an interactive-mode concern; a headless session may not\n\t\t// have them. Missing commands is not a reason to skip skills and agents.\n\t\tcommands = [];\n\t}\n\n\tconst signature = [\n\t\tskills.map((s) => s.name).join(\",\"),\n\t\tagents.map((a) => a.name).join(\",\"),\n\t\tcommands.map((c) => c.name).join(\",\"),\n\t].join(\"|\");\n\tif (signature === lastSignature) return;\n\tlastSignature = signature;\n\n\tregisterCapabilities(\n\t\t\"skill\",\n\t\tskills.map(\n\t\t\t(skill): CapabilityDoc => ({\n\t\t\t\tid: `skill:${skill.name}`,\n\t\t\t\tkind: \"skill\",\n\t\t\t\tname: skill.name,\n\t\t\t\tdescription: skill.description ?? \"\",\n\t\t\t\tsource: skill.filePath,\n\t\t\t\t// Eager: the prompt already lists these, so a hit is a convenience.\n\t\t\t\tdeferred: false,\n\t\t\t}),\n\t\t),\n\t);\n\tregisterCapabilities(\n\t\t\"agent\",\n\t\tagents.map(\n\t\t\t(agent): CapabilityDoc => ({\n\t\t\t\tid: `agent:${agent.name}`,\n\t\t\t\tkind: \"agent\",\n\t\t\t\tname: agent.name,\n\t\t\t\tdescription: agent.description ?? \"\",\n\t\t\t\tdeferred: false,\n\t\t\t}),\n\t\t),\n\t);\n\tregisterCapabilities(\n\t\t\"command\",\n\t\tcommands.map(\n\t\t\t(command): CapabilityDoc => ({\n\t\t\t\tid: `command:${command.name}`,\n\t\t\t\tkind: \"command\",\n\t\t\t\tname: `/${command.name}`,\n\t\t\t\tdescription: command.description ?? \"\",\n\t\t\t\tdeferred: false,\n\t\t\t}),\n\t\t),\n\t);\n\tresetCapabilitySearch();\n}\n\nfunction describeHit(doc: CapabilityDoc, sections: Map<string, { path: string; line: number }>): string {\n\tif (doc.kind === \"doc\") {\n\t\tconst where = sections.get(doc.id);\n\t\tconst location = where ? `${where.path}:${where.line}` : (doc.source ?? \"\");\n\t\treturn `- [doc] ${doc.name}\\n  read ${location}\\n  ${doc.description}`;\n\t}\n\tconst summary = doc.description ? ` — ${doc.description}` : \"\";\n\treturn `- [${doc.kind}] ${doc.name}${summary}`;\n}\n\nexport function setupSelfKnowledge(pi: ExtensionAPI): void {\n\tpi.on(\"before_agent_start\", (event: BeforeAgentStartEvent) => {\n\t\tregisterSessionCapabilities(event, pi);\n\t});\n\n\tconst params = Type.Object(\n\t\t{\n\t\t\tquery: Type.String({\n\t\t\t\tdescription:\n\t\t\t\t\t\"What you want to know about hoocode, in your own words — 'how do I write an extension', \" +\n\t\t\t\t\t\"'where are sessions stored', 'can it run subagents'.\",\n\t\t\t}),\n\t\t\tlimit: Type.Optional(Type.Number({ description: `Maximum results. Default ${DEFAULT_LIMIT}.` })),\n\t\t},\n\t\t{ additionalProperties: false },\n\t);\n\n\tpi.registerTool({\n\t\tname: SEARCH_HOOCODE_TOOL_NAME,\n\t\tlabel: SEARCH_HOOCODE_TOOL_NAME,\n\t\tdescription:\n\t\t\t\"Search hoocode's own documentation and the capabilities loaded in this session (skills, slash \" +\n\t\t\t\"commands, subagents, installed plugins). Use it when the user asks what hoocode can do, how one of \" +\n\t\t\t\"its features works, or how to configure or extend it. Doc results come back as a file path and line \" +\n\t\t\t\"number — read that range for the answer rather than replying from the excerpt alone. \" +\n\t\t\t\"MCP tools are not covered here; find those with ResolveMcpTools.\",\n\t\tpromptSnippet: \"Search hoocode's own docs and this session's capabilities by describing what you need.\",\n\t\tpromptGuidelines: [\n\t\t\t\"For questions about hoocode itself — its features, configuration, or how to extend it — use SearchHooCode and read the section it points at instead of answering from memory.\",\n\t\t],\n\t\tparameters: params,\n\t\texecutionMode: \"parallel\",\n\t\tasync execute(_toolCallId: string, args: Static<typeof params>) {\n\t\t\tconst query = args.query?.trim();\n\t\t\tif (!query) {\n\t\t\t\treturn { content: [{ type: \"text\" as const, text: \"Provide a query.\" }], details: undefined };\n\t\t\t}\n\n\t\t\tensureDocsRegistered();\n\t\t\tconst limit = Math.min(Math.max(1, Math.trunc(args.limit ?? DEFAULT_LIMIT)), MAX_LIMIT);\n\n\t\t\t// Fire-and-forget over everything registered, not just the docs: the\n\t\t\t// dense store is shared, so indexing a subset here would evict whatever\n\t\t\t// the MCP resolver indexed. The lexical leg answers this call either way.\n\t\t\tvoid ensureDenseIndex(getCapabilities()).catch(() => {});\n\n\t\t\tconst { hits, legs } = await searchCapabilities(query, { kinds: [...SEARCHABLE], limit });\n\t\t\tif (hits.length === 0) {\n\t\t\t\treturn {\n\t\t\t\t\tcontent: [\n\t\t\t\t\t\t{\n\t\t\t\t\t\t\ttype: \"text\" as const,\n\t\t\t\t\t\t\ttext: `Nothing matched \"${query}\". The docs are listed in the system prompt under \"About hoocode itself\" — read the most likely file directly.`,\n\t\t\t\t\t\t},\n\t\t\t\t\t],\n\t\t\t\t\tdetails: undefined,\n\t\t\t\t};\n\t\t\t}\n\n\t\t\tconst sections = sectionIndex();\n\t\t\tconst body = hits.map((hit) => describeHit(hit.doc, sections)).join(\"\\n\");\n\t\t\t// Say which legs answered: lexical-only on a conceptual query is a\n\t\t\t// weaker result, and the caller should be able to see that.\n\t\t\tconst note = legs.includes(\"dense\") ? \"\" : \"\\n(Lexical match only — try naming the feature if this missed.)\";\n\t\t\treturn {\n\t\t\t\tcontent: [{ type: \"text\" as const, text: `Results for \"${query}\":\\n${body}${note}` }],\n\t\t\t\tdetails: undefined,\n\t\t\t};\n\t\t},\n\t} as ToolDefinition);\n}\n\n/** Tests, and anything that relocates the package root mid-process. */\nexport function resetSelfKnowledge(): void {\n\tdocsRegistered = false;\n\tlastSignature = \"\";\n}\n"]}

package/docs/canvas.md

@@ -0,0 +1,117 @@
+# Canvas extensions
+
+A canvas extension is a separate process that serves an interactive surface —
+a web UI the agent can also drive — while the session keeps running. Canvases
+are how a task that needs a real interface (a diff explorer, a chart, a form)
+gets one without leaving the terminal.
+
+hoocode implements GitHub's canvas wire protocol, so extensions written for
+GitHub Copilot work unchanged.
+
+## Using canvases
+
+```
+/canvas list                              # what the loaded extensions provide
+/canvas open <extension>[:<canvas>]       # open one
+/canvas reload [extension]                # pick up code changes without restarting
+/canvas close <instanceId>                # close a running one
+/canvas rename <extension> <new-name>     # rename everywhere the name appears
+/canvas remove <extension>                # delete it, after confirming
+```
+
+Esc during an open cancels it, and the extension is told to release any port it
+had already bound — the spinner disappearing is not the whole story.
+
+`rename` matters more than it looks: a canvas's name lives in four places — the
+directory (which *is* the extension id), the canvas's own `id`, its
+`displayName`, and its header comment. Getting the `id` wrong by hand drops the
+canvas you are looking at on the next reload. `rename` does all four at once,
+closes what was open first, and prints every line it rewrote; it only touches a
+string that is *entirely* the old name, so a sentence merely mentioning the
+canvas is reported rather than rewritten.
+
+`rename` and `remove` both refuse a canvas that came from a plugin, and point at
+`/plugin` instead.
+
+## Reloading
+
+Editing an extension's code while it is open used to do nothing: the running
+process was forked from the old code, so neither the open page nor a newly
+opened second instance saw the change, and only restarting the session helped.
+
+`/canvas reload` (and the `reload_canvas` tool) forks the new code and asks it
+for its declarations **before** stopping the old process, so an edit that does
+not run leaves the canvas you are looking at exactly as it was and reports the
+error instead.
+
+Instances keep their ids and the input they were opened with, but each gets a
+**new url** — the extension binds a new port and mints a new token on every
+open — so the previous browser tab is dead and the replacement url is printed.
+
+## Discovery
+
+An extension is a directory containing an `extension.mjs` entry file. That file
+is the entire detection contract: no `package.json` is read, and the directory
+name is the extension id.
+
+Search roots, in precedence order:
+
+| Directory | Scope |
+|-----------|-------|
+| `./.agents/extensions/` | Project (hoocode convention) |
+| `./.github/extensions/` | Project (Copilot convention) |
+| `~/.copilot/extensions/` | User |
+
+Only ES modules are supported.
+
+Plugins can also ship canvases; see [Plugins](plugins.md).
+
+## Trust
+
+`.github/extensions/` travels with a clone, so a canvas extension found there is
+repository-supplied code. A canvas extension is a process **that also opens a
+listening socket**, so it sits behind the same workspace-trust record as plugin
+hooks and MCP servers — granted with `/plugin trust`, revoked with
+`/plugin untrust`, and stored outside the repository so repository content
+cannot forge it. See [Plugins → Trust](plugins.md#trust).
+
+Discovery itself is read-only and always runs; the gate applies before an
+extension is forked.
+
+## Agent-facing tools
+
+These register on the **first successful open** and stay for the session:
+
+| Tool | Purpose |
+|------|---------|
+| `list_canvas_capabilities` | What is open and which actions each instance declares |
+| `invoke_canvas_action` | Call an action on an instance, with input matching its declared schema |
+| `reload_canvas` | Re-fork an extension after its code changed, keeping instance ids |
+
+A session that never opens a canvas pays nothing for them, and they answer
+honestly when nothing is open.
+
+## Authoring
+
+```
+/new-canvas <what it should do>          # scaffold, open, and build it
+/new-canvas <name>                       # scaffold the template only
+/new-canvas <name>: <what it should do>  # name it yourself, then build
+```
+
+Given a description, hoocode scaffolds the extension, derives and reports a
+directory name, opens the canvas, and hands the agent a brief to build it —
+which you then steer like any other turn, with `reload_canvas` picking up each
+edit. Given a bare name, you get the template to edit by hand and no build
+starts.
+
+Scaffolding into the project grants workspace trust, since you are demonstrably
+working in the directory on purpose.
+
+hoocode ships one canvas of its own at `.agents/extensions/arrow-key-games/`
+(`/canvas open arrow-key-games`), built this way.
+
+## Related
+
+- [Extensions](extensions.md) — in-process TypeScript extensions, which canvases are not
+- [Plugins](plugins.md) — distribution and the shared trust model

package/docs/compaction.md

@@ -2,7 +2,7 @@
 
 LLMs have limited context windows. When conversations grow too long, hoocode uses compaction to summarize older content while preserving recent work. This page covers both auto-compaction and branch summarization.
 
-**Source files** ([pi-mono](https://github.com/kolisachint/hoocode)):
+**Source files** ([hoocode](https://github.com/kolisachint/hoocode)):
 - [`packages/coding-agent/src/core/compaction/compaction.ts`](https://github.com/kolisachint/hoocode/blob/main/packages/coding-agent/src/core/compaction/compaction.ts) - Auto-compaction logic
 - [`packages/coding-agent/src/core/compaction/branch-summarization.ts`](https://github.com/kolisachint/hoocode/blob/main/packages/coding-agent/src/core/compaction/branch-summarization.ts) - Branch summarization
 - [`packages/coding-agent/src/core/compaction/utils.ts`](https://github.com/kolisachint/hoocode/blob/main/packages/coding-agent/src/core/compaction/utils.ts) - Shared utilities (file tracking, serialization)
@@ -32,13 +32,13 @@ Auto-compaction triggers when:
 contextTokens > contextWindow - reserveTokens
 ```
 
-By default, `reserveTokens` is 16384 tokens (configurable in `~/.hoocode/agent/settings.json` or `<project-dir>/.hoocode/settings.json`). This leaves room for the LLM's response.
+By default, `reserveTokens` is 16384 tokens (configurable in `~/.hoocode/settings.json` or `<project-dir>/.hoocode/settings.json`). This leaves room for the LLM's response.
 
 You can also trigger manually with `/compact [instructions]`, where optional instructions focus the summary.
 
 ### How It Works
 
-1. **Find cut point**: Walk backwards from newest message, accumulating token estimates until `keepRecentTokens` (default 20k, configurable in `~/.hoocode/agent/settings.json` or `<project-dir>/.hoocode/settings.json`) is reached
+1. **Find cut point**: Walk backwards from newest message, accumulating token estimates until `keepRecentTokens` (default 20k, configurable in `~/.hoocode/settings.json` or `<project-dir>/.hoocode/settings.json`) is reached
 2. **Extract messages**: Collect messages from the previous kept boundary (or session start) up to the cut point
 3. **Generate summary**: Call LLM to summarize with structured format, passing the previous summary as iterative context when present
 4. **Append entry**: Save `CompactionEntry` with summary and `firstKeptEntryId`
@@ -373,7 +373,7 @@ See `SessionBeforeTreeEvent` and `TreePreparation` in the types file.
 
 ## Settings
 
-Configure compaction in `~/.hoocode/agent/settings.json` or `<project-dir>/.hoocode/settings.json`:
+Configure compaction in `~/.hoocode/settings.json` or `<project-dir>/.hoocode/settings.json`:
 
 ```json
 {

package/docs/custom-provider.md

@@ -330,7 +330,7 @@ interface OAuthLoginCallbacks {
 
 ### OAuthCredentials
 
-Credentials are persisted in `~/.hoocode/agent/auth.json`:
+Credentials are persisted in `~/.hoocode/auth.json`:
 
 ```typescript
 interface OAuthCredentials {

package/docs/development.md

@@ -48,7 +48,7 @@ Never use `__dirname` directly for package assets.
 
 ## Debug Command
 
-`/debug` (hidden) writes to `~/.hoocode/agent/hoocode-debug.log`:
+`/debug` (hidden) writes to `~/.hoocode/hoocode-debug.log`:
 - Rendered TUI lines with ANSI codes
 - Last messages sent to the LLM
 

package/docs/docs.json

@@ -12,7 +12,7 @@
           "path": "quickstart.md"
         },
         {
-          "title": "Using Pi",
+          "title": "Using HooCode",
           "path": "usage.md"
         },
         {
@@ -34,6 +34,31 @@
         {
           "title": "Compaction",
           "path": "compaction.md"
+        },
+        {
+          "title": "Modes",
+          "path": "modes.md"
+        }
+      ]
+    },
+    {
+      "title": "Extending hoocode",
+      "items": [
+        {
+          "title": "MCP",
+          "path": "mcp.md"
+        },
+        {
+          "title": "Plugins",
+          "path": "plugins.md"
+        },
+        {
+          "title": "Canvas",
+          "path": "canvas.md"
+        },
+        {
+          "title": "Subagent delegation",
+          "path": "routing.md"
         }
       ]
     },
@@ -57,7 +82,7 @@
           "path": "themes.md"
         },
         {
-          "title": "Pi Packages",
+          "title": "HooCode Packages",
           "path": "packages.md"
         },
         {

package/docs/extensions.md

@@ -4,7 +4,7 @@
 
 Extensions are TypeScript modules that extend hoocode's behavior. They can subscribe to lifecycle events, register custom tools callable by the LLM, add commands, and more.
 
-> **Placement for /reload:** Put extensions in `~/.hoocode/agent/extensions/` (global) or `.hoocode/extensions/` (project-local) for auto-discovery. Use `hoocode -e ./path.ts` only for quick tests. Extensions in auto-discovered locations can be hot-reloaded with `/reload`.
+> **Placement for /reload:** Put extensions in `~/.hoocode/extensions/` (global) or `.hoocode/extensions/` (project-local) for auto-discovery. Use `hoocode -e ./path.ts` only for quick tests. Extensions in auto-discovered locations can be hot-reloaded with `/reload`.
 
 **Key capabilities:**
 - **Custom tools** - Register tools the LLM can call via `pi.registerTool()`
@@ -54,7 +54,7 @@ See [examples/extensions/](../examples/extensions/) for working implementations.
 
 ## Quick Start
 
-Create `~/.pi/agent/extensions/my-extension.ts`:
+Create `~/.hoocode/extensions/my-extension.ts`:
 
 ```typescript
 import type { ExtensionAPI } from "@kolisachint/hoocode-agent";
@@ -113,10 +113,10 @@ Extensions are auto-discovered from:
 
 | Location | Scope |
 |----------|-------|
-| `~/.pi/agent/extensions/*.ts` | Global (all projects) |
-| `~/.pi/agent/extensions/*/index.ts` | Global (subdirectory) |
-| `.pi/extensions/*.ts` | Project-local |
-| `.pi/extensions/*/index.ts` | Project-local (subdirectory) |
+| `~/.hoocode/extensions/*.ts` | Global (all projects) |
+| `~/.hoocode/extensions/*/index.ts` | Global (subdirectory) |
+| `.hoocode/extensions/*.ts` | Project-local |
+| `.hoocode/extensions/*/index.ts` | Project-local (subdirectory) |
 
 Additional paths via `settings.json`:
 
@@ -221,14 +221,14 @@ This pattern makes the fetched models available during normal startup and to `ho
 **Single file** - simplest, for small extensions:
 
 ```
-~/.pi/agent/extensions/
+~/.hoocode/extensions/
 └── my-extension.ts
 ```
 
 **Directory with index.ts** - for multi-file extensions:
 
 ```
-~/.pi/agent/extensions/
+~/.hoocode/extensions/
 └── my-extension/
     ├── index.ts        # Entry point (exports default function)
     ├── tools.ts        # Helper module
@@ -238,7 +238,7 @@ This pattern makes the fetched models available during normal startup and to `ho
 **Package with dependencies** - for extensions that need npm packages:
 
 ```
-~/.pi/agent/extensions/
+~/.hoocode/extensions/
 └── my-extension/
     ├── package.json    # Declares dependencies and entry points
     ├── package-lock.json
@@ -496,7 +496,7 @@ pi.on("before_agent_start", async (event, ctx) => {
 });
 ```
 
-The `systemPromptOptions` field gives extensions access to the same structured data Pi uses to build the system prompt. This lets you inspect what Pi has loaded — custom prompts, guidelines, tool snippets, context files, skills — without re-discovering resources or re-parsing flags. Use it when your extension needs to make deep, informed changes to the system prompt while respecting user-provided configuration.
+The `systemPromptOptions` field gives extensions access to the same structured data HooCode uses to build the system prompt. This lets you inspect what HooCode has loaded — custom prompts, guidelines, tool snippets, context files, skills — without re-discovering resources or re-parsing flags. Use it when your extension needs to make deep, informed changes to the system prompt while respecting user-provided configuration.
 
 Inside `before_agent_start`, `event.systemPrompt` and `ctx.getSystemPrompt()` both reflect the chained system prompt as of the current handler. Later `before_agent_start` handlers can still modify it again.
 
@@ -602,7 +602,7 @@ pi.on("context", async (event, ctx) => {
 
 Fired after the provider-specific payload is built, right before the request is sent. Handlers run in extension load order. Returning `undefined` keeps the payload unchanged. Returning any other value replaces the payload for later handlers and for the actual request.
 
-This hook can rewrite provider-level system instructions or remove them entirely. Those payload-level changes are not reflected by `ctx.getSystemPrompt()`, which reports Pi's system prompt string rather than the final serialized provider payload.
+This hook can rewrite provider-level system instructions or remove them entirely. Those payload-level changes are not reflected by `ctx.getSystemPrompt()`, which reports HooCode's system prompt string rather than the final serialized provider payload.
 
 ```typescript
 pi.on("before_provider_request", (event, ctx) => {
@@ -957,7 +957,7 @@ ctx.compact({
 
 ### ctx.getSystemPrompt()
 
-Returns Pi's current system prompt string.
+Returns HooCode's current system prompt string.
 
 - During `before_agent_start`, this reflects chained system-prompt changes made so far for the current turn.
 - It does not include later `context` message mutations.

package/docs/index.md

@@ -35,6 +35,14 @@ For the full first-run flow, see [Quickstart](quickstart.md).
 - [Keybindings](keybindings.md) - default shortcuts and custom keybindings.
 - [Sessions](sessions.md) - session management, branching, and tree navigation.
 - [Compaction](compaction.md) - context compaction and branch summarization.
+- [Modes](modes.md) - ask, plan, build, and debug, and the planning workflow.
+
+## Extending hoocode
+
+- [MCP](mcp.md) - connect Model Context Protocol servers and their tools.
+- [Plugins](plugins.md) - install capabilities from marketplaces, and the trust model.
+- [Canvas](canvas.md) - interactive surfaces the agent can drive.
+- [Subagent delegation](routing.md) - hand focused work to a separate agent.
 
 ## Customization
 

package/docs/keybindings.md

@@ -1,6 +1,6 @@
 # Keybindings
 
-All keyboard shortcuts can be customized via `~/.hoocode/agent/keybindings.json`. Each action can be bound to one or more keys.
+All keyboard shortcuts can be customized via `~/.hoocode/keybindings.json`. Each action can be bound to one or more keys.
 
 The config file uses the same namespaced keybinding ids that hoocode uses internally and that extension authors use in `keyHint()` and injected `keybindings` managers.
 
@@ -153,7 +153,7 @@ Used inside the scoped models selector (opened via `/scoped-models`).
 
 ## Custom Configuration
 
-Create `~/.hoocode/agent/keybindings.json`:
+Create `~/.hoocode/keybindings.json`:
 
 ```json
 {