@aria-cli/tools 1.0.0

package/src/slack/desktop-session.ts

@@ -0,0 +1,493 @@
+import crypto from "node:crypto";
+import { execFile } from "node:child_process";
+import { promises as fs } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+const SLACK_APP_SUPPORT_DIR = path.join(os.homedir(), "Library", "Application Support", "Slack");
+const SLACK_LEVELDB_DIR = path.join(SLACK_APP_SUPPORT_DIR, "Local Storage", "leveldb");
+const SLACK_COOKIE_DB_PATH = path.join(SLACK_APP_SUPPORT_DIR, "Cookies");
+const SLACK_SAFE_STORAGE_SERVICE = "Slack Safe Storage";
+const SLACK_APP_ORIGIN = "https://app.slack.com";
+const DEFAULT_BOOTSTRAP_TIMEOUT_MS = 30_000;
+
+const TEAM_ID_REGEX = /\bT[A-Z0-9]{8,}\b/g;
+const TOKEN_REGEX = /\bxoxc-[A-Za-z0-9-]{20,}\b/g;
+
+export interface SlackCachedDesktopState {
+  cachedToken: string | null;
+  teamIds: string[];
+}
+
+export interface SlackDesktopCookie {
+  name: string;
+  value: string;
+  domain: string;
+  path: string;
+  secure: boolean;
+  httpOnly: boolean;
+}
+
+export interface SlackDesktopBootstrap {
+  workspaceHost: string;
+  liveToken: string;
+}
+
+export interface SlackMessageView {
+  ts: string;
+  user: string | null;
+  text: string;
+  subtype: string | null;
+  threadTs: string | null;
+}
+
+export interface SlackConversationHistoryResult {
+  teamId: string;
+  workspaceHost: string;
+  channelId: string;
+  messages: SlackMessageView[];
+  hasMore: boolean;
+  nextCursor: string | null;
+}
+
+export interface SlackSendMessageResult {
+  teamId: string;
+  workspaceHost: string;
+  channelId: string;
+  ts: string;
+}
+
+export interface SlackAddReactionResult {
+  teamId: string;
+  workspaceHost: string;
+  channelId: string;
+}
+
+export function extractCachedSlackDesktopState(levelDbText: string): SlackCachedDesktopState {
+  const cachedToken = levelDbText.match(TOKEN_REGEX)?.[0] ?? null;
+  const teamIds: string[] = [];
+  const seen = new Set<string>();
+
+  const localConfigSegments = [...levelDbText.matchAll(/localConfig_v2[\s\S]{0,8000}/g)].map(
+    (match) => match[0],
+  );
+  const sources = localConfigSegments.length > 0 ? localConfigSegments : [levelDbText];
+
+  for (const source of sources) {
+    for (const teamId of source.match(TEAM_ID_REGEX) ?? []) {
+      if (seen.has(teamId)) continue;
+      seen.add(teamId);
+      teamIds.push(teamId);
+    }
+  }
+
+  return { cachedToken, teamIds };
+}
+
+export function extractWorkspaceHostFromAppHtml(html: string): string | null {
+  const enterpriseHosts = [...html.matchAll(/https:\/\/([A-Za-z0-9.-]+\.enterprise\.slack\.com)/g)]
+    .map((match) => match[1])
+    .filter(Boolean);
+  if (enterpriseHosts.length > 0) {
+    return enterpriseHosts[0] ?? null;
+  }
+
+  const workspaceHosts = [...html.matchAll(/https:\/\/([A-Za-z0-9.-]+\.slack\.com)/g)]
+    .map((match) => match[1])
+    .filter((host) => host !== "api.slack.com" && host !== "app.slack.com");
+  return workspaceHosts[0] ?? null;
+}
+
+export function extractLiveSlackTokenFromMultipartBody(body: string): string | null {
+  const match = body.match(/name="token"\r?\n\r?\n([^\r\n]+)/);
+  return match?.[1] ?? null;
+}
+
+function decryptChromiumCookieHex(cookieHex: string, safeStoragePassword: string): string {
+  const encryptedValue = Buffer.from(cookieHex, "hex");
+  if (encryptedValue.length === 0) {
+    return "";
+  }
+
+  const versionPrefix = encryptedValue.subarray(0, 3).toString("utf8");
+  if (versionPrefix !== "v10" && versionPrefix !== "v11") {
+    return encryptedValue.toString("utf8");
+  }
+
+  const key = crypto.pbkdf2Sync(safeStoragePassword, "saltysalt", 1003, 16, "sha1");
+  const decipher = crypto.createDecipheriv("aes-128-cbc", key, Buffer.alloc(16, 0x20));
+  let decrypted = Buffer.concat([decipher.update(encryptedValue.subarray(3)), decipher.final()]);
+
+  const padLength = decrypted.at(-1) ?? 0;
+  if (padLength > 0 && padLength <= 16) {
+    decrypted = decrypted.subarray(0, decrypted.length - padLength);
+  }
+
+  // Chromium cookie DB version 24 prefixes SHA-256(host_key) before the plaintext value.
+  if (decrypted.length >= 32) {
+    decrypted = decrypted.subarray(32);
+  }
+
+  return decrypted.toString("utf8");
+}
+
+async function readSlackLevelDbText(levelDbDir: string = SLACK_LEVELDB_DIR): Promise<string> {
+  const entries = await fs.readdir(levelDbDir);
+  const files = entries.filter((entry) => entry.endsWith(".ldb") || entry.endsWith(".log")).sort();
+
+  const chunks = await Promise.all(
+    files.map(async (entry) => {
+      const fullPath = path.join(levelDbDir, entry);
+      return fs.readFile(fullPath, "utf8").catch(async () => {
+        const bytes = await fs.readFile(fullPath);
+        return bytes.toString("utf8");
+      });
+    }),
+  );
+
+  return chunks.join("\n");
+}
+
+async function readSeedCookies(
+  cookieDbPath: string = SLACK_COOKIE_DB_PATH,
+): Promise<SlackDesktopCookie[]> {
+  const { stdout: passwordStdout } = await execFileAsync("security", [
+    "find-generic-password",
+    "-w",
+    "-s",
+    SLACK_SAFE_STORAGE_SERVICE,
+  ]);
+  const safeStoragePassword = passwordStdout.trim();
+
+  const sql = [
+    "SELECT host_key, name, path, is_secure, is_httponly, hex(encrypted_value)",
+    "FROM cookies",
+    "WHERE host_key IN ('.slack.com', 'app.slack.com')",
+    "AND name IN ('b', 'd')",
+    "ORDER BY name",
+  ].join(" ");
+  const { stdout } = await execFileAsync("sqlite3", ["-separator", "\t", cookieDbPath, sql]);
+
+  const cookies = stdout
+    .split("\n")
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => {
+      const [domain, name, cookiePath, secureFlag, httpOnlyFlag, encryptedHex] = line.split("\t");
+      if (!domain || !name || !encryptedHex) {
+        throw new Error(`Unexpected sqlite3 cookie row shape: ${line}`);
+      }
+      return {
+        name,
+        value: decryptChromiumCookieHex(encryptedHex ?? "", safeStoragePassword),
+        domain,
+        path: cookiePath || "/",
+        secure: secureFlag === "1",
+        httpOnly: httpOnlyFlag === "1",
+      } satisfies SlackDesktopCookie;
+    });
+
+  if (cookies.length === 0) {
+    throw new Error(
+      "Slack Desktop auth cookies were not found in the local Chromium cookie store.",
+    );
+  }
+
+  return cookies;
+}
+
+async function waitForLiveSlackBootstrap(
+  page: {
+    on(
+      event: "request",
+      listener: (request: { url(): string; postData(): string | null }) => void,
+    ): void;
+    off(
+      event: "request",
+      listener: (request: { url(): string; postData(): string | null }) => void,
+    ): void;
+  },
+  timeoutMs: number,
+): Promise<SlackDesktopBootstrap> {
+  return new Promise<SlackDesktopBootstrap>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      page.off("request", handleRequest);
+      reject(
+        new Error("Timed out while waiting for the live Slack Desktop API bootstrap request."),
+      );
+    }, timeoutMs);
+
+    const handleRequest = (request: { url(): string; postData(): string | null }) => {
+      const requestUrl = request.url();
+      if (!requestUrl.includes("/api/")) {
+        return;
+      }
+      const liveToken = extractLiveSlackTokenFromMultipartBody(request.postData() ?? "");
+      if (!liveToken) {
+        return;
+      }
+
+      clearTimeout(timer);
+      page.off("request", handleRequest);
+      resolve({
+        workspaceHost: new URL(requestUrl).host,
+        liveToken,
+      });
+    };
+
+    page.on("request", handleRequest);
+  });
+}
+
+type RequestValue = string | number | boolean | Record<string, unknown> | Array<unknown>;
+
+function normalizeRequestForm(
+  liveToken: string,
+  fields: Record<string, RequestValue | undefined>,
+): Record<string, string> {
+  const form: Record<string, string> = { token: liveToken };
+
+  for (const [key, value] of Object.entries(fields)) {
+    if (value === undefined) continue;
+    if (typeof value === "string") {
+      form[key] = value;
+      continue;
+    }
+    if (typeof value === "number" || typeof value === "boolean") {
+      form[key] = String(value);
+      continue;
+    }
+    form[key] = JSON.stringify(value);
+  }
+
+  return form;
+}
+
+function normalizeChannelRef(channelRef: string): string {
+  return channelRef.startsWith("#") ? channelRef.slice(1) : channelRef;
+}
+
+function looksLikeConversationId(channelRef: string): boolean {
+  return /^[CDG][A-Z0-9]{8,}$/.test(channelRef);
+}
+
+function toSlackMessageView(message: Record<string, unknown>): SlackMessageView {
+  return {
+    ts: typeof message.ts === "string" ? message.ts : "",
+    user:
+      typeof message.user === "string"
+        ? message.user
+        : typeof message.bot_id === "string"
+          ? message.bot_id
+          : null,
+    text: typeof message.text === "string" ? message.text : "",
+    subtype: typeof message.subtype === "string" ? message.subtype : null,
+    threadTs: typeof message.thread_ts === "string" ? message.thread_ts : null,
+  };
+}
+
+export interface SlackDesktopClient {
+  getTeamId(): string;
+  getWorkspaceHost(): string;
+  listMessages(input: {
+    channel: string;
+    limit?: number;
+    threadTs?: string;
+  }): Promise<SlackConversationHistoryResult>;
+  sendMessage(input: {
+    channel: string;
+    text: string;
+    threadTs?: string;
+  }): Promise<SlackSendMessageResult>;
+  addReaction(input: {
+    channel: string;
+    timestamp: string;
+    name: string;
+  }): Promise<SlackAddReactionResult>;
+  close(): Promise<void>;
+}
+
+export async function createSlackDesktopClient(options?: {
+  teamId?: string;
+  bootstrapTimeoutMs?: number;
+}): Promise<SlackDesktopClient> {
+  const cachedState = extractCachedSlackDesktopState(await readSlackLevelDbText());
+  const teamId = options?.teamId ?? cachedState.teamIds[0];
+  if (!teamId) {
+    throw new Error(
+      "No Slack workspace team id was discovered in the local Slack Desktop storage.",
+    );
+  }
+
+  const playwright = await import("playwright");
+  const browser = await playwright.chromium.launch({ headless: true });
+  const context = await browser.newContext();
+  await context.addCookies(await readSeedCookies());
+
+  const page = await context.newPage();
+  const bootstrapPromise = waitForLiveSlackBootstrap(
+    page,
+    options?.bootstrapTimeoutMs ?? DEFAULT_BOOTSTRAP_TIMEOUT_MS,
+  );
+  await page.goto(`${SLACK_APP_ORIGIN}/client/${teamId}`, {
+    waitUntil: "domcontentloaded",
+    timeout: options?.bootstrapTimeoutMs ?? DEFAULT_BOOTSTRAP_TIMEOUT_MS,
+  });
+  const bootstrap = await bootstrapPromise;
+
+  const invokeJsonApi = async (
+    method: string,
+    fields: Record<string, RequestValue | undefined>,
+  ): Promise<Record<string, unknown>> => {
+    const response = await context.request.post(
+      `https://${bootstrap.workspaceHost}/api/${method}`,
+      {
+        form: normalizeRequestForm(bootstrap.liveToken, fields),
+        headers: {
+          Origin: SLACK_APP_ORIGIN,
+          Referer: `${SLACK_APP_ORIGIN}/client/${teamId}`,
+        },
+      },
+    );
+    const text = await response.text();
+    let json: Record<string, unknown>;
+    try {
+      json = JSON.parse(text) as Record<string, unknown>;
+    } catch {
+      throw new Error(
+        `Slack API ${method} returned non-JSON response (HTTP ${response.status()}).`,
+      );
+    }
+
+    if (json.ok !== true) {
+      const errorCode = typeof json.error === "string" ? json.error : `http_${response.status()}`;
+      throw new Error(`Slack API ${method} failed: ${errorCode}`);
+    }
+
+    return json;
+  };
+
+  const resolveConversationId = async (channelRef: string): Promise<string> => {
+    const normalized = normalizeChannelRef(channelRef);
+    if (looksLikeConversationId(normalized)) {
+      return normalized;
+    }
+
+    let cursor: string | undefined;
+    for (let pageNumber = 0; pageNumber < 20; pageNumber += 1) {
+      const response = await invokeJsonApi("conversations.list", {
+        limit: 200,
+        exclude_archived: true,
+        types: "public_channel,private_channel,im,mpim",
+        cursor,
+      });
+      const channels = Array.isArray(response.channels) ? response.channels : [];
+      const match = channels.find((channel) => {
+        if (!channel || typeof channel !== "object") return false;
+        const name = typeof channel.name === "string" ? channel.name : null;
+        const nameNormalized =
+          typeof channel.name_normalized === "string" ? channel.name_normalized : null;
+        return name === normalized || nameNormalized === normalized.toLowerCase();
+      }) as Record<string, unknown> | undefined;
+
+      if (match && typeof match.id === "string") {
+        return match.id;
+      }
+
+      const responseMetadata =
+        response.response_metadata && typeof response.response_metadata === "object"
+          ? (response.response_metadata as Record<string, unknown>)
+          : undefined;
+      const nextCursor =
+        responseMetadata && typeof responseMetadata.next_cursor === "string"
+          ? responseMetadata.next_cursor.trim()
+          : "";
+      if (!nextCursor) {
+        break;
+      }
+      cursor = nextCursor;
+    }
+
+    throw new Error(
+      `Slack conversation "${channelRef}" was not found. Use a channel id like C..., G..., or D... if the name cannot be resolved.`,
+    );
+  };
+
+  return {
+    getTeamId: () => teamId,
+    getWorkspaceHost: () => bootstrap.workspaceHost,
+    listMessages: async ({ channel, limit = 20, threadTs }) => {
+      const channelId = await resolveConversationId(channel);
+      const method = threadTs ? "conversations.replies" : "conversations.history";
+      const response = await invokeJsonApi(method, {
+        channel: channelId,
+        limit: Math.max(1, Math.min(limit, 100)),
+        ...(threadTs ? { ts: threadTs } : {}),
+      });
+      const responseMetadata =
+        response.response_metadata && typeof response.response_metadata === "object"
+          ? (response.response_metadata as Record<string, unknown>)
+          : undefined;
+      const nextCursor =
+        responseMetadata && typeof responseMetadata.next_cursor === "string"
+          ? responseMetadata.next_cursor || null
+          : null;
+      const rawMessages = Array.isArray(response.messages) ? response.messages : [];
+
+      return {
+        teamId,
+        workspaceHost: bootstrap.workspaceHost,
+        channelId,
+        messages: rawMessages
+          .filter(
+            (message): message is Record<string, unknown> =>
+              !!message && typeof message === "object",
+          )
+          .map(toSlackMessageView),
+        hasMore: response.has_more === true,
+        nextCursor,
+      };
+    },
+    sendMessage: async ({ channel, text, threadTs }) => {
+      const channelId = await resolveConversationId(channel);
+      const response = await invokeJsonApi("chat.postMessage", {
+        channel: channelId,
+        text,
+        ...(threadTs ? { thread_ts: threadTs } : {}),
+      });
+      const ts = typeof response.ts === "string" ? response.ts : null;
+      if (!ts) {
+        throw new Error("Slack API chat.postMessage did not return a message timestamp.");
+      }
+
+      return {
+        teamId,
+        workspaceHost: bootstrap.workspaceHost,
+        channelId,
+        ts,
+      };
+    },
+    addReaction: async ({ channel, timestamp, name }) => {
+      const channelId = await resolveConversationId(channel);
+      await invokeJsonApi("reactions.add", {
+        channel: channelId,
+        timestamp,
+        name,
+      });
+
+      return {
+        teamId,
+        workspaceHost: bootstrap.workspaceHost,
+        channelId,
+      };
+    },
+    close: async () => {
+      await page.close().catch(() => undefined);
+      await context.close().catch(() => undefined);
+      await browser.close().catch(() => undefined);
+    },
+  };
+}

