pim-agent 0.0.1 → 0.9.0

package/packages/core/src/extensions/todo/todo.ts

@@ -0,0 +1,185 @@
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { STATUSES, type TodoItem, type TodoStatus } from "./schema";
+
+export const TODO_STATE_CUSTOM_TYPE = "pim-todo-state";
+
+export type TodoSummary = Record<TodoStatus, number>;
+
+export type TodoDetails = {
+  readonly todos: readonly TodoItem[];
+  readonly summary: TodoSummary;
+};
+
+export type FormatChecklistOptions = {
+  readonly activeOnly?: boolean;
+};
+
+/** Identity key for the per-session state slot. */
+export type TodoSessionKey = ExtensionContext["sessionManager"];
+
+const itemsBySession = new WeakMap<TodoSessionKey, TodoItem[]>();
+
+const markers: Record<TodoStatus, string> = {
+  pending: "[ ]",
+  in_progress: "[>]",
+  completed: "[x]",
+  cancelled: "[~]",
+};
+
+const statusSet: ReadonlySet<TodoStatus> = new Set(STATUSES);
+
+export function getCurrentItems(
+  sessionManager: TodoSessionKey
+): readonly TodoItem[] {
+  return itemsBySession.get(sessionManager) ?? [];
+}
+
+export function replaceItems(
+  sessionManager: TodoSessionKey,
+  items: readonly TodoItem[]
+): readonly TodoItem[] {
+  const normalized = normalizeItems(items);
+  itemsBySession.set(sessionManager, normalized);
+  return normalized;
+}
+
+export function resetItems(sessionManager: TodoSessionKey): void {
+  itemsBySession.set(sessionManager, []);
+}
+
+export function reconstructFromBranch(
+  sessionManager: TodoSessionKey,
+  branch: readonly unknown[]
+): readonly TodoItem[] {
+  const items = findLatestTodoItems(branch);
+  itemsBySession.set(sessionManager, items);
+  return items;
+}
+
+export function normalizeItems(items: readonly TodoItem[]): TodoItem[] {
+  return items.flatMap((item) => {
+    const content = normalizeContent(item.content);
+    return content ? [{ content, status: item.status }] : [];
+  });
+}
+
+export function hasActiveItems(items: readonly TodoItem[]): boolean {
+  return items.some(isActive);
+}
+
+export function summarizeItems(items: readonly TodoItem[]): TodoSummary {
+  const summary: TodoSummary = {
+    pending: 0,
+    in_progress: 0,
+    completed: 0,
+    cancelled: 0,
+  };
+  for (const item of items) {
+    summary[item.status] += 1;
+  }
+  return summary;
+}
+
+export function makeDetails(items: readonly TodoItem[]): TodoDetails {
+  return {
+    todos: structuredClone(items),
+    summary: summarizeItems(items),
+  };
+}
+
+export function formatUpdateSummary(items: readonly TodoItem[]): string {
+  const summary = summarizeItems(items);
+  const segments = [
+    summary.completed > 0 ? `${summary.completed} completed` : undefined,
+    summary.in_progress > 0 ? `${summary.in_progress} in progress` : undefined,
+    summary.pending > 0 ? `${summary.pending} pending` : undefined,
+    summary.cancelled > 0 ? `${summary.cancelled} cancelled` : undefined,
+  ].filter((segment) => segment !== undefined);
+  return segments.length === 0
+    ? "Todos cleared."
+    : `Todos updated: ${segments.join(", ")}.`;
+}
+
+export function formatChecklist(
+  items: readonly TodoItem[],
+  options: FormatChecklistOptions = {}
+): string {
+  return items
+    .filter((item) => !options.activeOnly || isActive(item))
+    .map((item) => `${markers[item.status]} ${item.content}`)
+    .join("\n");
+}
+
+function isActive(item: TodoItem): boolean {
+  return item.status === "pending" || item.status === "in_progress";
+}
+
+export function normalizeContent(content: string): string {
+  return content.trim().replaceAll(/\s+/g, " ");
+}
+
+function findLatestTodoItems(branch: readonly unknown[]): TodoItem[] {
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const items = extractTodoItems(branch[i]);
+    if (items) {
+      return items;
+    }
+  }
+  return [];
+}
+
+function extractTodoItems(entry: unknown): TodoItem[] | undefined {
+  if (!isRecord(entry)) {
+    return undefined;
+  }
+  if (entry.type === "message") {
+    const message = entry.message;
+    if (
+      !isRecord(message) ||
+      message.role !== "toolResult" ||
+      message.toolName !== "todo"
+    ) {
+      return undefined;
+    }
+    const details = message.details;
+    if (!isRecord(details) || !Array.isArray(details.todos)) {
+      return undefined;
+    }
+    return normalizeUnknownItems(details.todos);
+  }
+  if (entry.type === "custom" && entry.customType === TODO_STATE_CUSTOM_TYPE) {
+    const data = entry.data;
+    if (!isRecord(data) || !Array.isArray(data.todos)) {
+      return undefined;
+    }
+    return normalizeUnknownItems(data.todos);
+  }
+  return undefined;
+}
+
+function normalizeUnknownItems(items: readonly unknown[]): TodoItem[] {
+  const out: TodoItem[] = [];
+  for (const item of items) {
+    if (!isRecord(item)) {
+      continue;
+    }
+    const { content, status } = item;
+    if (typeof content !== "string" || !isStatus(status)) {
+      continue;
+    }
+    const normalizedContent = normalizeContent(content);
+    if (!normalizedContent) {
+      continue;
+    }
+    out.push({ content: normalizedContent, status });
+  }
+  return out;
+}
+
+function isStatus(value: unknown): value is TodoStatus {
+  return typeof value === "string" && statusSet.has(value as TodoStatus);
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/packages/core/src/extensions/web-fetch/JinaReaderClient.ts

@@ -0,0 +1,187 @@
+import { Errors } from "../../shared/Errors";
+import { createKy, type HttpFetch } from "../../shared/Http";
+import { Json } from "../../shared/Json";
+import { HTTPError, TimeoutError, type KyInstance } from "ky";
+import type { WebFetchPage } from "./fetch";
+
+type JinaReaderClientOptions = {
+  readonly endpoint?: string;
+  readonly apiKey?: string;
+  readonly fetch?: HttpFetch;
+  readonly timeoutMs?: number;
+};
+
+type JinaReaderFetchInput = {
+  readonly url: string;
+  readonly signal?: AbortSignal;
+};
+
+class JinaReaderClientError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "JinaReaderClientError";
+  }
+}
+
+const defaultTimeoutMs = 20_000;
+
+export class JinaReaderClient {
+  private readonly endpoint: string;
+  private readonly headers: Headers;
+  private readonly ky: KyInstance;
+  private readonly timeoutMs: number;
+
+  public constructor(options: JinaReaderClientOptions = {}) {
+    this.endpoint = normalizeEndpoint(options.endpoint ?? "https://r.jina.ai");
+    this.headers = buildHeaders(options.apiKey);
+    this.timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+    this.ky = createKy(options.fetch);
+  }
+
+  public async fetchUrl(input: JinaReaderFetchInput): Promise<WebFetchPage> {
+    if (input.signal?.aborted) {
+      throw new JinaReaderClientError("Request aborted.");
+    }
+
+    let response: Response;
+
+    try {
+      response = await this.ky(`${this.endpoint}/${input.url}`, {
+        headers: this.headers,
+        timeout: this.timeoutMs,
+        ...(input.signal === undefined ? {} : { signal: input.signal }),
+      });
+    } catch (error) {
+      const aborted = input.signal?.aborted ?? false;
+
+      if (Errors.isAbort(error) || aborted) {
+        throw new JinaReaderClientError("Request aborted.");
+      }
+
+      if (error instanceof TimeoutError) {
+        throw new JinaReaderClientError(
+          `Request timed out after ${this.timeoutMs}ms.`
+        );
+      }
+
+      if (error instanceof HTTPError) {
+        throw new JinaReaderClientError(
+          `Request failed with HTTP ${error.response.status}: ${excerpt(stringifyErrorData(error.data))}`
+        );
+      }
+
+      throw new JinaReaderClientError(
+        `Request failed: ${Errors.describe(error)}`
+      );
+    }
+
+    return parseResponse(input.url, response, await response.text());
+  }
+}
+
+function buildHeaders(apiKey: string | undefined): Headers {
+  const headers = new Headers({ Accept: "application/json" });
+
+  if (apiKey !== undefined && apiKey.length > 0) {
+    headers.set("Authorization", `Bearer ${apiKey}`);
+  }
+
+  return headers;
+}
+
+function normalizeEndpoint(endpoint: string): string {
+  return endpoint.replace(/\/+$/u, "");
+}
+
+function parseResponse(
+  requestedUrl: string,
+  response: Response,
+  responseText: string
+): WebFetchPage {
+  const contentType = response.headers.get("content-type") ?? "";
+  const declaresJson =
+    contentType.includes("application/json") || contentType.includes("+json");
+  const parsedJson = Json.tryParseJson(responseText);
+
+  if (parsedJson === undefined) {
+    if (declaresJson) {
+      throw new JinaReaderClientError("Response contained malformed JSON.");
+    }
+
+    return createPage({
+      title: "",
+      url: requestedUrl,
+      content: responseText,
+    });
+  }
+
+  return parseJsonPayload(requestedUrl, parsedJson);
+}
+
+function parseJsonPayload(
+  requestedUrl: string,
+  parsedJson: unknown
+): WebFetchPage {
+  const responseRecord = Json.asRecord(parsedJson);
+  const payload = Json.asRecord(responseRecord?.["data"]) ?? responseRecord;
+
+  if (payload === undefined) {
+    throw new JinaReaderClientError("Response contained invalid payload.");
+  }
+
+  return createPage({
+    title: optionalString(payload["title"], "title") ?? "",
+    url: optionalString(payload["url"], "url") ?? requestedUrl,
+    content: requiredString(payload["content"], "content"),
+  });
+}
+
+function createPage(page: WebFetchPage): WebFetchPage {
+  if (page.content.trim().length === 0) {
+    throw new JinaReaderClientError("Response contained empty content.");
+  }
+
+  return page;
+}
+
+function requiredString(value: unknown, name: string): string {
+  if (typeof value !== "string") {
+    throw new JinaReaderClientError(
+      `Response contained invalid payload: expected string ${name}.`
+    );
+  }
+
+  return value;
+}
+
+function optionalString(value: unknown, name: string): string | undefined {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  if (typeof value !== "string") {
+    throw new JinaReaderClientError(
+      `Response contained invalid payload: expected string ${name}.`
+    );
+  }
+
+  return value;
+}
+
+function stringifyErrorData(data: unknown): string {
+  if (typeof data === "string") {
+    return data;
+  }
+
+  if (data === undefined) {
+    return "";
+  }
+
+  return JSON.stringify(data);
+}
+
+function excerpt(text: string): string {
+  const excerpt = text.replaceAll(/\s+/gu, " ").trim().slice(0, 200);
+
+  return excerpt.length === 0 ? "empty response body" : excerpt;
+}

