@ineerajrajeev/aios-web-sdk

The official Browser JavaScript/TypeScript SDK for aiOS.

Integrate web applications with the local aiOS desktop agent through the Safari or Chrome browser extension. The SDK manages structured page exports, capability policies, component-level interaction constraints, consent-gated data sharing, and a permissioned sandbox for agent-invoked functions.

Requirements

| Component | Role | |-----------|------| | aiOS for Mac | Local agent + bridge server (localhost:18490) | | Safari or Chrome extension | Injects sdk-bridge.js into pages and relays agent commands | | This SDK | Your app declares policy, context, components, and consent |

Install the browser extension from getaios.tech and ensure the aiOS Mac app is running before testing agent flows.

Installation

npm install @ineerajrajeev/aios-web-sdk

"dependencies": {
  "@ineerajrajeev/aios-web-sdk": "^0.1.4"
}

Works in bundlers (Vite, Webpack, Next.js) and supports both ESM and CommonJS.

Quick start

import { aiOS } from "@ineerajrajeev/aios-web-sdk";

aiOS.init({
  appId: "com.example.myapp",
  requireConsent: true,
});

aiOS.setPagePolicy({
  allowed: true,
  capabilities: { read: true, write: false, execute: true, summarize: true },
  exportMode: "structured-only",
});

aiOS.setPageContext({
  pageType: "checkout",
  title: "Checkout",
  description: "Review cart and complete purchase.",
  agentIntent: "Help the user review items and proceed to payment.",
});

const approved = await aiOS.publish({
  schema: "cart.v1",
  data: { itemsCount: 2, total: 49.99, currency: "USD" },
});

if (approved) {
  console.log("Structured page data sent to aiOS.");
}

How it works

1. aiOS.init() — Handshake with the extension via window.postMessage and injects window.__aiOS_* globals.
2. Policy & context — The extension's sdk-bridge.js enforces capabilities before any agent action runs.
3. aiOS.publish() — Builds a structured payload, shows a consent modal (if required), then posts aios-sdk:export to the extension.
4. Agent actions — The Mac app sends commands (click, type, read) through the extension; blocked actions emit agent:active with blocked: true.
5. Sandbox functions — Register app functions the agent can call; permission prompts gate execution.

The extension caches agent actions in sessionStorage (aios:agent-actions-log) so activity can be audited or resumed across reloads.

API reference

aiOS.init(options)

| Option | Type | Default | Description | |--------|------|---------|-------------| | appId | string | — | Reverse-domain app identifier (required). | | requireConsent | boolean | true | Show consent UI before export reaches the extension. |

Also starts the extension event bus and queries extension presence.

aiOS.setPagePolicy(policy)

Master switch and per-capability gates for agent access.

| Field | Description | |-------|-------------| | allowed | false blocks all agent operations on this page. | | userMessage | Shown to the agent when blocked. | | capabilities.read | Page content / structured export reads. | | capabilities.write | Form fill, typing, selection. | | capabilities.execute | Clicks, scroll, navigation-style actions. | | capabilities.summarize | Summarization of page content. | | exportMode | "structured-only" (SDK export required) or "dom-allowed" (DOM fallback). |

aiOS.setPageContext(context)

Semantic metadata so the agent understands page purpose.

| Field | Description | |-------|-------------| | pageType | e.g. "checkout", "form", "job_application", "generic". | | title, description | Human-readable page summary. | | agentIntent | What the agent should accomplish here. | | seekFromUser | Fields the agent should ask the user for (not scrape). |

aiOS.defineZones(zones)

| Field | Description | |-------|-------------| | primary | CSS selector for main content. | | excluded | Selectors the agent must ignore (ads, footers, cookie banners). |

aiOS.markComponent(id, component) / aiOS.unmarkComponent(id)

Register named interactive elements with explicit capabilities (clickable, writable, readable, hidden, etc.) instead of relying on generic DOM discovery.

Export & consent

aiOS.exportPageData(options) / aiOS.prepareExport(options)

Build a structured payload without sending it. Updates window.__aiOS_pending_export__.

aiOS.buildConsentPreview()

