car-runtime 0.5.1 → 0.6.0

package/index.d.ts

@@ -3,6 +3,30 @@
  * Most methods that return structured data return a JSON-encoded string; the
  * caller is expected to `JSON.parse` the result. This keeps the FFI surface
  * small and avoids coupling the native binding to any specific TS shape.
+ *
+ * ## Runtime modes (closes #139's cross-process admission gap)
+ *
+ * `new CarRuntime()` runs in one of two modes, selected at construction:
+ *
+ * - **`daemon` (default)** — talks to the singleton car-server daemon over
+ *   WebSocket JSON-RPC. Methods that touch shared resources (inference,
+ *   embeddings, state, verification) proxy to the daemon — preserving the
+ *   process-wide admission semaphore so two Node consumers don't double-load
+ *   models or oversubscribe the GPU.
+ * - **`embedded`** — explicit opt-in via `CAR_FFI_MODE=embedded`. Every
+ *   method runs in-process. Useful for notebooks, offline dev, or single-
+ *   process deployments where the caller knows they own the machine.
+ *   Production embedders generally don't want this.
+ *
+ * Some methods are **embedded-only by design** because their callback
+ * surface (`ThreadsafeFunction` for tools, streaming events) doesn't
+ * survive a network boundary cleanly. Those throw in `daemon` mode with a
+ * clear message: `executeProposal`, `inferStream`. For streaming inference
+ * under the singleton-daemon contract, talk to `ws://127.0.0.1:9100/`
+ * directly.
+ *
+ * Daemon URL override: `CAR_DAEMON_URL=ws://...` (default
+ * `ws://127.0.0.1:9100`).
  */
 
 /** Persistent runtime instance with state, memory, tools, and policies. */
