busabase-sdk 0.14.1 → 0.16.0

package/dist/index.js

@@ -29,6 +29,109 @@ var toFilesOnlyGrepResult = (result) => ({
   truncated: result.truncated
 });
 var grepAssets = async (client, input) => toFilesOnlyGrepResult(await client.grep(toUnifiedFilesGrepInput(input)));
+var AgentTransportSchema = z.enum(["local-subprocess", "remote-websocket"]);
+var AgentCatalogEntryVOSchema = z.object({
+  /** Stable slug. For registry agents this is the official ACP registry id. */
+  slug: z.string(),
+  name: z.string(),
+  description: z.string().default(""),
+  transport: AgentTransportSchema,
+  /** Present for registry-sourced entries; absent for built-ins like Buda. */
+  version: z.string().nullable().default(null),
+  /** Whether this entry can be launched right now (binary present / URL configured). */
+  available: z.boolean().default(false),
+  /** Human-readable reason when `available` is false — never a bare "failed". */
+  unavailableReason: z.string().nullable().default(null)
+});
+var AgentSessionStatusSchema = z.enum([
+  "connecting",
+  "idle",
+  "busy",
+  "waiting_permission",
+  "ended",
+  "failed"
+]);
+var AgentPermissionOptionVOSchema = z.object({
+  optionId: z.string(),
+  name: z.string(),
+  kind: z.string().optional()
+});
+var AgentPermissionRequestVOSchema = z.object({
+  requestId: z.string(),
+  title: z.string().optional(),
+  description: z.string().optional(),
+  options: z.array(AgentPermissionOptionVOSchema)
+});
+var AgentSessionVOSchema = z.object({
+  /** Busabase's own id for the session; not the agent's ACP sessionId. */
+  id: z.string(),
+  slug: z.string(),
+  agentName: z.string(),
+  transport: AgentTransportSchema,
+  status: AgentSessionStatusSchema,
+  /** ISO 8601 — never a Date at the transport boundary. */
+  createdAt: z.string(),
+  lastActivityAt: z.string(),
+  /** Set when status is "failed"; surfaced verbatim to the user. */
+  error: z.string().nullable().default(null)
+});
+var AgentSessionEventVOSchema = z.object({
+  sessionId: z.string(),
+  /** Monotonic per session, so a reconnecting client can tell what it missed. */
+  seq: z.number().int(),
+  kind: z.enum(["acpUpdate", "status", "error", "permissionRequest", "permissionResolved"]),
+  acpUpdate: z.unknown().optional(),
+  status: AgentSessionStatusSchema.optional(),
+  message: z.string().optional(),
+  permissionRequest: AgentPermissionRequestVOSchema.optional(),
+  /** Present on a `permissionResolved` event — which request, and what the user picked. */
+  permissionRequestId: z.string().optional(),
+  permissionOptionId: z.string().optional(),
+  at: z.string()
+});
+var CreateAgentSessionInputSchema = z.object({
+  /** Must name a catalog entry. Deliberately NOT a command line — see below. */
+  slug: z.string().min(1)
+});
+var PromptAgentSessionInputSchema = z.object({
+  sessionId: z.string().min(1),
+  text: z.string().min(1)
+});
+var AgentSessionIdInputSchema = z.object({ sessionId: z.string().min(1) });
+var RespondToAgentPermissionInputSchema = z.object({
+  sessionId: z.string().min(1),
+  requestId: z.string().min(1),
+  optionId: z.string().min(1)
+});
+
+// ../../packages/busabase-contract/src/domains/agents/contract.ts
+var agentsContract = {
+  /** Connectable backends. Availability is resolved per request, not cached in the client. */
+  catalog: oc.output(AgentCatalogEntryVOSchema.array()),
+  sessions: {
+    list: oc.output(AgentSessionVOSchema.array()),
+    create: oc.input(CreateAgentSessionInputSchema).output(AgentSessionVOSchema),
+    /**
+     * Send a message. Returns as soon as the turn is accepted — the reply arrives
+     * on `subscribe`, not here, so a slow agent never blocks the caller.
+     */
+    prompt: oc.input(PromptAgentSessionInputSchema).output(z.object({ accepted: z.boolean(), sessionId: z.string() })),
+    cancel: oc.input(AgentSessionIdInputSchema).output(z.object({ ok: z.boolean() })),
+    close: oc.input(AgentSessionIdInputSchema).output(z.object({ ok: z.boolean() })),
+    /**
+     * Answer a pending `session/request_permission`. There is no auto-approve
+     * and no "remember this choice" in this pass (deliberate, see spec) — every
+     * request blocks the turn until a human calls this.
+     */
+    respondToPermission: oc.input(RespondToAgentPermissionInputSchema).output(z.object({ ok: z.boolean() })),
+    /**
+     * Live event stream for one session. Replays buffered events from `afterSeq`
+     * first so a client that reconnects mid-turn does not lose the tokens it
+     * missed, then follows live.
+     */
+    subscribe: oc.input(z.object({ sessionId: z.string().min(1), afterSeq: z.number().int().default(-1) })).output(eventIterator(AgentSessionEventVOSchema))
+  }
+};
 var i18n = {
   locales: ["en", "zh-CN", "zh-TW", "ja", "ko", "de", "fr", "es", "pt"]};
 var LocaleSchema = z.enum(i18n.locales);
