@ctliz/agent-intercom-pi 0.11.0-connect.2

package/licenses/MIT-pi-intercom.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Nico Bailon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/outbound-outbox.ts

@@ -0,0 +1,116 @@
+import { createHash } from "crypto";
+import { chmodSync, existsSync, mkdirSync, readFileSync, renameSync } from "fs";
+import { join } from "path";
+import { ensureIntercomRuntimeDir, getIntercomDirPath, INTERCOM_DIR_MODE, restrictIntercomRuntimeFile } from "./broker/paths.ts";
+import { writeDurableJson } from "./durable-json.ts";
+import type { Message } from "./types.ts";
+
+const OUTBOX_STATE_VERSION = 1;
+const MAX_OUTBOX_MESSAGES = 256;
+
+export interface StoredOutboundMessage {
+  to: string;
+  message: Message;
+  queuedAt: number;
+}
+
+interface OutboxState {
+  version: typeof OUTBOX_STATE_VERSION;
+  entries: StoredOutboundMessage[];
+}
+
+function fingerprint(entry: Pick<StoredOutboundMessage, "to" | "message">): string {
+  return JSON.stringify({
+    to: entry.to,
+    replyTo: entry.message.replyTo,
+    expectsReply: entry.message.expectsReply,
+    content: entry.message.content,
+  });
+}
+
+function isStoredOutboundMessage(value: unknown): value is StoredOutboundMessage {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) return false;
+  const entry = value as Record<string, unknown>;
+  if (typeof entry.to !== "string" || typeof entry.queuedAt !== "number") return false;
+  if (typeof entry.message !== "object" || entry.message === null || Array.isArray(entry.message)) return false;
+  const message = entry.message as Record<string, unknown>;
+  return typeof message.id === "string"
+    && typeof message.timestamp === "number"
+    && typeof message.content === "object"
+    && message.content !== null
+    && typeof (message.content as Record<string, unknown>).text === "string";
+}
+
+function fileName(sessionId: string): string {
+  return `${createHash("sha256").update(sessionId).digest("hex")}.json`;
+}
+
+export class PersistentOutboundOutbox {
+  private readonly directory: string;
+  private readonly filePath: string;
+  private state: OutboxState;
+
+  constructor(sessionId: string, intercomDir: string = getIntercomDirPath()) {
+    ensureIntercomRuntimeDir(intercomDir);
+    this.directory = join(intercomDir, "outbox");
+    mkdirSync(this.directory, { recursive: true, mode: INTERCOM_DIR_MODE });
+    if (process.platform !== "win32") chmodSync(this.directory, INTERCOM_DIR_MODE);
+    this.filePath = join(this.directory, fileName(sessionId));
+    this.state = this.load();
+  }
+
+  list(): StoredOutboundMessage[] {
+    return this.state.entries.map((entry) => ({ ...entry, message: { ...entry.message, content: { ...entry.message.content } } }));
+  }
+
+  enqueue(to: string, message: Message): "added" | "existing" {
+    const existing = this.state.entries.find((entry) => entry.message.id === message.id);
+    if (existing) {
+      if (fingerprint(existing) !== fingerprint({ to, message })) {
+        throw new Error(`Message ID ${message.id} is already queued with a different payload`);
+      }
+      return "existing";
+    }
+    if (this.state.entries.length >= MAX_OUTBOX_MESSAGES) {
+      throw new Error(`Durable outbox is full (${MAX_OUTBOX_MESSAGES} messages)`);
+    }
+    this.state.entries.push({ to, message, queuedAt: Date.now() });
+    this.persist();
+    return "added";
+  }
+
+  remove(messageId: string): void {
+    const remaining = this.state.entries.filter((entry) => entry.message.id !== messageId);
+    if (remaining.length === this.state.entries.length) return;
+    this.state.entries = remaining;
+    this.persist();
+  }
+
+  clear(): void {
+    if (this.state.entries.length === 0) return;
+    this.state.entries = [];
+    this.persist();
+  }
+
+  private load(): OutboxState {
+    if (!existsSync(this.filePath)) return { version: OUTBOX_STATE_VERSION, entries: [] };
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(this.filePath, "utf-8"));
+      if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) throw new Error("expected object");
+      const state = parsed as Record<string, unknown>;
+      if (state.version !== OUTBOX_STATE_VERSION || !Array.isArray(state.entries) || !state.entries.every(isStoredOutboundMessage)) {
+        throw new Error("invalid outbox state");
+      }
+      return { version: OUTBOX_STATE_VERSION, entries: state.entries };
+    } catch {
+      const corruptPath = `${this.filePath}.corrupt-${Date.now()}`;
+      renameSync(this.filePath, corruptPath);
+      restrictIntercomRuntimeFile(corruptPath);
+      return { version: OUTBOX_STATE_VERSION, entries: [] };
+    }
+  }
+
+  private persist(): void {
+    writeDurableJson(this.filePath, this.state);
+  }
+}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@ctliz/agent-intercom-pi",
+  "version": "0.11.0-connect.2",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "banner.png",
+    "*.ts",
+    "!*.test.ts",
+    "broker/**/*.ts",
+    "!broker/**/*.test.ts",
+    "protocol-v4/**/*.ts",
+    "!protocol-v4/**/*.test.ts",
+    "provider/provider.mjs",
+    "!provider/entry.ts",
+    "ui/**/*.ts",
+    "skills/**/*",
+    "!**/*.test.ts",
+    "THIRD_PARTY_NOTICES.md",
+    "licenses/**/*",
+    "COPYRIGHT",
+    "LICENSE_TRANSITION.md"
+  ],
+  "scripts": {
+    "build:protected-provider": "node scripts/build-protected-provider.mjs",
+    "prepack": "npm run build:protected-provider",
+    "test": "tsx --test broker/*.test.ts *.test.ts test/*.test.ts protocol-v4/*.test.ts",
+    "test:ci": "tsx --test --test-concurrency=1 broker/*.test.ts *.test.ts test/*.test.ts protocol-v4/*.test.ts",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "pi-package"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "skills": [
+      "./skills"
+    ]
+  },
+  "dependencies": {
+    "@ctliz/agent-intercom-core": "git+https://github.com/ctliz/agent-intercom-core.git#37e074970e2a9de32a16fc325607c3b476b0bd45",
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-tui": "*",
+    "tsx": "^4.20.0",
+    "typebox": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ctliz/agent-intercom-pi.git"
+  },
+  "homepage": "https://github.com/ctliz/agent-intercom-pi#readme",
+  "bugs": {
+    "url": "https://github.com/ctliz/agent-intercom-pi/issues"
+  }
+}

