@tt-a1i/openpi 0.1.0 → 0.2.0

package/extensions/background-terminals/src/result-delivery.ts

@@ -11,15 +11,29 @@ export function createDeferredResultDelivery<T extends { id: string }>() {
   return {
     defer(result: T) {
       pending.set(result.id, result);
+      return pending.size;
     },
     consume(ids: Iterable<string>) {
       for (const id of ids) pending.delete(id);
     },
-    drain() {
-      const results = [...pending.values()];
-      pending.clear();
+    drain(maxResults = Number.POSITIVE_INFINITY) {
+      const results: T[] = [];
+      for (const [id, result] of pending) {
+        if (results.length >= maxResults) break;
+        results.push(result);
+        pending.delete(id);
+      }
       return results;
     },
+    restore(results: readonly T[]) {
+      const current = [...pending.values()];
+      pending.clear();
+      for (const result of results) pending.set(result.id, result);
+      for (const result of current) pending.set(result.id, result);
+    },
+    size() {
+      return pending.size;
+    },
     clear() {
       pending.clear();
     },
@@ -36,6 +50,65 @@ export function createDeferredResultDelivery<T extends { id: string }>() {
  * result in context — carried alongside the user's next message — without
  * demanding a reply.
  */
+export interface IdleResultBatcherOptions<TimerHandle> {
+  readonly delayMs: number;
+  readonly isIdle: () => boolean;
+  readonly flush: (wake: boolean) => void;
+  readonly startTimer: (callback: () => void, delayMs: number) => TimerHandle;
+  readonly clearTimer: (timer: TimerHandle) => void;
+}
+
+/**
+ * Coalesce settlements that arrive while the agent is idle without turning
+ * the window into a sliding delay. A token rejects stale callbacks after
+ * cancellation, including callbacks already queued by the host event loop.
+ */
+export function createIdleResultBatcher<TimerHandle>(
+  options: IdleResultBatcherOptions<TimerHandle>,
+) {
+  let timer: TimerHandle | undefined;
+  let active: symbol | undefined;
+
+  const cancel = () => {
+    active = undefined;
+    if (timer !== undefined) options.clearTimer(timer);
+    timer = undefined;
+  };
+
+  return {
+    schedule() {
+      if (active !== undefined) return;
+      const token = Symbol("idle-result-batch");
+      active = token;
+      timer = options.startTimer(() => {
+        if (active !== token) return;
+        active = undefined;
+        timer = undefined;
+        if (options.isIdle()) options.flush(true);
+      }, options.delayMs);
+    },
+    flushNow() {
+      const wake = options.isIdle();
+      cancel();
+      options.flush(wake);
+    },
+    flushWithoutWake() {
+      cancel();
+      options.flush(false);
+    },
+    clear: cancel,
+  };
+}
+
+export function hasTerminalCapacity(options: {
+  readonly running: number;
+  readonly pending: number;
+  readonly reserved: number;
+  readonly maximum: number;
+}) {
+  return options.running + options.pending + options.reserved < options.maximum;
+}
+
 export function resultDeliveryOptions(wake: boolean) {
   return wake
     ? ({ deliverAs: "followUp", triggerTurn: true } as const)

package/extensions/background-terminals/src/ui/tool-result.ts

@@ -1,5 +1,5 @@
 import { keyHint, type Theme } from "@earendil-works/pi-coding-agent";
-import { Text, truncateToWidth, type Component } from "@earendil-works/pi-tui";
+import { type Component, Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { sanitizeText } from "./output-view.ts";
 
 const STREAM_PREVIEW_LINES = 2;
@@ -102,6 +102,57 @@ function fixedRows(rows: string[]): Component {
   };
 }
 
+interface TerminalBatchResult {
+  readonly id: string;
+  readonly title: string;
+  readonly status: string;
+  readonly exitCode?: number;
+  readonly signal?: string;
+}
+
+/** Render a batch as a truthful per-terminal summary; expand reveals raw logs. */
+export function renderTerminalBatchResult(
+  content: string,
+  expanded: boolean,
+  theme: Theme,
+  results: readonly TerminalBatchResult[],
+  omitted = 0,
+): Component {
+  if (expanded) return new Text(sanitizeText(content), 0, 0);
+  const rows = [
+    theme.fg("accent", `${results.length} background terminals completed`),
+    ...results.map((result) => {
+      const failed =
+        result.status === "failed" || result.status === "timed_out";
+      const icon = failed
+        ? theme.fg("error", "x")
+        : result.status === "killed"
+          ? theme.fg("muted", "■")
+          : theme.fg("success", "■");
+      const how =
+        result.status === "timed_out"
+          ? "timed out"
+          : result.status === "killed"
+            ? "killed"
+            : (result.signal ?? `exit ${result.exitCode ?? "?"}`);
+      return `${icon} ${theme.fg("accent", result.id)}${theme.fg("muted", ` · ${result.title} · ${how}`)}`;
+    }),
+    ...(omitted > 0
+      ? [
+          theme.fg(
+            "dim",
+            `… ${omitted} older result${omitted === 1 ? "" : "s"} omitted`,
+          ),
+        ]
+      : []),
+    theme.fg(
+      "dim",
+      `… logs hidden · ${keyHint("app.tools.expand", "to expand")}`,
+    ),
+  ];
+  return fixedRows(rows);
+}
+
 /** Render terminal results compactly by default; expanded mode preserves all text. */
 export function renderTerminalResult(
   content: string,

package/extensions/capabilities/index.ts

@@ -0,0 +1,198 @@
+import { fileURLToPath } from "node:url";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type Static, Type } from "typebox";
+import {
+  loadSetupConfig,
+  SETUP_CONFIG_CHANGED_CHANNEL,
+  type MyPiSetupConfig,
+} from "../shared/setup-config.ts";
+import {
+  getLoadedOpenPiCapabilities,
+  loadOpenPiCapabilities,
+  OPENPI_CAPABILITY_GROUPS,
+  OPENPI_CAPABILITY_NAMES,
+  OPENPI_TOOL_SURFACE,
+  type OpenPiCapability,
+  patchOwnedTools,
+  resetOpenPiToolSurface,
+} from "../shared/tool-surface.ts";
+
+const CapabilitySchema = Type.Enum(OPENPI_CAPABILITY_NAMES);
+
+const OpenPiLoadToolsParameters = Type.Object({
+  groups: Type.Optional(
+    Type.Array(CapabilitySchema, {
+      minItems: 1,
+      maxItems: OPENPI_CAPABILITY_NAMES.length,
+      uniqueItems: true,
+      description: "Groups to load; omit to list.",
+    }),
+  ),
+});
+
+type OpenPiLoadToolsInput = Static<typeof OpenPiLoadToolsParameters>;
+
+const CAPABILITY_INTENT = {
+  search:
+    /\b(?:use|run)\s+(?:fd|rg)\b|\buse\s+(?:structured\s+)?(?:(?:file|code|content)\s+)?search\b|\b(?:structured|fast)\s+(?:file|code|content)\s+search\b|(?:使用|运行).{0,8}(?:fd|rg)|结构化(?:文件|代码|内容)搜索/iu,
+  delegate:
+    /\b(?:use|spawn|run)\s+(?:an?\s+|multiple\s+|several\s+|two\s+)?(?:pi\s+)?subagents?\b|(?:^|[.!?]\s+)(?:please\s+)?(?:delegate|parallelize)\s+(?:this|the)\s+(?:task|work)\b|\b(?:can|could|would)\s+you\s+(?:please\s+)?(?:delegate|parallelize)\s+(?:this|the)\s+(?:task|work)\b|\bparallel\s+agents?\b|(?:使用|启动|调用|来|开).{0,8}子代理|(?:多个?|多路)子代理|并行.{0,8}(?:代理|agent)|委派.{0,6}任务/iu,
+  workflow:
+    /\b(?:use|run|create|build)\s+(?:(?:an?|the)\s+)?(?:openpi\s+)?workflow\b|(?:使用|运行|创建|构建).{0,8}工作流/iu,
+  background:
+    /\b(?:run|start|keep)\b.{0,40}\b(?:in the background|background\s+(?:process|terminal|job))\b|后台.{0,8}(?:运行|进程|终端|任务)/iu,
+  session:
+    /\b(?:create|set|update|track)\s+(?:an?\s+)?(?:session\s+)?(?:goal|task list|tasks)\b|(?:设置|创建|更新|跟踪|追踪).{0,8}(?:目标|任务)/iu,
+} as const satisfies Record<OpenPiCapability, RegExp>;
+
+const CAPABILITY_GATEWAY_INTENT =
+  /\bopenpi\s+(?:capabilit(?:y|ies)|tools?|features?)\b|openpi.{0,8}(?:能力|工具|功能)/iu;
+
+const CONDITIONAL_OR_NEGATED_INTENT =
+  /^(?:\s*(?:only\s+)?(?:if|when|unless|before|in case)\b)|\b(?:do not|don't|cannot|can't|not|no|never|avoid)\b|\b(?:if|unless)\b|\bwhen\s+(?:needed|required|necessary)\b|(?:如果|若|假如|除非|仅当|需要时|不要|不能|不用|不必|无需|避免|请勿|禁止)/iu;
+
+const CAPABILITY_SKILLS: Partial<Record<OpenPiCapability, string>> = {
+  delegate: fileURLToPath(
+    new URL("../../skills/subagents/SKILL.md", import.meta.url),
+  ),
+  workflow: fileURLToPath(
+    new URL("../../skills/workflows/SKILL.md", import.meta.url),
+  ),
+  background: fileURLToPath(
+    new URL("../../skills/background-terminals/SKILL.md", import.meta.url),
+  ),
+};
+
+function capabilitiesRequestedByPrompt(prompt: string) {
+  const clauses = prompt.split(/[\n.!?。！？;；]+/u);
+  return OPENPI_CAPABILITY_NAMES.filter((capability) =>
+    clauses.some(
+      (clause) =>
+        !CONDITIONAL_OR_NEGATED_INTENT.test(clause) &&
+        CAPABILITY_INTENT[capability].test(clause),
+    ),
+  );
+}
+
+function requestsCapabilityGateway(prompt: string) {
+  return prompt
+    .split(/[\n.!?。！？;；]+/u)
+    .some(
+      (clause) =>
+        !CONDITIONAL_OR_NEGATED_INTENT.test(clause) &&
+        CAPABILITY_GATEWAY_INTENT.test(clause),
+    );
+}
+
+function capabilitySkillPaths(capabilities: readonly OpenPiCapability[]) {
+  return capabilities.flatMap((capability) => {
+    const skill = CAPABILITY_SKILLS[capability];
+    return skill ? [skill] : [];
+  });
+}
+
+function skillGuidance(capabilities: readonly OpenPiCapability[]) {
+  const skills = capabilitySkillPaths(capabilities);
+  return skills.length > 0
+    ? `Before first use, read the matching OpenPI capability guidance: ${skills.join(", ")}.`
+    : "";
+}
+
+interface CapabilityExtensionDependencies {
+  readonly loadConfig: () => Pick<MyPiSetupConfig, "capabilities">;
+  readonly sourcePath?: string;
+}
+
+export function createCapabilitiesExtension(
+  dependencies: CapabilityExtensionDependencies = {
+    loadConfig: loadSetupConfig,
+  },
+) {
+  return function capabilities(pi: ExtensionAPI) {
+    const reconcileDiscoveryGateway = () => {
+      const adaptive =
+        dependencies.loadConfig().capabilities.discovery === "adaptive";
+      patchOwnedTools(pi, "capabilities", {
+        ...(adaptive
+          ? { enable: OPENPI_TOOL_SURFACE.capabilities.entry }
+          : { disable: OPENPI_TOOL_SURFACE.capabilities.entry }),
+      });
+    };
+
+    pi.events.on(SETUP_CONFIG_CHANGED_CHANNEL, reconcileDiscoveryGateway);
+
+    pi.on("session_start", () => {
+      resetOpenPiToolSurface(
+        pi,
+        dependencies.sourcePath
+          ? { capabilities: dependencies.sourcePath }
+          : undefined,
+      );
+      reconcileDiscoveryGateway();
+    });
+
+    pi.on("before_agent_start", (event) => {
+      if (requestsCapabilityGateway(event.prompt)) {
+        patchOwnedTools(pi, "capabilities", {
+          enable: OPENPI_TOOL_SURFACE.capabilities.entry,
+        });
+      }
+      const requested = capabilitiesRequestedByPrompt(event.prompt);
+      if (requested.length > 0) loadOpenPiCapabilities(pi, requested);
+      const guidance = skillGuidance(requested);
+      if (guidance) {
+        return {
+          message: {
+            customType: "openpi-capability-guidance",
+            content: guidance,
+            display: false,
+            details: { capabilities: requested },
+          },
+        };
+      }
+    });
+
+    pi.registerTool({
+      name: "openpi_load_tools",
+      label: "Load OpenPI Tools",
+      description:
+        "Load optional OpenPI groups only when useful: search, delegate, workflow, background, or session. Ordinary file and shell work needs none. Loaded groups stay available.",
+      parameters: OpenPiLoadToolsParameters,
+      async execute(_toolCallId, params: OpenPiLoadToolsInput) {
+        const result = params.groups
+          ? loadOpenPiCapabilities(pi, params.groups)
+          : {
+              newlyLoaded: [],
+              loaded: getLoadedOpenPiCapabilities(pi),
+              activatedTools: [],
+            };
+        const available = OPENPI_CAPABILITY_NAMES.map((name) => ({
+          name,
+          summary: OPENPI_CAPABILITY_GROUPS[name].summary,
+          loaded: result.loaded.includes(name),
+        }));
+        const text = params.groups
+          ? result.newlyLoaded.length > 0
+            ? `Loaded OpenPI capabilities: ${result.newlyLoaded.join(", ")}. Activated tools: ${result.activatedTools.join(", ") || "none yet"}.${skillGuidance(result.newlyLoaded) ? ` ${skillGuidance(result.newlyLoaded)}` : ""}`
+            : `Requested OpenPI capabilities were already loaded: ${result.loaded.join(", ") || "none"}.`
+          : `Available OpenPI capabilities:\n${available
+              .map(
+                ({ name, summary, loaded }) =>
+                  `- ${name}${loaded ? " (loaded)" : ""}: ${summary}`,
+              )
+              .join("\n")}`;
+        return {
+          content: [{ type: "text" as const, text }],
+          details: {
+            available,
+            loaded: result.loaded,
+            newlyLoaded: result.newlyLoaded,
+            activatedTools: result.activatedTools,
+          },
+        };
+      },
+    });
+  };
+}
+
+export default createCapabilitiesExtension();

package/extensions/context-pivot/index.ts

@@ -4,6 +4,10 @@ import type {
   SessionEntry,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
+import {
+  OPENPI_TOOL_SURFACE,
+  patchOwnedTools,
+} from "../shared/tool-surface.ts";
 
 export const MIN_CONTEXT_PIVOT_TOKENS = 30_000;
 const STATUS_KEY = "context-pivot";
@@ -78,6 +82,22 @@ export default function contextPivot(pi: ExtensionAPI) {
   let generation = 0;
   let pending: PendingPivot | undefined;
   let compacting = false;
+  const setVisibleForContext = (ctx?: ExtensionContext) => {
+    const tokens = ctx ? estimateContextTokens(ctx.getContextUsage()) : null;
+    patchOwnedTools(pi, "context", {
+      ...(tokens !== null && tokens >= MIN_CONTEXT_PIVOT_TOKENS
+        ? { enable: OPENPI_TOOL_SURFACE.context.deferred }
+        : { disable: OPENPI_TOOL_SURFACE.context.deferred }),
+    });
+  };
+
+  pi.on("session_start", () => {
+    setVisibleForContext();
+  });
+
+  pi.on("agent_start", (_event, ctx) => {
+    setVisibleForContext(ctx);
+  });
 
   pi.on("session_before_compact", (event) => {
     const pivot = pending;
@@ -99,6 +119,7 @@ export default function contextPivot(pi: ExtensionAPI) {
     generation += 1;
     pending = undefined;
     compacting = false;
+    setVisibleForContext();
     if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, undefined);
   });
 

package/extensions/cron/index.ts

@@ -17,10 +17,10 @@ import type {
 } from "@earendil-works/pi-coding-agent";
 import {
   advanceDeliveredJobs,
+  type CronJob,
   dueJobs,
   formatInterval,
   parseCronCommand,
-  type CronJob,
 } from "./schedule.ts";
 
 /** How often the scheduler looks for due jobs. */
@@ -55,20 +55,47 @@ export default function cron(
     stopPolling = undefined;
   };
 
-  const fire = (job: CronJob) => {
+  const fire = (due: readonly CronJob[]) => {
+    if (due.length === 0) return true;
     try {
-      pi.sendMessage(
-        {
-          customType: "cron-fire",
-          content: job.prompt,
-          display: true,
-          details: { id: job.id, recurring: job.intervalMs !== undefined },
-        },
-        { deliverAs: "followUp", triggerTurn: true },
-      );
+      const jobs = due.map((job) => ({
+        id: job.id,
+        prompt: job.prompt,
+        recurring: job.intervalMs !== undefined,
+      }));
+      const message =
+        due.length === 1
+          ? {
+              customType: "cron-fire",
+              content: `[cron ${jobs[0]!.id} · ${jobs[0]!.recurring ? "recurring" : "once"}]\n${jobs[0]!.prompt}`,
+              display: true,
+              details: jobs[0],
+            }
+          : {
+              customType: "cron-fire",
+              content: `${due.length} scheduled prompts are due:\n\n${jobs
+                .map(
+                  (job) =>
+                    `[cron ${job.id} · ${job.recurring ? "recurring" : "once"}]\n${job.prompt}`,
+                )
+                .join("\n\n")}`,
+              display: true,
+              details: { count: jobs.length, jobs },
+            };
+      pi.sendMessage<
+        | { id: number; prompt: string; recurring: boolean }
+        | {
+            count: number;
+            jobs: Array<{ id: number; prompt: string; recurring: boolean }>;
+          }
+      >(message, {
+        deliverAs: "followUp",
+        triggerTurn: true,
+      });
       return true;
     } catch {
-      // Session may be shutting down; leave the job due for the next tick.
+      // Session may be shutting down; leave the whole batch due for the next
+      // tick. A partial advance would silently lose prompts.
       return false;
     }
   };
@@ -83,10 +110,10 @@ export default function cron(
     const due = dueJobs(jobs, now);
     if (due.length === 0) return;
     const deliveredIds = new Set<number>();
-    for (const job of due) {
-      if (fire(job)) deliveredIds.add(job.id);
+    if (fire(due)) {
+      for (const job of due) deliveredIds.add(job.id);
     }
-    jobs = advanceDeliveredJobs(jobs, deliveredIds, now);
+    jobs = advanceDeliveredJobs(jobs, deliveredIds, runtime.now());
     if (jobs.length === 0) stopTicker();
   };
 

package/extensions/execution-convergence/active-evidence.ts

@@ -0,0 +1,129 @@
+import { createHash } from "node:crypto";
+import type { ContextEvent } from "@earendil-works/pi-coding-agent";
+
+type Message = ContextEvent["messages"][number];
+
+export interface ActiveEvidencePolicy {
+  minimumTransactionsBeforeProjection: number;
+  minActiveTransactions: number;
+  epochStride: number;
+}
+
+const DEFAULT_ACTIVE_EVIDENCE_POLICY: ActiveEvidencePolicy = {
+  minimumTransactionsBeforeProjection: 9,
+  minActiveTransactions: 3,
+  epochStride: 6,
+};
+
+export const DELAYED_ACTIVE_EVIDENCE_POLICY: ActiveEvidencePolicy = {
+  minimumTransactionsBeforeProjection: 15,
+  minActiveTransactions: 3,
+  epochStride: 6,
+};
+
+interface Transaction {
+  start: number;
+  end: number;
+  callIds: string[];
+}
+
+function serializedChars(messages: readonly Message[]) {
+  return messages.reduce(
+    (total, message) => total + JSON.stringify(message).length,
+    0,
+  );
+}
+
+function assistantToolCallIds(message: Message) {
+  if (message.role !== "assistant") return [];
+  return message.content.flatMap((block) =>
+    block.type === "toolCall" ? [block.id] : [],
+  );
+}
+
+function parseTransactions(messages: readonly Message[], start: number) {
+  const transactions: Transaction[] = [];
+  let index = start;
+  while (index < messages.length) {
+    const assistant = messages[index];
+    if (!assistant) return undefined;
+    const callIds = assistantToolCallIds(assistant);
+    if (callIds.length === 0 || new Set(callIds).size !== callIds.length) {
+      return undefined;
+    }
+
+    const expected = new Set(callIds);
+    const observed = new Set<string>();
+    let cursor = index + 1;
+    while (cursor < messages.length && observed.size < expected.size) {
+      const result = messages[cursor];
+      if (result?.role !== "toolResult") return undefined;
+      if (!expected.has(result.toolCallId) || observed.has(result.toolCallId)) {
+        return undefined;
+      }
+      observed.add(result.toolCallId);
+      cursor += 1;
+    }
+    if (observed.size !== expected.size) return undefined;
+
+    transactions.push({ start: index, end: cursor, callIds });
+    index = cursor;
+  }
+  return transactions;
+}
+
+function latestUserIndex(messages: readonly Message[]) {
+  for (let index = messages.length - 1; index >= 0; index -= 1) {
+    if (messages[index]?.role === "user") return index;
+  }
+  return -1;
+}
+
+export function projectActiveEvidence(
+  messages: readonly Message[],
+  policy = DEFAULT_ACTIVE_EVIDENCE_POLICY,
+) {
+  const userIndex = latestUserIndex(messages);
+  if (userIndex < 0 || userIndex === messages.length - 1) return undefined;
+
+  const transactions = parseTransactions(messages, userIndex + 1);
+  if (!transactions) return undefined;
+  if (transactions.length < policy.minimumTransactionsBeforeProjection) {
+    return undefined;
+  }
+
+  const closable = transactions.length - policy.minActiveTransactions;
+  const closedTransactions =
+    Math.floor(closable / policy.epochStride) * policy.epochStride;
+  if (closedTransactions < policy.epochStride) return undefined;
+
+  const first = transactions[0];
+  const retained = transactions[closedTransactions];
+  if (!first || !retained) return undefined;
+
+  const closedMessages = messages.slice(first.start, retained.start);
+  const digest = createHash("sha256")
+    .update(JSON.stringify(closedMessages))
+    .digest("hex")
+    .slice(0, 16);
+  const epoch = closedTransactions / policy.epochStride;
+  const projectedMessages: Message[] = [
+    ...messages.slice(0, first.start),
+    ...messages.slice(retained.start),
+  ];
+  const originalChars = serializedChars(messages);
+  const projectedChars = serializedChars(projectedMessages);
+  if (projectedChars >= originalChars) return undefined;
+
+  return {
+    messages: projectedMessages,
+    receipt: {
+      epoch,
+      closedTransactions,
+      retainedTransactions: transactions.length - closedTransactions,
+      originalChars,
+      projectedChars,
+      digest,
+    },
+  };
+}