@aria-cli/tools 1.0.0

package/src/network-runtime/runtime-bootstrap-contract.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import {
+  LoopbackTlsIdentitySchema,
+  NodeIdSchema,
+  OwnerGenerationSchema,
+  PeerTransportIdSchema,
+  PrincipalFingerprintSchema,
+  RuntimeIdSchema,
+  SigningPublicKeySchema,
+  TlsCaFingerprintSchema,
+  TransportEndpointAdvertisementSchema,
+} from "./address-types.js";
+import { NetworkRuntimeProtocolVersionSchema } from "./protocol-schemas.js";
+
+const NonEmptyTrimmedStringSchema = z.string().trim().min(1);
+const NonBlankVerbatimStringSchema = z
+  .string()
+  .min(1)
+  .refine((value) => value.trim().length > 0);
+
+export const RuntimeBootstrapRevisionSchema = z.number().int().nonnegative();
+export type RuntimeBootstrapRevision = z.infer<typeof RuntimeBootstrapRevisionSchema>;
+
+export const RuntimeBootstrapPhaseSchema = z.enum([
+  "starting",
+  "tls_bound",
+  "control_ready",
+  "network_ready",
+  "mesh_ready",
+  "degraded",
+  "stopped",
+]);
+export type RuntimeBootstrapPhase = z.infer<typeof RuntimeBootstrapPhaseSchema>;
+
+export const RuntimeBootstrapControlEndpointSchema = z
+  .object({
+    host: NonEmptyTrimmedStringSchema,
+    port: z.number().int().min(1).max(65535),
+  })
+  .strict();
+export type RuntimeBootstrapControlEndpoint = z.infer<typeof RuntimeBootstrapControlEndpointSchema>;
+
+export const RuntimeBootstrapTlsSchema = z
+  .object({
+    caFingerprint: TlsCaFingerprintSchema,
+    caCertPem: NonBlankVerbatimStringSchema,
+    principalIdentity: PrincipalFingerprintSchema,
+    loopbackIdentity: LoopbackTlsIdentitySchema,
+  })
+  .strict();
+export type RuntimeBootstrapTls = z.infer<typeof RuntimeBootstrapTlsSchema>;
+
+export const RuntimeBootstrapIdentitySchema = z
+  .object({
+    signingPublicKey: SigningPublicKeySchema,
+    transportPublicKey: PeerTransportIdSchema,
+    transportEndpoint: TransportEndpointAdvertisementSchema,
+    displayNameSnapshot: NonEmptyTrimmedStringSchema.optional(),
+  })
+  .strict();
+export type RuntimeBootstrapIdentity = z.infer<typeof RuntimeBootstrapIdentitySchema>;
+
+export const RuntimeBootstrapRecordSchema = z
+  .object({
+    nodeId: NodeIdSchema,
+    runtimeId: RuntimeIdSchema,
+    arionName: NonEmptyTrimmedStringSchema.optional(),
+    ownerGeneration: OwnerGenerationSchema,
+    bootstrapRevision: RuntimeBootstrapRevisionSchema,
+    phase: RuntimeBootstrapPhaseSchema,
+    protocolVersion: NetworkRuntimeProtocolVersionSchema,
+    controlEndpoint: RuntimeBootstrapControlEndpointSchema,
+    displayNameSnapshot: NonEmptyTrimmedStringSchema.optional(),
+    signingPublicKey: SigningPublicKeySchema,
+    transportPublicKey: PeerTransportIdSchema,
+    transportEndpoint: TransportEndpointAdvertisementSchema,
+    tls: RuntimeBootstrapTlsSchema,
+    publishedAt: NonEmptyTrimmedStringSchema,
+    degradedReason: NonEmptyTrimmedStringSchema.optional(),
+    failedPhase: RuntimeBootstrapPhaseSchema.optional(),
+  })
+  .strict();
+export type RuntimeBootstrapRecord = z.infer<typeof RuntimeBootstrapRecordSchema>;

package/src/outlook/desktop-session.ts

