@blackbelt-technology/pi-agent-dashboard 0.5.0 → 0.5.2

package/packages/extension/src/__tests__/prompt-expander.test.ts

@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, afterEach } from "vitest";
 import { mkdirSync, writeFileSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 import { expandPromptTemplateFromDisk } from "../prompt-expander.js";
 import { parseSkillBlock } from "@blackbelt-technology/pi-dashboard-shared/skill-block-parser.js";
 
@@ -96,4 +96,113 @@ describe("expandPromptTemplateFromDisk", () => {
     const result = expandPromptTemplateFromDisk("/opsx:continue x", tmpDir);
     expect(result).not.toContain("<skill name=");
   });
+
+  // Change: unify-opsx-colon-hyphen-aliases — symmetric : ↔ - resolution.
+
+  function makeSkillFile(relPath: string, body = "skill body"): string {
+    const abs = join(tmpDir, relPath);
+    mkdirSync(dirname(abs), { recursive: true });
+    writeFileSync(abs, `---\nname: ignored\n---\n${body}`);
+    return abs;
+  }
+
+  it("expands hyphen-typed slash command resolving a colon-registered pi.getCommands skill", () => {
+    const skillPath = makeSkillFile("registry/colon/SKILL.md");
+    const pi = {
+      getCommands: () => [{ name: "opsx:archive", source: "skill", path: skillPath }],
+    };
+    const result = expandPromptTemplateFromDisk("/opsx-archive my-change", tmpDir, pi);
+    expect(result.startsWith('<skill name="opsx:archive" location="')).toBe(true);
+    expect(result.endsWith("\n\nmy-change")).toBe(true);
+    const parsed = parseSkillBlock(result);
+    expect(parsed!.name).toBe("opsx:archive");
+    expect(parsed!.args).toBe("my-change");
+  });
+
+  it("expands colon-typed slash command resolving a hyphen-registered pi.getCommands skill", () => {
+    const skillPath = makeSkillFile("registry/hyphen/SKILL.md");
+    const pi = {
+      getCommands: () => [{ name: "opsx-archive", source: "skill", path: skillPath }],
+    };
+    const result = expandPromptTemplateFromDisk("/opsx:archive my-change", tmpDir, pi);
+    expect(result.startsWith('<skill name="opsx-archive" location="')).toBe(true);
+    expect(result.endsWith("\n\nmy-change")).toBe(true);
+    const parsed = parseSkillBlock(result);
+    expect(parsed!.name).toBe("opsx-archive");
+  });
+
+  it("expands colon-typed slash command resolving a hyphen-named local SKILL.md directory", () => {
+    mkdirSync(join(skillsDir, "opsx-archive"), { recursive: true });
+    writeFileSync(join(skillsDir, "opsx-archive", "SKILL.md"), "---\nname: x\n---\nbody");
+    const result = expandPromptTemplateFromDisk("/opsx:archive arg", tmpDir);
+    expect(result.startsWith('<skill name="opsx-archive" location="')).toBe(true);
+    const parsed = parseSkillBlock(result);
+    expect(parsed!.name).toBe("opsx-archive");
+    expect(parsed!.args).toBe("arg");
+  });
+
+  it("expands hyphen-typed slash command resolving a colon-named local SKILL.md directory", () => {
+    mkdirSync(join(skillsDir, "opsx:archive"), { recursive: true });
+    writeFileSync(join(skillsDir, "opsx:archive", "SKILL.md"), "---\nname: x\n---\nbody");
+    const result = expandPromptTemplateFromDisk("/opsx-archive arg", tmpDir);
+    expect(result.startsWith('<skill name="opsx:archive" location="')).toBe(true);
+    const parsed = parseSkillBlock(result);
+    expect(parsed!.name).toBe("opsx:archive");
+  });
+
+  it("original-form precedence: colon-typed prefers colon-registered skill over hyphen-form prompt template", () => {
+    // Local prompt opsx-foo.md exists; registry has skill opsx:foo.
+    writeFileSync(join(promptsDir, "opsx-foo.md"), "prompt body");
+    const skillPath = makeSkillFile("registry/precedence/SKILL.md", "skill body");
+    const pi = {
+      getCommands: () => [{ name: "opsx:foo", source: "skill", path: skillPath }],
+    };
+    // /opsx:foo → must wrap as skill (registry hit on original form).
+    const colon = expandPromptTemplateFromDisk("/opsx:foo", tmpDir, pi);
+    expect(colon.startsWith('<skill name="opsx:foo" location="')).toBe(true);
+    // /opsx-foo → must NOT wrap (local prompt hit on original form).
+    const hyphen = expandPromptTemplateFromDisk("/opsx-foo", tmpDir, pi);
+    expect(hyphen).not.toContain("<skill name=");
+    expect(hyphen).toContain("prompt body");
+  });
+
+  it("original-form-first across distinct pi.getCommands entries", () => {
+    const aPath = makeSkillFile("registry/A/SKILL.md", "A body");
+    const bPath = makeSkillFile("registry/B/SKILL.md", "B body");
+    const pi = {
+      getCommands: () => [
+        { name: "opsx:foo", source: "skill", path: aPath },
+        { name: "opsx-foo", source: "skill", path: bPath },
+      ],
+    };
+    const colon = expandPromptTemplateFromDisk("/opsx:foo arg", tmpDir, pi);
+    expect(colon).toContain(`location="${aPath}"`);
+    expect(colon).toContain('name="opsx:foo"');
+    expect(colon).not.toContain(`location="${bPath}"`);
+    const hyphen = expandPromptTemplateFromDisk("/opsx-foo arg", tmpDir, pi);
+    expect(hyphen).toContain(`location="${bPath}"`);
+    expect(hyphen).toContain('name="opsx-foo"');
+    expect(hyphen).not.toContain(`location="${aPath}"`);
+  });
+
+  it("original form in pi-registry beats remapped form in local-scan", () => {
+    // Local prompt opsx-foo.md exists; registry has skill opsx:foo.
+    writeFileSync(join(promptsDir, "opsx-foo.md"), "prompt body");
+    const skillPath = makeSkillFile("registry/outer/SKILL.md", "skill body");
+    const pi = {
+      getCommands: () => [{ name: "opsx:foo", source: "skill", path: skillPath }],
+    };
+    // /opsx:foo: outer-loop probes original form across ALL stores first.
+    // Step 3 hit on registry — must NOT fall through to remapped opsx-foo local prompt.
+    const result = expandPromptTemplateFromDisk("/opsx:foo", tmpDir, pi);
+    expect(result.startsWith('<skill name="opsx:foo" location="')).toBe(true);
+    expect(result).not.toContain("prompt body");
+  });
+
+  it("misspelled name with wrong separator returns input unchanged", () => {
+    rmSync(tmpDir, { recursive: true, force: true });
+    mkdirSync(tmpDir, { recursive: true });
+    const result = expandPromptTemplateFromDisk("/opsx:nonexistent foo", tmpDir);
+    expect(result).toBe("/opsx:nonexistent foo");
+  });
 });