@@ -3275,6 +3378,7 @@ var busabaseContractRoutes = {
   forms: formContract,
   assets: assetsContract,
   vault: vaultContract,
+  agents: agentsContract,
   webhooks: webhookContract,
   dump: dumpContract,
   install: installContract,

package/dist/oauth-node.d.ts

@@ -10,6 +10,11 @@ interface BusabaseAirAppOAuthCredential {
     expiresAt: string;
     scope: string[];
     tokenType: string;
+    /** Validated target for this local AirApp. Tokens remain user-scoped. */
+    selectedSpace?: {
+        id: string;
+        name: string;
+    };
 }
 interface BusabaseAirAppCredentialStoreOptions {
     /** Override only for tests or an explicitly isolated installation. */
@@ -18,16 +23,42 @@ interface BusabaseAirAppCredentialStoreOptions {
 /** Directory containing one owner-only OAuth registration per local AirApp. */
 declare const busabaseAirAppCredentialsDir: (options?: BusabaseAirAppCredentialStoreOptions) => string;
 declare const busabaseAirAppCredentialPath: (appId: string, options?: BusabaseAirAppCredentialStoreOptions) => string;
+/**
+ * Dynamically registered public client ids, keyed by `${baseUrl}|${redirectUri}`.
+ *
+ * Kept out of the credential file because registration happens before any token exists, and the
+ * mapping must outlive both the process and a logout — re-registering on every restart would
+ * churn server-side client records and burn the registration rate limit.
+ */
+declare const busabaseAirAppDynamicClientsPath: (appId: string, options?: BusabaseAirAppCredentialStoreOptions) => string;
 declare function loadBusabaseAirAppOAuthCredential(appId: string, options?: BusabaseAirAppCredentialStoreOptions): BusabaseAirAppOAuthCredential | null;
 declare function storeBusabaseAirAppOAuthCredential(input: {
     appId: string;
     baseUrl: string;
     tokenSet: BusabaseOAuthTokenSet;
     clientId?: string;
+    selectedSpace?: BusabaseAirAppOAuthCredential["selectedSpace"];
 }, options?: BusabaseAirAppCredentialStoreOptions): BusabaseAirAppOAuthCredential;
+/** Reuse a previously registered public client for this exact origin and callback. */
+declare function loadBusabaseAirAppDynamicClientId(input: {
+    appId: string;
+    baseUrl: string;
+    redirectUri: string;
+}, options?: BusabaseAirAppCredentialStoreOptions): string | null;
+declare function storeBusabaseAirAppDynamicClientId(input: {
+    appId: string;
+    baseUrl: string;
+    redirectUri: string;
+    clientId: string;
+}, options?: BusabaseAirAppCredentialStoreOptions): void;
 /** Load a valid access token, rotating and persisting the token set when needed. */
 declare function getBusabaseAirAppAccessToken(appId: string, options?: BusabaseAirAppCredentialStoreOptions, fetchImpl?: typeof fetch): Promise<BusabaseAirAppOAuthCredential | null>;
+/** Persist a Space only after the caller has verified membership through `/api/v1/auth`. */
+declare function storeBusabaseAirAppSelectedSpace(appId: string, selectedSpace: {
+    id: string;
+    name: string;
+} | null, options?: BusabaseAirAppCredentialStoreOptions): BusabaseAirAppOAuthCredential;
 declare function clearBusabaseAirAppOAuthCredential(appId: string, options?: BusabaseAirAppCredentialStoreOptions): void;
 declare function revokeBusabaseAirAppOAuthCredential(appId: string, options?: BusabaseAirAppCredentialStoreOptions, fetchImpl?: typeof fetch): Promise<void>;
 
-export { type BusabaseAirAppCredentialStoreOptions, type BusabaseAirAppOAuthCredential, busabaseAirAppCredentialPath, busabaseAirAppCredentialsDir, clearBusabaseAirAppOAuthCredential, getBusabaseAirAppAccessToken, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential, storeBusabaseAirAppOAuthCredential };
+export { type BusabaseAirAppCredentialStoreOptions, type BusabaseAirAppOAuthCredential, busabaseAirAppCredentialPath, busabaseAirAppCredentialsDir, busabaseAirAppDynamicClientsPath, clearBusabaseAirAppOAuthCredential, getBusabaseAirAppAccessToken, loadBusabaseAirAppDynamicClientId, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential, storeBusabaseAirAppDynamicClientId, storeBusabaseAirAppOAuthCredential, storeBusabaseAirAppSelectedSpace };

package/dist/oauth-node.js

@@ -1,147 +1,3 @@
-import { BusabaseOAuthError, BUSABASE_AIRAPP_CLIENT_ID, refreshBusabaseOAuthToken, revokeBusabaseOAuthToken } from './chunk-J2DZKX7A.js';
-import { normalizeBaseUrl } from './chunk-5NYQX65A.js';
-import { randomUUID } from 'crypto';
-import { readFileSync, mkdirSync, chmodSync, writeFileSync, renameSync, rmSync } from 'fs';
-import { homedir } from 'os';
-import { join, dirname } from 'path';
-
-var STORE_VERSION = 1;
-var APP_ID_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-var REFRESH_WINDOW_MS = 6e4;
-var refreshesByCredentialPath = /* @__PURE__ */ new Map();
-var assertAppId = (appId) => {
-  if (!APP_ID_RE.test(appId)) {
-    throw new BusabaseOAuthError(
-      "invalid_airapp_id",
-      "AirApp id must use letters, digits, dot, dash, or underscore"
-    );
-  }
-  return appId;
-};
-var storeRoot = (options = {}) => options.rootDir ?? join(homedir(), ".busabase");
-var busabaseAirAppCredentialsDir = (options = {}) => join(storeRoot(options), "airapps");
-var busabaseAirAppCredentialPath = (appId, options = {}) => join(busabaseAirAppCredentialsDir(options), `${assertAppId(appId)}.json`);
-var normalizeOrigin = (raw) => {
-  const url = new URL(normalizeBaseUrl(raw));
-  if (url.username || url.password || url.search || url.hash) {
-    throw new BusabaseOAuthError("invalid_base_url", "Busabase base URL must be an origin");
-  }
-  return url.origin;
-};
-var parseCredential = (raw, expectedAppId) => {
-  let value;
-  try {
-    value = JSON.parse(raw);
-  } catch {
-    throw new BusabaseOAuthError("invalid_local_credential", "AirApp OAuth credential is invalid");
-  }
-  const item = value;
-  if (item.version !== STORE_VERSION || item.appId !== expectedAppId || typeof item.baseUrl !== "string" || typeof item.clientId !== "string" || typeof item.accessToken !== "string" || typeof item.refreshToken !== "string" || typeof item.expiresAt !== "string" || !Array.isArray(item.scope) || item.scope.some((scope) => typeof scope !== "string") || typeof item.tokenType !== "string") {
-    throw new BusabaseOAuthError("invalid_local_credential", "AirApp OAuth credential is invalid");
-  }
-  return item;
-};
-function loadBusabaseAirAppOAuthCredential(appId, options = {}) {
-  const path = busabaseAirAppCredentialPath(appId, options);
-  try {
-    return parseCredential(readFileSync(path, "utf8"), appId);
-  } catch (error) {
-    if (error.code === "ENOENT") return null;
-    throw error;
-  }
-}
-function storeBusabaseAirAppOAuthCredential(input, options = {}) {
-  if (!input.tokenSet.refreshToken) {
-    throw new BusabaseOAuthError(
-      "missing_refresh_token",
-      "A refresh token is required for a persistent local AirApp login"
-    );
-  }
-  const credential = {
-    version: STORE_VERSION,
-    appId: assertAppId(input.appId),
-    baseUrl: normalizeOrigin(input.baseUrl),
-    clientId: input.clientId ?? BUSABASE_AIRAPP_CLIENT_ID,
-    accessToken: input.tokenSet.accessToken,
-    refreshToken: input.tokenSet.refreshToken,
-    expiresAt: input.tokenSet.expiresAt,
-    scope: input.tokenSet.scope,
-    tokenType: input.tokenSet.tokenType
-  };
-  const path = busabaseAirAppCredentialPath(input.appId, options);
-  const directory = dirname(path);
-  mkdirSync(directory, { recursive: true, mode: 448 });
-  try {
-    chmodSync(directory, 448);
-  } catch {
-  }
-  const temporaryPath = `${path}.${randomUUID()}.tmp`;
-  writeFileSync(temporaryPath, `${JSON.stringify(credential, null, 2)}
-`, { mode: 384 });
-  try {
-    chmodSync(temporaryPath, 384);
-  } catch {
-  }
-  renameSync(temporaryPath, path);
-  return credential;
-}
-async function getBusabaseAirAppAccessToken(appId, options = {}, fetchImpl = fetch) {
-  const credential = loadBusabaseAirAppOAuthCredential(appId, options);
-  if (!credential) return null;
-  const expiresAt = Date.parse(credential.expiresAt);
-  if (Number.isFinite(expiresAt) && expiresAt > Date.now() + REFRESH_WINDOW_MS) return credential;
-  const credentialPath = busabaseAirAppCredentialPath(appId, options);
-  const activeRefresh = refreshesByCredentialPath.get(credentialPath);
-  if (activeRefresh) return activeRefresh;
-  const refresh = (async () => {
-    const tokenSet = await refreshBusabaseOAuthToken(
-      {
-        baseUrl: credential.baseUrl,
-        refreshToken: credential.refreshToken,
-        clientId: credential.clientId
-      },
-      fetchImpl
-    );
-    return storeBusabaseAirAppOAuthCredential(
-      {
-        appId,
-        baseUrl: credential.baseUrl,
-        clientId: credential.clientId,
-        tokenSet: {
-          ...tokenSet,
-          refreshToken: tokenSet.refreshToken ?? credential.refreshToken
-        }
-      },
-      options
-    );
-  })();
-  refreshesByCredentialPath.set(credentialPath, refresh);
-  try {
-    return await refresh;
-  } finally {
-    if (refreshesByCredentialPath.get(credentialPath) === refresh) {
-      refreshesByCredentialPath.delete(credentialPath);
-    }
-  }
-}
-function clearBusabaseAirAppOAuthCredential(appId, options = {}) {
-  rmSync(busabaseAirAppCredentialPath(appId, options), { force: true });
-}
-async function revokeBusabaseAirAppOAuthCredential(appId, options = {}, fetchImpl = fetch) {
-  const credential = loadBusabaseAirAppOAuthCredential(appId, options);
-  if (!credential) return;
-  try {
-    await revokeBusabaseOAuthToken(
-      {
-        baseUrl: credential.baseUrl,
-        token: credential.refreshToken,
-        clientId: credential.clientId
-      },
-      fetchImpl
-    );
-  } finally {
-    clearBusabaseAirAppOAuthCredential(appId, options);
-  }
-}
-
-export { busabaseAirAppCredentialPath, busabaseAirAppCredentialsDir, clearBusabaseAirAppOAuthCredential, getBusabaseAirAppAccessToken, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential, storeBusabaseAirAppOAuthCredential };
+export { busabaseAirAppCredentialPath, busabaseAirAppCredentialsDir, busabaseAirAppDynamicClientsPath, clearBusabaseAirAppOAuthCredential, getBusabaseAirAppAccessToken, loadBusabaseAirAppDynamicClientId, loadBusabaseAirAppOAuthCredential, revokeBusabaseAirAppOAuthCredential, storeBusabaseAirAppDynamicClientId, storeBusabaseAirAppOAuthCredential, storeBusabaseAirAppSelectedSpace } from './chunk-C23JVY2Y.js';
+import './chunk-WSHJMHUS.js';
+import './chunk-5NYQX65A.js';

package/dist/oauth.d.ts

@@ -1,6 +1,8 @@
 /** Public client identifier used by local Hono/AirApp development servers. */
 declare const BUSABASE_AIRAPP_CLIENT_ID = "busabase-airapp";
 
+/** The only scope an AirApp ever requests; bound to the `/api/v1` resource. */
+declare const AIRAPP_OAUTH_SCOPE = "api";
 interface BusabaseOAuthRequest {
     authorizeUrl: string;
     baseUrl: string;
@@ -31,11 +33,21 @@ interface BusabaseOAuthTokenSet {
         image: string | null;
     };
 }
+interface RegisterBusabaseAirAppOAuthClientInput {
+    appId: string;
+    baseUrl: string;
+    redirectUri: string;
+}
 declare class BusabaseOAuthError extends Error {
     readonly code: string;
     readonly status?: number;
     constructor(code: string, message: string, status?: number);
 }
+/** Register an exact HTTPS callback for a public AirApp OAuth client. */
+declare function registerBusabaseAirAppOAuthClient(input: RegisterBusabaseAirAppOAuthClientInput, fetchImpl?: typeof fetch): Promise<{
+    clientId: string;
+    redirectUri: string;
+}>;
 /** Build a public-client OAuth 2.1 authorization request with PKCE S256. */
 declare function createBusabaseOAuthRequest(input: CreateBusabaseOAuthRequestInput): Promise<BusabaseOAuthRequest>;
 /** Validate state and issuer before accepting the authorization code. */
@@ -52,4 +64,4 @@ declare function revokeBusabaseOAuthToken(input: {
     clientId?: string;
 }, fetchImpl?: typeof fetch): Promise<void>;
 
-export { BUSABASE_AIRAPP_CLIENT_ID, BusabaseOAuthError, type BusabaseOAuthRequest, type BusabaseOAuthTokenSet, type CreateBusabaseOAuthRequestInput, createBusabaseOAuthRequest, exchangeBusabaseOAuthCode, parseBusabaseOAuthCallback, refreshBusabaseOAuthToken, revokeBusabaseOAuthToken };
+export { AIRAPP_OAUTH_SCOPE, BUSABASE_AIRAPP_CLIENT_ID, BusabaseOAuthError, type BusabaseOAuthRequest, type BusabaseOAuthTokenSet, type CreateBusabaseOAuthRequestInput, type RegisterBusabaseAirAppOAuthClientInput, createBusabaseOAuthRequest, exchangeBusabaseOAuthCode, parseBusabaseOAuthCallback, refreshBusabaseOAuthToken, registerBusabaseAirAppOAuthClient, revokeBusabaseOAuthToken };

package/dist/oauth.js

@@ -1,2 +1,2 @@
-export { BUSABASE_AIRAPP_CLIENT_ID, BusabaseOAuthError, createBusabaseOAuthRequest, exchangeBusabaseOAuthCode, parseBusabaseOAuthCallback, refreshBusabaseOAuthToken, revokeBusabaseOAuthToken } from './chunk-J2DZKX7A.js';
+export { AIRAPP_OAUTH_SCOPE, BUSABASE_AIRAPP_CLIENT_ID, BusabaseOAuthError, createBusabaseOAuthRequest, exchangeBusabaseOAuthCode, parseBusabaseOAuthCallback, refreshBusabaseOAuthToken, registerBusabaseAirAppOAuthClient, revokeBusabaseOAuthToken } from './chunk-WSHJMHUS.js';
 import './chunk-5NYQX65A.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-sdk",
-  "version": "0.14.1",
+  "version": "0.16.0",
   "description": "Typed TypeScript/JavaScript SDK for the Busabase OpenAPI REST API. Talks to a local or remote `busabase server` (or Busabase Cloud).",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/apps/busabase-sdk",
@@ -30,7 +30,20 @@
     "./oauth-node": {
       "types": "./dist/oauth-node.d.ts",
       "default": "./dist/oauth-node.js"
-    }
+    },
+    "./airapp-node": {
+      "types": "./dist/airapp-node.d.ts",
+      "default": "./dist/airapp-node.js"
+    },
+    "./airapp": {
+      "types": "./dist/airapp.d.ts",
+      "default": "./dist/airapp.js"
+    },
+    "./airapp-gate": {
+      "types": "./dist/airapp-gate.d.ts",
+      "default": "./dist/airapp-gate.js"
+    },
+    "./airapp-gate.css": "./dist/airapp-gate.css"
   },
   "files": [
     "dist",
@@ -45,12 +58,13 @@
   },
   "devDependencies": {
     "@types/node": "^24.13.2",
+    "jsdom": "^27.0.0",
     "tsup": "^8.5.0",
     "tsx": "^4.20.5",
     "typescript": "^5.9.3",
     "vitest": "^2.1.8",
-    "busabase-contract": "0.14.1",
     "open-domains": "0.0.2",
+    "busabase-contract": "0.16.0",
     "openlib": "0.1.1"
   },
   "engines": {