Returns a preview object for custom consent UIs.

aiOS.requestConsent(options?)

Shows the built-in consent modal (or uses remembered site approval). Returns true if approved.

aiOS.publish(options?)

Convenience: prepareExport → requestConsent → flush on approval.

aiOS.flushApprovedExport(options?)

Send a previously approved payload immediately (used internally after consent).

aiOS.getPendingExport() / aiOS.getApprovedExport()

Inspect staged or last-approved structured payloads.

Events

aiOS.onEvent(type, handler) → unsubscribe

| Event | When | |-------|------| | extension:present | Extension content script loaded on this page. | | extension:status | Extension/agent session snapshot updated. | | agent:session-start | Agent began a new interaction session. | | agent:active | Agent performed an action (click, type, read, …). | | agent:session-end | Agent session idle timeout (120s). | | agent:data-access | User approved export or agent read page data. | | agent:function-request | Agent requested a sandbox function call. | | agent:permission-request | Sandbox needs user permission before running a function. | | agent:permission-result | Permission prompt resolved. |

Shortcuts: aiOS.onExtensionPresent(handler), aiOS.onAgentActive(handler), aiOS.onAnyExtensionEvent(handler).

Status: aiOS.getExtensionStatus(), aiOS.queryExtensionPresence(), aiOS.ping().

const off = aiOS.onAgentActive((event) => {
  const { action, success, blocked, capability } = event.payload;
  console.log({ action, success, blocked, capability });
});
off();

Sandbox (aiOS.sandbox)

Register functions the local agent can invoke through the extension's executeSdkFunction command. Permissions are prompted per function.

aiOS.init({ appId: "com.example.shop" });

aiOS.sandbox.registerFunction(
  "getCartTotal",
  async () => ({ total: 89.99, currency: "USD" }),
  ["execute_custom_function"]
);

aiOS.onEvent("agent:permission-request", (event) => {
  const { requestId, permissions } = event.payload;
  // Show your own UI, then:
  aiOS.sandbox.resolvePermission(requestId, userClickedAllow);
});

| Method | Description | |--------|-------------| | registerFunction(name, fn, requiredPermissions?) | Expose a callable to the agent. | | unregisterFunction(name) | Remove a registration. | | getPermissionState(permission) | "granted" | "denied" | "prompt". | | setPermissionState(permission, state) | Pre-grant or deny a permission. | | resolvePermission(requestId, granted) | Complete a permission prompt. |

Built-in permission names include execute_custom_function, dom_read, clipboard_access, and network_request (extensible via string).

TypeScript

Full types are exported from the package entry:

import type {
  PagePolicy,
  PageContext,
  ComponentDescriptor,
  StructuredPagePayload,
  ExtensionEvent,
  SandboxPermission,
} from "@ineerajrajeev/aios-web-sdk";

Development

npm run test        # vitest (includes Safari extension bridge integration test)
npm run build       # dist/ ESM + CJS + .d.ts
npm run typecheck
npm run dev         # watch mode

Changelog

0.1.4

• Screenshot Capability — Added built-in takeScreenshot sandbox function to support agent viewport captures.
• Custom Fallback Mechanism — Added fallbackScreenshot to aiOS.init() options. If the user denies permission to capture the screen, the SDK automatically falls back to the provided image or renders a custom black placeholder.

0.1.3

• Chrome extension parity — Documented Safari + Chrome support; protocol matches extension sdk-bridge.js v2.5.
• Sandbox API — aiOS.sandbox for permission-gated agent function calls (executeSdkFunction bridge).
• Export flow docs — exportPageData, prepareExport, requestConsent, flushApprovedExport.
• Extended events — agent:data-access, agent:function-request, agent:permission-request, extension:status.
• Agent action cache — Extension logs actions to sessionStorage for audit/resume (SDK + non-SDK pages).

0.1.2

• Agent action session cache integration with the browser extension.
• SessionStorage fallback when the SDK is not present on a page.

0.1.0

• Initial release: policy, context, zones, components, consent, and publish().

Links

• Website: getaios.tech
• npm: @ineerajrajeev/aios-web-sdk
• Browser extensions: downloads