package/packages/extension/src/__tests__/provider-register-reload.test.ts

@@ -367,6 +367,80 @@ describe("reloadProviders", () => {
     expect(opus.input).toEqual(["text", "image"]);
   });
 
+  // ── custom-flag race regression (see change: fix-custom-provider-flag-race) ──
+  // The bridge's first `providers_list` push fires from `session_start`
+  // shortly after `activate()` kicked off async `registerEntry()` calls.
+  // The catalogue's `custom: true` flag MUST be set on that first push,
+  // even when each provider's `/v1/models` endpoint hasn't responded yet —
+  // otherwise custom providers from `~/.pi/agent/providers.json` leak into
+  // Settings → Provider Authentication → API Keys (where they don't belong;
+  // the LLM Providers section already manages them).
+
+  it("custom flag is set on first providers_list push, before discoverModels resolves (regression)", async () => {
+    const mod = await importFresh();
+    const { pi } = makeMockPi();
+
+    // Capture event handlers so we can fire model_select to set modelRegistryRef.
+    const handlers = new Map<string, (event: any, ctx: any) => Promise<void> | void>();
+    pi.on = vi.fn((event: string, handler: any) => { handlers.set(event, handler); });
+
+    // Stub fetch with a never-resolving promise — simulates a slow or
+    // unreachable /v1/models endpoint. The fix's correctness does NOT depend
+    // on this resolving; the synchronous `lastRegistered.set` runs before the
+    // await.
+    let resolveFetch: ((value: Response) => void) | null = null;
+    globalThis.fetch = vi.fn(
+      () => new Promise<Response>((r) => { resolveFetch = r; }),
+    ) as any;
+
+    // Two custom providers. With the fix, both end up in lastRegistered
+    // synchronously when activate() iterates them.
+    writeProvidersJson(tmpHome, {
+      proxy: { baseUrl: "https://example.com/v1", apiKey: "sk-test", api: "openai-completions" },
+      "your-llmproxy": { baseUrl: "https://example2.com/v1", apiKey: "sk-test", api: "openai-completions" },
+    });
+
+    // activate() fires registerEntry async (.catch(() => {})). The synchronous
+    // body runs to the first await before yielding.
+    mod.activate(pi);
+
+    // Capture modelRegistry via a model_select event — buildProviderCatalogue()
+    // returns [] when modelRegistryRef is null. We use model_select rather
+    // than session_start because session_start would re-register every entry
+    // (also stalling on the never-resolving fetch).
+    const fakeRegistry = {
+      find: () => null,
+      getAll: () => [
+        { provider: "proxy", id: "some-model" },
+        { provider: "your-llmproxy", id: "some-model" },
+        { provider: "deepseek", id: "deepseek-chat" },
+      ],
+      getProviderDisplayName: (id: string) => id,
+      authStorage: {
+        getOAuthProviders: () => [],
+        getAuthStatus: () => ({ configured: false }),
+        get: () => undefined,
+      },
+    };
+    const modelSelectHandler = handlers.get("model_select");
+    expect(modelSelectHandler).toBeDefined();
+    await modelSelectHandler!({}, { modelRegistry: fakeRegistry, model: undefined });
+
+    // Build the catalogue while discovery is still in flight. With the fix,
+    // both custom providers are flagged custom: true. Without it, lastRegistered
+    // is still empty (the post-await `lastRegistered.set` never runs because
+    // fetch never resolves) and the flags are missing.
+    const cat = mod.buildProviderCatalogue();
+
+    expect(cat.find((c) => c.id === "proxy")?.custom).toBe(true);
+    expect(cat.find((c) => c.id === "your-llmproxy")?.custom).toBe(true);
+    // Built-in pi-ai providers must remain unflagged.
+    expect(cat.find((c) => c.id === "deepseek")?.custom).toBeUndefined();
+
+    // Cleanup: settle the dangling fetches so the test process doesn't leak.
+    if (resolveFetch) (resolveFetch as (value: Response) => void)(new Response(JSON.stringify({ data: [] }), { status: 200 }));
+  });
+
   it("discovered unknown model falls back to api-appropriate defaults (openai-completions → 128k)", async () => {
     const mod = await importFresh();
     const { pi, registerProvider } = makeMockPi();

package/packages/extension/src/__tests__/retry-tracker.test.ts

@@ -0,0 +1,147 @@
+import { describe, it, expect } from "vitest";
+import { RetryTracker, RETRYABLE_PATTERN } from "../retry-tracker.js";
+
+describe("RetryTracker", () => {
+  it("synthesizes auto_retry_start on retryable assistant error", () => {
+    const t = new RetryTracker();
+    const ev = t.observeMessageEnd("s1", {
+      role: "assistant",
+      stopReason: "error",
+      errorMessage: "rate limit exceeded",
+    });
+    expect(ev).not.toBeNull();
+    expect(ev!.eventType).toBe("auto_retry_start");
+    expect(ev!.data).toEqual({
+      attempt: 1,
+      maxAttempts: -1,
+      delayMs: -1,
+      errorMessage: "rate limit exceeded",
+    });
+    expect(t.isRetrying("s1")).toBe(true);
+  });
+
+  it("does not synthesize for non-retryable error (e.g. context overflow)", () => {
+    const t = new RetryTracker();
+    const ev = t.observeMessageEnd("s1", {
+      role: "assistant",
+      stopReason: "error",
+      errorMessage: "prompt is too long: 300000 tokens > 200000 maximum",
+    });
+    expect(ev).toBeNull();
+    expect(t.isRetrying("s1")).toBe(false);
+  });
+
+  it("does not synthesize for non-assistant messages", () => {
+    const t = new RetryTracker();
+    expect(t.observeMessageEnd("s1", { role: "user" })).toBeNull();
+    expect(t.observeMessageEnd("s1", { role: "toolResult", stopReason: "error" })).toBeNull();
+  });
+
+  it("does not synthesize for missing or empty errorMessage", () => {
+    const t = new RetryTracker();
+    expect(t.observeMessageEnd("s1", { role: "assistant", stopReason: "error" })).toBeNull();
+    expect(
+      t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "" }),
+    ).toBeNull();
+  });
+
+  it("increments attempt counter across multiple retryable errors", () => {
+    const t = new RetryTracker();
+    const a = t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    const b = t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    const c = t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    expect((a!.data as any).attempt).toBe(1);
+    expect((b!.data as any).attempt).toBe(2);
+    expect((c!.data as any).attempt).toBe(3);
+  });
+
+  it("synthesizes auto_retry_end success on successful assistant message_end after retry", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    const ev = t.observeMessageEnd("s1", { role: "assistant", stopReason: "end_turn" });
+    expect(ev).not.toBeNull();
+    expect(ev!.eventType).toBe("auto_retry_end");
+    expect(ev!.data).toEqual({ success: true, attempt: 1 });
+    expect(t.isRetrying("s1")).toBe(false);
+  });
+
+  it("does not synthesize auto_retry_end when no retry was tracked", () => {
+    const t = new RetryTracker();
+    expect(t.observeMessageEnd("s1", { role: "assistant", stopReason: "end_turn" })).toBeNull();
+  });
+
+  it("synthesizes auto_retry_end failure on agent_end with terminal error", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "rate limit" });
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "rate limit" });
+    const ev = t.observeAgentEnd("s1", {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: "Rate limit exceeded permanently" }],
+    });
+    expect(ev).not.toBeNull();
+    expect(ev!.eventType).toBe("auto_retry_end");
+    expect(ev!.data).toEqual({
+      success: false,
+      attempt: 2,
+      finalError: "Rate limit exceeded permanently",
+    });
+    expect(t.isRetrying("s1")).toBe(false);
+  });
+
+  it("synthesizes auto_retry_end success on agent_end with non-error terminal message", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    const ev = t.observeAgentEnd("s1", {
+      messages: [{ role: "assistant", stopReason: "end_turn" }],
+    });
+    expect(ev).not.toBeNull();
+    expect((ev!.data as any).success).toBe(true);
+  });
+
+  it("agent_end without prior retry returns null", () => {
+    const t = new RetryTracker();
+    expect(t.observeAgentEnd("s1", { messages: [] })).toBeNull();
+  });
+
+  it("noteAbort clears tracker so subsequent agent_end does not double-emit", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    t.noteAbort("s1");
+    expect(t.isRetrying("s1")).toBe(false);
+    expect(t.observeAgentEnd("s1", { messages: [] })).toBeNull();
+  });
+
+  it("scopes retry state per-session", () => {
+    const t = new RetryTracker();
+    t.observeMessageEnd("s1", { role: "assistant", stopReason: "error", errorMessage: "429" });
+    expect(t.isRetrying("s1")).toBe(true);
+    expect(t.isRetrying("s2")).toBe(false);
+  });
+
+  it.each([
+    "rate limit exceeded",
+    "Rate Limit hit",
+    "overloaded_error",
+    "too many requests",
+    "HTTP 429",
+    "HTTP 500 Internal Server Error",
+    "service unavailable",
+    "fetch failed",
+    "socket hang up",
+    "connection refused",
+    "connection lost",
+    "request timed out",
+    "terminated",
+    "retry delay exceeded",
+  ])("RETRYABLE_PATTERN matches: %s", (msg) => {
+    expect(RETRYABLE_PATTERN.test(msg)).toBe(true);
+  });
+
+  it.each([
+    "prompt is too long: 300000 tokens > 200000 maximum",
+    "tool execution failed",
+    "invalid input",
+    "",
+  ])("RETRYABLE_PATTERN does NOT match: %s", (msg) => {
+    expect(RETRYABLE_PATTERN.test(msg)).toBe(false);
+  });
+});

