pi-twitterapi.io 0.1.1

package/src/backend/synthesis.ts

@@ -0,0 +1,344 @@
+import type { TwitterSearchDetails } from "../types.js";
+import type { SynthesisRequest } from "../synthesize.js";
+import {
+  assistantText,
+  availableModels,
+  resolveModel,
+  type ModelLike,
+  type RegistryLike,
+  type TwitterApiSynthesisOptions,
+} from "./model.js";
+
+/**
+ * Validate a completion result before its text is treated as an answer.
+ *
+ * `ModelRegistry.complete` resolves with the assistant message even when the
+ * provider reported a failure, so an unchecked result turns an error into an
+ * empty-but-successful answer. Anything other than a normal stop must fail here
+ * rather than reach the user as a blank answer with real sources attached.
+ */
+export function completionText(message: unknown): string {
+  const record = typeof message === "object" && message !== null ? (message as Record<string, unknown>) : {};
+  const stopReason = typeof record.stopReason === "string" ? record.stopReason : undefined;
+  const detail = typeof record.errorMessage === "string" && record.errorMessage ? `: ${record.errorMessage}` : "";
+  if (stopReason === "error") throw new Error(`twitter synthesis failed${detail}`);
+  if (stopReason === "aborted") throw new Error("twitter synthesis was cancelled before it produced an answer");
+  if (stopReason === "toolUse") throw new Error("twitter synthesis tried to call a tool instead of answering");
+  const text = assistantText(message);
+  if (!text) {
+    throw new Error(
+      stopReason === "length"
+        ? "twitter synthesis hit the model's output limit before producing any text"
+        : "twitter synthesis returned an empty answer",
+    );
+  }
+  return text;
+}
+
+
+/**
+ * Build the synthesis completion for a resolved model. Shared by every
+ * twitterapi.io path so failure handling cannot differ between them.
+ */
+function createCompletion(
+  registry: RegistryLike,
+  run: NonNullable<RegistryLike["complete"]>,
+  model: ModelLike,
+): (request: SynthesisRequest) => Promise<string> {
+  return async (request) => {
+    const promptText =
+      request.mediaManifest && request.images.length > 0
+        ? `${request.prompt}\n\nAttached images, in order:\n${request.mediaManifest}`
+        : request.prompt;
+    const message = await run.call(
+      registry,
+      model as never,
+      {
+        systemPrompt: request.system,
+        messages: [
+          {
+            role: "user",
+            content:
+              request.images.length > 0
+                ? [
+                    { type: "text", text: promptText },
+                    ...request.images.map((image) => ({
+                      type: "image",
+                      data: image.data,
+                      mimeType: image.mimeType,
+                    })),
+                  ]
+                : request.prompt,
+            timestamp: Date.now(),
+          },
+        ],
+      } as never,
+      { signal: request.signal } as never,
+    );
+    return completionText(message);
+  };
+}
+
+export interface SynthesisBackend {
+  fetcher: typeof fetch;
+  apiKey: string;
+  model: ModelLike;
+  /** Ready-to-use synthesis completion, with fallback and failure handling applied. */
+  complete: (request: SynthesisRequest) => Promise<string>;
+  /** Model that served the most recent completion after the primary failed. */
+  fallback?: ModelLike;
+  /** True when the most recent completion was served by the fallback model. */
+  isFallbackUsed: () => boolean;
+  /** True when images were dropped because the answering model cannot take them. */
+  imagesDropped: () => boolean;
+}
+
+/** True for an aborted/cancelled completion, which must not trigger a fallback. */
+export type SynthesisFailureKind =
+  | "cancelled"
+  | "quota"
+  | "auth"
+  | "unknown-model"
+  | "invalid-request"
+  | "rate-limit"
+  | "server"
+  | "transport"
+  | "empty"
+  | "unknown";
+
+/**
+ * Failure classes worth one retry on the last model. Deterministic failures
+ * (quota, auth, unknown model, invalid request, and anything unclassified) are
+ * never retried: a second attempt cannot succeed or is not worth a second billed
+ * call.
+ */
+const RETRYABLE_ON_LAST: ReadonlySet<SynthesisFailureKind> = new Set([
+  "rate-limit",
+  "server",
+  "transport",
+  "empty",
+]);
+
+const LAST_MODEL_RETRY_BASE_MS = 500;
+const LAST_MODEL_RETRY_CAP_MS = 4_000;
+
+/** Bounded exponential backoff: 500 ms, doubling to a 4 s cap. */
+export function synthesisRetryDelayMs(attempt: number): number {
+  return Math.min(LAST_MODEL_RETRY_BASE_MS * 2 ** attempt, LAST_MODEL_RETRY_CAP_MS);
+}
+
+/**
+ * Classify a synthesis failure so the chain reacts per kind instead of treating
+ * every error alike.
+ *
+ * Cancellation is authoritative from the signal or error type; the text match is
+ * only a fallback for pi's own "was cancelled" wording, so a provider message
+ * like "connection aborted" is a transport failure rather than a caller cancel.
+ * Explicit status codes are checked before text heuristics, so a 429 carrying
+ * quota wording is still a rate limit and an `api key` mention cannot turn a rate
+ * limit into an auth failure.
+ */
+export function classifySynthesisError(error: unknown, signal?: AbortSignal): SynthesisFailureKind {
+  const name = error instanceof Error ? error.name : "";
+  const message = (error instanceof Error ? error.message : String(error)).toLowerCase();
+  if (signal?.aborted || name === "AbortError" || /\bwas cancelled\b|generation was cancelled/.test(message)) {
+    return "cancelled";
+  }
+  if (/\b429\b/.test(message)) {
+    return /insufficient_quota|billing|payment required/.test(message) ? "quota" : "rate-limit";
+  }
+  if (/\b402\b/.test(message)) return "quota";
+  if (/\b401\b|\b403\b/.test(message)) return "auth";
+  if (/\b404\b/.test(message)) return "unknown-model";
+  if (/\b400\b|\b422\b/.test(message)) return "invalid-request";
+  if (/\b5\d\d\b/.test(message)) return "server";
+  if (/insufficient_quota|quota|billing|payment required|subscription|\bcredits?\b/.test(message)) return "quota";
+  if (/unauthor|invalid api key|forbidden|authentication|\bapi key\b/.test(message)) return "auth";
+  if (/does not exist|unknown model|no such model|not found/.test(message)) return "unknown-model";
+  if (/malformed|invalid request|bad request|validation|tried to call a tool|context length|too long|token limit/.test(message)) {
+    return "invalid-request";
+  }
+  if (/too many requests|rate limit|overloaded/.test(message)) return "rate-limit";
+  if (/bad gateway|unavailable|internal server error|gateway timeout/.test(message)) return "server";
+  if (
+    /timeout|timed out|econnreset|econnrefused|enotfound|socket hang up|network|fetch failed|premature|stream ended|\babort(ed)?\b|connection (closed|drop|lost|reset)/.test(
+      message,
+    )
+  ) {
+    return "transport";
+  }
+  if (/empty answer|no usable text|output limit|empty response/.test(message)) return "empty";
+  // Unclassified failures are deterministic here: an unrecognised error is not
+  // worth a second billed call.
+  return "unknown";
+}
+
+/** Resolve after `ms`, or reject when the caller aborts. */
+function synthesisDelay(ms: number, signal?: AbortSignal): Promise<void> {
+  if (signal?.aborted) return Promise.reject(new Error("twitter synthesis was cancelled"));
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      cleanup();
+      resolve();
+    }, ms);
+    const cleanup = () => {
+      clearTimeout(timer);
+      signal?.removeEventListener("abort", onAbort);
+    };
+    const onAbort = () => {
+      cleanup();
+      reject(new Error("twitter synthesis was cancelled"));
+    };
+    signal?.addEventListener("abort", onAbort, { once: true });
+  });
+}
+
+/** Disclose the fallback model and any dropped images on the result. */
+export function applyFallbackNote(backend: SynthesisBackend, details: TwitterSearchDetails): void {
+  const fallback = backend.fallback;
+  if (backend.isFallbackUsed() && fallback) {
+    details.model = `${fallback.provider}/${fallback.id}`;
+    details.notes = [
+      ...(details.notes ?? []),
+      `The configured synthesis model failed; the answer was produced by ${fallback.provider}/${fallback.id}.`,
+    ];
+  }
+  if (backend.imagesDropped()) {
+    details.notes = [
+      ...(details.notes ?? []),
+      "The model that answered does not accept image input, so attached images were omitted.",
+    ];
+  }
+}
+
+/**
+ * Shared preflight: credentials, the synthesis model, and its completion. Runs
+ * before any network work so a misconfiguration fails immediately and says why.
+ */
+export function resolveSynthesisBackend(options: TwitterApiSynthesisOptions): SynthesisBackend {
+  const fetcher = options.fetcher ?? fetch;
+  const apiKey = options.env?.TWITTERAPI_IO_API_KEY;
+  if (!apiKey) {
+    throw new Error("TWITTERAPI_IO_API_KEY must be configured to use the twitterapi.io backend.");
+  }
+  const registry = options.registry;
+  if (!registry) {
+    throw new Error("twitter could not reach pi's model registry, which the twitterapi.io backend needs for synthesis.");
+  }
+
+  // `complete` is not present on every supported pi version, so it is detected
+  // here instead of being assumed (verified absent on pi 0.80.6, present on 0.99.2).
+  const run = registry.complete;
+  if (typeof run !== "function") {
+    throw new Error(
+      "the twitterapi.io backend needs pi's ModelRegistry.complete, which this pi version does not provide " +
+        "(verified absent on pi 0.80.6, present on 0.99.2). Upgrade pi to a version that provides it.",
+    );
+  }
+
+  const synthesisModelId = options.config.synthesisModel;
+  if (!synthesisModelId) {
+    throw new Error(
+      "twitter needs a synthesis model: set twitter.synthesisModel to a model id from pi's catalogue, " +
+        "or call it from a session whose active model is resolvable.",
+    );
+  }
+  const model = resolveModel(registry, synthesisModelId);
+  if (!model) {
+    const slash = synthesisModelId.indexOf("/");
+    const provider = slash > 0 ? synthesisModelId.slice(0, slash) : undefined;
+    const available = availableModels(registry.getAll(), provider);
+    throw new Error(
+      `twitter synthesis model "${synthesisModelId}" was not found in pi's model catalogue. ` +
+        (available ? `Known models${provider ? ` for "${provider}"` : ""}: ${available}. ` : "") +
+        "Set twitter.synthesisModel to a model id from pi's catalogue.",
+    );
+  }
+  // Build the model chain: the configured model first, then any caller-supplied
+  // fallbacks (typically the session model), deduplicated.
+  const chain: ModelLike[] = [model];
+  for (const id of options.fallbackModelIds ?? []) {
+    if (!id) continue;
+    const resolved = resolveModel(registry, id);
+    if (!resolved) continue;
+    if (chain.some((entry) => entry.provider === resolved.provider && entry.id === resolved.id)) continue;
+    chain.push(resolved);
+  }
+
+  const completions = new Map<ModelLike, (request: SynthesisRequest) => Promise<string>>();
+  let imagesDropped = false;
+  const completionFor = (target: ModelLike): ((request: SynthesisRequest) => Promise<string>) => {
+    let completion = completions.get(target);
+    if (!completion) {
+      const completeModel = createCompletion(registry, run, target);
+      const supportsImage = (target.input ?? []).includes("image");
+      completion = supportsImage
+        ? completeModel
+        : async (request) => {
+            // A fallback that cannot take images must not receive them: a vision
+            // primary can fail and hand images to a text-only session model.
+            if (request.images.length > 0 || request.mediaManifest) {
+              imagesDropped = true;
+              return completeModel({ ...request, images: [], mediaManifest: undefined });
+            }
+            return completeModel(request);
+          };
+      completions.set(target, completion);
+    }
+    return completion;
+  };
+
+  let fallback: ModelLike | undefined;
+  const sleepForRetry = options.synthesisSleep ?? synthesisDelay;
+
+  const complete = async (request: SynthesisRequest): Promise<string> => {
+    // Reset per call so a run that completes more than once never mislabels the
+    // answering model from an earlier call.
+    fallback = undefined;
+    imagesDropped = false;
+    const failures: string[] = [];
+    for (let index = 0; index < chain.length; index += 1) {
+      const candidate = chain[index];
+      // An untried model is the better bet than retrying a model that already
+      // failed, so the retry budget is only spent on the last model in the chain.
+      const isLast = index === chain.length - 1;
+      const maxAttempts = isLast ? 2 : 1;
+      for (let attempt = 0; attempt < maxAttempts; attempt += 1) {
+        if (attempt > 0) {
+          // attempt 1 only happens on the last model after a retryable class.
+          await sleepForRetry(synthesisRetryDelayMs(attempt - 1), request.signal);
+        }
+        try {
+          const text = await completionFor(candidate)(request);
+          if (index > 0) fallback = candidate;
+          return text;
+        } catch (error) {
+          const kind = classifySynthesisError(error, request.signal);
+          // A cancellation stops the chain: it is the caller's intent, not a
+          // model failure to route around.
+          if (kind === "cancelled") throw error;
+          failures.push(`${candidate.provider}/${candidate.id} (${kind}): ${error instanceof Error ? error.message : String(error)}`);
+          if (!isLast || !RETRYABLE_ON_LAST.has(kind)) break;
+        }
+      }
+    }
+    // Every model's cause is reported, not just the last one.
+    throw new Error(`twitter synthesis failed: ${failures.join("; ")}`);
+  };
+
+  // `fallback` is resolved lazily: the completion runs after this object is
+  // built, so a plain property would freeze the pre-run value (undefined).
+  const backend: SynthesisBackend = {
+    fetcher,
+    apiKey,
+    model,
+    complete,
+    get fallback(): ModelLike | undefined {
+      return fallback;
+    },
+    isFallbackUsed: () => fallback !== undefined,
+    imagesDropped: () => imagesDropped,
+  };
+  return backend;
+}
+

