@opengeni/sdk 0.52.1 → 0.57.0

package/README.md

@@ -139,6 +139,60 @@ and long-lived credentials are never placed in the WebSocket URL. Hosts may
 inject both `fetch` and the WebSocket factory for authenticated proxies and
 tests; negotiated frame and mutation limits are enforced before work is queued.
 
+## Browser and computer interaction (`@opengeni/sdk/interaction`)
+
+An interaction **resource** is a workspace-scoped, durable object with a stable
+id and lifecycle, such as a `BrowserSession`, `ComputerSession`, browser
+identity, network route, auth run, or pending human intervention. This use of
+"resource" is unrelated to the file/repository `resources` attached to a chat
+message. A **facade** is only the typed, resource-oriented SDK organization
+shown below; it owns no state or authority of its own.
+
+`OpenGeniClient.interaction` is the framework-free resource facade over the same
+public BrowserSession, ComputerSession, identity, auth, network-route, and human
+intervention APIs used by OpenGeni itself. It adds no second state or execution
+path: facade methods call the ordinary typed transport, and every mutation still
+uses the canonical generation fences, operation receipt, permission check, and
+placement controller.
+
+```ts
+const browser = await client.interaction.browsers.currentOrOpen({
+  workspaceId,
+  associationSessionId: session.id,
+  initialUrl: "http://127.0.0.1:3000",
+});
+
+const { targets } = await browser.tabs.list();
+const target = targets.find((candidate) => candidate.selected) ?? targets[0]!;
+const page = await browser.observe(target.id);
+
+const receipt = await browser.act({
+  operationId: crypto.randomUUID(),
+  targetId: target.id,
+  expectedTargetGeneration: target.targetGeneration,
+  expectedDocumentGeneration: target.documentGeneration,
+  expectedFrameId: page.frameId,
+  action: { type: "click", locator: { kind: "role", role: "button", name: "Continue" } },
+});
+
+if (receipt.state === "outcome_unknown") {
+  // Do not replay a mutation blindly. Re-observe, then inspect this exact receipt.
+  console.log(await browser.receipt(receipt.operationId));
+}
+```
+
+Browser identities are immutable version graphs: live browser state stays
+private until `browser.publishRevision(...)` explicitly creates a new revision.
+Protected auth fills resolve connection secrets only inside the broker/controller
+path; normal SDK reads, observations, diagnostics, receipts, and logs never
+return credential values. `client.openWorkspaceInteractionRevisionStream(...)`
+is the low-volume latest-wins invalidation stream for keeping resource catalogs
+fresh without attaching them to an inference/session event stream.
+
+Use the flat `OpenGeniClient` interaction methods when implementing a proxy or
+custom transport. Use `client.interaction` for application logic. Both are the
+same API and authority boundary.
+
 ## Workspace artifacts
 
 Workspace artifacts are generic, immutable HTML publications. The SDK does not
@@ -484,13 +538,13 @@ Every public endpoint group has typed methods:
 | Packs | `listPacks`, `registerPack`, `getPack`, `enablePack`, `deletePack`, `listPackInstallations` |
 | Capabilities | `listCapabilities`, `createCapability`, `enableCapability`, `disableCapability`, `discoverMcpCapabilities` |
 | Plugin packages | `previewPlugin`, `installPlugin`, `previewPluginUninstall`, `uninstallPlugin` |
-| API Integrations | `listApiIntegrationPresets`, `listApiIntegrations`, `previewApiIntegration`, `startApiIntegrationOAuth`, `installApiIntegration`, `previewApiIntegrationUninstall`, `uninstallApiIntegration`, `listIntegrationFeatures`, `configureIntegrationFeature`, `pauseIntegrationFeature`, `resumeIntegrationFeature`, `removeIntegrationFeature`, `browseGoogleDriveIntegrationSource`, `saveGoogleDriveIntegrationSource` |
+| API Integrations | `listIntegrationDefinitions`, `listApiIntegrations`, `previewApiIntegration`, `startApiIntegrationOAuth`, `installApiIntegration`, `previewApiIntegrationUninstall`, `uninstallApiIntegration`, `listIntegrationFacets`, `configureIntegrationFacet`, `pauseIntegrationFacet`, `resumeIntegrationFacet`, `removeIntegrationFacet`, `browseGoogleDriveFacetSource`, `saveGoogleDriveFacetSource` |
 | Remote Skills | `previewSkillImport`, `installSkill`, `previewSkillUninstall`, `uninstallSkill` |
 | GitHub | `getGitHubApp`, `githubConnectUrl`, `listGitHubRepositories`, `syncGitHubRepositories`, `createGitHubAppManifest` |
 | API keys | `listApiKeys`, `createApiKey`, `deleteApiKey` |
 | Billing | `getBilling`, `getBillingUsage`, `getBillingEntitlements`, `createBillingCheckout` |
 