package/packages/core/src/extensions/web-fetch/WebViewFetchClient.ts

@@ -0,0 +1,183 @@
+import { Errors } from "../../shared/Errors";
+import { platform } from "node:os";
+import type { WebFetchPage } from "./fetch";
+import { createMarkdownSnapshotScript } from "./WebViewMarkdownSnapshot";
+
+export type WebViewLike = {
+  readonly url: string;
+  readonly title: string;
+  readonly navigate: (url: string) => Promise<void>;
+  readonly evaluate: <T = unknown>(script: string) => Promise<T>;
+  readonly close: () => void;
+};
+
+export type WebViewFactory = () => WebViewLike;
+
+type WebViewFetchClientOptions = {
+  readonly factory?: WebViewFactory;
+  readonly timeoutMs?: number;
+};
+
+type WebViewFetchInput = {
+  readonly url: string;
+  readonly signal?: AbortSignal;
+};
+
+type WebViewSnapshot = {
+  readonly title: string;
+  readonly url: string;
+  readonly content: string;
+};
+
+class WebViewFetchClientError extends Error {
+  public constructor(message: string) {
+    super(message);
+    this.name = "WebViewFetchClientError";
+  }
+}
+
+const defaultTimeoutMs = 20_000;
+
+export class WebViewFetchClient {
+  private readonly factory: WebViewFactory;
+  private readonly timeoutMs: number;
+
+  public constructor(options: WebViewFetchClientOptions = {}) {
+    this.factory = options.factory ?? defaultFactory;
+    this.timeoutMs = options.timeoutMs ?? defaultTimeoutMs;
+  }
+
+  public async fetchHtml(input: WebViewFetchInput): Promise<WebFetchPage> {
+    return this.capturePage(input, htmlSnapshotScript());
+  }
+
+  public async fetchMarkdown(input: WebViewFetchInput): Promise<WebFetchPage> {
+    return this.capturePage(input, createMarkdownSnapshotScript());
+  }
+
+  private async capturePage(
+    input: WebViewFetchInput,
+    snapshotScript: string
+  ): Promise<WebFetchPage> {
+    const signal = input.signal;
+
+    if (signal?.aborted) {
+      throw new WebViewFetchClientError("Request aborted.");
+    }
+
+    let view: WebViewLike;
+
+    try {
+      view = this.factory();
+    } catch (error) {
+      throw new WebViewFetchClientError(
+        `Request failed: ${Errors.describe(error)}`
+      );
+    }
+
+    let aborted = false;
+    let timedOut = false;
+    const onAbort = () => {
+      aborted = true;
+      safeClose(view);
+    };
+
+    signal?.addEventListener("abort", onAbort, { once: true });
+
+    const timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      safeClose(view);
+    }, this.timeoutMs);
+
+    const checkInterrupted = (): void => {
+      if (timedOut) {
+        throw new WebViewFetchClientError(
+          `Request timed out after ${this.timeoutMs}ms.`
+        );
+      }
+      if (aborted) {
+        throw new WebViewFetchClientError("Request aborted.");
+      }
+    };
+
+    try {
+      await view.navigate(input.url);
+      checkInterrupted();
+
+      const snapshot = readSnapshot(
+        await view.evaluate<unknown>(snapshotScript)
+      );
+
+      if (snapshot.content.trim().length === 0) {
+        throw new WebViewFetchClientError("Response contained empty content.");
+      }
+
+      const finalUrl =
+        snapshot.url.length > 0
+          ? snapshot.url
+          : view.url.length > 0
+            ? view.url
+            : input.url;
+
+      return {
+        title: snapshot.title,
+        url: finalUrl,
+        content: snapshot.content,
+      };
+    } catch (error) {
+      checkInterrupted();
+
+      if (error instanceof WebViewFetchClientError) {
+        throw error;
+      }
+
+      throw new WebViewFetchClientError(
+        `Request failed: ${Errors.describe(error)}`
+      );
+    } finally {
+      clearTimeout(timeoutHandle);
+      signal?.removeEventListener("abort", onAbort);
+      safeClose(view);
+    }
+  }
+}
+
+function htmlSnapshotScript(): string {
+  return String.raw`(() => ({
+    title: document.title,
+    url: location.href,
+    content: document.documentElement.outerHTML,
+  }))()`;
+}
+
+function readSnapshot(value: unknown): WebViewSnapshot {
+  if (typeof value !== "object" || value === null) {
+    throw new WebViewFetchClientError("Response contained invalid payload.");
+  }
+
+  const record = value as Record<string, unknown>;
+
+  if (typeof record["content"] !== "string") {
+    throw new WebViewFetchClientError("Response contained invalid payload.");
+  }
+
+  return {
+    content: record["content"],
+    title: typeof record["title"] === "string" ? record["title"] : "",
+    url: typeof record["url"] === "string" ? record["url"] : "",
+  };
+}
+
+function safeClose(view: WebViewLike): void {
+  try {
+    view.close();
+  } catch {
+    // close() throws if already closed.
+  }
+}
+
+function defaultFactory(): WebViewLike {
+  return new Bun.WebView(
+    platform() === "darwin" ? undefined : { backend: "chrome" }
+  );
+}