package/packages/extension/src/__tests__/server-launcher-launch.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Pins the Bridge → `launchDashboardServer` forwarding contract: the
+ * extension's `launchServer` must always pass `starter: "Bridge"`,
+ * `stdio: "ignore"`, and `healthTimeoutMs: 2_000`. The shared
+ * launcher is mocked so this test never spawns a real server.
+ *
+ * See change: unify-server-launch-ts-loader (§3.1.2).
+ */
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import type { launchDashboardServer } from "@blackbelt-technology/pi-dashboard-shared/server-launcher.js";
+
+const { launchSpy } = vi.hoisted(() => ({
+  launchSpy: vi.fn<typeof launchDashboardServer>(async () => ({ childPid: 1, reportedPid: 1, healthOk: true as const })),
+}));
+
+vi.mock("@blackbelt-technology/pi-dashboard-shared/server-launcher.js", () => ({
+  launchDashboardServer: launchSpy,
+  JitiNotFoundError: class JitiNotFoundError extends Error {},
+  PortConflictError: class PortConflictError extends Error {},
+  EarlyExitError: class EarlyExitError extends Error { code: number | null = null; },
+}));
+
+import { launchServer } from "../server-launcher.js";
+
+const cfg = {
+  port: 3000,
+  piPort: 4000,
+  autoStart: true,
+  autoShutdown: true,
+  shutdownIdleSeconds: 300,
+  spawnStrategy: "tmux" as const,
+  tunnel: { enabled: true },
+  devBuildOnReload: false,
+  memoryLimits: { maxEventsPerSession: 5000, maxStringFieldSize: 0, maxWsBufferBytes: 4194304 },
+  editor: { idleTimeoutMinutes: 10, maxInstances: 3 },
+  defaultModel: "",
+  trustedNetworks: [],
+  resolvedTrustedNetworks: [],
+  cors: { allowedOrigins: [] },
+  electronMode: false,
+} as any;
+
+beforeEach(() => {
+  launchSpy.mockClear();
+  launchSpy.mockResolvedValue({ childPid: 1, reportedPid: 1, healthOk: true } as any);
+});
+
+describe("Bridge launchServer → launchDashboardServer forwarding", () => {
+  it("passes starter:Bridge + stdio:ignore + 2s health timeout + port", async () => {
+    const r = await launchServer(cfg);
+    expect(r.success).toBe(true);
+    expect(launchSpy).toHaveBeenCalledOnce();
+    const opts = launchSpy.mock.calls[0]![0]!;
+    expect(opts.starter).toBe("Bridge");
+    expect(opts.stdio).toBe("ignore");
+    expect(opts.healthTimeoutMs).toBe(2000);
+    expect(opts.port).toBe(3000);
+    expect(opts.extraArgs).toEqual(["--port", "3000", "--pi-port", "4000"]);
+  });
+
+  it("maps JitiNotFoundError to a failed LaunchResult (no throw)", async () => {
+    const { JitiNotFoundError } = await import("@blackbelt-technology/pi-dashboard-shared/server-launcher.js");
+    launchSpy.mockRejectedValueOnce(new JitiNotFoundError("loader missing"));
+    const r = await launchServer(cfg);
+    expect(r.success).toBe(false);
+    expect(r.message).toContain("loader missing");
+  });
+
+  it("maps EarlyExitError to a failed LaunchResult mentioning the exit code", async () => {
+    const { EarlyExitError } = await import("@blackbelt-technology/pi-dashboard-shared/server-launcher.js");
+    const err = new (EarlyExitError as unknown as new (...args: unknown[]) => Error & { code: number })();
+    err.code = 17;
+    launchSpy.mockRejectedValueOnce(err);
+    const r = await launchServer(cfg);
+    expect(r.success).toBe(false);
+    expect(r.message).toMatch(/code=17/);
+  });
+});

