pi-t3-bridge 0.5.0 → 0.6.0

package/README.md

@@ -223,6 +223,26 @@ sequenceDiagram
     Note over Parent: the extension adds the report from the ledger
 ```
 
+## pi-amplike in T3
+
+`amplike.ts` adapts [pi-amplike](https://github.com/pasky/pi-amplike) for T3 threads. T3 shows Pi's `notify`, `select`, `confirm`, `input` and `editor` calls. It drops widgets, status lines, custom UI and key presses, and it resumes a thread from the session file it first recorded. So in T3, amplike's subagents, `/btw` and handoff show nothing or break. To use the adapter, turn off amplike's own extensions in `~/.pi/agent/settings.json` and keep its skills:
+
+```json
+{ "source": "npm:pi-amplike", "extensions": [] }
+```
+
+`amplike.ts` then loads amplike's extensions itself. Outside T3 they load unchanged. In a T3 thread, the adapter changes these parts:
+
+| amplike | In a T3 thread |
+| --- | --- |
+| `subagent` tool | Off. T3's `delegate_task` runs subagents. |
+| `/btw <prompt>` | Starts a `delegate_task` child that reads this thread's session with `session_query`. Its answer wakes this thread. |
+| `handoff` tool and `/handoff <goal>` | Writes a summary with the session model, then starts a new T3 thread with `t3_thread_launch`. The new thread gets the goal, the summary and the parent session file. This thread keeps its session. |
+| `/mode` | Works as in the terminal. Each model or thinking change also goes to `t3_thread_configure`, so T3's model picker matches. |
+| Shortcuts | Off. T3 sends Pi no key presses. |
+
+`session_query`, `/permissions` and amplike's skills work unchanged. While amplike still loads its own extensions, the adapter does nothing, and a T3 thread shows a notice with the settings change.
+
 ## Configuration
 
 The bridge reads one JSON file per machine, at `~/.config/pi-t3/config.json`. Every key is optional. The bridge reads the file again on each prompt, so an edit applies on the next prompt. When one value is invalid, only the invalid key falls back to its default, and the bridge tells you once.

package/amplike.ts

@@ -0,0 +1,46 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import {
+  findAmplike,
+  loadFactory,
+  loadModeSpecFrom,
+} from "./src/amplike/package.ts";
+import { t3View } from "./src/amplike/t3-view.ts";
+import { insideT3 } from "./src/bridge/t3-http.ts";
+
+// Loads pi-amplike's extensions in place of Pi, so a T3 thread gets T3's
+// versions of the parts T3 can't show. Outside T3 amplike loads unchanged.
+// It runs only when the settings entry for amplike turns its extensions off.
+const amplikeExtension = async (pi: ExtensionAPI): Promise<void> => {
+  const amplike = await findAmplike(process.cwd());
+
+  if (amplike === undefined) {
+    return;
+  }
+
+  if (amplike.selfLoaded) {
+    if (insideT3()) {
+      pi.on("session_start", (_event, ctx) => {
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            `pi-t3 can't adapt pi-amplike for T3 while pi-amplike loads its own extensions. In ~/.pi/agent/settings.json, change "${amplike.source}" to {"source":"${amplike.source}","extensions":[]}.`,
+            "warning"
+          );
+        }
+      });
+    }
+
+    return;
+  }
+
+  const host = insideT3()
+    ? t3View(pi, await loadModeSpecFrom(amplike.root))
+    : pi;
+
+  const factories = await Promise.all(amplike.extensions.map(loadFactory));
+
+  // Each call starts in file order, as when Pi loads the files itself.
+  await Promise.all(factories.map((factory) => factory(host)));
+};
+
+export default amplikeExtension;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-t3-bridge",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Pi extension adapter for t3-pstack inside T3 Code.",
   "keywords": [
     "pi-extension",
@@ -38,7 +38,8 @@
     "overlay",
     "LICENSE",
     "tstack.ts",
-    "tstack"
+    "tstack",
+    "amplike.ts"
   ],
   "type": "module",
   "scripts": {
@@ -81,7 +82,8 @@
     "extensions": [
       "./bridge.ts",
       "./tstack.ts",
-      "./pstack.ts"
+      "./pstack.ts",
+      "./amplike.ts"
     ]
   },
   "upstreams": {

package/src/amplike/btw.ts

@@ -0,0 +1,91 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+import { callT3Tool } from "../bridge/t3-http.ts";
+import type { LoadModeSpec } from "./package.ts";
+import {
+  changeFromFlags,
+  currentSelection,
+  isEmptyChange,
+  parseFlags,
+} from "./selection.ts";
+import type { SelectionChange } from "./selection.ts";
+
+type Command = Parameters<ExtensionAPI["registerCommand"]>[1];
+
+const DelegatedSchema = Type.Object({
+  link: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  taskId: Type.String(),
+});
+
+const TITLE_LENGTH = 80;
+
+const USAGE = "Usage: /btw [-mode <name>] [-model <provider/id>] <prompt>";
+
+// delegate_task's target for a Pi child: model as "provider/modelId", and the
+// thinking level as an option. A flag that names only one keeps the other.
+const targetFor = async (change: SelectionChange) => {
+  const current = await currentSelection();
+  const options: Record<string, string> = {};
+
+  if (change.thinking !== undefined) {
+    options.thinking = change.thinking;
+  }
+
+  return { model: change.model ?? current.model, options };
+};
+
+// In T3, /btw is a delegate_task child. The child shows up in T3, and its
+// result wakes this thread when it finishes.
+export const btwCommand = (loadModeSpec: LoadModeSpec): Command => ({
+  description:
+    "Ask a side question in a T3 child thread: /btw [-mode <name>] [-model <provider/id>] <prompt>",
+  handler: async (args, ctx) => {
+    try {
+      const { flags, text } = parseFlags(args);
+
+      if (text.length === 0) {
+        throw new Error(USAGE);
+      }
+
+      const change = await changeFromFlags(flags, ctx.cwd, loadModeSpec);
+      const parent = ctx.sessionManager.getSessionFile();
+
+      const task = [
+        "The user asked this side question while working in another thread. Answer it. Inspect only, change no file.",
+        text,
+        ...(parent === undefined
+          ? []
+          : [
+              `The other thread's Pi session file is \`${parent}\`. Call session_query on it for any context the question needs.`,
+            ]),
+      ].join("\n\n");
+
+      const delegate = {
+        mode: "async",
+        role: "research",
+        task,
+        title: `btw: ${text}`.slice(0, TITLE_LENGTH),
+      };
+
+      const delegated = isEmptyChange(change)
+        ? await callT3Tool("delegate_task", delegate)
+        : await callT3Tool("delegate_task", {
+            ...delegate,
+            target: await targetFor(change),
+          });
+
+      if (!Value.Check(DelegatedSchema, delegated)) {
+        throw new Error("delegate_task returned no task.");
+      }
+
+      ctx.ui.notify(
+        `btw started: ${delegated.link ?? delegated.taskId}`,
+        "info"
+      );
+    } catch (error) {
+      ctx.ui.notify(`btw failed: ${String(error)}`, "error");
+    }
+  },
+});

package/src/amplike/handoff.ts

@@ -0,0 +1,190 @@
+import type { Message } from "@earendil-works/pi-ai";
+import {
+  convertToLlm,
+  defineTool,
+  serializeConversation,
+} from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { Value } from "typebox/value";
+
+import { callT3Tool } from "../bridge/t3-http.ts";
+import type { LoadModeSpec } from "./package.ts";
+import {
+  applyChange,
+  changeFromFlags,
+  currentSelection,
+  isEmptyChange,
+  parseFlags,
+} from "./selection.ts";
+import type { Flags } from "./selection.ts";
+
+type Command = Parameters<ExtensionAPI["registerCommand"]>[1];
+
+const SUMMARY_PROMPT = `You write the first message of a new thread that continues work from a conversation. Given the conversation and the user's goal for the new thread, write a self-contained prompt with:
+
+## Context
+The decisions made, approaches taken, and key findings that matter for the goal.
+
+Files involved:
+- each relevant file that was discussed or changed
+
+## Task
+What the new thread should do next, based on the goal.
+
+Output only the prompt, with no preamble.`;
+
+const TITLE_LENGTH = 80;
+
+const LaunchSchema = Type.Object({
+  link: Type.Optional(Type.Union([Type.String(), Type.Null()])),
+  threadId: Type.String(),
+});
+
+const summarize = async (
+  ctx: ExtensionContext,
+  goal: string,
+  signal: AbortSignal | undefined
+): Promise<string> => {
+  const { model } = ctx;
+
+  if (model === undefined) {
+    throw new Error("No model selected.");
+  }
+
+  const messages = ctx.sessionManager
+    .getBranch()
+    .flatMap((entry) => (entry.type === "message" ? [entry.message] : []));
+
+  if (messages.length === 0) {
+    throw new Error("No conversation to hand off.");
+  }
+
+  const request: Message = {
+    content: [
+      {
+        text: `## Conversation\n\n${serializeConversation(convertToLlm(messages))}\n\n## Goal for the new thread\n\n${goal}`,
+        type: "text",
+      },
+    ],
+    role: "user",
+    timestamp: Date.now(),
+  };
+
+  const response = await ctx.modelRegistry
+    .streamSimple(
+      model,
+      { messages: [request], systemPrompt: SUMMARY_PROMPT },
+      { signal }
+    )
+    .result();
+
+  if (response.stopReason === "aborted" || response.stopReason === "error") {
+    throw new Error(
+      response.errorMessage ?? `The summary ${response.stopReason}.`
+    );
+  }
+
+  return response.content
+    .flatMap((part) => (part.type === "text" ? [part.text] : []))
+    .join("\n");
+};
+
+// In T3 a handoff is a new T3 thread. Pi keeps its own session file, which is
+// the one T3 resumes this thread from.
+const handoff = async (
+  ctx: ExtensionContext,
+  goal: string,
+  flags: Flags,
+  loadModeSpec: LoadModeSpec,
+  signal: AbortSignal | undefined
+): Promise<string> => {
+  const change = await changeFromFlags(flags, ctx.cwd, loadModeSpec);
+  const summary = await summarize(ctx, goal, signal);
+  const parent = ctx.sessionManager.getSessionFile();
+
+  const message = [
+    goal,
+    ...(parent === undefined
+      ? []
+      : ["/skill:session-query", `**Parent session:** \`${parent}\``]),
+    summary,
+  ].join("\n\n");
+
+  const launch = { message, title: goal.slice(0, TITLE_LENGTH) };
+
+  const launched = isEmptyChange(change)
+    ? await callT3Tool("t3_thread_launch", launch)
+    : await callT3Tool("t3_thread_launch", {
+        ...launch,
+        modelSelection: { ...applyChange(await currentSelection(), change) },
+      });
+
+  if (!Value.Check(LaunchSchema, launched)) {
+    throw new Error("t3_thread_launch returned no thread.");
+  }
+
+  return launched.link ?? launched.threadId;
+};
+
+export const handoffTool = (loadModeSpec: LoadModeSpec) =>
+  defineTool({
+    description:
+      "Transfer context to a new focused T3 thread. ONLY use this when the user explicitly asks for a handoff. Provide a goal describing what the new thread should focus on. The result is the new thread's link, which you show the user verbatim.",
+    execute: async (_toolCallId, params, signal, _onUpdate, ctx) => {
+      const link = await handoff(
+        ctx,
+        params.goal,
+        { mode: params.mode, model: params.model },
+        loadModeSpec,
+        signal
+      );
+
+      return {
+        content: [{ text: `Handoff thread started: ${link}`, type: "text" }],
+        details: { link },
+      };
+    },
+    label: "Handoff",
+    name: "handoff",
+    parameters: Type.Object({
+      goal: Type.String({ description: "The goal/task for the new thread" }),
+      mode: Type.Optional(
+        Type.String({
+          description:
+            "Amplike mode name to start the new thread with (e.g. 'rush', 'smart', 'deep')",
+        })
+      ),
+      model: Type.Optional(
+        Type.String({
+          description:
+            "Model to start the new thread with, as provider/modelId (e.g. 'anthropic/claude-haiku-4-5')",
+        })
+      ),
+    }),
+  });
+
+export const handoffCommand = (loadModeSpec: LoadModeSpec): Command => ({
+  description:
+    "Start a new T3 thread with a summary of this one: /handoff [-mode <name>] [-model <provider/id>] <goal>",
+  handler: async (args, ctx) => {
+    try {
+      const { flags, text } = parseFlags(args);
+
+      if (text.length === 0) {
+        throw new Error(
+          "Usage: /handoff [-mode <name>] [-model <provider/id>] <goal>"
+        );
+      }
+
+      const link = await handoff(ctx, text, flags, loadModeSpec, ctx.signal);
+
+      ctx.ui.notify(`Handoff thread started: ${link}`, "info");
+    } catch (error) {
+      ctx.ui.notify(`Handoff failed: ${String(error)}`, "error");
+    }
+  },
+});

package/src/amplike/package.ts

@@ -0,0 +1,123 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+
+import {
+  DefaultPackageManager,
+  getAgentDir,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import type {
+  ExtensionFactory,
+  ResolvedResource,
+} from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import type { Static } from "typebox";
+import { Value } from "typebox/value";
+
+const PACKAGE_NAME = "pi-amplike";
+
+const ManifestSchema = Type.Object({ name: Type.String() });
+
+const FactoryModuleSchema = Type.Object({
+  default: Type.Function([Type.Unknown()], Type.Unknown()),
+});
+
+const ModeUtilsSchema = Type.Object({
+  loadModeSpec: Type.Function([Type.String(), Type.String()], Type.Unknown()),
+});
+
+const ModeSpecSchema = Type.Object({
+  modelId: Type.Optional(Type.String()),
+  provider: Type.Optional(Type.String()),
+  thinkingLevel: Type.Optional(Type.String()),
+});
+
+export type ModeSpec = Static<typeof ModeSpecSchema>;
+
+export type LoadModeSpec = (
+  cwd: string,
+  name: string
+) => Promise<ModeSpec | undefined>;
+
+export interface Amplike {
+  readonly extensions: readonly string[];
+  readonly root: string;
+  // True when Pi loads amplike's extensions itself, so this adapter must not.
+  readonly selfLoaded: boolean;
+  readonly source: string;
+}
+
+const isAmplikeRoot = (root: string): boolean => {
+  try {
+    const manifest: unknown = JSON.parse(
+      readFileSync(path.join(root, "package.json"), "utf-8")
+    );
+
+    return (
+      Value.Check(ManifestSchema, manifest) && manifest.name === PACKAGE_NAME
+    );
+  } catch {
+    return false;
+  }
+};
+
+const isAmplike = (resource: ResolvedResource): boolean =>
+  resource.metadata.packageRoot !== undefined &&
+  isAmplikeRoot(resource.metadata.packageRoot);
+
+// Pi's own package manager gives the extension files amplike's manifest names,
+// and whether the settings entry for amplike turns them off.
+export const findAmplike = async (
+  cwd: string
+): Promise<Amplike | undefined> => {
+  const agentDir = getAgentDir();
+
+  const manager = new DefaultPackageManager({
+    agentDir,
+    cwd,
+    settingsManager: SettingsManager.create(cwd, agentDir),
+  });
+
+  const resolved = await manager.resolve(async () => "skip");
+  const own = resolved.extensions.filter(isAmplike);
+  const [first] = own;
+
+  if (first?.metadata.packageRoot === undefined) {
+    return undefined;
+  }
+
+  return {
+    extensions: own.map((resource) => resource.path),
+    root: first.metadata.packageRoot,
+    selfLoaded: own.some((resource) => resource.enabled),
+    source: first.metadata.source,
+  };
+};
+
+export const loadFactory = async (file: string): Promise<ExtensionFactory> => {
+  const module: unknown = await import(file);
+
+  if (!Value.Check(FactoryModuleSchema, module)) {
+    throw new TypeError(`${file} has no default extension factory.`);
+  }
+
+  // SAFETY: amplike's extension files default-export a Pi extension factory.
+  return module.default as ExtensionFactory;
+};
+
+// amplike's handoff and subagent read -mode through this helper, so the T3
+// replacements read it the same way.
+export const loadModeSpecFrom = async (root: string): Promise<LoadModeSpec> => {
+  const file = path.join(root, "extensions", "lib", "mode-utils.ts");
+  const module: unknown = await import(file);
+
+  if (!Value.Check(ModeUtilsSchema, module)) {
+    throw new TypeError(`${file} has no loadModeSpec export.`);
+  }
+
+  return async (cwd, name) => {
+    const spec = await module.loadModeSpec(cwd, name);
+
+    return Value.Check(ModeSpecSchema, spec) ? spec : undefined;
+  };
+};

package/src/amplike/selection.ts

@@ -0,0 +1,132 @@
+import { Type } from "typebox";
+import type { Static } from "typebox";
+import { Value } from "typebox/value";
+
+import { callT3Tool } from "../bridge/t3-http.ts";
+import type { LoadModeSpec } from "./package.ts";
+
+const OptionSchema = Type.Object({
+  id: Type.String(),
+  value: Type.Union([Type.String(), Type.Boolean()]),
+});
+
+const SelectionSchema = Type.Object({
+  instanceId: Type.Optional(Type.String()),
+  model: Type.String(),
+  options: Type.Optional(Type.Array(OptionSchema)),
+});
+
+const ConfigureSchema = Type.Object({ modelSelection: SelectionSchema });
+
+// T3's modelSelection for a Pi thread: model is "provider/modelId", and the
+// thinking level is the "thinking" option.
+export type Selection = Static<typeof SelectionSchema>;
+
+export interface SelectionChange {
+  model?: string;
+  thinking?: string;
+}
+
+export interface Flags {
+  mode?: string;
+  model?: string;
+}
+
+export interface ParsedArgs {
+  readonly flags: Flags;
+  readonly text: string;
+}
+
+const THINKING = "thinking";
+
+export const isEmptyChange = (change: SelectionChange): boolean =>
+  change.model === undefined && change.thinking === undefined;
+
+export const currentSelection = async (): Promise<Selection> => {
+  const result = await callT3Tool("t3_thread_configure", {});
+
+  if (!Value.Check(ConfigureSchema, result)) {
+    throw new Error("t3_thread_configure returned no modelSelection.");
+  }
+
+  return result.modelSelection;
+};
+
+export const applyChange = (
+  current: Selection,
+  change: SelectionChange
+): Selection => {
+  const next: Selection = { ...current, model: change.model ?? current.model };
+
+  if (change.thinking !== undefined) {
+    next.options = [
+      ...(current.options ?? []).filter((option) => option.id !== THINKING),
+      { id: THINKING, value: change.thinking },
+    ];
+  }
+
+  return next;
+};
+
+export const configureThread = async (selection: Selection): Promise<void> => {
+  await callT3Tool("t3_thread_configure", { modelSelection: { ...selection } });
+};
+
+// amplike's commands take `-mode <name>` and `-model <provider/id>` before the
+// text, in either order.
+export const parseFlags = (args: string): ParsedArgs => {
+  const words = args.trim().split(/\s+/u);
+  const flags: Flags = {};
+
+  while (words[0] === "-mode" || words[0] === "-model") {
+    const [flag, value] = words.splice(0, 2);
+
+    if (value === undefined) {
+      throw new Error(`${flag} needs a value.`);
+    }
+
+    if (flag === "-mode") {
+      flags.mode = value;
+    } else {
+      flags.model = value;
+    }
+  }
+
+  return { flags, text: words.join(" ") };
+};
+
+// Same order as amplike: the mode sets model and thinking, then -model
+// overrides the model.
+export const changeFromFlags = async (
+  flags: Flags,
+  cwd: string,
+  loadModeSpec: LoadModeSpec
+): Promise<SelectionChange> => {
+  const change: SelectionChange = {};
+
+  if (flags.mode !== undefined) {
+    const spec = await loadModeSpec(cwd, flags.mode);
+
+    if (spec === undefined) {
+      throw new Error(`Unknown mode "${flags.mode}".`);
+    }
+
+    if (spec.provider !== undefined && spec.modelId !== undefined) {
+      change.model = `${spec.provider}/${spec.modelId}`;
+    }
+
+    change.thinking = spec.thinkingLevel;
+  }
+
+  if (flags.model !== undefined) {
+    if (!flags.model.includes("/")) {
+      throw new Error(
+        `Model "${flags.model}" must be written as provider/modelId.`
+      );
+    }
+
+    change.model = flags.model;
+  }
+
+  return change;
+};

package/src/amplike/t3-view.ts

@@ -0,0 +1,88 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+import { btwCommand } from "./btw.ts";
+import { handoffCommand, handoffTool } from "./handoff.ts";
+import type { LoadModeSpec } from "./package.ts";
+import { applyChange, configureThread, currentSelection } from "./selection.ts";
+import type { SelectionChange } from "./selection.ts";
+
+type Tool = Parameters<ExtensionAPI["registerTool"]>[0];
+
+type Command = Parameters<ExtensionAPI["registerCommand"]>[1];
+
+// What a T3 thread gets for each name amplike registers. A missing name is
+// registered as amplike wrote it. null drops it.
+interface Rules {
+  readonly commands: Readonly<Record<string, Command | null>>;
+  readonly tools: Readonly<Record<string, Tool | null>>;
+}
+
+const t3Rules = (loadModeSpec: LoadModeSpec): Rules => ({
+  commands: {
+    btw: btwCommand(loadModeSpec),
+    handoff: handoffCommand(loadModeSpec),
+  },
+  tools: {
+    handoff: handoffTool(loadModeSpec),
+    // T3's delegate_task runs subagents as T3 threads.
+    subagent: null,
+  },
+});
+
+// T3 owns the thread's model. When amplike's /mode switches Pi's model or
+// thinking level, the same change goes to T3, so T3's model picker matches and
+// T3's next set_model keeps it. amplike awaits setModel before it sets the
+// thinking level, so the two calls reach T3 in order.
+const mirror = async (change: SelectionChange): Promise<void> => {
+  await configureThread(applyChange(await currentSelection(), change));
+};
+
+const mirrorThinking = async (thinking: string): Promise<void> => {
+  try {
+    await mirror({ thinking });
+  } catch (error) {
+    console.error(`pi-t3: T3 kept its thinking level: ${String(error)}`);
+  }
+};
+
+// Pi's extension API is a plain object of closures, so a copy with some
+// methods replaced behaves like the original for everything else.
+export const t3View = (
+  pi: ExtensionAPI,
+  loadModeSpec: LoadModeSpec
+): ExtensionAPI => {
+  const rules = t3Rules(loadModeSpec);
+
+  return {
+    ...pi,
+    registerCommand: (name, options) => {
+      const rule = rules.commands[name];
+
+      if (rule !== null) {
+        pi.registerCommand(name, rule ?? options);
+      }
+    },
+    // T3 sends Pi no key presses.
+    registerShortcut: () => null,
+    registerTool: (tool) => {
+      const rule = rules.tools[tool.name];
+
+      if (rule !== null) {
+        pi.registerTool(rule ?? tool);
+      }
+    },
+    setModel: async (model) => {
+      const ok = await pi.setModel(model);
+
+      if (ok) {
+        await mirror({ model: `${model.provider}/${model.id}` });
+      }
+
+      return ok;
+    },
+    setThinkingLevel: (level) => {
+      pi.setThinkingLevel(level);
+      void mirrorThinking(level);
+    },
+  };
+};