package/protocol-v4/contract.ts

@@ -0,0 +1,39 @@
+import {
+  INTERCOM_PROTOCOL_NAME,
+  INTERCOM_PROTOCOL_V4_SEMANTICS_HASH,
+  INTERCOM_PROTOCOL_V4_VECTOR_SCHEMA_VERSION,
+  INTERCOM_PROTOCOL_V4_VECTORS,
+  INTERCOM_PROTOCOL_VERSION,
+  INTERCOM_SCOPE_ENV,
+  INTERCOM_SCOPE_ID_PATTERN,
+  INTERCOM_SCOPE_ID_PATTERN_SOURCE,
+  intercomScopeIdFromEnv,
+  parseIntercomScopeId,
+  sameIntercomScope,
+} from "@ctliz/agent-intercom-core/protocol-v4";
+
+export const INTERCOM_REGISTRATION_METADATA_ERROR = "Registration metadata is invalid" as const;
+
+export function parseIntercomScopeIdForRegistration(value: unknown): string | undefined {
+  try { return parseIntercomScopeId(value, "registrationMetadata"); }
+  catch { throw new Error(INTERCOM_REGISTRATION_METADATA_ERROR); }
+}
+
+export function intercomScopeIdFromEnvForRegistration(env: NodeJS.ProcessEnv = process.env): string | undefined {
+  try { return intercomScopeIdFromEnv(env); }
+  catch { throw new Error(INTERCOM_REGISTRATION_METADATA_ERROR); }
+}
+
+export {
+  INTERCOM_PROTOCOL_NAME,
+  INTERCOM_PROTOCOL_V4_SEMANTICS_HASH,
+  INTERCOM_PROTOCOL_V4_VECTOR_SCHEMA_VERSION,
+  INTERCOM_PROTOCOL_V4_VECTORS,
+  INTERCOM_PROTOCOL_VERSION,
+  INTERCOM_SCOPE_ENV,
+  INTERCOM_SCOPE_ID_PATTERN,
+  INTERCOM_SCOPE_ID_PATTERN_SOURCE,
+  intercomScopeIdFromEnv,
+  parseIntercomScopeId,
+  sameIntercomScope,
+};