package/packages/extension/src/__tests__/session-sync.test.ts

@@ -133,3 +133,75 @@ describe("handleSessionChange", () => {
     expect(registerMsg.registerReason).toBe("spawn");
   });
 });
+
+// See change: spawn-correlation-token — bridge token inclusion contract.
+describe("sendStateSync: spawnToken from env", () => {
+  const ENV_VAR = "PI_DASHBOARD_SPAWN_TOKEN";
+
+  function withEnvVar<T>(value: string | undefined, fn: () => T): T {
+    const prior = process.env[ENV_VAR];
+    if (value === undefined) delete process.env[ENV_VAR];
+    else process.env[ENV_VAR] = value;
+    try {
+      return fn();
+    } finally {
+      if (prior === undefined) delete process.env[ENV_VAR];
+      else process.env[ENV_VAR] = prior;
+    }
+  }
+
+  it("first register includes spawnToken from env", () => {
+    withEnvVar("tok_first", () => {
+      const bc = createMockBridgeContext({ hasRegisteredOnce: false } as any);
+      sendStateSync(bc, () => []);
+      const sent = (bc as any)._sent;
+      const registerMsg = sent.find((m: any) => m.type === "session_register");
+      expect(registerMsg.spawnToken).toBe("tok_first");
+      expect(registerMsg.registerReason).toBe("spawn");
+    });
+  });
+
+  it("reattach register omits spawnToken (even when env still set)", () => {
+    withEnvVar("tok_first", () => {
+      const bc = createMockBridgeContext({ hasRegisteredOnce: true } as any);
+      sendStateSync(bc, () => []);
+      const sent = (bc as any)._sent;
+      const registerMsg = sent.find((m: any) => m.type === "session_register");
+      expect(registerMsg.spawnToken).toBeUndefined();
+      expect(registerMsg.registerReason).toBe("reattach");
+    });
+  });
+
+  it("first register without env var omits spawnToken", () => {
+    withEnvVar(undefined, () => {
+      const bc = createMockBridgeContext({ hasRegisteredOnce: false } as any);
+      sendStateSync(bc, () => []);
+      const sent = (bc as any)._sent;
+      const registerMsg = sent.find((m: any) => m.type === "session_register");
+      expect(registerMsg.spawnToken).toBeUndefined();
+      expect(registerMsg.registerReason).toBe("spawn");
+    });
+  });
+
+  it("handleSessionChange register omits spawnToken (in-process new/fork/resume)", () => {
+    withEnvVar("tok_first", () => {
+      const bc = createMockBridgeContext({ hasRegisteredOnce: true } as any);
+      const ctx = {
+        cwd: "/proj",
+        sessionManager: {
+          getSessionId: () => "sess-fork",
+          getSessionFile: () => "/path/new.json",
+          getSessionDir: () => "/path",
+          getBranch: () => [],
+          getEntries: () => [],
+        },
+      };
+      handleSessionChange(bc, ctx as any, () => []);
+      const sent = (bc as any)._sent;
+      const registerMsg = sent.find((m: any) => m.type === "session_register" && m.sessionId === "sess-fork");
+      expect(registerMsg).toBeDefined();
+      expect(registerMsg.spawnToken).toBeUndefined();
+      expect(registerMsg.registerReason).toBe("spawn");
+    });
+  });
+});