@@ -61,19 +85,40 @@ export class CarRuntime {
 
   // --- Memory / Facts (graph-backed) ---
 
-  /** Add a fact. `kind` is typically "pattern" or "constraint". */
-  addFact(subject: string, body: string, kind: string, confidence?: number | null): number;
+  /**
+   * Add a fact. `kind` is typically "pattern" or "constraint".
+   *
+   * In Daemon mode, rejects with the daemon-unreachable error
+   * instead of silently returning 0 (#146).
+   */
+  addFact(
+    subject: string,
+    body: string,
+    kind: string,
+    confidence?: number | null,
+  ): Promise<number>;
 
   /** Query facts via graph spreading activation. Returns a JSON array. */
   queryFacts(query: string, k?: number | null): string;
 
-  factCount(): number;
+  /**
+   * Total valid fact count.
+   *
+   * In Daemon mode, hits the daemon's per-session memgine — the
+   * embedded fallback memgine stays empty by design and would
+   * silently return 0 (#146). Rejects with the daemon-unreachable
+   * error instead.
+   */
+  factCount(): Promise<number>;
 
   /**
    * Build the full 4-layer context for a query.
    * When `modelContextWindow` is provided, dynamically sizes the budget.
+   *
+   * In Daemon mode, rejects with the daemon-unreachable error
+   * instead of silently returning "" (#146).
    */
-  buildContext(query: string, modelContextWindow?: number | null): string;
+  buildContext(query: string, modelContextWindow?: number | null): Promise<string>;
 
   /**
    * Build context in Fast mode for latency-sensitive paths.
@@ -86,7 +131,14 @@ export class CarRuntime {
 
   // --- Skills ---
 
-  /** Save a learned skill with trigger context. Returns the node index. */
+  /**
+   * Save a learned skill with trigger context. Returns the node
+   * index.
+   *
+   * In Daemon mode, rejects with the daemon-unreachable error
+   * (or a parse error if the response is malformed) instead of
+   * silently returning 0 (#146).
+   */
   ingestSkill(
     name: string,
     code: string,
@@ -96,7 +148,7 @@ export class CarRuntime {
     taskKeywords: string[],
     description: string,
     supersedesSkill?: string | null,
-  ): number;
+  ): Promise<number>;
 
   /** Find best matching skill for context. Returns JSON or `"null"`. */
   findSkill(
@@ -129,12 +181,33 @@ export class CarRuntime {
 
   // --- Inference ---
 
-  /** Generate text. Returns JSON: `{"text":"..."}`. */
-  infer(prompt: string, model?: string | null, maxTokens?: number | null): Promise<string>;
+  /**
+   * Generate text. Returns JSON: `{"text":"..."}`.
+   *
+   * `intentJson` is an optional serialized {@link IntentHint} —
+   * caller-facing routing hints (task, prefer_local, require). Omit to
+   * preserve the existing adaptive vs. pinned-model behavior.
+   */
+  infer(
+    prompt: string,
+    model?: string | null,
+    maxTokens?: number | null,
+    intentJson?: string | null,
+  ): Promise<string>;
 
   /**
-   * Generate with full tracking: text, tool_calls, usage, model_used, latency_ms.
-   * Returns JSON.
+   * Generate with full tracking. Returns JSON with `text`, `tool_calls`,
+   * `usage`, `model_used`, `latency_ms`, `time_to_first_token_ms`,
+   * `trace_id`. `time_to_first_token_ms` is wall-clock to the first
+   * sampled token (populated by local Candle/MLX paths; `null` for
+   * non-streaming remote calls).
+   *
+   * **Note:** intent is not exposed on the tracked path until the
+   * positional argument list is converted to an options object —
+   * this method already takes 8 positional parameters and adding a
+   * 9th would push call sites past readability. For new code, use
+   * {@link inferTrackedWithRequest} which takes a JSON-stringified
+   * `GenerateRequest` and exposes every field including `intent`.
    */
   inferTracked(
     prompt: string,
@@ -147,11 +220,24 @@ export class CarRuntime {
     parallelToolCalls?: boolean | null,
   ): Promise<string>;
 
-  /** Generate text grounded with memory context from this runtime's memgine. */
+  /**
+   * Generate with full tracking, options-object form.
+   * `requestJson` is a `JSON.stringify`d `GenerateRequest` (every
+   * field optional except `prompt`). Exposes every field on the
+   * Rust struct including `intent`. Same pattern as
+   * {@link verifyProposal}. Closes #107.
+   */
+  inferTrackedWithRequest(requestJson: string): Promise<string>;
+
+  /**
+   * Generate text grounded with memory context from this runtime's
+   * memgine. `intentJson` works the same as on {@link infer}.
+   */
   inferWithContext(
     prompt: string,
     model?: string | null,
     maxTokens?: number | null,
+    intentJson?: string | null,
   ): Promise<string>;
 
   /** Embed texts. Returns JSON array of float arrays. */
@@ -172,6 +258,20 @@ export class CarRuntime {
   /** Classify text against labels. Returns JSON array of `{label, score}`. */
   classify(text: string, labels: string[], model?: string | null): Promise<string>;
 
+  /**
+   * Encode `text` via the named local model's tokenizer. Returns a JSON
+   * array of u32 token IDs, raw (no chat-template wrapping, no BOS).
+   * Pair with `detokenize` for byte-identical round-trip. Remote models
+   * are not supported — call rejects with an error there.
+   */
+  tokenize(model: string, text: string): Promise<string>;
+
+  /**
+   * Decode token IDs back to text via the named local model's tokenizer.
+   * Inverse of `tokenize` for the round-trip property.
+   */
+  detokenize(model: string, tokens: number[]): Promise<string>;
+
   // --- Speech ---
 
   /** Prepare the managed speech runtime and return its root path. */
@@ -215,7 +315,14 @@ export class CarRuntime {
   /** Remove a downloaded model. */
   removeModel(name: string): void;
 
-  /** Unified registry (local + remote). Returns JSON array. */
+  /**
+   * Unified registry (local + remote). Returns JSON array of
+   * `{ id, name, provider, capabilities, param_count, size_mb,
+   *   context_length, available, is_local, public_benchmarks }`.
+   * `public_benchmarks` is `[{ name, score, harness?, source_url?,
+   * measured_at? }]` with score on a 0.0–1.0 scale; ships empty in
+   * the built-in catalog and is populated via curated registry data.
+   */
   listModelsUnified(): string;
 
   /** Register a model schema (persists to `~/.car/models.json`). */
@@ -248,12 +355,167 @@ export class CarRuntime {
    * Supported ops: navigate, observe, click, type, scroll, keypress, wait.
    * Returns JSON: `{steps:[{op,status,data,error,duration_ms}]}`. Execution
    * short-circuits on first error.
+   *
+   * `headed`: when `true`, launches a visible Chromium window
+   * instead of headless mode — for interactive flows like
+   * first-time auth (LinkedIn / OAuth / SSO / 2FA / captcha).
+   * Honoured only on the *first* call that launches the session;
+   * subsequent calls reuse the existing browser regardless. To
+   * switch modes, call `browserClose()` first.
+   *
+   * `extraArgs`: extra Chromium command-line flags appended
+   * verbatim to argv at launch (#112). Use cases: the Google
+   * Meet bot needing `--use-fake-ui-for-media-stream`,
+   * `--autoplay-policy=no-user-gesture-required`, and the
+   * container-friendly `--no-sandbox` /
+   * `--disable-dev-shm-usage` / `--disable-setuid-sandbox`. Like
+   * `headed`, honoured only on the launch call.
    */
   browserRun(
     scriptJson: string,
     width?: number | null,
     height?: number | null,
+    headed?: boolean | null,
+    extraArgs?: string[] | null,
   ): Promise<string>;
+
+  /** Close any persistent browser session attached to this runtime. */
+  browserClose(): Promise<void>;
+
+  /**
+   * Register a tool with a full JSON-serialized `ToolSchema`.
+   * `verifyProposal` validates `Action.parameters` against the schema's
+   * `parameters` field — catching type mismatches like `{path: 42}` for a
+   * tool wanting `{path: string}` before dispatch. The schema also carries
+   * idempotency, cache TTL, and rate-limit hints that the engine wires up
+   * automatically.
+   *
+   * Tools registered via the schemaless `registerTool(name)` bypass type
+   * validation; this is the opt-in upgrade path.
+   *
+   * `schemaJson` matches:
+   * ```json
+   * {
+   *   "name": "read_file",
+   *   "description": "...",
+   *   "parameters": {"type":"object","properties":{"path":{"type":"string"}},"required":["path"]},
+   *   "returns": null,
+   *   "idempotent": true,
+   *   "cache_ttl_secs": 60,
+   *   "rate_limit": {"max_calls": 100, "interval_secs": 60}
+   * }
+   * ```
+   */
+  registerToolSchema(schemaJson: string): Promise<void>;
+
+  // -------------------------------------------------------------------------
+  // OS-native secret store (Keychain / Credential Manager / Secret Service)
+  // -------------------------------------------------------------------------
+
+  /** Returns JSON `{available: boolean, reason?: string}`. */
+  secretAvailable(): string;
+
+  /**
+   * Store a secret. Returns JSON `{ok: true}` on success. Throws if the
+   * backend is unavailable. `service` defaults to the runtime-wide bundle id.
+   */
+  secretPut(key: string, value: string, service?: string | null): string;
+
+  /**
+   * Retrieve a secret. Returns JSON `{value: string}`. Throws `not_found`
+   * if the secret does not exist.
+   */
+  secretGet(key: string, service?: string | null): string;
+
+  /** Delete a secret (idempotent). Returns JSON `{ok: true}`. */
+  secretDelete(key: string, service?: string | null): string;
+
+  /** Returns JSON `{exists: boolean, key, service}` without exposing the value. */
+  secretStatus(key: string, service?: string | null): string;
+
+  // -------------------------------------------------------------------------
+  // OS permission preflight
+  // -------------------------------------------------------------------------
+
+  /** Returns JSON `{domains: [...]}` listing every permission domain CAR knows. */
+  permissionDomains(): string;
+
+  /** Returns JSON `{status: "granted"|"denied"|"prompt"|"unsupported", ...}`. */
+  permissionStatus(domain: string, targetBundleId?: string | null): string;
+
+  /** Triggers the OS permission prompt; returns the resulting status. */
+  permissionRequest(domain: string, targetBundleId?: string | null): string;
+
+  /** Returns JSON describing what the permission unlocks and how to revoke it. */
+  permissionExplain(domain: string, targetBundleId?: string | null): string;
+
+  // -------------------------------------------------------------------------
+  // Native account discovery (system Settings → Internet Accounts on macOS)
+  // -------------------------------------------------------------------------
+
+  /** Returns JSON array of accounts known to the OS. */
+  accountsList(): string;
+
+  /** Open the OS's native account-management UI for an account or the root pane. */
+  accountsOpen(accountId?: string | null): string;
+
+  // -------------------------------------------------------------------------
+  // Calendar / Contacts / Mail integrations (delegated to OS providers)
+  // -------------------------------------------------------------------------
+
+  /** Returns JSON array of calendars discovered through the OS provider. */
+  calendarList(): string;
+
+  /**
+   * Returns JSON array of events in the [start, end] window. Times are
+   * RFC3339; `calendarIdsCsv` is an optional comma-separated filter.
+   */
+  calendarEvents(
+    startRfc3339: string,
+    endRfc3339: string,
+    calendarIdsCsv?: string | null,
+  ): string;
+
+  /** Returns JSON array of contact containers (sources). */
+  contactsContainers(): string;
+
+  /** Returns JSON array of contacts matching `query`. */
+  contactsFind(
+    query: string,
+    limit?: number | null,
+    containerIdsCsv?: string | null,
+  ): string;
+
+  /** Returns JSON array of mail accounts known to the OS provider. */
+  mailAccounts(): string;
+
+  /**
+   * Returns JSON inbox snapshot. `accountIdsCsv` is an optional
+   * comma-separated filter; omit to query all known accounts.
+   */
+  mailInbox(accountIdsCsv?: string | null): string;
+
+  /**
+   * Send mail. `sendRequestJson` is `{to, subject, body, ...}` per the
+   * provider contract. Returns JSON `{ok, message_id?}`.
+   */
+  mailSend(sendRequestJson: string): string;
+
+  // -------------------------------------------------------------------------
+  // Wearable / activity (HealthKit + Fitbit/Garmin/Oura/etc.)
+  // -------------------------------------------------------------------------
+
+  /** Returns JSON `{available, reason?, providers?}`. */
+  healthStatus(): string;
+
+  /** Times are RFC3339. Returns JSON array of sleep sessions. */
+  healthSleep(startRfc3339: string, endRfc3339: string): string;
+
+  /** Times are RFC3339. Returns JSON array of workouts. */
+  healthWorkouts(startRfc3339: string, endRfc3339: string): string;
+
+  /** Dates are YYYY-MM-DD. Returns JSON array of daily activity summaries. */
+  healthActivity(startYmd: string, endYmd: string): string;
 }
 
 // ---------------------------------------------------------------------------
@@ -278,19 +540,90 @@ export function executeProposal(
  *   `{"type":"tool_start","name":"...","index":N}`
  *   `{"type":"tool_delta","index":N,"data":"..."}`
  *   `{"type":"done","text":"...","tool_calls":[...]}`
+ *
+ * **Breaking change in 0.5.x:** the prior 9-positional signature
+ * has been replaced with an options-object form. Migration: build
+ * the request object and `JSON.stringify` it as `requestJson`. The
+ * options object exposes every `GenerateRequest` field including
+ * `intent` (closes #107). The replacement (rather than addition of
+ * a sibling) is forced by napi-rs's 3-standalone-TSF cap — see the
+ * project rules for the rationale.
  */
 export function inferStream(
   rt: CarRuntime,
-  prompt: string,
-  model: string | null | undefined,
-  maxTokens: number | null | undefined,
-  context: string | null | undefined,
-  toolsJson: string | null | undefined,
+  requestJson: string,
   onEvent: (eventJson: string) => void,
-  toolChoice?: string | null,
-  parallelToolCalls?: boolean | null,
 ): Promise<string>;
 
+// --- Caller-facing routing intent (parslee-ai/car-releases#18) ---
+
+/**
+ * Coarse-grained task hint the adaptive router maps to its internal
+ * `InferenceTask`. A closed set so adding a new task type is a
+ * deliberate, FFI-visible change rather than a silent fallback.
+ */
+export type TaskHint =
+  | 'chat'
+  | 'classify'
+  | 'summarize'
+  | 'reasoning'
+  | 'code'
+  | 'extract';
+
+/**
+ * Hard model-capability filters the router enforces in addition to
+ * any prompt-derived requirements. Mirrors `ModelCapability` in the
+ * registry; values must be one of these snake_case strings.
+ */
+export type ModelCapabilityRequirement =
+  | 'generate'
+  | 'embed'
+  | 'rerank'
+  | 'classify'
+  | 'code'
+  | 'reasoning'
+  | 'summarize'
+  | 'tool_use'
+  | 'multi_tool_call'
+  | 'vision'
+  | 'video_understanding'
+  | 'audio_understanding'
+  | 'grounding'
+  | 'speech_to_text'
+  | 'text_to_speech'
+  | 'image_generation'
+  | 'video_generation';
+
+/**
+ * Caller-facing routing intent — express requirements, not model IDs.
+ *
+ * All fields are optional. An IntentHint with no fields set is
+ * equivalent to omitting the hint entirely (adaptive routing as today).
+ *
+ * @example
+ *   await rt.infer(
+ *     prompt,
+ *     null,
+ *     null,
+ *     JSON.stringify({ task: 'chat', prefer_local: true } satisfies IntentHint),
+ *   );
+ */
+export interface IntentHint {
+  /** What the caller is doing. Maps to `InferenceTask` server-side. */
+  task?: TaskHint;
+  /**
+   * Hard filter — every required capability must be present on the
+   * candidate before scoring runs.
+   */
+  require?: ModelCapabilityRequirement[];
+  /**
+   * Bias the score profile toward local on-device models. Maps to a
+   * dedicated `RoutingWorkload::LocalPreferred` weight profile —
+   * quality-aware with a strong local_bonus so the hint wins ties.
+   */
+  prefer_local?: boolean;
+}
+
 // --- Voice streaming (stored-callback pattern) ---
 
 export type AudioSourceSpec =
@@ -363,6 +696,20 @@ export function transcribeStreamPush(
 
 export function listVoiceSessions(rt: CarRuntime): string;
 
+/**
+ * Voice providers (STT + TTS) compiled into this build.
+ *
+ * Returns a JSON-encoded array of objects with shape:
+ * `{ id: string, kind: "stt" | "tts", available: boolean, description: string }`.
+ *
+ * `available` reflects build-time presence (cfg-target, build features) —
+ * runtime readiness (API key set, permission granted, model downloaded)
+ * surfaces via per-provider error paths when you actually use them.
+ *
+ * Stateless; safe to call before constructing a `CarRuntime`.
+ */
+export function listVoiceProviders(): string;
+
 // --- Meeting capture ---
 
 export interface StartMeetingRequest {
@@ -454,6 +801,103 @@ export function getMeeting(
   rootOverride?: string | null,
 ): string;
 
+// --- Agent registry (file-based, no daemon) ---
+
+/**
+ * Register or replace an agent's entry in the user-default registry
+ * (`~/.car/registry/`) or at the path supplied as `registryPath`.
+ *
+ * `entryJson` is a JSON-serialised `AgentEntry`:
+ * ```json
+ * {
+ *   "name": "trader-paper",
+ *   "dashboard_url": "http://127.0.0.1:8731",
+ *   "status": "running",
+ *   "display_name": "Trader (paper)",
+ *   "port": 8731,
+ *   "pid": 12345
+ * }
+ * ```
+ * `name` and `dashboard_url` are required; the rest are optional.
+ * Returns `"null"` on success.
+ */
+export function registerAgent(
+  entryJson: string,
+  registryPath?: string | null,
+): string;
+
+/**
+ * Bump `last_heartbeat_at` for the named agent. Returns
+ * `'{"refreshed": true}'` if the agent was registered, or
+ * `'{"refreshed": false}'` if the caller should re-register.
+ */
+export function agentHeartbeat(
+  name: string,
+  registryPath?: string | null,
+): string;
+
+/** Remove an agent's entry. Idempotent. */
+export function unregisterAgent(
+  name: string,
+  registryPath?: string | null,
+): string;
+
+/**
+ * List all currently-registered agents. Returns a JSON array of
+ * `AgentEntry` objects, sorted by name.
+ */
+export function listAgents(registryPath?: string | null): string;
+
+/**
+ * Reap entries whose last heartbeat is older than `maxAgeSecs`.
+ * Returns a JSON array of names that were reaped.
+ */
+export function reapStaleAgents(
+  maxAgeSecs: number,
+  registryPath?: string | null,
+): string;
+
+// --- car-a2a server lifecycle ---
+//
+// Expose CAR as an Agent2Agent (A2A) v1.0 peer programmatically,
+// without shelling out to `car-server --a2a-bind`. Process-global
+// state holds the bound listener and join handle so a later
+// `stopA2aServer` / `a2aServerStatus` call reaches the right server.
+
+/**
+ * Start an A2A listener.
+ *
+ * `paramsJson` shape:
+ * ```jsonc
+ * {
+ *   "bind": "127.0.0.1:8731",        // required
+ *   "public_url": "https://...",     // optional; defaults to http://<bound>
+ *   "agent_name": "...",             // optional
+ *   "agent_description": "...",      // optional
+ *   "organization": "...",           // optional
+ *   "organization_url": "..."        // optional
+ * }
+ * ```
+ *
+ * Returns `'{"bound":"127.0.0.1:8731"}'` on success. Errors if a
+ * server is already running, the bind fails, or `paramsJson` is
+ * malformed.
+ */
+export function startA2aServer(paramsJson: string): Promise<string>;
+
+/**
+ * Stop the running A2A listener. Returns `'{"stopped":true}'` on
+ * success. Errors if no server is running.
+ */
+export function stopA2aServer(): string;
+
+/**
+ * Report whether the A2A listener is up. Always returns a JSON
+ * object — `{"running":true,"bound":"...","uptime_secs":N}` when
+ * running, `{"running":false}` otherwise.
+ */
+export function a2aServerStatus(): string;
+
 // --- Verification (stateless) ---
 
 export function verify(
@@ -552,3 +996,74 @@ export function rankProposals(
   tools?: string[] | null,
   costWeight?: number | null,
 ): string;
+
+// --- macOS automation (car-automation) ---
+//
+// AppleScript / JXA / Shortcuts bridges. Subprocess-backed so the
+// surface is uniform across binding layers. On non-macOS hosts each
+// call rejects with a PlatformUnsupported error.
+
+/**
+ * Run an AppleScript or JXA snippet via `osascript`.
+ *
+ * `argsJson` shape:
+ * ```jsonc
+ * {
+ *   "script": "return 1 + 2",
+ *   "language": "applescript" | "javascript",  // optional, default applescript
+ *   "args": ["positional", "args"],             // optional
+ *   "timeout_ms": 5000                          // optional
+ * }
+ * ```
+ *
+ * Returns JSON `{stdout, stderr, exit_code}`. Rejects with the
+ * subprocess stderr on non-zero exit.
+ */
+export function runApplescript(argsJson: string): Promise<string>;
+
+/**
+ * Enumerate Shortcuts (user-authored *and* AppShortcuts donated by
+ * apps via the App Intents framework). Returns an array of
+ * `{name, identifier?, tool_slug, tool_description, parameters_schema}`,
+ * suitable for registering each as a runtime tool.
+ *
+ * `argsJson` shape: `{ folder?: string, with_identifiers?: boolean }`.
+ */
+export function listShortcuts(argsJson: string): Promise<string>;
+
+/**
+ * Invoke a Shortcut by name or UUID. `argsJson` shape:
+ * ```jsonc
+ * {
+ *   "name_or_id": "Shazam shortcut" | "43E9-...",
+ *   "input": "optional text input",            // optional
+ *   "output_type": "public.plain-text",         // optional UTI
+ *   "timeout_ms": 30000                         // optional
+ * }
+ * ```
+ * Returns JSON `{stdout, stderr, exit_code}`.
+ */
+export function runShortcut(argsJson: string): Promise<string>;
+
+// --- Vision OCR (car-vision) ---
+
+/**
+ * Apple Vision-framework on-device text recognition.
+ *
+ * `argsJson` shape:
+ * ```jsonc
+ * {
+ *   "image_path": "/path/to/screen.png",
+ *   "fast_path": false,                  // optional; true = .fast vs .accurate
+ *   "languages": ["en-US"],              // optional BCP-47 hints
+ *   "language_correction": true,         // optional, default true
+ *   "minimum_text_height": 0.0           // optional, normalized; floors tiny noise
+ * }
+ * ```
+ *
+ * Returns JSON `{available, observations}`. `available` is `false`
+ * when the Vision shim wasn't built into this binary (non-macOS or
+ * skipped Swift compile); in that case `observations` is an empty
+ * array rather than an error.
+ */
+export function visionOcr(argsJson: string): Promise<string>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "car-runtime",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Common Agent Runtime — a deterministic execution layer for AI agents",
   "main": "index.js",
   "types": "index.d.ts",