package/provider/provider.mjs

@@ -0,0 +1,34 @@
+// Generated from provider/entry.ts by scripts/build-protected-provider.mjs.
+// Do not edit this artifact directly.
+const supportedBossFeature = Object.freeze({
+    version: "intercom.broker-feature.v1",
+    feature: "boss-run-v1",
+    featureVersion: 1,
+    semanticsHash: "8943eb60d29afa5264322b5cc7df3de245b01b1cf48a8cbf9cfb6188b02fcfa9",
+    controlEnvelopeVersion: 1,
+    capabilityDigest: "239bee8bb64cc8c149d49ac00c7396f33f375a89a1d6dea6bd86ff840d551a59",
+});
+/** Immutable build-time contract only; it is not an installed-provider claim. */
+export const PI_BOSS_PROTECTED_PROVIDER_BUILD_IDENTITY = Object.freeze({
+    contractVersion: "pi.boss-protected-provider.v1",
+    adapterId: "pi",
+    providerPackage: "@ctliz/agent-intercom-pi",
+    supportedBaseProtocolVersions: Object.freeze([4]),
+    supportedFeatures: Object.freeze([supportedBossFeature]),
+    protocolFeatureContractHash: "dae30efe2c48d2de0fe72a7ebdfd107d3feaefc180d42056ba05df6088a94364",
+    authoritative: false,
+    providerStartAvailable: false,
+    bossAdvertisementEnabled: false,
+});
+const BOSS_PROTECTED_PROVIDER_START_UNAVAILABLE = "BOSS_PROTECTED_PROVIDER_START_UNAVAILABLE";
+class PiBossProtectedProviderStartUnavailableError extends Error {
+    code = BOSS_PROTECTED_PROVIDER_START_UNAVAILABLE;
+    constructor() {
+        super(`${BOSS_PROTECTED_PROVIDER_START_UNAVAILABLE}: protected provider execution is not installed`);
+        this.name = "PiBossProtectedProviderStartUnavailableError";
+    }
+}
+/** A later protected service may replace this dormant entry after release gates. */
+export function startPiBossProtectedProvider(_request) {
+    throw new PiBossProtectedProviderStartUnavailableError();
+}

package/reply-tracker.ts