package/src/backend.ts

@@ -0,0 +1,11 @@
+/**
+ * Backend barrel: internal wiring for the split modules (model, media,
+ * synthesis chain, runs). The *published* surface is `src/index.ts`, which
+ * re-exports an explicit subset; `export *` here also exposes sibling-module
+ * helpers (e.g. `applyFallbackNote`, `resolveSynthesisBackend`) to the rest of
+ * the source tree by design.
+ */
+export * from "./backend/model.js";
+export * from "./backend/media.js";
+export * from "./backend/synthesis.js";
+export * from "./backend/runs.js";

package/src/config.ts

@@ -0,0 +1,78 @@
+import type { PiSettings } from "./settings.js";
+
+import { DEFAULT_MAX_PAGES_CEILING } from "./twitterapi.js";
+
+export const DEFAULT_MAX_MEDIA_PER_SEARCH = 4;
+export const DEFAULT_MAX_PAGES = 5;
+/**
+ * Unpaid twitterapi.io accounts allow 0.2 QPS (one request every 5 seconds), so
+ * this is the safest default both for pacing and for retry backoff. Paid tiers
+ * can raise it.
+ */
+export const DEFAULT_MIN_REQUEST_INTERVAL_MS = 5_000;
+export const DEFAULT_RETRY_BASE_DELAY_MS = 5_000;
+const MAX_INTERVAL_MS = 600_000;
+
+export interface TwitterConfig {
+  /**
+   * pi model id ("provider/model") that synthesizes the answer from posts
+   * retrieved via twitterapi.io. Resolved through pi's model catalogue. There is
+   * no default: an unset value is a configuration error, reported before any
+   * network work.
+   */
+  synthesisModel?: string;
+  /** Attach image media to the synthesis request. */
+  enableImageUnderstanding: boolean;
+  /** Attach video poster frames to the synthesis request. */
+  enableVideoUnderstanding: boolean;
+  /** Upper bound on media attachments per search. */
+  maxMediaPerSearch: number;
+  /** Base page budget per search. */
+  maxPages: number;
+  /**
+   * Hard ceiling on pages fetched in one search. `maxPages` is clamped to it, so
+   * an explicit ceiling can never be exceeded.
+   */
+  maxPagesCeiling: number;
+  /** Minimum spacing between upstream requests. */
+  minRequestIntervalMs: number;
+  /** Base delay for retry backoff. */
+  retryBaseDelayMs: number;
+}
+
+function isObject(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Non-negative finite milliseconds, clamped, or the fallback when absent/invalid. */
+function intervalMs(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isFinite(value) && value >= 0 ? Math.min(value, MAX_INTERVAL_MS) : fallback;
+}
+
+/** Positive integer page count, clamped, or the fallback when absent/invalid. */
+function pageCount(value: unknown, fallback: number): number {
+  return typeof value === "number" && Number.isInteger(value) && value >= 1 ? Math.min(value, 100) : fallback;
+}
+
+export function loadTwitterConfig(settings: PiSettings): TwitterConfig {
+  const config = isObject(settings.twitter) ? settings.twitter : {};
+  const maxMedia = config.maxMediaPerSearch;
+  const ceiling = pageCount(config.maxPagesCeiling, DEFAULT_MAX_PAGES_CEILING);
+  const synthesisModel =
+    typeof config.synthesisModel === "string" && config.synthesisModel.trim()
+      ? config.synthesisModel.trim()
+      : undefined;
+  return {
+    synthesisModel,
+    enableImageUnderstanding: config.enableImageUnderstanding === true,
+    enableVideoUnderstanding: config.enableVideoUnderstanding === true,
+    maxMediaPerSearch:
+      typeof maxMedia === "number" && Number.isInteger(maxMedia) && maxMedia >= 0
+        ? Math.min(maxMedia, 20)
+        : DEFAULT_MAX_MEDIA_PER_SEARCH,
+    minRequestIntervalMs: intervalMs(config.minRequestIntervalMs, DEFAULT_MIN_REQUEST_INTERVAL_MS),
+    retryBaseDelayMs: intervalMs(config.retryBaseDelayMs, DEFAULT_RETRY_BASE_DELAY_MS),
+    maxPages: Math.min(pageCount(config.maxPages, DEFAULT_MAX_PAGES), ceiling),
+    maxPagesCeiling: ceiling,
+  };
+}

package/src/format.ts

@@ -0,0 +1,28 @@
+import type { TwitterSearchDetails } from "./types.js";
+
+export function formatTwitterResults(details: TwitterSearchDetails): string {
+  const lines = [
+    `Query: ${details.query}`,
+    `Model: ${details.model}`,
+    `Synthesis Calls: ${details.synthesisCalls ?? 0}`,
+    `Citations: ${details.citations.length}`,
+    "",
+    "## Answer",
+    "",
+    details.text || "No answer text returned.",
+  ];
+
+  if (details.citations.length > 0) {
+    lines.push("", "## Sources", "");
+    details.citations.forEach((citation, index) => {
+      lines.push(`${index + 1}. ${citation}`);
+    });
+  }
+
+  if (details.notes?.length) {
+    lines.push("", "## Notes", "");
+    details.notes.forEach((note) => lines.push(`- ${note}`));
+  }
+
+  return lines.join("\n");
+}

package/src/index.ts

@@ -0,0 +1,131 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { registerTwitterTool } from "./tool.js";
+
+/**
+ * pi-twitterapi.io — a twitterapi.io-backed X/Twitter search extension for the
+ * pi coding agent.
+ *
+ * Registers the `twitter` tool, which reads X/Twitter through twitterapi.io and
+ * synthesizes an answer with citation URLs using a pi model. Requires
+ * `TWITTERAPI_IO_API_KEY`; synthesis uses `twitter.synthesisModel`, falling back
+ * to the model running the session.
+ */
+export default function (pi: ExtensionAPI) {
+  registerTwitterTool(pi);
+}
+
+export { registerTwitterTool, type TwitterToolOptions } from "./tool.js";
+export {
+  runTwitterApiAbout,
+  runTwitterApiCommunity,
+  runTwitterApiFollowers,
+  runTwitterApiFollowings,
+  runTwitterApiList,
+  runTwitterApiMentions,
+  runTwitterApiProfile,
+  runTwitterApiQuotes,
+  runTwitterApiReplies,
+  runTwitterApiRetweeters,
+  runTwitterApiSearch,
+  runTwitterApiSpace,
+  runTwitterApiThread,
+  runTwitterApiTrends,
+  runTwitterApiTweetsByIds,
+  runTwitterApiUserSearch,
+  runTwitterApiUserTimeline,
+  resolveModel,
+  assistantText,
+  classifySynthesisError,
+  completionText,
+  createFetchMedia,
+  isAllowedMediaUrl,
+  synthesisRetryDelayMs,
+  toSynthesisModel,
+} from "./backend.js";
+export type {
+  BackendOptions,
+  ModelLike,
+  RegistryLike,
+  SynthesisFailureKind,
+  TwitterApiAboutOptions,
+  TwitterApiCommunityOptions,
+  TwitterApiFollowOptions,
+  TwitterApiListOptions,
+  TwitterApiMentionsOptions,
+  TwitterApiProfileOptions,
+  TwitterApiQuotesOptions,
+  TwitterApiRepliesOptions,
+  TwitterApiRetweetersOptions,
+  TwitterApiRunOptions,
+  TwitterApiSpaceOptions,
+  TwitterApiSynthesisOptions,
+  TwitterApiThreadOptions,
+  TwitterApiTrendsOptions,
+  TwitterApiTweetsByIdsOptions,
+  TwitterApiUserSearchOptions,
+  TwitterApiUserTimelineOptions,
+} from "./backend.js";
+export { DEFAULT_MAX_MEDIA_PER_SEARCH, loadTwitterConfig } from "./config.js";
+export type { TwitterConfig } from "./config.js";
+export {
+  buildCandidatePrompt,
+  buildTrendCandidatePrompt,
+  DOCUMENT_SYNTHESIS_SYSTEM_PROMPT,
+  collectMedia,
+  deriveCitations,
+  extractUrls,
+  statusId,
+  SYNTHESIS_SYSTEM_PROMPT,
+  synthesizeAnswer,
+  synthesizeDocument,
+  synthesizeTrends,
+  synthesizeUserAnswer,
+  toBase64,
+  TREND_SYNTHESIS_SYSTEM_PROMPT,
+  USER_SYNTHESIS_SYSTEM_PROMPT,
+} from "./synthesize.js";
+export type { ImageAttachment, SynthesisModel } from "./synthesize.js";
+export {
+  buildExpression,
+  fetchCommunityTweets,
+  fetchFollowers,
+  fetchFollowings,
+  fetchListTweets,
+  fetchSpaceDetail,
+  fetchThread,
+  fetchTrends,
+  fetchTweetQuotes,
+  fetchTweetReplies,
+  fetchTweetsByIds,
+  fetchTweetRetweeters,
+  fetchUserAbout,
+  fetchUserMentions,
+  fetchUserProfile,
+  fetchUserTweets,
+  normalizeParams,
+  searchTweets,
+  searchUsers,
+  statusIdFromUrl,
+  tweetIdFromInput,
+} from "./twitterapi.js";
+export type {
+  FollowersDetails,
+  ReplySort,
+  RetweetersDetails,
+  SearchDetails,
+  SpaceDetails,
+  Trend,
+  TrendsDetails,
+  Tweet,
+  TweetCollection,
+  TweetQuotesDetails,
+  TweetRepliesDetails,
+  TwitterApiSearchParams,
+  UserAbout,
+  UserCollection,
+  UserMentionsDetails,
+  UserTweetsDetails,
+} from "./twitterapi.js";
+export type { TwitterSearchDetails } from "./types.js";
+export { readMergedPiSettings, readPiProjectSettings, readPiUserSettings } from "./settings.js";
+export type { PiSettings } from "./settings.js";

package/src/settings.ts

@@ -0,0 +1,66 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { getAgentDir } from "@earendil-works/pi-coding-agent";
+
+export type PiSettings = Record<string, unknown>;
+
+function readJsonFile(filePath: string): PiSettings {
+	try {
+		return JSON.parse(readFileSync(filePath, "utf8")) as PiSettings;
+	} catch (error) {
+		const err = error as NodeJS.ErrnoException;
+		if (err.code === "ENOENT") {
+			return {};
+		}
+		throw error;
+	}
+}
+
+export function readPiProjectSettings(cwd = process.cwd()): PiSettings {
+	return readJsonFile(join(cwd, ".pi", "settings.json"));
+}
+
+/**
+ * Read the global settings file. The directory comes from pi's `getAgentDir()`,
+ * so `PI_CODING_AGENT_DIR` (and any other supported override) is respected
+ * instead of assuming `~/.pi/agent`.
+ */
+export function readPiUserSettings(agentDir = getAgentDir()): PiSettings {
+	return readJsonFile(join(agentDir, "settings.json"));
+}
+
+export interface ReadMergedPiSettingsOptions {
+	cwd?: string;
+	/** Override the global agent config directory (defaults to pi's `getAgentDir()`). */
+	agentDir?: string;
+}
+
+export function mergePiSettings(userSettings: PiSettings = {}, projectSettings: PiSettings = {}): PiSettings {
+	return deepMerge(userSettings, projectSettings);
+}
+
+export function readMergedPiSettings(options: ReadMergedPiSettingsOptions = {}): PiSettings {
+	return mergePiSettings(
+		readPiUserSettings(options.agentDir),
+		readPiProjectSettings(options.cwd),
+	);
+}
+
+function deepMerge(base: PiSettings, override: PiSettings): PiSettings {
+	const result: PiSettings = { ...base };
+	for (const [key, value] of Object.entries(override)) {
+		if (value === undefined) continue;
+
+		const existing = result[key];
+		if (isPlainObject(existing) && isPlainObject(value)) {
+			result[key] = deepMerge(existing, value);
+		} else {
+			result[key] = value;
+		}
+	}
+	return result;
+}
+
+function isPlainObject(value: unknown): value is PiSettings {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}