package/packages/extension/src/__tests__/usage-limit-orderer.test.ts

@@ -0,0 +1,105 @@
+import { describe, it, expect } from "vitest";
+import { UsageLimitOrderer, USAGE_LIMIT_PATTERN } from "../usage-limit-orderer.js";
+
+describe("UsageLimitOrderer", () => {
+  it("returns null when no retry was pending", () => {
+    const o = new UsageLimitOrderer();
+    const result = o.maybeSynthesize("s1", {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: "usage_limit_reached" }],
+    });
+    expect(result).toBeNull();
+  });
+
+  it("returns null when retry was pending but error is not a usage-limit", () => {
+    const o = new UsageLimitOrderer();
+    o.noteRetryStart("s1");
+    const result = o.maybeSynthesize("s1", {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: "tool execution failed" }],
+    });
+    expect(result).toBeNull();
+  });
+
+  it("returns null on a non-error agent_end even with pending retry", () => {
+    const o = new UsageLimitOrderer();
+    o.noteRetryStart("s1");
+    const result = o.maybeSynthesize("s1", {
+      messages: [{ role: "assistant", stopReason: "end_turn" }],
+    });
+    expect(result).toBeNull();
+  });
+
+  it("synthesizes auto_retry_end on usage_limit_reached when retry was pending", () => {
+    const o = new UsageLimitOrderer();
+    o.noteRetryStart("s1");
+    const result = o.maybeSynthesize("s1", {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: "usage_limit_reached: 5000 RPM" }],
+    });
+    expect(result).not.toBeNull();
+    expect(result!.eventType).toBe("auto_retry_end");
+    expect(result!.data).toEqual({ success: false, attempt: -1, finalError: "usage_limit_reached: 5000 RPM" });
+  });
+
+  it.each([
+    "usage_limit_reached",
+    "usage_not_included",
+    "quota_exceeded",
+    "monthly limit reached for free tier",
+    "hourly limit hit",
+    "Your quota will reset after 18h31m10s",
+  ])("matches usage-limit variant: %s", (msg) => {
+    expect(USAGE_LIMIT_PATTERN.test(msg)).toBe(true);
+  });
+
+  it.each([
+    "rate limit exceeded",
+    "overloaded_error",
+    "tool execution failed",
+    "fetch failed",
+    "",
+  ])("does not match non-usage-limit variant: %s", (msg) => {
+    expect(USAGE_LIMIT_PATTERN.test(msg)).toBe(false);
+  });
+
+  it("clears pending after agent_end (no double-synthesis on subsequent agent_end)", () => {
+    const o = new UsageLimitOrderer();
+    o.noteRetryStart("s1");
+    const first = o.maybeSynthesize("s1", {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: "usage_limit_reached" }],
+    });
+    expect(first).not.toBeNull();
+    // Same payload again — pending was cleared, so no synthesis.
+    const second = o.maybeSynthesize("s1", {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: "usage_limit_reached" }],
+    });
+    expect(second).toBeNull();
+  });
+
+  it("noteRetryEnd clears pending so subsequent agent_end does not synthesize", () => {
+    const o = new UsageLimitOrderer();
+    o.noteRetryStart("s1");
+    o.noteRetryEnd("s1");
+    expect(o.hasPending("s1")).toBe(false);
+    const result = o.maybeSynthesize("s1", {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: "usage_limit_reached" }],
+    });
+    expect(result).toBeNull();
+  });
+
+  it("scopes pending state per-session", () => {
+    const o = new UsageLimitOrderer();
+    o.noteRetryStart("s1");
+    expect(o.hasPending("s2")).toBe(false);
+    const result = o.maybeSynthesize("s2", {
+      messages: [{ role: "assistant", stopReason: "error", errorMessage: "usage_limit_reached" }],
+    });
+    expect(result).toBeNull();
+  });
+
+  it("returns null on missing or empty messages array", () => {
+    const o = new UsageLimitOrderer();
+    o.noteRetryStart("s1");
+    expect(o.maybeSynthesize("s1", {})).toBeNull();
+    o.noteRetryStart("s1");
+    expect(o.maybeSynthesize("s1", { messages: [] })).toBeNull();
+  });
+});

package/packages/extension/src/ask-user-tool.ts

@@ -5,7 +5,7 @@
  * static tool-name conflicts with other extensions (e.g. pi-flows) that also
  * register ask_user. Runtime registration bypasses detectExtensionConflicts.
  */
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { polyfillMultiselect } from "./multiselect-polyfill.js";