agent-accelerator 0.4.0 → 0.5.0

package/src/types/response.ts

@@ -9,6 +9,8 @@ export interface SubAgentStep {
   name?: string;
   text?: string;
   thinking?: string;
+  /** Opaque provider thought signature captured with this step's reasoning, when present. */
+  thoughtSignature?: string;
   isError?: boolean;
   timestamp: number;
   /** True while the worker is still streaming this step; finalized on turn end. */
@@ -101,6 +103,8 @@ export function normalizeFinishReason(raw?: string): {
 /** JSON representation returned by AgentResponse.toJSON(). */
 export interface AgentResponseJSON {
   text: string;
+  /** Validated structured-output value when `AgentConfig.output` was set. */
+  parsed?: unknown;
   thinking?: string;
   thoughtSignature?: string;
   toolCalls?: ToolCallRecord[];
@@ -121,6 +125,8 @@ export interface AgentResponseJSON {
 /** Normalized final result returned by every Agent run. */
 export class AgentResponse {
   readonly text: string;
+  /** Validated structured-output value when `AgentConfig.output` was set. */
+  readonly parsed?: unknown;
   readonly thinking?: string;
   readonly thoughtSignature?: string;
   readonly toolCalls: ToolCallRecord[];
@@ -146,6 +152,7 @@ export class AgentResponse {
    */
   constructor(data: {
     text: string;
+    parsed?: unknown;
     thinking?: string;
     thoughtSignature?: string;
     toolCalls?: ToolCallRecord[];
@@ -162,6 +169,7 @@ export class AgentResponse {
     turns?: number;
   }) {
     this.text = data.text;
+    if (data.parsed !== undefined) (this as { parsed?: unknown }).parsed = data.parsed;
     this.thinking = data.thinking;
     this.thoughtSignature = data.thoughtSignature;
     this.toolCalls = data.toolCalls ?? [];
@@ -187,6 +195,7 @@ export class AgentResponse {
   toJSON(): AgentResponseJSON {
     return {
       text: this.text,
+      ...(this.parsed !== undefined ? { parsed: this.parsed } : {}),
       thinking: this.thinking,
       thoughtSignature: this.thoughtSignature,
       toolCalls: this.toolCalls.length > 0 ? this.toolCalls : undefined,

package/src/types/scheduler.ts

@@ -0,0 +1,81 @@
+/** Lifecycle of a scheduled action as stored in `tasks.json`. */
+export type ScheduledState = "waiting" | "cooking" | "missed" | "done";
+
+/** Outcome of one run. */
+export type ScheduledRunStatus = "ok" | "failed";
+
+/** Schedule fields shared by `create` input and the stored record. */
+export interface ScheduleSpec {
+  /** Delivery clock time `DD:HH:MM`: `DD` days from today, `HH:MM` on a 12-hour clock (see `meridiem`). */
+  timeToDeliver: string;
+  meridiem: "AM" | "PM";
+  /** Duration `DD:HH:MM` before delivery at which the run starts. Default 10 minutes (`00:00:10`). */
+  startCookingInAdvance?: string;
+  /** Duration `DD:HH:MM` between deliveries (`01:00:00` daily). Omit to run once. */
+  repeatEvery?: string;
+  /** Extra attempts if a run fails, only while time remains before delivery. Default 0. */
+  retries?: number;
+}
+
+/** What `createScheduledAction` receives: dynamic sub-agent fields plus the schedule. */
+export interface ScheduledActionInput {
+  role?: string;
+  instructions: string;
+  task: string;
+  /** Names from the developer's `dynamicSubagents.tools` pool. */
+  tools?: string[];
+  timeoutMs?: number;
+  scheduled_action: ScheduleSpec & {
+    /** Human label. */
+    name: string;
+    /** Lowercase kebab-case, max 48 chars. The SDK appends 6 random chars. */
+    id: string;
+  };
+}
+
+/** What `updateScheduledAction` may change. `id` and the creating agent are immutable. */
+export type ScheduledActionPatch = Partial<Omit<ScheduledActionInput, "scheduled_action">> & {
+  scheduled_action?: Partial<Omit<ScheduledActionInput["scheduled_action"], "id">>;
+};
+
+/** One entry of `tasks.json`. All times are local clock strings `YYYY-MM-DDTHH:mm:ss` (no offset). */
+export interface ScheduledActionRecord {
+  id: string;
+  name: string;
+  /** Name of the creating Agent; it runs the worker. */
+  agent: string;
+  role?: string;
+  instructions: string;
+  task: string;
+  /** Tool NAMES only; resolved against the live agent's pool at run time. */
+  tools: string[];
+  timeoutMs?: number;
+  /** The schedule as given. The stored truth is `nextCookAt` / `nextDeliverAt`. */
+  schedule: ScheduleSpec & { startCookingInAdvance: string };
+  state: ScheduledState;
+  /** `null` for a finished one-shot. */
+  nextCookAt: string | null;
+  nextDeliverAt: string | null;
+  createdAt: string;
+  /** Present only while `state` is `cooking`. */
+  current?: { cookStartedAt: string; deliverAt: string };
+  lastRun?: { status: ScheduledRunStatus; file: string; deliverAt: string; deliveredAt: string; late: boolean };
+}
+
+/** Payload of the `scheduled_action.delivered` telemetry event. Plain JSON. */
+export interface ScheduledDelivery {
+  id: string;
+  name: string;
+  status: ScheduledRunStatus;
+  /** Absolute path of the run file. */
+  file: string;
+  readyAt: string;
+  deliverAt: string;
+  late: boolean;
+}
+
+/** Result of `killScheduledAction`. */
+export type KillResult =
+  | { ok: true }
+  | { ok: false; reason: "not_found" }
+  | { ok: false; reason: "running"; message: string };

package/src/types/tool.ts

@@ -136,3 +136,18 @@ export interface ToolResultRecord {
   isError?: boolean;
   durationMs?: number;
 }
+
+/**
+ * Key of the marker object that replaces tool arguments whose streamed JSON
+ * never parsed (`{ __truncated_raw: "<partial text>" }`). It is deliberately
+ * not a plausible parameter name, so a real tool with a `raw` parameter is
+ * never mistaken for a truncated call. Such calls are never executed.
+ */
+export const TRUNCATED_ARGS_KEY = "__truncated_raw";
+
+/** True when `args` is exactly the truncated-arguments marker. */
+export function isTruncatedArguments(args: unknown): boolean {
+  if (!args || typeof args !== "object" || Array.isArray(args)) return false;
+  const keys = Object.keys(args as Record<string, unknown>);
+  return keys.length === 1 && keys[0] === TRUNCATED_ARGS_KEY && typeof (args as Record<string, unknown>)[TRUNCATED_ARGS_KEY] === "string";
+}

package/src/utils/cache.ts

@@ -71,7 +71,7 @@ export interface CreateExplicitCacheOptions {
 
 /**
  * Creates an explicit cached content object using Google Gemini's cachedContents API.
- * REST: POST https://generativelanguage.googleapis.com/v1beta/cachedContents?key=...
+ * REST: POST https://generativelanguage.googleapis.com/v1beta/cachedContents (key in the `x-goog-api-key` header)
  */
 /**
  * Creates a Google Gemini cachedContents resource through the REST API.
@@ -125,11 +125,13 @@ export async function createExplicitCache(
     (payload as any).tool_config = options.toolConfig;
   }
 
-  const url = `${baseUrl}/cachedContents?key=${apiKey}`;
+  // The key travels in a header, never in the URL (URLs end up in proxy and access logs).
+  const url = `${baseUrl}/cachedContents`;
   const response = await fetch(url, {
     method: "POST",
     headers: {
       "Content-Type": "application/json",
+      "x-goog-api-key": apiKey,
     },
     body: JSON.stringify(payload),
   });
@@ -152,8 +154,15 @@ export async function createExplicitCache(
 /** Header-name deny-list (case-insensitive substring match). */
 const REDACT_HEADER_SUBSTRINGS = ["key", "token", "secret", "cookie", "authorization"];
 
-/** Secret-looking value prefixes. */
-const REDACT_VALUE_PREFIXES = ["sk-", "AIza", "gsk-", "xox-"];
+/**
+ * Credential-looking values. Anchored on a non-alphanumeric boundary so plain
+ * words that merely contain "sk-" (e.g. `Task-Manager`, `Disk-Cache`) are NOT
+ * redacted, while `sk-…`, `gsk_…`, `xoxb-…` and `AIza…` tokens are.
+ */
+const SENSITIVE_VALUE_PATTERNS: RegExp[] = [
+  /(^|[^A-Za-z0-9])(sk|gsk|xox[a-z]?)[-_][A-Za-z0-9_-]{8,}/,
+  /(^|[^A-Za-z0-9])AIza[A-Za-z0-9_-]{10,}/,
+];
 
 function headerNameIsSensitive(name: string): boolean {
   const lower = String(name ?? "").toLowerCase();
@@ -163,7 +172,7 @@ function headerNameIsSensitive(name: string): boolean {
 function valueLooksSensitive(value: unknown): boolean {
   if (typeof value !== "string") return false;
   const v = value.trim();
-  if (REDACT_VALUE_PREFIXES.some((p) => v.includes(p))) return true;
+  if (SENSITIVE_VALUE_PATTERNS.some((re) => re.test(v))) return true;
   // Bearer-style long tokens: "Bearer <20+ chars>"
   if (/^bearer\s+\S{20,}/i.test(v)) return true;
   return false;

package/src/utils/documents.ts

@@ -6,6 +6,7 @@ import { normalizeMediaInput } from "./media.ts";
 import { base64ToBytes } from "./base64.ts";
 import { escapeXml } from "./serialization.ts";
 import { getModelFromCatalog } from "../models/catalog.ts";
+import { assertPathAllowed, fetchRemoteBytes, RemoteFetchError } from "./safe-io.ts";
 
 /**
  * Client-side document conversion (anydoc engine).
@@ -104,6 +105,16 @@ export interface ConvertDocumentOptions {
   maxChars?: number;
   /** Abort signal honored by the remote-fetch leg. */
   signal?: AbortSignal;
+  /**
+   * Allowed local roots for path inputs (see `AgentConfig.fileAccess`).
+   * Omitted = unrestricted (developer-supplied inputs); `[]` denies every path.
+   */
+  roots?: readonly string[];
+  /**
+   * Input is model/user-controlled: private/internal hosts are refused for
+   * remote URLs. The built-in tool always sets this.
+   */
+  untrusted?: boolean;
 }
 
 /** Normalized conversion result (pre-XML-envelope). */
@@ -296,7 +307,23 @@ export async function convertDocumentInput(
   try {
     // Remote URL leg: fetch bytes first (anydoc reads files, not URLs).
     if (typeof input === "string" && isHttpUrl(input)) {
-      const res = await fetch(input, { signal: opts.signal });
+      let res;
+      try {
+        res = await fetchRemoteBytes(input, {
+          signal: opts.signal,
+          maxBytes: MAX_DOCUMENT_FETCH_BYTES,
+          allowPrivateNetwork: !opts.untrusted,
+        });
+      } catch (err) {
+        if (err instanceof RemoteFetchError) {
+          throw new DocumentConversionError(
+            err.reason === "too_large" ? "resourceLimit" : "blocked",
+            `[Agent Accelerator] Could not download document "${input}": ${err.message}`,
+            input
+          );
+        }
+        throw err;
+      }
       if (!res.ok) {
         throw new DocumentConversionError(
           "io",
@@ -304,19 +331,12 @@ export async function convertDocumentInput(
           input
         );
       }
-      const buf = new Uint8Array(await res.arrayBuffer());
-      if (buf.byteLength > MAX_DOCUMENT_FETCH_BYTES) {
-        throw new DocumentConversionError(
-          "resourceLimit",
-          `[Agent Accelerator] Remote document "${input}" is ${(buf.byteLength / 1_000_000).toFixed(1)} MB, over the ${MAX_DOCUMENT_FETCH_BYTES / 1_000_000} MB fetch cap.`,
-          input
-        );
-      }
+      const buf = res.bytes;
       const name = filenameOpt || basenameOf(input);
       const inferred = resolveDocumentFormat({
         filename: name,
         format: opts.format,
-        mimeType: res.headers.get("content-type") || opts.mimeType,
+        mimeType: res.contentType || opts.mimeType,
       });
       let wire = canonicalizeFormat(anydoc, inferred);
       if (!wire) {
@@ -340,6 +360,17 @@ export async function convertDocumentInput(
 
     // Local path leg: the engine reads + detects from the path itself.
     if (typeof input === "string" && looksLikePath(input)) {
+      if (opts.roots) {
+        try {
+          await assertPathAllowed(input, opts.roots);
+        } catch (err) {
+          throw new DocumentConversionError(
+            "blocked",
+            `[Agent Accelerator] Could not read document "${input.slice(0, 120)}": ${err instanceof Error ? err.message : String(err)}`,
+            input
+          );
+        }
+      }
       const name = filenameOpt || basenameOf(input);
       const markdown = await anydoc.toMarkdown(input);
       const inferred = resolveDocumentFormat({ filename: name, format: opts.format });
@@ -424,7 +455,7 @@ export function modelSupportsFileInput(providerId: string, modelId: string): boo
  */
 export async function preprocessFilePartsForBypass(
   messages: Message[],
-  opts: { providerId: string; modelId: string; signal?: AbortSignal; maxChars?: number }
+  opts: { providerId: string; modelId: string; signal?: AbortSignal; maxChars?: number; roots?: readonly string[] }
 ): Promise<void> {
   if (modelSupportsFileInput(opts.providerId, opts.modelId)) return;
   for (const m of messages) {
@@ -451,6 +482,7 @@ export async function preprocessFilePartsForBypass(
           mimeType,
           maxChars: opts.maxChars,
           signal: opts.signal,
+          roots: opts.roots,
         });
         const destination =
           filename ||
@@ -466,8 +498,75 @@ export async function preprocessFilePartsForBypass(
   }
 }
 
+/** Options for {@link createConvertDocumentTool}. */
+export interface ConvertDocumentToolOptions {
+  /**
+   * Local roots the model may read from. Defaults to `[process.cwd()]`; pass
+   * `[]` to deny every local path (URLs only).
+   */
+  roots?: readonly string[];
+}
+
+/**
+ * Builds the model-callable document converter. The `destination` is chosen
+ * by the model, so it is always treated as untrusted: local paths must sit
+ * inside `roots`, and remote URLs may not target private/internal hosts.
+ *
+ * @example `const tool = createConvertDocumentTool({ roots: ["./docs"] });`
+ */
+export function createConvertDocumentTool(options: ConvertDocumentToolOptions = {}): ToolDefinition {
+  return tool({
+    name: "convert_document_to_markdown",
+    description:
+      "Convert a document file to Markdown text. Call this when the user provides a document file path or URL, or asks about the contents of a document. " +
+      "Supported formats: PDF (.pdf), Word (.doc, .docx, .docm), PowerPoint (.ppt, .pps, .pot, .pptx, .pptm, .ppsx, .ppsm), " +
+      "Excel (.xls, .xlsx, .xlsm, .xlsb), OpenDocument (.odt, .ods, .odp), RTF (.rtf), EPUB (.epub), CSV (.csv). " +
+      "Returns the content wrapped in <Document name destination> tags. Do not use for images, audio, or video.",
+    input: z.object({
+      destination: z
+        .string()
+        .min(1)
+        .describe("Local file path or http(s) URL of the document to convert."),
+      format: z
+        .string()
+        .optional()
+        .describe(
+          "Explicit format override, e.g. 'pdf', 'docx', 'xlsx', 'csv'. Inferred from the destination when omitted."
+        ),
+      maxChars: z
+        .number()
+        .int()
+        .positive()
+        .optional()
+        .describe("Maximum Markdown characters to return (default 100000). Excess is truncated with a marker."),
+    }),
+    timeoutMs: 60_000,
+    execute: async ({ destination, format, maxChars }, ctx) => {
+      const dest = String(destination ?? "").trim();
+      if (!dest) {
+        return "Error: convert_document_to_markdown needs a non-empty destination (local file path or http(s) URL).";
+      }
+      try {
+        const doc = await convertDocumentInput(dest, {
+          format,
+          maxChars,
+          signal: ctx?.signal,
+          untrusted: true,
+          roots: options.roots ?? [process.cwd()],
+        });
+        return buildDocumentXml(doc.name, dest, doc.markdown);
+      } catch (err) {
+        const detail = err instanceof Error ? err.message : String(err);
+        return `Error: ${detail}`;
+      }
+    },
+  });
+}
+
 /**
- * Built-in model-callable document converter. Register it and move on:
+ * Built-in model-callable document converter with the default policy (local
+ * paths limited to the working directory, no private-network URLs). Use
+ * {@link createConvertDocumentTool} to choose other roots.
  *
  * @example
  * ```ts
@@ -475,43 +574,4 @@ export async function preprocessFilePartsForBypass(
  * const agent = new Agent({ model, tools: { convert_document_to_markdown } });
  * ```
  */
-export const convert_document_to_markdown: ToolDefinition = tool({
-  name: "convert_document_to_markdown",
-  description:
-    "Convert a document file to Markdown text. Call this when the user provides a document file path or URL, or asks about the contents of a document. " +
-    "Supported formats: PDF (.pdf), Word (.doc, .docx, .docm), PowerPoint (.ppt, .pps, .pot, .pptx, .pptm, .ppsx, .ppsm), " +
-    "Excel (.xls, .xlsx, .xlsm, .xlsb), OpenDocument (.odt, .ods, .odp), RTF (.rtf), EPUB (.epub), CSV (.csv). " +
-    "Returns the content wrapped in <Document name destination> tags. Do not use for images, audio, or video.",
-  input: z.object({
-    destination: z
-      .string()
-      .min(1)
-      .describe("Local file path or http(s) URL of the document to convert."),
-    format: z
-      .string()
-      .optional()
-      .describe(
-        "Explicit format override, e.g. 'pdf', 'docx', 'xlsx', 'csv'. Inferred from the destination when omitted."
-      ),
-    maxChars: z
-      .number()
-      .int()
-      .positive()
-      .optional()
-      .describe("Maximum Markdown characters to return (default 100000). Excess is truncated with a marker."),
-  }),
-  timeoutMs: 60_000,
-  execute: async ({ destination, format, maxChars }, ctx) => {
-    const dest = String(destination ?? "").trim();
-    if (!dest) {
-      return "Error: convert_document_to_markdown needs a non-empty destination (local file path or http(s) URL).";
-    }
-    try {
-      const doc = await convertDocumentInput(dest, { format, maxChars, signal: ctx?.signal });
-      return buildDocumentXml(doc.name, dest, doc.markdown);
-    } catch (err) {
-      const detail = err instanceof Error ? err.message : String(err);
-      return `Error: ${detail}`;
-    }
-  },
-});
+export const convert_document_to_markdown: ToolDefinition = createConvertDocumentTool();

package/src/utils/env.ts

@@ -9,7 +9,10 @@
  */
 export function getEnv(key: string, fallback?: string): string | undefined {
   if (typeof process !== "undefined" && process.env && process.env[key]) {
-    return process.env[key];
+    // Trim quotes/whitespace from .env files (`sk-..."\n` -> 401 otherwise).
+    const raw = String(process.env[key]);
+    const trimmed = raw.trim().replace(/^["']|["']$/g, "").trim();
+    if (trimmed) return trimmed;
   }
   return fallback;
 }
@@ -22,20 +25,31 @@ export type ProviderEnv = Record<string, string>;
  * @example `const key = getApiKey("google");`
  */
 export function getApiKey(provider: string, explicitKey?: string, env?: ProviderEnv): string | undefined {
-  if (explicitKey) return explicitKey;
+  const clean = (v: unknown): string | undefined => {
+    if (typeof v !== "string") return undefined;
+    const t = v.trim().replace(/^["']|["']$/g, "").trim();
+    return t || undefined;
+  };
+  const cleanedExplicit = clean(explicitKey);
+  if (cleanedExplicit) return cleanedExplicit;
   // ProviderEnv override takes precedence (agent-accel inspiration, SDK-light)
   if (env) {
     const upper = `${provider.toUpperCase().replace(/[^A-Z0-9]/g, "_")}_API_KEY`;
-    if (env[upper]) return env[upper];
+    const fromEnv = clean(env[upper]);
+    if (fromEnv) return fromEnv;
     // google aliases
     if (provider.toLowerCase().startsWith("google") || provider.toLowerCase() === "gemini") {
-      if (env["GEMINI_API_KEY"]) return env["GEMINI_API_KEY"];
-      if (env["GOOGLE_API_KEY"]) return env["GOOGLE_API_KEY"];
+      const g1 = clean(env["GEMINI_API_KEY"]);
+      if (g1) return g1;
+      const g2 = clean(env["GOOGLE_API_KEY"]);
+      if (g2) return g2;
     }
     // openai aliases
     if (provider.toLowerCase() === "openai") {
-      if (env["OPENAI_BASE_API_KEY"]) return env["OPENAI_BASE_API_KEY"];
-      if (env["OPENAI_API_KEY"]) return env["OPENAI_API_KEY"];
+      const o1 = clean(env["OPENAI_BASE_API_KEY"]);
+      if (o1) return o1;
+      const o2 = clean(env["OPENAI_API_KEY"]);
+      if (o2) return o2;
     }
   }
 

package/src/utils/errors.ts

@@ -54,7 +54,18 @@ export function toConciseProviderError(error: unknown, providerId: string, model
   const err = error as any;
   const status = readStatus(err);
   const url = readUrl(err);
-  const detail = readProviderMessage(err);
+  let detail = readProviderMessage(err);
+  // Append OpenRouter-style raw metadata once (pi api/openai-completions.ts:719
+  // rule): normalize already stringifies error.error, so only append raw when
+  // absent to avoid double-printing.
+  const rawMeta =
+    (typeof err?.raw === "string" && err.raw.trim() ? err.raw.trim() : undefined) ??
+    (typeof err?.error?.metadata?.raw === "string" && err.error.metadata.raw.trim()
+      ? err.error.metadata.raw.trim()
+      : undefined);
+  if (rawMeta && !detail.includes(rawMeta.slice(0, 80))) {
+    detail = `${detail}\n${rawMeta.slice(0, 500)}`.slice(0, 800);
+  }
   const concise = new Error(
     `[${displayModel(providerId, modelId)}] request failed${status ? ` (${status})` : ""}: ${detail}`
   );
@@ -75,6 +86,20 @@ export function toConciseProviderError(error: unknown, providerId: string, model
     ...(typeof err?.errorType === "string"
       ? { errorType: { value: err.errorType, enumerable: false } }
       : {}),
+    // Forwarded when present (e.g. Google's `not_found` chain-eviction code,
+    // which carries no HTTP status on SSE error frames). Survives re-wraps
+    // so chain-expiry detectors never lose it.
+    ...((typeof err?.code === "string" || typeof err?.code === "number") && err.code !== ""
+      ? { code: { value: err.code, enumerable: false } }
+      : {}),
+    // Server rate-limit hint in ms (from Retry-After); survives re-wraps so
+    // `withRetries` can honor it instead of hammering a 429.
+    ...(typeof err?.retryAfterMs === "number" && Number.isFinite(err.retryAfterMs)
+      ? { retryAfterMs: { value: err.retryAfterMs, enumerable: false } }
+      : {}),
+    ...(typeof (err as { raw?: unknown })?.raw === "string"
+      ? { raw: { value: (err as { raw: string }).raw.slice(0, 500), enumerable: false } }
+      : {}),
   });
   return concise;
 }

package/src/utils/headers.ts

@@ -24,7 +24,7 @@ export function getPackageVersion(): string {
     const v = (globalThis as any).process?.env?.npm_package_version;
     if (typeof v === "string" && v) return v;
   } catch {}
-  return "0.4.0";
+  return "0.5.0";
 }
 
 function getAgentAccelUserAgent(): string {
@@ -55,9 +55,9 @@ export interface AttributionConfig {
 let attribution: AttributionConfig = {};
 
 /**
- * Configures global attribution headers. Defaults to none (no hardcoded
- * site); OpenRouter keeps its legacy `sashvat.com` / `Agent Accelerator`
- * fallback when no custom attribution is set (backward compat).
+ * Configures global attribution headers (OpenRouter `HTTP-Referer` / `X-Title`).
+ * Defaults to none: nothing is sent unless you call this, so your traffic is
+ * never credited to a site or app you did not choose.
  * @example `setAttribution({ referer: "https://example.com", title: "My App" });`
  */
 export function setAttribution(cfg: AttributionConfig): void {
@@ -151,9 +151,8 @@ function stripForBrowser(headers: Record<string, string>): Record<string, string
 /**
  * Builds provider-specific session, cache-affinity, and attribution headers.
  *
- * Q-17: attribution is configurable via `setAttribution()` (default none).
- * OpenRouter keeps its legacy `https://sashvat.com` / `Agent Accelerator`
- * fallback when no custom attribution is set. Custom (non-first-class)
+ * Q-17: attribution is configurable via `setAttribution()` (default none; no
+ * referer/title is ever sent unless you set one). Custom (non-first-class)
  * prefixes receive minimal `x-session-id`/`x-client-request-id` affinity only
  * (no `session_id` alias, no attribution) when a session id is present.
  * `customHeaders` merge case-insensitively against canonical names.
@@ -193,14 +192,18 @@ export function buildSessionHeaders(
     return key !== undefined ? headers[key] : undefined;
   };
 
+  // OpenRouter app attribution is strictly opt-in (`setAttribution`): by default
+  // a user's traffic is not credited to any third-party app or site.
+  const applyOpenRouterAttribution = (): void => {
+    if (attr.referer !== undefined && getHeader("HTTP-Referer") === undefined) headers["HTTP-Referer"] = attr.referer;
+    if (attr.title !== undefined && getHeader("X-Title") === undefined) headers["X-Title"] = attr.title;
+  };
+
   if (sessionId && !browser) {
     if (provider === "openrouter") {
       setHeaderCaseInsensitive(headers, "x-session-id", sessionId);
       setHeaderCaseInsensitive(headers, "x-client-request-id", sessionId);
-      const referer = attr.referer ?? "https://sashvat.com";
-      const title = attr.title ?? "Agent Accelerator";
-      if (getHeader("HTTP-Referer") === undefined) headers["HTTP-Referer"] = referer;
-      if (getHeader("X-Title") === undefined) headers["X-Title"] = title;
+      applyOpenRouterAttribution();
     } else if (provider === "google") {
       if (getHeader("x-goog-api-client") === undefined) {
         headers["x-goog-api-client"] = "agent-accel/1.0";
@@ -219,10 +222,7 @@ export function buildSessionHeaders(
       setHeaderCaseInsensitive(headers, "x-client-request-id", sessionId);
     }
   } else if (provider === "openrouter") {
-    const referer = attr.referer ?? "https://sashvat.com";
-    const title = attr.title ?? "Agent Accelerator";
-    if (getHeader("HTTP-Referer") === undefined) headers["HTTP-Referer"] = referer;
-    if (getHeader("X-Title") === undefined) headers["X-Title"] = title;
+    applyOpenRouterAttribution();
   }
 
   if (provider === "google" && !browser && getHeader("x-goog-api-client") === undefined) {

package/src/utils/home.ts

@@ -0,0 +1,30 @@
+import * as path from "node:path";
+import { getEnv } from "./env.ts";
+
+/**
+ * The Agent Accelerator home: ONE folder that holds everything the SDK stores
+ * (`sessions/`, `scheduled_actions/`, `telemetry/`, `catalog/`), so nothing is
+ * scattered across the project or the package.
+ */
+let defaultHome: string | undefined;
+const listeners = new Set<() => void>();
+
+/**
+ * Sets where the home lives for every Agent created afterwards, so nothing lands
+ * in the working directory unless you want it there. Call once at startup;
+ * `setHome()` clears it.
+ */
+export function setHome(dir?: string): void {
+  defaultHome = dir ? path.resolve(dir) : undefined;
+  for (const fn of listeners) fn();
+}
+
+/** The home folder: explicit `home`, else `setHome()`, else `AGENT_ACCEL_HOME`, else `.agent-accel/` in the working directory. */
+export function resolveHome(home?: string): string {
+  return path.resolve(home || defaultHome || getEnv("AGENT_ACCEL_HOME") || ".agent-accel");
+}
+
+/** Runs `fn` whenever `setHome` changes the default (the catalog cache reloads from the new place). */
+export function onHomeChange(fn: () => void): void {
+  listeners.add(fn);
+}