larkin 0.4.13 → 0.4.15

package/dist/runtime/runtime-host.mjs

@@ -2,6 +2,7 @@ import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { agentCliPromptCapabilities } from "../agent/agent-cli-capabilities.mjs";
+import { auditReminderDelivery } from "../agent/reminder-delivery-audit.mjs";
 import { isCanonicalInboxTarget, targetKeyOfInboxEnvelope } from "../agent/inbox-projection.mjs";
 import { SpanKind } from "@opentelemetry/api";
 import { buildStrictProviderErrorInput, classifyStrictProviderError } from "./provider-error-classifier.mjs";
@@ -1062,6 +1063,33 @@ export function createRuntimeHost(options) {
         agent.piProactiveCompaction = tracked;
         return tracked;
     };
+    // Reminder audit contexts are in-turn capabilities. Finalize any survivors
+    // at both turn boundaries: turn end reconciles the turn that consumed them,
+    // and turn start expires contexts left by a crashed/aborted prior turn so a
+    // direct outbound cannot be falsely attributed to a stale reminder.
+    const finalizeReminderContexts = (agent, reason) => {
+        const legacyReminder = agent.stateStore?.resolveCurrentReminders ? null : agent.stateStore?.resolveCurrentReminder?.() ?? null;
+        const reminderContexts = agent.stateStore?.resolveCurrentReminders?.() ?? (legacyReminder ? [legacyReminder] : []);
+        let reminderAuditComplete = true;
+        if (agent.stateStore?.paths?.reminders && agent.stateStore.clearCurrentReminder) {
+            for (const reminder of reminderContexts) {
+                try {
+                    auditReminderDelivery({ stateStore: agent.stateStore, agentId: agent.config.agentId,
+                        reminderId: reminder.reminderId, deliveryAnchor: reminder.deliveryAnchor, target: reminder.deliveryTarget,
+                        succeeded: reminder.deliveryCommitted === true, finalize: true,
+                        ...(reminder.deliveryMessageId ? { messageId: reminder.deliveryMessageId } : {}),
+                        ...(!reminder.deliveryCommitted ? { reason } : {}) });
+                }
+                catch {
+                    // Retain the context if the failure could not be durably recorded;
+                    // a later matching outbound or turn can reconcile it.
+                    reminderAuditComplete = false;
+                }
+            }
+        }
+        if (reminderAuditComplete)
+            agent.stateStore?.clearCurrentReminders?.();
+    };
     const observe = (agent, session, event) => {
         if (agent.session !== session)
             return; // Ignore late output from a replaced child.
@@ -1104,6 +1132,10 @@ export function createRuntimeHost(options) {
                 ...(event.model ? { model: event.model } : {}), ...(event.reasoningEffort ? { reasoningEffort: event.reasoningEffort } : {}) });
         }
         else if (event.type === "turn-start") {
+            // Clear a source left by a crashed/aborted prior turn before a new turn
+            // can execute a direct task without an Inbox poll.
+            agent.stateStore?.clearCurrentInboxSource?.();
+            finalizeReminderContexts(agent, "Runtime turn started before a prior turn reconciled this reminder delivery");
             agent.busy = true;
             agent.turnInProgress = true;
             agent.turnHadFailure = false;
@@ -1125,6 +1157,11 @@ export function createRuntimeHost(options) {
             agent.busy = false;
             emit({ type: "activity", agentId: agent.config.agentId, activity: "idle", activityKind: "idle", detailKind: "turn_ended" });
             reconcileAcceptedAtTurnEnd(agent);
+            // last_source and reminder audit contexts are in-turn capabilities,
+            // never cross-turn defaults. A later direct Runtime task must fail
+            // closed instead of inheriting a previous turn's chat or reminder.
+            agent.stateStore?.clearCurrentInboxSource?.();
+            finalizeReminderContexts(agent, "Runtime turn ended without a matching Feishu write");
             if (agent.backgroundCompletionInFlight) {
                 if (agent.turnHadFailure)
                     failBackgroundCompletionWake(agent);

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "larkin",
-  "version": "0.4.13",
+  "version": "0.4.15",
   "private": false,
   "larkinPackageRole": "npm-published",
   "files": [
     "dist/",
+    "patches/",
     "assets/",
     "scripts/npm/",
     "README.md",
@@ -114,5 +115,8 @@
     "typescript": "^7.0.2",
     "vite": "^8.1.5",
     "vitest": "^4.1.10"
+  },
+  "patchedDependencies": {
+    "@tintinweb/pi-subagents@0.14.3": "patches/@tintinweb%2Fpi-subagents@0.14.3.patch"
   }
 }

package/patches/@tintinweb%2Fpi-subagents@0.14.3.patch

@@ -0,0 +1,249 @@
+diff --git a/node_modules/@tintinweb/pi-subagents/.bun-tag-58e08ce8246a76a0 b/.bun-tag-58e08ce8246a76a0
+new file mode 100644
+index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
+diff --git a/node_modules/@tintinweb/pi-subagents/.bun-tag-6ef69510e99ece5d b/.bun-tag-6ef69510e99ece5d
+new file mode 100644
+index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
+diff --git a/node_modules/@tintinweb/pi-subagents/.bun-tag-80c5d241789d23ea b/.bun-tag-80c5d241789d23ea
+new file mode 100644
+index 0000000000000000000000000000000000000000..e69de29bb2d1d6434b8b29ae775ad8c2e48c5391
+diff --git a/dist/index.js b/dist/index.js
+index ab65ef15b5c1da803c0378b1d0ba383645198028..dc18e00d2ce4bddb6ee77608364d3c8b39fdfd60 100644
+--- a/dist/index.js
++++ b/dist/index.js
+@@ -69,6 +69,44 @@ function abortable(promise, signal) {
+         });
+     });
+ }
++const RESULT_WAIT_QUEUE_POLL_MS = 50;
++const DEFAULT_RESULT_WAIT_TIMEOUT_MS = 30000;
++const MAX_RESULT_WAIT_TIMEOUT_MS = 60000;
++function normalizeResultWaitTimeout(timeoutMs) {
++    if (timeoutMs === undefined || !Number.isFinite(timeoutMs))
++        return DEFAULT_RESULT_WAIT_TIMEOUT_MS;
++    return Math.max(1, Math.min(MAX_RESULT_WAIT_TIMEOUT_MS, Math.floor(timeoutMs)));
++}
++function waitWithDeadline(promise, timeoutMs, signal) {
++    let timer;
++    const timeout = new Promise((resolve) => {
++        timer = setTimeout(() => resolve({ timedOut: true }), timeoutMs);
++    });
++    return abortable(Promise.race([
++        promise.then((value) => ({ timedOut: false, value })),
++        timeout,
++    ]), signal).finally(() => {
++        if (timer !== undefined)
++            clearTimeout(timer);
++    });
++}
++/** Wait for one background record without cancelling it when the deadline expires. */
++export async function waitForSubagentResult(record, timeoutMs, signal) {
++    const deadline = Date.now() + timeoutMs;
++    while (record.status === "queued") {
++        const remainingMs = deadline - Date.now();
++        if (remainingMs <= 0)
++            return true;
++        await abortable(new Promise((resolve) => setTimeout(resolve, Math.min(RESULT_WAIT_QUEUE_POLL_MS, remainingMs))), signal);
++    }
++    if (!record.promise)
++        return false;
++    const remainingMs = deadline - Date.now();
++    if (remainingMs <= 0)
++        return true;
++    return (await waitWithDeadline(record.promise, remainingMs, signal)).timedOut;
++}
++const LARKIN_BOUNDED_WAIT_CAPABILITY = "larkin-pi-subagents-bounded-wait-v1";
+ export function renderRunningAgentStatus(frame, statsText, activity, theme) {
+     const container = new Container();
+     container.addChild(new Text(theme.fg("accent", frame) + (statsText ? " " + statsText : ""), 0, 0));
+@@ -280,9 +318,14 @@ export default function (pi) {
+     // before they reach pi.sendMessage (fire-and-forget).
+     const pendingNudges = new Map();
+     const NUDGE_HOLD_MS = 200;
++    // A parent agent run may span multiple model turns. Consume the one-wait
++    // budget when a queued/running wait begins, rather than only after timeout.
++    let resultWaitConsumedInParentTurn = false;
++    pi.on("agent_start", () => {
++        resultWaitConsumedInParentTurn = false;
++    });
+     // A queued result wait must observe completion before its held notification
+     // can fire, so successful waits can still suppress that redundant nudge.
+-    const QUEUE_WAIT_POLL_MS = Math.floor(NUDGE_HOLD_MS / 4);
+     function scheduleNudge(key, send, delay = NUDGE_HOLD_MS) {
+         cancelNudge(key);
+         pendingNudges.set(key, setTimeout(() => {
+@@ -1293,6 +1336,9 @@ Terse command-style prompts produce shallow, generic work.
+             wait: Type.Optional(Type.Boolean({
+                 description: "If true, wait for the agent to complete before returning. Default: false.",
+             })),
++            timeout_ms: Type.Optional(Type.Number({
++                description: "Maximum wait in milliseconds when wait is true. Defaults to 30000 and is capped at 60000.",
++            })),
+             verbose: Type.Optional(Type.Boolean({
+                 description: "If true, include the agent's full conversation (messages + tool calls). Default: false.",
+             })),
+@@ -1307,12 +1353,15 @@ Terse command-style prompts produce shallow, generic work.
+             // completion notification can still be delivered.
+             // Queued agents have no promise yet (it's created when the queue starts
+             // them), so poll until they leave the queue, then await like a running one.
++            // One deadline covers both phases so queue polling cannot reset the wait.
++            if (params.wait && resultWaitConsumedInParentTurn) {
++                throw new Error("Refusing wait: true after an earlier wait began in this parent turn; yield and await the completion notification instead.");
++            }
++            let timedOut = false;
++            const waitTimeoutMs = normalizeResultWaitTimeout(params.timeout_ms);
+             if (params.wait && (record.status === "running" || record.status === "queued")) {
+-                while (record.status === "queued") {
+-                    await abortable(new Promise((resolve) => setTimeout(resolve, QUEUE_WAIT_POLL_MS)), signal);
+-                }
+-                if (record.promise)
+-                    await abortable(record.promise, signal);
++                resultWaitConsumedInParentTurn = true;
++                timedOut = await waitForSubagentResult(record, waitTimeoutMs, signal);
+             }
+             const displayName = getDisplayName(record.type);
+             const duration = formatDuration(record.startedAt, record.completedAt);
+@@ -1327,10 +1376,12 @@ Terse command-style prompts produce shallow, generic work.
+                 statsParts.push(`Compactions: ${record.compactionCount}`);
+             statsParts.push(`Duration: ${duration}`);
+             let output = `Agent: ${record.id}\n` +
+-                `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
++                `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)}${timedOut ? " | timedOut: true" : ""} | ${statsParts.join(" | ")}\n` +
+                 `Description: ${record.description}\n\n`;
+-            if (record.status === "running") {
+-                output += "Agent is still running. Use wait: true or check back later.";
++            if (record.status === "running" || record.status === "queued") {
++                output += timedOut
++                    ? `Agent is still ${record.status}. Wait timed out after ${waitTimeoutMs}ms; the background agent was not cancelled. Yield/end this turn and await the completion notification; do not call wait: true again.`
++                    : "Agent is still running. Use wait: true or check back later.";
+             }
+             else if (record.status === "error") {
+                 output += `Error: ${record.error}${partialOutputSuffix(record)}`;
+diff --git a/src/index.ts b/src/index.ts
+index 828938e6d710dc5a8f99a6185e37f9592b12352d..fb2d3119a50c6aa9c8864037af65ff95bbe4bb1f 100644
+--- a/src/index.ts
++++ b/src/index.ts
+@@ -91,6 +91,54 @@ function abortable<T>(promise: Promise<T>, signal?: AbortSignal): Promise<T> {
+   });
+ }
+ 
++const RESULT_WAIT_QUEUE_POLL_MS = 50;
++const DEFAULT_RESULT_WAIT_TIMEOUT_MS = 30_000;
++const MAX_RESULT_WAIT_TIMEOUT_MS = 60_000;
++
++function normalizeResultWaitTimeout(timeoutMs: number | undefined): number {
++  if (timeoutMs === undefined || !Number.isFinite(timeoutMs)) return DEFAULT_RESULT_WAIT_TIMEOUT_MS;
++  return Math.max(1, Math.min(MAX_RESULT_WAIT_TIMEOUT_MS, Math.floor(timeoutMs)));
++}
++
++function waitWithDeadline<T>(promise: Promise<T>, timeoutMs: number, signal?: AbortSignal): Promise<{ timedOut: true } | { timedOut: false; value: T }> {
++  let timer: ReturnType<typeof setTimeout> | undefined;
++  const timeout = new Promise<{ timedOut: true }>((resolve) => {
++    timer = setTimeout(() => resolve({ timedOut: true }), timeoutMs);
++  });
++  return abortable(
++    Promise.race([
++      promise.then((value) => ({ timedOut: false as const, value })),
++      timeout,
++    ]),
++    signal,
++  ).finally(() => {
++    if (timer !== undefined) clearTimeout(timer);
++  });
++}
++
++/** Wait for one background record without cancelling it when the deadline expires. */
++export async function waitForSubagentResult(
++  record: Pick<AgentRecord, "status" | "promise">,
++  timeoutMs: number,
++  signal?: AbortSignal,
++): Promise<boolean> {
++  const deadline = Date.now() + timeoutMs;
++  while (record.status === "queued") {
++    const remainingMs = deadline - Date.now();
++    if (remainingMs <= 0) return true;
++    await abortable(
++      new Promise<void>((resolve) => setTimeout(resolve, Math.min(RESULT_WAIT_QUEUE_POLL_MS, remainingMs))),
++      signal,
++    );
++  }
++  if (!record.promise) return false;
++  const remainingMs = deadline - Date.now();
++  if (remainingMs <= 0) return true;
++  return (await waitWithDeadline(record.promise, remainingMs, signal)).timedOut;
++}
++
++export const LARKIN_BOUNDED_WAIT_CAPABILITY = "larkin-pi-subagents-bounded-wait-v1";
++
+ export function renderRunningAgentStatus(
+   frame: string,
+   statsText: string,
+@@ -330,10 +378,14 @@ export default function (pi: ExtensionAPI) {
+   // before they reach pi.sendMessage (fire-and-forget).
+   const pendingNudges = new Map<string, ReturnType<typeof setTimeout>>();
+   const NUDGE_HOLD_MS = 200;
++  // A parent agent run may span multiple model turns. Consume the one-wait
++  // budget when a queued/running wait begins, rather than only after timeout.
++  let resultWaitConsumedInParentTurn = false;
++  pi.on("agent_start", () => {
++    resultWaitConsumedInParentTurn = false;
++  });
+   // A queued result wait must observe completion before its held notification
+   // can fire, so successful waits can still suppress that redundant nudge.
+-  const QUEUE_WAIT_POLL_MS = Math.floor(NUDGE_HOLD_MS / 4);
+-
+   function scheduleNudge(key: string, send: () => void, delay = NUDGE_HOLD_MS) {
+     cancelNudge(key);
+     pendingNudges.set(key, setTimeout(() => {
+@@ -1453,6 +1505,11 @@ Terse command-style prompts produce shallow, generic work.
+           description: "If true, wait for the agent to complete before returning. Default: false.",
+         }),
+       ),
++      timeout_ms: Type.Optional(
++        Type.Number({
++          description: "Maximum wait in milliseconds when wait is true. Defaults to 30000 and is capped at 60000.",
++        }),
++      ),
+       verbose: Type.Optional(
+         Type.Boolean({
+           description: "If true, include the agent's full conversation (messages + tool calls). Default: false.",
+@@ -1470,14 +1527,15 @@ Terse command-style prompts produce shallow, generic work.
+       // completion notification can still be delivered.
+       // Queued agents have no promise yet (it's created when the queue starts
+       // them), so poll until they leave the queue, then await like a running one.
++      // One deadline covers both phases so queue polling cannot reset the wait.
++      if (params.wait && resultWaitConsumedInParentTurn) {
++        throw new Error("Refusing wait: true after an earlier wait began in this parent turn; yield and await the completion notification instead.");
++      }
++      let timedOut = false;
++      const waitTimeoutMs = normalizeResultWaitTimeout(params.timeout_ms);
+       if (params.wait && (record.status === "running" || record.status === "queued")) {
+-        while (record.status === "queued") {
+-          await abortable(
+-            new Promise<void>((resolve) => setTimeout(resolve, QUEUE_WAIT_POLL_MS)),
+-            signal,
+-          );
+-        }
+-        if (record.promise) await abortable(record.promise, signal);
++        resultWaitConsumedInParentTurn = true;
++        timedOut = await waitForSubagentResult(record, waitTimeoutMs, signal);
+       }
+ 
+       const displayName = getDisplayName(record.type);
+@@ -1492,11 +1550,13 @@ Terse command-style prompts produce shallow, generic work.
+ 
+       let output =
+         `Agent: ${record.id}\n` +
+-        `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
++        `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)}${timedOut ? " | timedOut: true" : ""} | ${statsParts.join(" | ")}\n` +
+         `Description: ${record.description}\n\n`;
+ 
+-      if (record.status === "running") {
+-        output += "Agent is still running. Use wait: true or check back later.";
++      if (record.status === "running" || record.status === "queued") {
++        output += timedOut
++          ? `Agent is still ${record.status}. Wait timed out after ${waitTimeoutMs}ms; the background agent was not cancelled. Yield/end this turn and await the completion notification; do not call wait: true again.`
++          : "Agent is still running. Use wait: true or check back later.";
+       } else if (record.status === "error") {
+         output += `Error: ${record.error}${partialOutputSuffix(record)}`;
+       } else {