-`listApiIntegrationPresets` returns safe curated-provider metadata without any
+`listIntegrationDefinitions` returns safe Integration Definition metadata without any
 deployment OAuth client credentials. API Integrations are multi-instance:
 `installApiIntegration` may supply a
 stable `instanceKey`, display name, and exact Connection. The returned
@@ -499,14 +553,14 @@ selected in one session without tool-name collision. Uninstall preview and
 uninstall both require the exact `instanceKey` and instance version; neither
 operation disconnects the underlying Connection.
 
-Adapter-owned Integration features are listed and mutated under the exact
-`capabilityId` + `instanceKey` + `featureKey`. Generic primitive schemas use
-`configureIntegrationFeature`; lifecycle changes and removal require the
+Adapter-owned Integration facets are listed and mutated under the exact
+`capabilityId` + `instanceKey` + `facetKey`. Generic primitive schemas use
+`configureIntegrationFacet`; lifecycle changes and removal require the
 binding's exact optimistic version plus a caller UUID idempotency key. Google
 Drive's nested folder/Shared Drive source schema has dedicated
-`browseGoogleDriveIntegrationSource` and `saveGoogleDriveIntegrationSource`
+`browseGoogleDriveFacetSource` and `saveGoogleDriveFacetSource`
 methods. They verify provider metadata through that instance's exact Connection
-and persist only a versioned feature binding—never provider credentials, page
+and persist only a versioned facet binding—never provider credentials, page
 tokens, or selected-source configuration on the Connection.
 
 ### Protocol routes (deliberately not in the SDK)

package/dist/artifacts.js

@@ -1,10 +1,10 @@
 import {
   OpenGeniClient
-} from "./chunk-FHI4DFIG.js";
-import "./chunk-ILQZR5N6.js";
-import "./chunk-V5F253OG.js";
-import "./chunk-MZWTWOX6.js";
-import "./chunk-FRJFNDIR.js";
+} from "./chunk-JRPFWI6T.js";
+import "./chunk-PKQ377ED.js";
+import "./chunk-HJ3HHUT5.js";
+import "./chunk-GU6JF75T.js";
+import "./chunk-ST5DDKJP.js";
 export {
   OpenGeniClient
 };

package/dist/{chunk-V5F253OG.js → chunk-GU6JF75T.js}

@@ -21,7 +21,7 @@ var OpenGeniApiError = class extends Error {
     this.code = options.code ?? decoded?.code ?? (gatewayFailure && fromResponse ? "upstream_unavailable" : void 0);
     this.retryable = options.retryable ?? decoded?.retryable ?? retryableApiStatus(status);
     this.correlationId = correlationId;
-    this.outcomeUnknown = options.outcomeUnknown ?? (gatewayFailure && !!options.mutation && !decoded);
+    this.outcomeUnknown = options.outcomeUnknown ?? decoded?.outcomeUnknown ?? (gatewayFailure && !!options.mutation && !decoded);
     this.body = !fromResponse || decoded ? body : "";
     this.details = decoded?.details;
   }
