@fargowealth/fargo-ai-cli 1.3.0 → 1.4.1

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # Changelog
 
+## 1.4.1
+
+- Capture Connector-declared refresh-only localStorage values without exposing
+  them as website request headers or MCP arguments.
+- Add the shared Runtime `auth.refresh.aws-cognito` capability so Browser
+  Gateway can refresh expiring ID/access tokens and persist token rotation
+  before continuing an operation.
+- Keep rejected refresh credentials fail-closed as `needs_reauth`; transient
+  Cognito failures leave the encrypted Connection available for retry.
+- Show Website command help before validating required execution options.
+
+## 1.4.0
+
+- Allow Website Connector operations to select an explicit text response mode
+  for upstream endpoints whose Content-Type does not match their response body.
+- Capture allowlisted localStorage from single-page apps once their DOM is
+  interactive, without waiting indefinitely for `document.readyState=complete`.
+- Add `fargo website runtime` and a local execution mode for Connector
+  development with `fargo website call --mode local --file <definition>`.
+- Use the same versioned `@fargowealth/website-connector-runtime` implementation
+  in Fargo CLI and Browser Gateway, including required-capability negotiation.
+
 ## 1.3.0
 
 - Add `fargo website connect` and `fargo website sync` with an isolated local

package/README.md

@@ -58,6 +58,7 @@ synchronize later; that Profile is isolated from the user's normal Chrome data.
 
 ```sh
 fargo website validate --file connector.json
+fargo website runtime
 fargo website release --file connector.json --expected-revision 0 --confirm
 fargo website list
 fargo website operations --connector earningshub
@@ -66,6 +67,7 @@ fargo website sync --connector earningshub
 fargo website sync --connector earningshub --no-prompt --settle-ms 5000
 fargo website connection-status --connector earningshub
 fargo website call --connector earningshub --operation get_symbol --args '{"symbol":"AMZN"}'
+fargo website call --mode local --file connector.json --operation get_symbol --args '{"symbol":"AMZN"}'
 fargo website binding
 ```
 
@@ -78,6 +80,14 @@ capability using SHA-256 digests; the Profile body then goes directly to
 protection before replacing the encrypted cloud state. `--no-prompt` is for a
 Profile that is already authenticated.
 
+Connectors can declare refresh-only storage selectors separately from request
+headers. For AWS Cognito, Browser Gateway exchanges the encrypted Refresh Token
+for new ID/access tokens before expiry, saves any rotated Refresh Token inside
+the same connection-scoped Durable Object, and only then continues the website
+operation. Refresh Tokens never enter MCP arguments, command output, or normal
+website requests. `sync` is required again only after Cognito rejects or revokes
+the Refresh Token.
+
 Connector operations remain brokered through App MCP `website-bridge`, so the
 same operations are available to Codex, WorkBuddy, other Agents, and Teammates.
 V1 releases are owner-private. A Teammate binding delegates the invoking user's
@@ -85,6 +95,13 @@ identity and contains neither a `connectionId` nor website credentials. The old
 `authorize` / `authorize-complete` Cloud Live View commands remain an optional
 fallback, not the primary connection path.
 