@@ -0,0 +1,231 @@
+import { createHash } from "node:crypto";
+import { getAskTimeoutMs } from "./config.ts";
+import type { Message, SessionInfo } from "./types.ts";
+
+export interface IntercomContext {
+  from: SessionInfo;
+  message: Message;
+  receivedAt: number;
+  deferredAt?: number;
+}
+
+export type ReplyWhich = "oldest" | "latest";
+
+/** Stable, receiver-local selector that does not expose the wire message ID. */
+export function pendingAskId(fromSessionId: string, messageId: string): string {
+  const digest = createHash("sha256")
+    .update(fromSessionId)
+    .update("\0")
+    .update(messageId)
+    .digest("base64url");
+  return `ask-${digest}`;
+}
+
+function matchesPendingSender(context: IntercomContext, to: string): boolean {
+  if (context.from.id === to) {
+    return true;
+  }
+
+  return context.from.name?.toLowerCase() === to.toLowerCase();
+}
+
+function contextKey(fromSessionId: string, messageId: string): string {
+  return `${fromSessionId}\u0000${messageId}`;
+}
+
+function selectByAge(contexts: IntercomContext[], which: ReplyWhich): IntercomContext {
+  const sorted = [...contexts].sort((a, b) => a.receivedAt - b.receivedAt);
+  return which === "oldest" ? sorted[0]! : sorted[sorted.length - 1]!;
+}
+
+function distinctSenders(contexts: IntercomContext[]): number {
+  return new Set(contexts.map((context) => context.from.id)).size;
+}
+
+export class ReplyTracker {
+  private readonly pendingAsks = new Map<string, IntercomContext>();
+  private readonly pendingTurnContexts: IntercomContext[][] = [];
+  private currentTurnContexts: IntercomContext[] = [];
+
+  constructor(private readonly askTimeoutMs = getAskTimeoutMs()) {}
+
+  recordIncomingMessage(from: SessionInfo, message: Message, receivedAt = Date.now()): IntercomContext {
+    const key = contextKey(from.id, message.id);
+    const existing = this.pendingAsks.get(key);
+    const context = {
+      from,
+      message,
+      receivedAt,
+      ...(existing?.deferredAt === undefined ? {} : { deferredAt: existing.deferredAt }),
+    };
+    if (message.expectsReply) {
+      this.pendingAsks.set(key, context);
+    }
+    return context;
+  }
+
+  queueTurnContext(context: IntercomContext): void {
+    this.queueTurnContexts([context]);
+  }
+
+  queueTurnContexts(contexts: readonly IntercomContext[]): void {
+    if (contexts.length > 0) {
+      this.pendingTurnContexts.push([...contexts]);
+    }
+  }
+
+  beginTurn(now = Date.now()): void {
+    this.pruneExpired(now);
+    if (this.currentTurnContexts.length === 0) {
+      this.currentTurnContexts = this.pendingTurnContexts.shift() ?? [];
+    }
+  }
+
+  endTurn(): void {
+    this.currentTurnContexts = [];
+  }
+
+  reset(): void {
+    this.pendingAsks.clear();
+    this.pendingTurnContexts.length = 0;
+    this.currentTurnContexts = [];
+  }
+
+  resolveReplyTarget(options: { to?: string; replyTo?: string; askId?: string; which?: ReplyWhich }, now = Date.now()): IntercomContext {
+    this.pruneExpired(now);
+
+    if (options.askId) {
+      const match = Array.from(this.pendingAsks.values()).find((context) =>
+        pendingAskId(context.from.id, context.message.id) === options.askId
+      );
+      if (!match) {
+        throw new Error(`No pending ask with ask ID "${options.askId}"`);
+      }
+      if (options.to && !matchesPendingSender(match, options.to)) {
+        throw new Error(`Pending ask "${options.askId}" is not from "${options.to}"`);
+      }
+      return match;
+    }
+
+    if (options.replyTo) {
+      const candidates = Array.from(this.pendingAsks.values()).filter((context) => context.message.id === options.replyTo);
+      if (candidates.length === 0) {
+        throw new Error(`No pending ask with message ID "${options.replyTo}"`);
+      }
+      const matches = options.to ? candidates.filter((context) => matchesPendingSender(context, options.to!)) : candidates;
+      if (matches.length === 0) {
+        throw new Error(`Pending ask "${options.replyTo}" is not from "${options.to}"`);
+      }
+      if (matches.length > 1) {
+        throw new Error(`Multiple pending asks use message ID "${options.replyTo}" — specify \`to\``);
+      }
+      return matches[0]!;
+    }
+
+    if (this.currentTurnContexts.length > 0) {
+      const turnMatches = options.to
+        ? this.currentTurnContexts.filter((context) => matchesPendingSender(context, options.to!))
+        : this.currentTurnContexts;
+      const replyableMatches = turnMatches.filter((context) => context.message.expectsReply);
+      if (replyableMatches.length === 1) {
+        return replyableMatches[0]!;
+      }
+      if (replyableMatches.length > 1) {
+        if (!options.to && distinctSenders(replyableMatches) > 1) {
+          throw new Error("Multiple asks are active in this intercom batch — specify `to` to select the sender");
+        }
+        if (options.which) return selectByAge(replyableMatches, options.which);
+        throw new Error("Multiple asks from the selected sender are active — specify `which` as `oldest` or `latest`");
+      }
+      if (turnMatches.length === 1) {
+        return turnMatches[0]!;
+      }
+      if (turnMatches.length > 1) {
+        if (distinctSenders(turnMatches) === 1) return selectByAge(turnMatches, "latest");
+        throw new Error("Multiple senders are active in this intercom batch — specify `to` using an exact sender name or full session ID");
+      }
+    }
+
+    const pending = Array.from(this.pendingAsks.values());
+    if (pending.length === 1) {
+      return pending[0]!;
+    }
+
+    const matches = options.to
+      ? pending.filter((context) => matchesPendingSender(context, options.to!))
+      : pending;
+    if (matches.length === 1) return matches[0]!;
+    if (matches.length > 1) {
+      if (!options.to && distinctSenders(matches) > 1) {
+        throw new Error("Multiple pending asks — specify `to` using a sender from `intercom_pending`");
+      }
+      if (options.which) return selectByAge(matches, options.which);
+      const sender = options.to ? ` from \"${options.to}\"` : "";
+      throw new Error(`Multiple pending asks${sender} — specify \`which\` as \`oldest\` or \`latest\``);
+    }
+    if (pending.length === 0) {
+      throw new Error("No active intercom context to reply to");
+    }
+    if (options.to) throw new Error(`No pending ask from \"${options.to}\"`);
+    throw new Error("No matching pending ask");
+  }
+
+  markReplied(replyTo: string, fromSessionId?: string): void {
+    this.dismissPendingAsk(replyTo, fromSessionId);
+  }
+
+  dismissOrdinarySender(fromSessionId: string): void {
+    this.currentTurnContexts = this.currentTurnContexts.filter((context) =>
+      context.message.expectsReply || context.from.id !== fromSessionId
+    );
+  }
+
+  markDeferred(replyTo: string, fromSessionIdOrDeferredAt?: string | number, deferredAt = Date.now()): boolean {
+    const fromSessionId = typeof fromSessionIdOrDeferredAt === "string" ? fromSessionIdOrDeferredAt : undefined;
+    const effectiveDeferredAt = typeof fromSessionIdOrDeferredAt === "number" ? fromSessionIdOrDeferredAt : deferredAt;
+    let changed = false;
+    for (const context of this.pendingAsks.values()) {
+      if (context.message.id === replyTo && (!fromSessionId || context.from.id === fromSessionId)) {
+        context.deferredAt = effectiveDeferredAt;
+        changed = true;
+      }
+    }
+    return changed;
+  }
+
+  dismissPendingAsk(replyTo: string, fromSessionId?: string): void {
+    for (const [key, context] of this.pendingAsks) {
+      if (context.message.id === replyTo && (!fromSessionId || context.from.id === fromSessionId)) {
+        this.pendingAsks.delete(key);
+      }
+    }
+    for (let batchIndex = this.pendingTurnContexts.length - 1; batchIndex >= 0; batchIndex -= 1) {
+      const batch = this.pendingTurnContexts[batchIndex]!;
+      for (let contextIndex = batch.length - 1; contextIndex >= 0; contextIndex -= 1) {
+        if (
+          batch[contextIndex]?.message.id === replyTo
+          && (!fromSessionId || batch[contextIndex]?.from.id === fromSessionId)
+        ) {
+          batch.splice(contextIndex, 1);
+        }
+      }
+      if (batch.length === 0) this.pendingTurnContexts.splice(batchIndex, 1);
+    }
+    this.currentTurnContexts = this.currentTurnContexts.filter((context) =>
+      context.message.id !== replyTo || (fromSessionId !== undefined && context.from.id !== fromSessionId)
+    );
+  }
+
+  listPending(now = Date.now()): IntercomContext[] {
+    this.pruneExpired(now);
+    return Array.from(this.pendingAsks.values()).sort((a, b) => a.receivedAt - b.receivedAt);
+  }
+
+  private pruneExpired(now: number): void {
+    for (const context of Array.from(this.pendingAsks.values())) {
+      if (now - context.receivedAt > this.askTimeoutMs) {
+        this.dismissPendingAsk(context.message.id, context.from.id);
+      }
+    }
+  }
+}