@introspection-ai/pi-recipes 0.1.0-beta.0

package/README.md

@@ -0,0 +1,116 @@
+# @introspection-ai/pi-recipes
+
+Experimental Pi recipe tooling with a `recipes` CLI and Pi extension
+support.
+
+Recipes are Pi packages: folders with a `package.json` manifest containing a
+`pi` block, plus agent YAML files, prompts, skills, and optional TypeScript
+runtime extensions. The `recipes` CLI installs or registers recipes in a
+local store and ensures the Pi extension is installed before recipes are run.
+The Pi extension resolves an installed recipe into a local directory and wires
+those recipe files into the live Pi session at launch time.
+
+`package.json` owns both recipe identity and Node dependency metadata. The
+top-level `name`, `version`, and `description` identify the recipe, while the
+`pi` block declares recipe resources such as agents, extensions, skills,
+prompts, and themes.
+
+## Documentation
+
+- [Recipe Flow](docs/recipe-flow.md): quick user-facing guide to installing, customizing, creating, and publishing recipes.
+- [Recipe CLI](docs/recipe-cli.md): creating, installing, resolving, publishing, and removing recipes.
+- [Pi Recipe Extension](docs/pi-extension.md): installing the Pi extension, launching recipes, agent selection, resources, subagents, and recipe extension loading.
+
+## Package Exports
+
+- `@introspection-ai/pi-recipes`: extension factory and recipe-loading helpers.
+- `@introspection-ai/pi-recipes/pi-extension`: Pi extension entrypoint.
+- `@introspection-ai/pi-recipes/recipe-store`: recipe install and resolution helpers.
+
+## Quick Start
+
+Install the recipe tooling:
+
+```bash
+npm install -g @introspection-ai/pi-recipes
+```
+
+The first `recipes install ...` run automatically installs the companion Pi
+extension with `pi install npm:@introspection-ai/pi-recipes`.
+
+Create a local recipe:
+
+```bash
+recipes create ./my-recipe
+recipes doctor ./my-recipe
+recipes install ./my-recipe
+```
+
+Launch it with Pi:
+
+```bash
+pi --recipe my-recipe
+pi --recipe my-recipe --agent agent
+```
+
+`recipes create` writes a starter `package.json`, `SYSTEM.md`, `agents/agent.yaml`,
+and recipe README. Edit those files as the recipe grows. Named variants are
+agents too:
+
+```yaml
+name: agent-opus
+from: agent
+model:
+  name: openrouter/anthropic/claude-opus-4.8
+```
+
+## Install Recipes
+
+Install public GitHub recipes:
+
+```bash
+recipes install github:owner/repo
+recipes install github:owner/repo/path/to/recipe
+recipes install github:owner/repo#v1.0.0
+```
+
+Install private recipes with normal Git authentication:
+
+```bash
+recipes install git@github.com:owner/private-recipe.git
+GITHUB_TOKEN=... recipes install github:owner/private-recipe
+```
+
+No recipe registry is required. Publishing a recipe creates or updates a GitHub
+repository and pushes the local recipe:
+
+```bash
+recipes publish ./my-recipe --github owner/my-recipe --visibility private
+```
+
+Customize an installed recipe into an editable local copy:
+
+```bash
+recipes customize pi-codex
+recipes doctor pi-codex
+pi --recipe pi-codex
+```
+
+## Development
+
+```bash
+pnpm install
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+Install from a local clone into Pi:
+
+```bash
+pnpm build
+pi install "$(pwd)"
+```
+
+Pi records the local package path in `~/.pi/agent/settings.json`. Re-run
+`pnpm build` after changing extension source.

package/dist/child-agent.d.ts

@@ -0,0 +1,40 @@
+import { AuthStorage, type ModelRegistry } from "@earendil-works/pi-coding-agent";
+export interface CreateRecipeChildAgentRunnerOptions {
+    recipeDir: string;
+    workspaceDir: string;
+    agentName: string;
+    env?: NodeJS.ProcessEnv;
+    authStorage?: AuthStorage;
+    modelRegistry?: ModelRegistry;
+    onAssistantMessage?: (text: string, stream: "delta" | "final") => void;
+    onToolEvent?: (event: RecipeChildToolEvent) => void;
+}
+export interface RecipeChildAgentRunner {
+    start(): Promise<void>;
+    prompt(task: string): Promise<string>;
+    cancel(): Promise<void>;
+    shutdown(): Promise<void>;
+}
+export type CreateRecipeChildAgentRunner = (opts: CreateRecipeChildAgentRunnerOptions) => RecipeChildAgentRunner;
+export type RecipeChildToolEvent = {
+    type: "start";
+    id: string;
+    name: string;
+    args: unknown;
+} | {
+    type: "update";
+    id: string;
+    name: string;
+    args: unknown;
+    partialResult: unknown;
+} | {
+    type: "end";
+    id: string;
+    name: string;
+    args: unknown;
+    result: unknown;
+    isError: boolean;
+};
+export declare function promptResultText(result: unknown): string;
+export declare function createRecipeChildAgentRunner(opts: CreateRecipeChildAgentRunnerOptions): RecipeChildAgentRunner;
+//# sourceMappingURL=child-agent.d.ts.map

package/dist/child-agent.js

@@ -0,0 +1,235 @@
+import { getEnvApiKey, getModel } from "@earendil-works/pi-ai";
+import { AuthStorage, createAgentSessionFromServices, createAgentSessionServices, SessionManager, SettingsManager, } from "@earendil-works/pi-coding-agent";
+import { loadRecipeSystemPrompt, REQUIRED_RECIPE_AGENT_FIELDS, resolveRecipeAgentDefinition, validateResolvedRecipeAgentDefinition, } from "./recipe-agent.js";
+function parseModelSpec(spec) {
+    const slash = spec.indexOf("/");
+    if (slash < 0) {
+        throw new Error(`Invalid recipe model "${spec}" - expected "<provider>/<model_id>"`);
+    }
+    const provider = spec.slice(0, slash);
+    const modelId = spec.slice(slash + 1);
+    const lookupProvider = provider === "gemini" ? "google" : provider;
+    return { provider, modelId, lookupProvider };
+}
+function modelFromSpec(spec, modelRegistry) {
+    const { modelId, lookupProvider } = parseModelSpec(spec);
+    return (modelRegistry?.find(lookupProvider, modelId) ??
+        getModel(lookupProvider, modelId));
+}
+function authStorageForChildAgent(model, opts) {
+    if (opts.authStorage)
+        return opts.authStorage;
+    if (opts.modelRegistry)
+        return opts.modelRegistry.authStorage;
+    const env = opts.env ?? process.env;
+    const apiKey = getEnvApiKey(model.provider) ?? env[`${model.provider.toUpperCase()}_API_KEY`];
+    if (!apiKey) {
+        throw new Error(`${model.provider.toUpperCase()}_API_KEY is required when the recipe child agent is not running inside Pi`);
+    }
+    const authStorage = AuthStorage.inMemory();
+    authStorage.setRuntimeApiKey(model.provider, apiKey);
+    return authStorage;
+}
+function applySystemInstructions(base, instructions) {
+    if (!instructions)
+        return base;
+    if (instructions.mode === "replace")
+        return instructions.content;
+    return [base, instructions.content].filter(Boolean).join("\n\n");
+}
+function runtimeContextPrompt(workspaceDir, recipeDir) {
+    return [
+        "## Recipe Runtime Context",
+        "- Current workspace: " + workspaceDir,
+        "- Recipe directory: " + recipeDir,
+    ].join("\n");
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function contentText(content) {
+    if (typeof content === "string")
+        return content;
+    if (!Array.isArray(content))
+        return "";
+    return content
+        .map((part) => {
+        const record = asRecord(part);
+        return record?.type === "text" && typeof record.text === "string"
+            ? record.text
+            : "";
+    })
+        .filter(Boolean)
+        .join("\n");
+}
+export function promptResultText(result) {
+    if (typeof result === "string")
+        return result;
+    if (!result || typeof result !== "object")
+        return "";
+    const record = result;
+    if (typeof record.output === "string")
+        return record.output;
+    const messages = Array.isArray(record.messages) ? record.messages : [];
+    for (let index = messages.length - 1; index >= 0; index -= 1) {
+        const message = asRecord(messages[index]);
+        if (!message)
+            continue;
+        if (message.role && message.role !== "assistant")
+            continue;
+        const text = contentText(message.content).trim();
+        if (text)
+            return text;
+    }
+    return "";
+}
+function messageFromEvent(event) {
+    const record = asRecord(event);
+    const direct = asRecord(record?.message);
+    if (direct)
+        return direct;
+    const assistantEvent = asRecord(record?.assistantMessageEvent);
+    return asRecord(assistantEvent?.partial);
+}
+class RecipeChildAgentSessionRunner {
+    opts;
+    session = null;
+    unsubscribe = null;
+    assistantStreamedText = false;
+    constructor(opts) {
+        this.opts = opts;
+    }
+    emitAssistantText(text, stream) {
+        const trimmed = text.trim();
+        if (!trimmed)
+            return;
+        this.opts.onAssistantMessage?.(trimmed, stream);
+        if (stream === "delta")
+            this.assistantStreamedText = true;
+    }
+    handleSessionEvent(event) {
+        const record = asRecord(event);
+        const message = messageFromEvent(event);
+        const role = typeof message?.role === "string" ? message.role : undefined;
+        if (record?.type === "tool_execution_start") {
+            this.opts.onToolEvent?.({
+                type: "start",
+                id: String(record.toolCallId ?? ""),
+                name: String(record.toolName ?? ""),
+                args: record.args,
+            });
+            return;
+        }
+        if (record?.type === "tool_execution_update") {
+            this.opts.onToolEvent?.({
+                type: "update",
+                id: String(record.toolCallId ?? ""),
+                name: String(record.toolName ?? ""),
+                args: record.args,
+                partialResult: record.partialResult,
+            });
+            return;
+        }
+        if (record?.type === "tool_execution_end") {
+            this.opts.onToolEvent?.({
+                type: "end",
+                id: String(record.toolCallId ?? ""),
+                name: String(record.toolName ?? ""),
+                args: record.args,
+                result: record.result,
+                isError: record.isError === true,
+            });
+            return;
+        }
+        if (record?.type === "message_start" && role === "assistant") {
+            this.assistantStreamedText = false;
+        }
+        const assistantEvent = asRecord(record?.assistantMessageEvent);
+        if (role === "assistant" &&
+            record?.type === "message_update" &&
+            assistantEvent?.type === "text_delta" &&
+            typeof assistantEvent.delta === "string") {
+            this.emitAssistantText(assistantEvent.delta, "delta");
+            return;
+        }
+        if (role === "assistant" &&
+            record?.type === "message_end" &&
+            !this.assistantStreamedText) {
+            this.emitAssistantText(contentText(message?.content), "final");
+        }
+    }
+    async start() {
+        if (this.session)
+            return;
+        const { agentName, agent } = resolveRecipeAgentDefinition({
+            recipeDir: this.opts.recipeDir,
+            agentName: this.opts.agentName,
+        });
+        if (!agent) {
+            throw new Error(`Recipe agent not found: ${agentName}`);
+        }
+        const validationFindings = validateResolvedRecipeAgentDefinition({
+            recipeDir: this.opts.recipeDir,
+            agentName,
+            requireExplicitName: true,
+            requiredFields: REQUIRED_RECIPE_AGENT_FIELDS,
+        });
+        if (validationFindings.length > 0) {
+            throw new Error(validationFindings.map((finding) => finding.message).join("\n"));
+        }
+        const modelSpec = agent.model?.name;
+        if (!modelSpec) {
+            throw new Error(`Recipe agent "${agentName}" must declare model.name`);
+        }
+        const model = modelFromSpec(modelSpec, this.opts.modelRegistry);
+        const authStorage = authStorageForChildAgent(model, this.opts);
+        const services = await createAgentSessionServices({
+            cwd: this.opts.workspaceDir,
+            agentDir: this.opts.recipeDir,
+            authStorage,
+            modelRegistry: this.opts.modelRegistry,
+            settingsManager: SettingsManager.create(this.opts.workspaceDir, this.opts.recipeDir),
+            resourceLoaderOptions: {
+                systemPromptOverride: (base) => applySystemInstructions(loadRecipeSystemPrompt(this.opts.recipeDir) ?? base, agent.systemInstructions),
+                appendSystemPromptOverride: (base) => [
+                    ...base,
+                    runtimeContextPrompt(this.opts.workspaceDir, this.opts.recipeDir),
+                ],
+            },
+        });
+        const created = await createAgentSessionFromServices({
+            services,
+            sessionManager: SessionManager.inMemory(this.opts.workspaceDir),
+            model,
+            thinkingLevel: (agent.model?.thinkingLevel ?? "low"),
+            tools: agent.tools.length > 0 ? agent.tools : undefined,
+        });
+        this.session = created.session;
+        await this.session.bindExtensions({});
+        this.unsubscribe = this.session.subscribe((event) => {
+            this.handleSessionEvent(event);
+        });
+    }
+    async prompt(task) {
+        await this.start();
+        if (!this.session)
+            throw new Error("Recipe child agent did not start");
+        await this.session.prompt(task);
+        return promptResultText({ messages: [...this.session.messages] });
+    }
+    async cancel() {
+        await this.session?.abort();
+    }
+    async shutdown() {
+        this.unsubscribe?.();
+        this.unsubscribe = null;
+        this.session?.dispose();
+        this.session = null;
+    }
+}
+export function createRecipeChildAgentRunner(opts) {
+    return new RecipeChildAgentSessionRunner(opts);
+}
+//# sourceMappingURL=child-agent.js.map

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map