+For V3 development, `--mode local` opens the isolated local Profile and executes
+the definition with the same `@fargowealth/website-connector-runtime` package
+used by Browser Gateway. Local mode never uploads its captured Profile. Remote
+mode remains the default and authoritative path for production Agents and
+Teammates. `fargo website runtime` prints the local Runtime version and supported
+capabilities so Connector requirements can be checked before execution.
+
 ## LEGO source snapshots
 
 ```sh

package/node_modules/@fargowealth/website-connector-runtime/README.md

@@ -0,0 +1,15 @@
+# Fargo Website Connector Runtime
+
+The shared, declarative Website Connector compiler and execution runtime used
+by both Fargo CLI local debugging and the Fargo Browser Gateway.
+
+Connector definitions contain data only. They cannot ship executable code.
+Callers provide browser storage at execution time; the runtime never persists
+cookies or localStorage.
+
+Runtime `1.1.0` adds declarative AWS Cognito token refresh. `secretSources`
+select refresh-only browser values, while `headerSources` remains the complete
+set of values allowed in business requests. The runtime can exchange an
+expiring session through Cognito's `GetTokensFromRefreshToken` API and returns a
+new in-memory storage state; the hosting BrowserConnectionSession Durable Object
+is responsible for encrypting and persisting that state before use.

package/node_modules/@fargowealth/website-connector-runtime/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@fargowealth/website-connector-runtime",
+  "version": "1.1.0",
+  "description": "Shared declarative Website Connector runtime for Fargo AI",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./src/index.d.mts",
+      "import": "./src/index.mjs"
+    }
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20.19.0"
+  },
+  "private": true,
+  "scripts": {
+    "test": "node --test test/*.test.mjs"
+  },
+  "license": "UNLICENSED"
+}

package/node_modules/@fargowealth/website-connector-runtime/src/index.d.mts

@@ -0,0 +1,136 @@
+export type WebsiteConnectorInputSchema = {
+  additionalProperties: false;
+  properties: Record<string, {
+    enum?: Array<string | number | boolean>;
+    maxLength?: number;
+    type: "string" | "number" | "integer" | "boolean";
+  }>;
+  required: string[];
+  type: "object";
+};
+
+export type WebsiteConnectorAuth =
+  | { kind: "none" }
+  | {
+      kind: "browser_storage";
+      sendCookies: boolean;
+      headerSources: Array<{ keySuffix: string; name: string; origin: string; prefix?: string }>;
+      secretSources: Array<{ id: string; keySuffix: string; origin: string }>;
+      refresh?: {
+        kind: "aws_cognito";
+        accessTokenSource: { keySuffix: string; origin: string };
+        clientId: string;
+        idTokenSource: { keySuffix: string; origin: string };
+        leewaySeconds: number;
+        refreshTokenSource: string;
+        region: string;
+        userPoolId: string;
+      };
+    };
+
+export type WebsiteConnectorOperation = {
+  operationId: string;
+  description: string;
+  readOnly: boolean;
+  requiresConnection: boolean;
+  riskLevel: "low" | "medium" | "high" | "critical";
+  inputSchema: WebsiteConnectorInputSchema;
+  request: {
+    origin: string;
+    method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+    path: string;
+    query: Record<string, string>;
+    headers: Record<string, string>;
+    responseMode: "auto" | "json" | "text";
+    body?: unknown;
+  };
+};
+
+export type WebsiteConnectorDefinition = {
+  schemaVersion: "fargo.website-connector/v1";
+  connectorId: string;
+  displayName: string;
+  allowedOrigins: string[];
+  loginUrl?: string;
+  runtime?: {
+    minimumVersion: string;
+    requiredCapabilities: string[];
+  };
+  auth: WebsiteConnectorAuth;
+  operations: WebsiteConnectorOperation[];
+};
+
+export type WebsiteConnectorBrowserStorageState = {
+  cookies: Array<{
+    domain: string;
+    expires?: number;
+    httpOnly?: boolean;
+    name: string;
+    path: string;
+    sameSite?: "Strict" | "Lax" | "None";
+    secure?: boolean;
+    value: string;
+  }>;
+  origins: Array<{
+    localStorage: Array<{ name: string; value: string }>;
+    origin: string;
+  }>;
+};
+
+export type WebsiteConnectorRuntimeDescriptor = {
+  capabilities: string[];
+  runtimeVersion: string;
+};
+
+export const WEBSITE_CONNECTOR_SCHEMA_VERSION: "fargo.website-connector/v1";
+export const WEBSITE_CONNECTOR_RUNTIME_VERSION: "1.1.0";
+export const WEBSITE_CONNECTOR_RUNTIME_CAPABILITIES: readonly string[];
+export class WebsiteConnectorDefinitionError extends Error {
+  code: string;
+  path: string;
+}
+export class WebsiteConnectorRuntimeError extends Error {
+  code: string;
+  details?: Record<string, unknown>;
+  status: number;
+}
+export function parseWebsiteConnectorDefinition(value: unknown): WebsiteConnectorDefinition;
+export function connectorToolName(connectorId: string, operationId: string): string;
+export function renderWebsiteOperation(definition: unknown, operationId: string, rawArguments: unknown): {
+  definition: WebsiteConnectorDefinition;
+  operation: WebsiteConnectorOperation;
+  request: { body?: unknown; headers: Record<string, string>; method: string; responseMode: "auto" | "json" | "text"; url: string };
+};
+export function websiteConnectorRuntimeDescriptor(): WebsiteConnectorRuntimeDescriptor;
+export function requiredWebsiteConnectorCapabilities(definition: unknown): string[];
+export function assertWebsiteConnectorRuntimeCompatibility(
+  definition: unknown,
+  descriptor?: WebsiteConnectorRuntimeDescriptor
+): { definition: WebsiteConnectorDefinition; descriptor: WebsiteConnectorRuntimeDescriptor };
+export function executeWebsiteConnectorOperation(
+  definition: unknown,
+  operationId: string,
+  args: unknown,
+  options?: {
+    fetchImpl?: typeof fetch;
+    readOnlyOnly?: boolean;
+    runtimeDescriptor?: WebsiteConnectorRuntimeDescriptor;
+    storageState?: WebsiteConnectorBrowserStorageState;
+    timeoutMs?: number;
+  }
+): Promise<unknown>;
+export function refreshWebsiteConnectorAuthentication(
+  definition: unknown,
+  storageState: WebsiteConnectorBrowserStorageState,
+  options?: {
+    fetchImpl?: typeof fetch;
+    now?: () => number;
+    timeoutMs?: number;
+  }
+): Promise<{ refreshed: boolean; storageState: WebsiteConnectorBrowserStorageState }>;
+export function browserStorageAuthenticated(
+  state: WebsiteConnectorBrowserStorageState,
+  auth: WebsiteConnectorAuth,
+  now?: number
+): boolean;
+export function sanitizeWebsiteConnectorOutput(value: unknown, storageState: WebsiteConnectorBrowserStorageState): unknown;