@@ -0,0 +1,409 @@
+import os from "node:os";
+import path from "node:path";
+import { promises as fs } from "node:fs";
+
+const OUTLOOK_SESSION_DIR = path.join(os.homedir(), ".aria", "outlook-session");
+const OUTLOOK_TOKEN_CACHE = path.join(os.homedir(), ".aria", "cache", "outlook-token.json");
+const OUTLOOK_WEB_URL = "https://outlook.office.com/mail/";
+// Outlook web uses outlook.office.com-scoped tokens, not graph.microsoft.com.
+// The Outlook REST v2 API at outlook.office.com/api/v2.0 accepts these tokens.
+const OUTLOOK_REST_API_BASE = "https://outlook.office.com/api/v2.0";
+const DEFAULT_BOOTSTRAP_TIMEOUT_MS = 60_000;
+
+interface CachedToken {
+  bearerToken: string;
+  accountEmail: string;
+  expiresAt: number; // epoch ms
+}
+
+async function loadCachedToken(): Promise<CachedToken | null> {
+  try {
+    const raw = await fs.readFile(OUTLOOK_TOKEN_CACHE, "utf-8");
+    const cached = JSON.parse(raw) as CachedToken;
+    // Token valid if >5 min remaining
+    if (cached.bearerToken && cached.expiresAt > Date.now() + 5 * 60_000) {
+      return cached;
+    }
+  } catch {
+    // no cache or invalid
+  }
+  return null;
+}
+
+async function saveCachedToken(token: string, email: string): Promise<void> {
+  // Decode JWT to get expiry
+  let exp = Date.now() + 60 * 60_000; // default 1h
+  try {
+    const part = token.split(".")[1];
+    if (!part) throw new Error("no payload");
+    const payload = JSON.parse(Buffer.from(part, "base64").toString());
+    if (payload.exp) exp = payload.exp * 1000;
+  } catch {
+    /* best-effort */
+  }
+  const cached: CachedToken = { bearerToken: token, accountEmail: email, expiresAt: exp };
+  await fs.mkdir(path.dirname(OUTLOOK_TOKEN_CACHE), { recursive: true });
+  await fs.writeFile(OUTLOOK_TOKEN_CACHE, JSON.stringify(cached, null, 2));
+}
+
+export interface OutlookMessageView {
+  id: string;
+  subject: string;
+  from: { name: string; email: string };
+  toRecipients: { name: string; email: string }[];
+  receivedDateTime: string;
+  isRead: boolean;
+  hasAttachments: boolean;
+  bodyPreview: string;
+  conversationId: string;
+}
+
+export interface OutlookMessageDetail extends OutlookMessageView {
+  body: { contentType: string; content: string };
+  ccRecipients: { name: string; email: string }[];
+  importance: string;
+}
+
+export interface OutlookListMessagesResult {
+  accountEmail: string;
+  folder: string;
+  messages: OutlookMessageView[];
+  totalCount: number;
+}
+
+export interface OutlookSendResult {
+  accountEmail: string;
+  status: "sent";
+}
+
+export interface OutlookDesktopClient {
+  getAccountEmail(): string;
+  listMessages(input: {
+    folder?: string;
+    limit?: number;
+    filter?: string;
+    search?: string;
+  }): Promise<OutlookListMessagesResult>;
+  getMessage(input: { messageId: string }): Promise<OutlookMessageDetail>;
+  sendMessage(input: {
+    to: string[];
+    cc?: string[];
+    subject: string;
+    body: string;
+    bodyType?: "text" | "html";
+  }): Promise<OutlookSendResult>;
+  replyMessage(input: {
+    messageId: string;
+    body: string;
+    bodyType?: "text" | "html";
+    replyAll?: boolean;
+  }): Promise<OutlookSendResult>;
+  close(): Promise<void>;
+}
+
+// Outlook REST v2 returns PascalCase keys (Subject, From, EmailAddress)
+// while Graph API uses camelCase (subject, from, emailAddress).
+// Helper to read a field with either casing.
+function field(obj: Record<string, unknown>, camelKey: string): unknown {
+  if (camelKey in obj) return obj[camelKey];
+  const pascalKey = camelKey.charAt(0).toUpperCase() + camelKey.slice(1);
+  return obj[pascalKey];
+}
+
+function fieldStr(obj: Record<string, unknown>, camelKey: string): string {
+  const v = field(obj, camelKey);
+  return typeof v === "string" ? v : "";
+}
+
+function parseRecipient(
+  recipient: Record<string, unknown>,
+): { name: string; email: string } | null {
+  const emailAddress = (field(recipient, "emailAddress") as Record<string, unknown>) ?? null;
+  if (!emailAddress || typeof emailAddress !== "object") return null;
+  return {
+    name: fieldStr(emailAddress, "name"),
+    email: fieldStr(emailAddress, "address"),
+  };
+}
+
+function parseRecipients(raw: unknown): { name: string; email: string }[] {
+  if (!Array.isArray(raw)) return [];
+  return raw
+    .filter((r): r is Record<string, unknown> => !!r && typeof r === "object")
+    .map(parseRecipient)
+    .filter((r): r is { name: string; email: string } => r !== null);
+}
+
+function toMessageView(msg: Record<string, unknown>): OutlookMessageView {
+  const fromRaw = field(msg, "from");
+  const from =
+    fromRaw && typeof fromRaw === "object"
+      ? parseRecipient(fromRaw as Record<string, unknown>)
+      : null;
+  return {
+    id: fieldStr(msg, "id") || fieldStr(msg, "Id"),
+    subject: fieldStr(msg, "subject"),
+    from: from ?? { name: "", email: "" },
+    toRecipients: parseRecipients(field(msg, "toRecipients")),
+    receivedDateTime: fieldStr(msg, "receivedDateTime"),
+    isRead: field(msg, "isRead") === true,
+    hasAttachments: field(msg, "hasAttachments") === true,
+    bodyPreview: fieldStr(msg, "bodyPreview"),
+    conversationId: fieldStr(msg, "conversationId"),
+  };
+}
+
+function toMessageDetail(msg: Record<string, unknown>): OutlookMessageDetail {
+  const view = toMessageView(msg);
+  const bodyRaw = field(msg, "body");
+  const body = bodyRaw && typeof bodyRaw === "object" ? (bodyRaw as Record<string, unknown>) : {};
+  return {
+    ...view,
+    body: {
+      contentType: fieldStr(body, "contentType") || "text",
+      content: fieldStr(body, "content"),
+    },
+    ccRecipients: parseRecipients(field(msg, "ccRecipients")),
+    importance: fieldStr(msg, "importance") || "normal",
+  };
+}
+
+async function waitForMailBearerToken(
+  page: {
+    on(
+      event: "request",
+      listener: (request: { url(): string; headers(): Record<string, string> }) => void,
+    ): void;
+    off(
+      event: "request",
+      listener: (request: { url(): string; headers(): Record<string, string> }) => void,
+    ): void;
+  },
+  timeoutMs: number,
+): Promise<{ bearerToken: string; accountEmail: string }> {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      page.off("request", handleRequest);
+      reject(
+        new Error(
+          "Timed out waiting for a Mail-scoped bearer token. " +
+            "Ensure you are logged in to outlook.office.com.",
+        ),
+      );
+    }, timeoutMs);
+
+    const seen = new Set<string>();
+
+    const handleRequest = (request: { url(): string; headers(): Record<string, string> }) => {
+      const authHeader = request.headers()["authorization"];
+      if (!authHeader || !authHeader.startsWith("Bearer ")) return;
+
+      const bearerToken = authHeader.slice(7);
+
+      const dedup = bearerToken.substring(0, 30);
+      if (seen.has(dedup)) return;
+      seen.add(dedup);
+
+      // Decode JWT payload to extract email and scopes
+      let accountEmail = "";
+      let scp = "";
+      try {
+        const payloadB64 = bearerToken.split(".")[1];
+        if (payloadB64) {
+          const payload = JSON.parse(
+            Buffer.from(payloadB64, "base64url").toString("utf8"),
+          ) as Record<string, unknown>;
+          scp = typeof payload.scp === "string" ? payload.scp : "";
+          accountEmail =
+            typeof payload.upn === "string"
+              ? payload.upn
+              : typeof payload.preferred_username === "string"
+                ? payload.preferred_username
+                : typeof payload.unique_name === "string"
+                  ? payload.unique_name
+                  : "";
+        }
+      } catch {
+        // JWT decode is best-effort
+      }
+
+      // Only accept tokens with Mail.Read scope (from outlook.cloud.microsoft)
+      if (!scp.includes("Mail.Read")) return;
+
+      clearTimeout(timer);
+      page.off("request", handleRequest);
+      resolve({ bearerToken, accountEmail });
+    };
+
+    page.on("request", handleRequest);
+  });
+}
+
+// Stateless client using a cached bearer token (no Playwright needed)
+function createStatelessClient(bearerToken: string, accountEmail: string): OutlookDesktopClient {
+  const invokeApi = async (
+    method: "GET" | "POST",
+    endpoint: string,
+    body?: Record<string, unknown>,
+  ): Promise<Record<string, unknown>> => {
+    const url = `${OUTLOOK_REST_API_BASE}${endpoint}`;
+    const headers: Record<string, string> = {
+      Authorization: `Bearer ${bearerToken}`,
+      "Content-Type": "application/json",
+    };
+    const resp = await fetch(url, {
+      method,
+      headers,
+      body: body ? JSON.stringify(body) : undefined,
+    });
+    if (resp.status === 204) return { status: 204 };
+    const text = await resp.text();
+    let json: Record<string, unknown>;
+    try {
+      json = JSON.parse(text);
+    } catch {
+      throw new Error(`Outlook API ${method} ${endpoint} returned non-JSON (HTTP ${resp.status}).`);
+    }
+    if (resp.status >= 400) {
+      const error =
+        json.error && typeof json.error === "object" ? (json.error as Record<string, unknown>) : {};
+      const code = typeof error.code === "string" ? error.code : `http_${resp.status}`;
+      const message = typeof error.message === "string" ? error.message : "Unknown error";
+      throw new Error(`Outlook API ${method} ${endpoint} failed: ${code} — ${message}`);
+    }
+    return json;
+  };
+
+  return buildClientMethods(invokeApi, accountEmail, async () => {
+    /* no-op close */
+  });
+}
+
+export async function createOutlookDesktopClient(opts?: {
+  accountHint?: string;
+  bootstrapTimeoutMs?: number;
+}): Promise<OutlookDesktopClient> {
+  const timeoutMs = opts?.bootstrapTimeoutMs ?? DEFAULT_BOOTSTRAP_TIMEOUT_MS;
+
+  // Strategy 1: Use cached token if still valid (no Playwright needed)
+  const cached = await loadCachedToken();
+  if (cached) {
+    return createStatelessClient(cached.bearerToken, cached.accountEmail);
+  }
+
+  // Strategy 2: Launch Playwright headful to get a fresh token via SSO
+  // Must be headful — Microsoft SSO blocks headless Chromium
+  await fs.mkdir(OUTLOOK_SESSION_DIR, { recursive: true });
+  const playwright = await import("playwright");
+  const context = await playwright.chromium.launchPersistentContext(OUTLOOK_SESSION_DIR, {
+    headless: false,
+    args: ["--start-maximized"],
+    viewport: null,
+  });
+
+  const page = context.pages()[0] ?? (await context.newPage());
+
+  const bootstrapPromise = waitForMailBearerToken(page, timeoutMs);
+  await page.goto(OUTLOOK_WEB_URL, {
+    waitUntil: "domcontentloaded",
+    timeout: timeoutMs,
+  });
+
+  const { bearerToken, accountEmail } = await bootstrapPromise;
+
+  // Cache the token for subsequent calls (avoids launching Playwright)
+  await saveCachedToken(bearerToken, accountEmail);
+
+  // Close browser immediately — we have the token, use stateless client
+  await page.close().catch(() => undefined);
+  await context.close().catch(() => undefined);
+
+  return createStatelessClient(bearerToken, accountEmail);
+}
+
+type ApiInvoker = (
+  method: "GET" | "POST",
+  endpoint: string,
+  body?: Record<string, unknown>,
+) => Promise<Record<string, unknown>>;
+
+function buildClientMethods(
+  invokeApi: ApiInvoker,
+  accountEmail: string,
+  closeFn: () => Promise<void>,
+): OutlookDesktopClient {
+  return {
+    getAccountEmail: () => accountEmail,
+
+    listMessages: async ({ folder = "inbox", limit = 20, filter, search }) => {
+      const params = new URLSearchParams();
+      params.set("$top", String(Math.max(1, Math.min(limit, 50))));
+      params.set(
+        "$select",
+        "Id,Subject,From,ToRecipients,ReceivedDateTime,IsRead,HasAttachments,BodyPreview,ConversationId",
+      );
+      params.set("$orderby", "ReceivedDateTime desc");
+      if (filter) params.set("$filter", filter);
+      if (search) params.set("$search", `"${search}"`);
+
+      const endpoint = `/me/mailFolders/${encodeURIComponent(folder)}/messages?${params.toString()}`;
+      const json = await invokeApi("GET", endpoint);
+
+      const rawMessages = Array.isArray(json.value) ? json.value : [];
+      const messages = rawMessages
+        .filter((m): m is Record<string, unknown> => !!m && typeof m === "object")
+        .map(toMessageView);
+
+      return {
+        accountEmail,
+        folder,
+        messages,
+        totalCount:
+          typeof json["@odata.count"] === "number" ? json["@odata.count"] : messages.length,
+      };
+    },
+
+    getMessage: async ({ messageId }) => {
+      const json = await invokeApi("GET", `/me/messages/${encodeURIComponent(messageId)}`);
+      return toMessageDetail(json);
+    },
+
+    sendMessage: async ({ to, cc, subject, body, bodyType = "text" }) => {
+      const toRecipients = to.map((email) => ({
+        EmailAddress: { Address: email },
+      }));
+      const ccRecipients = (cc ?? []).map((email) => ({
+        EmailAddress: { Address: email },
+      }));
+
+      await invokeApi("POST", "/me/sendMail", {
+        Message: {
+          Subject: subject,
+          Body: { ContentType: bodyType === "html" ? "HTML" : "Text", Content: body },
+          ToRecipients: toRecipients,
+          ...(ccRecipients.length > 0 ? { CcRecipients: ccRecipients } : {}),
+        },
+      });
+
+      return { accountEmail, status: "sent" as const };
+    },
+
+    replyMessage: async ({ messageId, body, bodyType = "text", replyAll = false }) => {
+      const replyMethod = replyAll ? "ReplyAll" : "Reply";
+      await invokeApi("POST", `/me/messages/${encodeURIComponent(messageId)}/${replyMethod}`, {
+        Comment: body,
+        ...(bodyType === "html"
+          ? {
+              Message: {
+                Body: { ContentType: "HTML", Content: body },
+              },
+            }
+          : {}),
+      });
+
+      return { accountEmail, status: "sent" as const };
+    },
+
+    close: closeFn,
+  };
+}