@@ -37,13 +37,16 @@ function decodeApiErrorBody(body) {
     const message = boundedApiField(nested.message);
     const requestId = boundedCorrelationId(nested.requestId);
     const retryable = typeof nested.retryable === "boolean" ? nested.retryable : void 0;
+    const outcomeUnknown = typeof nested.outcomeUnknown === "boolean" ? nested.outcomeUnknown : void 0;
     const details = boundedApiDetails(nested.details);
-    if (!code && !message && !requestId && retryable === void 0 && !details) return null;
+    if (!code && !message && !requestId && retryable === void 0 && outcomeUnknown === void 0 && !details)
+      return null;
     return {
       code,
       message,
       requestId,
       retryable,
+      outcomeUnknown,
       details
     };
   } catch {
@@ -113,4 +116,4 @@ export {
   isAbortError,
   isRetryableStreamError
 };
-//# sourceMappingURL=chunk-V5F253OG.js.map
+//# sourceMappingURL=chunk-GU6JF75T.js.map

package/dist/chunk-GU6JF75T.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts"],"sourcesContent":["/** Error for a non-2xx OpenGeni API response. */\nexport class OpenGeniApiError extends Error {\n  readonly status: number;\n  readonly code: string | undefined;\n  readonly retryable: boolean;\n  readonly correlationId: string | undefined;\n  /** True only when an uncontrolled transport failed after a mutation may have been accepted. */\n  readonly outcomeUnknown: boolean;\n  readonly body: string;\n  readonly details: Record<string, unknown> | undefined;\n\n  constructor(\n    status: number,\n    body: string,\n    options: {\n      code?: string | undefined;\n      retryable?: boolean | undefined;\n      correlationId?: string | undefined;\n      outcomeUnknown?: boolean | undefined;\n      displayMessage?: string | undefined;\n      mutation?: boolean | undefined;\n    } = {},\n  ) {\n    const decoded = decodeApiErrorBody(body);\n    const correlationId = decoded?.requestId ?? boundedCorrelationId(options.correlationId);\n    const gatewayFailure = status >= 502 && status <= 504;\n    const fromResponse = options.mutation !== undefined;\n    const message = decoded?.message ?? (fromResponse ? \"Request failed.\" : body || \"(empty body)\");\n    const displayMessage =\n      options.displayMessage ??\n      (gatewayFailure && fromResponse\n        ? (decoded?.message ?? \"OpenGeni is temporarily unavailable — retry.\")\n        : `OpenGeni API ${status}: ${message}`);\n    super(correlationId ? `${displayMessage} Reference: ${correlationId}.` : displayMessage);\n    this.name = \"OpenGeniApiError\";\n    this.status = status;\n    this.code =\n      options.code ??\n      decoded?.code ??\n      (gatewayFailure && fromResponse ? \"upstream_unavailable\" : undefined);\n    this.retryable = options.retryable ?? decoded?.retryable ?? retryableApiStatus(status);\n    this.correlationId = correlationId;\n    this.outcomeUnknown =\n      options.outcomeUnknown ??\n      decoded?.outcomeUnknown ??\n      (gatewayFailure && !!options.mutation && !decoded);\n    this.body = !fromResponse || decoded ? body : \"\";\n    this.details = decoded?.details;\n  }\n}\n\nfunction decodeApiErrorBody(body: string): {\n  code: string | undefined;\n  message: string | undefined;\n  requestId: string | undefined;\n  retryable: boolean | undefined;\n  outcomeUnknown: boolean | undefined;\n  details: Record<string, unknown> | undefined;\n} | null {\n  if (!body) return null;\n  try {\n    const decoded: unknown = JSON.parse(body);\n    if (!decoded || typeof decoded !== \"object\" || Array.isArray(decoded)) return null;\n    const record = decoded as Record<string, unknown>;\n    const nested =\n      record.error && typeof record.error === \"object\" && !Array.isArray(record.error)\n        ? (record.error as Record<string, unknown>)\n        : record;\n    const code = boundedApiField(nested.code);\n    const message = boundedApiField(nested.message);\n    const requestId = boundedCorrelationId(nested.requestId);\n    const retryable = typeof nested.retryable === \"boolean\" ? nested.retryable : undefined;\n    const outcomeUnknown =\n      typeof nested.outcomeUnknown === \"boolean\" ? nested.outcomeUnknown : undefined;\n    const details = boundedApiDetails(nested.details);\n    if (\n      !code &&\n      !message &&\n      !requestId &&\n      retryable === undefined &&\n      outcomeUnknown === undefined &&\n      !details\n    )\n      return null;\n    return {\n      code,\n      message,\n      requestId,\n      retryable,\n      outcomeUnknown,\n      details,\n    };\n  } catch {\n    return null;\n  }\n}\n\nfunction boundedApiDetails(value: unknown): Record<string, unknown> | undefined {\n  if (!value || typeof value !== \"object\" || Array.isArray(value)) return;\n  const entries = Object.entries(value as Record<string, unknown>).slice(0, 16);\n  const details: Record<string, unknown> = {};\n  for (const [key, entry] of entries) {\n    if (!/^[a-zA-Z][\\w.-]{0,63}$/.test(key)) continue;\n    if (typeof entry === \"string\") {\n      const bounded = boundedApiField(entry);\n      if (bounded !== undefined) details[key] = bounded;\n    } else if (typeof entry === \"number\" || typeof entry === \"boolean\" || entry === null) {\n      details[key] = entry;\n    }\n  }\n  return Object.keys(details).length > 0 ? details : undefined;\n}\n\nfunction boundedApiField(value: unknown): string | undefined {\n  if (typeof value !== \"string\") return;\n  const bytes = new TextEncoder().encode(value);\n  return bytes.byteLength <= 512 ? value : new TextDecoder().decode(bytes.slice(0, 512));\n}\n\nfunction retryableApiStatus(status: number): boolean {\n  return status === 408 || status === 409 || status === 425 || status === 429 || status >= 500;\n}\n\nfunction boundedCorrelationId(value: unknown): string | undefined {\n  if (typeof value !== \"string\" || value.length > 128 || !/^[\\w.:-]+$/.test(value)) {\n    return;\n  }\n  return value;\n}\n\n/** A short-lived session-list snapshot cursor can no longer be continued. */\nexport class OpenGeniSessionListCursorError extends OpenGeniApiError {}\n\n/** The browser bundle and API disagree about their state-changing wire contract. */\nexport class OpenGeniApiContractMismatchError extends Error {\n  readonly expected: string;\n  readonly actual: string;\n\n  constructor(expected: string, actual: string) {\n    super(`OpenGeni API contract mismatch: client expects ${expected}, API serves ${actual}`);\n    this.name = \"OpenGeniApiContractMismatchError\";\n    this.expected = expected;\n    this.actual = actual;\n  }\n}\n\n/** Error for an unrecoverable event-stream condition (not a transient drop). */\nexport class OpenGeniStreamError extends Error {\n  constructor(message: string) {\n    super(message);\n    this.name = \"OpenGeniStreamError\";\n  }\n}\n\nexport function isAbortError(error: unknown): boolean {\n  return (\n    (error instanceof DOMException && error.name === \"AbortError\") ||\n    (error instanceof Error && error.name === \"AbortError\")\n  );\n}\n\n/**\n * Transient conditions worth a reconnect: network-level failures (`fetch`\n * rejects with `TypeError`) and HTTP statuses that signal a temporary server\n * or contention condition. Auth/validation failures (401/403/404/...) are\n * permanent and surface to the caller instead.\n */\nexport function isRetryableStreamError(error: unknown): boolean {\n  if (error instanceof OpenGeniApiError) return error.retryable;\n  return error instanceof TypeError;\n}\n"],"mappings":"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","names":[]}

package/dist/{chunk-FRJFNDIR.js → chunk-HJ3HHUT5.js}

@@ -47,6 +47,9 @@ var SESSION_EVENT_TYPES = [
   "artifact.created",
   "goal.set",
   "goal.updated",
+  "goal.progress",
+  "goal.rewrite.proposed",
+  "goal.rewrite.rejected",
   "goal.completed",
   "goal.paused",
   "goal.resumed",
@@ -86,6 +89,7 @@ var SESSION_EVENT_TYPES = [
   "terminal.pty.output.delta",
   "terminal.pty.exited",
   "session.title_set",
+  "session.visibility.changed",
   "session.mcp.approval_policy.updated",
   "session.tool_policy.updated",
   // Multi-account Codex (P1): the session's inference account changed.
@@ -215,4 +219,4 @@ export {
   GENERATED_VIDEO_MAX_BYTES,
   KNOWN_USAGE_EVENT_TYPES
 };
-//# sourceMappingURL=chunk-FRJFNDIR.js.map
+//# sourceMappingURL=chunk-HJ3HHUT5.js.map