package/src/tool-factory.ts

@@ -0,0 +1,91 @@
+/**
+ * @aria/tools - Tool factory function
+ *
+ * Creates Tool objects from Zod schemas with runtime validation.
+ */
+
+import type { ZodType } from "zod";
+import { z } from "zod";
+import type { JSONSchema7 } from "json-schema";
+import type {
+  Tool,
+  ToolCategory,
+  ToolContext,
+  ToolResult,
+  RiskLevel,
+  LoadingTier,
+} from "./types.js";
+
+/** Options for the tool() factory function */
+export interface ToolFactoryOptions<T> {
+  /** Unique tool name */
+  name: string;
+  /** Human-readable description */
+  description: string;
+  /** Zod schema for parameter validation */
+  parameters: ZodType<T>;
+  /** Tool execution handler - receives Zod-validated input */
+  execute: (input: T, context: ToolContext) => Promise<ToolResult>;
+  /** Risk level for auto-approval (default: "safe") */
+  riskLevel?: RiskLevel;
+  /** Whether this tool only reads state (default: true) */
+  isReadOnly?: boolean;
+  /** Tool category (default: "meta") */
+  category?: ToolCategory;
+  /** Loading tier for TTFT optimization (default: "always") */
+  loadingTier?: LoadingTier;
+}
+
+/**
+ * Factory function for creating Tool objects from Zod schemas.
+ *
+ * Converts the Zod schema to JSON Schema 7 for LLM consumption,
+ * and wraps the execute handler with Zod validation.
+ *
+ * @example
+ * ```ts
+ * const getWeather = tool({
+ *   name: "get_weather",
+ *   description: "Get weather for a city",
+ *   parameters: z.object({ city: z.string(), units: z.enum(["F", "C"]) }),
+ *   execute: async (input) => ({
+ *     success: true,
+ *     message: `Weather in ${input.city}: sunny`,
+ *   }),
+ * });
+ * ```
+ */
+export function tool<T>(options: ToolFactoryOptions<T>): Tool {
+  const {
+    name,
+    description,
+    parameters: zodSchema,
+    execute,
+    riskLevel = "safe",
+    isReadOnly = true,
+    category = "meta",
+    loadingTier = "always",
+  } = options;
+
+  // Convert Zod schema to JSON Schema 7 using Zod v4's built-in conversion
+  const jsonSchema = z.toJSONSchema(zodSchema) as JSONSchema7;
+
+  // Remove the $schema key since the Tool interface expects a plain JSONSchema7 object
+  // describing the parameters, not a full standalone schema document
+  delete jsonSchema.$schema;
+
+  return {
+    name,
+    description,
+    category,
+    parameters: jsonSchema,
+    riskLevel,
+    isReadOnly,
+    loadingTier,
+    execute: async (input: unknown, context: ToolContext): Promise<ToolResult> => {
+      // Validate input with Zod before calling the handler
+      const parsed = zodSchema.parse(input) as T;
+      return execute(parsed, context);
+    },
+  };
+}