package/src/policy.ts

@@ -0,0 +1,171 @@
+/**
+ * Tool Policy Engine
+ *
+ * Evaluates whether a tool is allowed based on allow/deny lists with group expansion.
+ * Supports layered policy merging (intersection semantics) for arion + RunOptions policies.
+ */
+
+export interface ToolPolicy {
+  /** Tool names or group names to allow. Empty array or undefined = allow all */
+  allow?: string[];
+  /** Tool names or group names to deny. Applied after allow. Deny wins. */
+  deny?: string[];
+  /**
+   * Internal marker used by policy merging:
+   * when true, treat allow (even empty) as an explicit restriction.
+   * This preserves deny-all semantics for empty intersections.
+   */
+  restrictAllow?: boolean;
+}
+
+/** Built-in tool groups */
+export const TOOL_GROUPS: Record<string, string[]> = {
+  "group:memory": [
+    "remember",
+    "recall",
+    "forget",
+    "recall_knowledge",
+    "reflect",
+    "search",
+    "learn",
+    "session_history",
+  ],
+  "group:web": ["web_search", "web_fetch", "browse", "browser"],
+  "group:filesystem": ["read_file", "write_file", "edit_file", "glob", "grep", "ls", "apply_patch"],
+  "group:shell": [
+    "bash",
+    "exec",
+    "spawn",
+    "kill",
+    "list_processes",
+    "wait_process",
+    "write_stdin",
+    "process",
+  ],
+  "group:arion": [
+    "hatch_arion",
+    "wake_arion",
+    "rest_arion",
+    "retire_arion",
+    "delegate_arion",
+    "manage_network",
+    "list_clients",
+    "deploy",
+  ],
+  "group:meta": [
+    "ask_user",
+    "quest_update",
+    "quest_list",
+    "search",
+    "learn",
+    "learn_tool",
+    "learn_skill",
+    "create_tool",
+    "create_skill",
+    "use_skill",
+    "restart",
+    "spawn_worker",
+    "check_delegation",
+    "pause_delegation",
+    "resume_delegation",
+    "quest_report",
+    "self_diagnose",
+  ],
+};
+
+/**
+ * Expand group references in a policy list.
+ * "group:memory" → ["remember", "recall", "forget", "reflect"]
+ * Individual tool names pass through unchanged.
+ * Unknown group names are ignored (treated as empty).
+ */
+export function expandGroups(names: string[]): Set<string> {
+  const result = new Set<string>();
+  for (const name of names) {
+    const lower = name.toLowerCase();
+    if (lower.startsWith("group:")) {
+      const members = TOOL_GROUPS[lower];
+      if (members) {
+        for (const member of members) {
+          result.add(member.toLowerCase());
+        }
+      }
+      // Unknown group names are silently ignored
+    } else {
+      result.add(lower);
+    }
+  }
+  return result;
+}
+
+/**
+ * Evaluate whether a tool is allowed by a policy.
+ * Rules:
+ * 1. If allow is empty/undefined and restrictAllow is false/undefined
+ *    → all tools allowed (then check deny)
+ * 2. If allow is non-empty OR restrictAllow=true
+ *    → only listed tools/groups allowed (empty allow + restrictAllow=true denies all)
+ * 3. Deny always wins over allow
+ */
+export function isToolAllowed(toolName: string, policy: ToolPolicy): boolean {
+  const normalized = toolName.toLowerCase();
+
+  // Check allow list: when restricted, tool must be in allowed set.
+  const isAllowRestricted =
+    policy.restrictAllow === true || (policy.allow !== undefined && policy.allow.length > 0);
+  if (isAllowRestricted) {
+    const allowed = expandGroups(policy.allow ?? []);
+    if (!allowed.has(normalized)) {
+      return false;
+    }
+  }
+
+  // Check deny list: deny always wins
+  if (policy.deny && policy.deny.length > 0) {
+    const denied = expandGroups(policy.deny);
+    if (denied.has(normalized)) {
+      return false;
+    }
+  }
+
+  return true;
+}
+
+/**
+ * Merge two policies (intersection). Used for layered evaluation:
+ * arion policy ∩ RunOptions policy = effective policy.
+ * A tool must be allowed by BOTH layers.
+ */
+export function mergePolicies(a: ToolPolicy, b: ToolPolicy): ToolPolicy {
+  // Merge deny: union of both deny lists
+  const mergedDeny = [...(a.deny ?? []), ...(b.deny ?? [])];
+
+  // Merge allow with restriction semantics:
+  // - both restricted: intersection (possibly empty = deny all)
+  // - one restricted: inherit that restriction
+  // - neither restricted: unrestricted
+  const aRestricts = a.restrictAllow === true || (a.allow?.length ?? 0) > 0;
+  const bRestricts = b.restrictAllow === true || (b.allow?.length ?? 0) > 0;
+
+  let mergedAllow: string[] | undefined;
+  let mergedRestrictAllow = false;
+
+  if (aRestricts && bRestricts) {
+    const expandedA = expandGroups(a.allow ?? []);
+    const expandedB = expandGroups(b.allow ?? []);
+    mergedAllow = [...expandedA].filter((name) => expandedB.has(name));
+    mergedRestrictAllow = true;
+  } else if (aRestricts) {
+    mergedAllow = [...(a.allow ?? [])];
+    mergedRestrictAllow = true;
+  } else if (bRestricts) {
+    mergedAllow = [...(b.allow ?? [])];
+    mergedRestrictAllow = true;
+  }
+
+  return {
+    ...(mergedAllow !== undefined ? { allow: mergedAllow } : {}),
+    ...(mergedRestrictAllow ? { restrictAllow: true } : {}),
+    ...(mergedDeny.length ? { deny: mergedDeny } : {}),
+  };
+}