@inneranimalmedia/agentsam-sdk 2.6.10 → 2.6.12

package/docs/engineering/provider-internal-renames/01a-runtime-environment-contract.md

@@ -0,0 +1,115 @@
+        # Runtime Environment Contract
+
+        Schema: `agentsam.runtime-environment-contract.v1`
+
+        Status: **APPROVED / PROTECTED**
+
+        ## Meaning of "safe"
+
+        These runtime bindings are known-good parts of the existing
+        AgentSam / Local Studio environment contract.
+
+        "Safe" means:
+
+        - preserve the binding name
+        - preserve its existing environment value
+        - preserve Variable vs Secret classification
+        - allow existing Production / Previews / Base wiring to continue
+        - do not reinterpret the name during internal provider refactors
+
+        It does **not** mean secret values are public.
+
+        Secret values must remain encrypted and must never be written into
+        this repository, logs, frontend state, query parameters, generated
+        documentation, test snapshots, or Git diffs.
+
+        ## Approved runtime variables
+
+        - `CLOUDFLARE_ACCOUNT_ID`
+- `GITHUB_APP_ID`
+- `GITHUB_CLIENT_ID`
+- `GOOGLE_CLIENT_ID`
+- `GOOGLE_DESKTOP_CLIENT_ID`
+- `IAM_CLIENT_ID`
+- `IAM_OAUTH_ISSUER`
+
+        ## Approved runtime secrets
+
+        - `AGENTSAM_API_KEY`
+- `AGENTSAM_BRIDGE_KEY`
+- `CLOUDFLARE_API_TOKEN`
+- `CLOUDFLARE_BREAK_GLASS_ADMIN_TOKEN`
+- `CLOUDFLARE_OAUTH_CLIENT_ID`
+- `CURSOR_API_KEY`
+- `GEMINI_API_KEY`
+- `GITHUB_APP_PRIVATE_KEY`
+- `GITHUB_CLIENT_SECRET`
+- `GITHUB_WEBHOOK_SECRET`
+- `GOOGLE_CLIENT_SECRET`
+- `GOOGLE_DESKTOP_CLIENT_SECRET`
+- `IAM_CLIENT_SECRET`
+- `OPENAI_API_KEY`
+- `VAULT_MASTER_KEY`
+
+        ## Refactor protection
+
+        Internal provider abbreviations are implementation-path vocabulary:
+
+        - `cfoa`
+        - `gclioa`
+        - `goaude`
+        - `gdrv`
+
+        They MUST NOT cause environment variables such as:
+
+        - `CLOUDFLARE_ACCOUNT_ID`
+        - `CLOUDFLARE_API_TOKEN`
+        - `CLOUDFLARE_OAUTH_CLIENT_ID`
+        - `GOOGLE_CLIENT_ID`
+        - `GOOGLE_CLIENT_SECRET`
+        - `GOOGLE_DESKTOP_CLIENT_ID`
+        - `GOOGLE_DESKTOP_CLIENT_SECRET`
+
+        to be renamed.
+
+        Environment-variable names are runtime contracts, not implementation
+        filenames.
+
+        ## Existing `.env` / deployment behavior
+
+        Preserve the working runtime environment pattern.
+
+        This lane does not require moving, deleting, rotating, renaming, or
+        changing the values of these bindings.
+
+        Environment-specific values remain managed by their existing runtime
+        environment / secret-management authority.
+
+        ## OAuth boundary
+
+        Provider implementation-file cleanup does not redesign authentication.
+
+        Existing Google, Google Desktop, Cloudflare, IAM, GitHub, AgentSam,
+        bridge, Vault, and model-provider credentials retain their current
+        runtime authority.
+
+        Portable UI packages must consume server/native capability adapters.
+        They must not ingest these secrets directly.
+
+        ## Environments
+
+        Approved contract scopes:
+
+        - Production
+        - Previews
+        - Base
+
+        A later deployment hardening pass may intentionally vary whether a
+        particular credential is populated in each environment, but that is
+        separate from this mechanical rename lane.
+
+        ## Values
+
+        Actual runtime values are intentionally omitted from this document.
+
+        The repository records the contract, not the credentials.

package/docs/engineering/provider-internal-renames/02-cfoa.md

@@ -0,0 +1,57 @@
+        # Stage 02 — Cloudflare OAuth Internal Directory
+
+        ## Change
+
+        Renamed:
+
+        `packages/connectors/cloudflare/`
+        → `packages/connectors/cfoa/`
+
+        `cfoa` means **Cloudflare OAuth**.
+
+        ## Scope
+
+        This stage changes implementation filesystem naming only.
+
+        It does **not** rename:
+
+        - runtime provider ID `cloudflare`
+        - Cloudflare OAuth routes
+        - Cloudflare API URLs
+        - environment variables
+        - D1/R2 scope strings
+        - D1/R2 provider IDs
+        - persisted connection/provider values
+        - public package names
+
+        ## Rewritten tracked references
+
+        - `apps/agentsamd/agentsam.package.json`
+- `apps/local-studio/backend/worker/cloudflare-code-mode.js`
+- `apps/local-studio/backend/worker/connections-registry.js`
+- `apps/local-studio/backend/worker/database-service.js`
+- `apps/local-studio/backend/worker/index.js`
+- `apps/local-studio/backend/worker/plugin-registry.js`
+- `apps/local-studio/package-lock.json`
+- `docs/SOURCE_ARCHITECTURE.md`
+- `docs/engineering/provider-internal-renames/README.md`
+- `package-lock.json`
+- `package.json`
+- `packages/agentsam-knowledge/src/backends/index.js`
+- `packages/connectors/cfoa/package.json`
+- `packages/identity/src/oauth/credentials.js`
+- `scripts/verify-package.mjs`
+- `src/commands/cloudflare-login.js`
+- `src/commands/cloudflare.js`
+- `src/commands/connections.js`
+- `src/lib/deploy/local-studio.js`
+- `src/lib/whoami-capabilities.js`
+- `src/mcp/cloudflare-bundles.js`
+- `test/cloudflare-connector.test.mjs`
+- `test/local-studio-deploy.test.mjs`
+
+        ## Architecture
+
+        Cloudflare authentication remains a host/provider authority.
+        Portable Work/content UI packages consume capability-bearing
+        adapters and must not own OAuth tokens themselves.

package/docs/engineering/provider-internal-renames/03-gclioa.md

@@ -0,0 +1,32 @@
+        # Stage 03 — Google CLI OAuth Internal Filename
+
+        ## Change
+
+        Renamed:
+
+        `apps/local-studio/backend/worker/google-cli-cloud.js`
+        → `apps/local-studio/backend/worker/gclioa.js`
+
+        `gclioa` means **Google CLI OAuth**.
+
+        ## Important boundary
+
+        This stage intentionally does not globally replace the string
+        `google-cli-cloud`.
+
+        Any external OAuth route, callback identifier, protocol value,
+        persisted value, or API contract retains its existing name.
+
+        Only the implementation filename and module references were
+        mechanically revised.
+
+        ## Tracked files rewritten
+
+        - `apps/local-studio/backend/worker/index.js`
+- `docs/engineering/provider-internal-renames/README.md`
+
+        ## Auth authority
+
+        This remains the existing Google CLI/cloud OAuth lane. No new
+        credential store, identity system, or frontend token transport
+        is introduced.

package/docs/engineering/provider-internal-renames/04-goaude.md

@@ -0,0 +1,50 @@
+        # Stage 04 — Google Desktop OAuth Exchange Internals
+
+        ## Change
+
+        Renamed the two implementation files representing the desktop
+        Google OAuth/native handoff lane:
+
+        `apps/local-studio/backend/worker/google-desktop-exchange.js`
+        → `apps/local-studio/backend/worker/goaude.js`
+
+        `packages/identity/src/oauth/google-desktop-exchange.js`
+        → `packages/identity/src/oauth/goaude.js`
+
+        `goaude` is the compact internal name for the Google OAuth
+        desktop/dashboard exchange implementation.
+
+        ## Preserved behavior
+
+        The existing desktop PKCE/native OAuth architecture remains
+        unchanged.
+
+        This stage does not rename or redesign:
+
+        - OAuth callback URLs
+        - native deep-link protocols
+        - PKCE semantics
+        - native handoff records
+        - IAM session semantics
+        - Google provider identity
+        - browser-to-native exchange behavior
+
+        ## Tracked references revised
+
+        - `apps/local-studio/backend/worker/goaude.js`
+- `apps/local-studio/backend/worker/index.js`
+- `apps/local-studio/scripts/google-desktop-exchange.test.mjs`
+- `apps/local-studio/scripts/smoke-desktop-auth.mjs`
+- `docs/engineering/provider-internal-renames/README.md`
+- `package.json`
+- `packages/identity/src/index.js`
+- `packages/identity/src/oauth/README.md`
+- `packages/identity/src/server/worker-router.js`
+- `packages/identity/tests/google-desktop-identity-login.test.mjs`
+- `packages/identity/tests/oauth-presets-accounts-ssot.test.mjs`
+
+        ## SDK law
+
+        Installed Local Studio remains independently usable. Desktop
+        Google OAuth must continue through its existing native/PKCE
+        authority rather than depending on a hosted-only Work UI flow.

package/docs/engineering/provider-internal-renames/05-gdrv.md

@@ -0,0 +1,33 @@
+        # Stage 05 — Google Drive Provider Internal Filename
+
+        ## Change
+
+        Renamed:
+
+        `packages/agentsam-content/src/providers/google-drive.ts`
+        → `packages/agentsam-content/src/providers/gdrv.ts`
+
+        `gdrv` is only the implementation filename.
+
+        ## Runtime identity remains unchanged
+
+        The provider/source identifier remains:
+
+        `google-drive`
+
+        This matters because Work routing, library metadata, provider
+        registries, persisted records, capability resolution, analytics,
+        and external integrations may depend on that stable semantic ID.
+
+        ## Tracked module/path references revised
+
+        - `docs/engineering/provider-internal-renames/README.md`
+- `packages/agentsam-content/src/providers/index.ts`
+
+        ## Future Work integration
+
+        The Work product should consume this provider through the
+        `agentsam-content` contract.
+
+        Work must not directly acquire Google OAuth credentials or keep
+        provider tokens in React/frontend state.

package/docs/engineering/provider-internal-renames/06-verification.md

@@ -0,0 +1,103 @@
+# Stage 06 — Provider Internal Rename Verification
+
+Verified: `2026-10-04T04:04:40.116058+00:00`
+
+Branch: `feat/work-suite-graduation-20261003`
+
+Verified implementation HEAD before this documentation commit:
+
+`eae86e57`
+
+Status: **PASS**
+
+## Scope
+
+This verification closes the provider-internal filesystem/module
+rename lane.
+
+The following are internal implementation abbreviations only:
+
+- `cfoa` — Cloudflare OAuth internals
+- `gclioa` — Google CLI OAuth internals
+- `goaude` — Google desktop/native OAuth exchange internals
+- `gdrv` — Google Drive provider implementation internals
+
+They do not replace public provider names, persisted provider IDs,
+OAuth route semantics, API URLs, capability names, environment
+variables, or user-facing provider vocabulary.
+
+## Verified paths
+
+Present:
+
+- `packages/connectors/cfoa/`
+- `apps/local-studio/backend/worker/gclioa.js`
+- `apps/local-studio/backend/worker/goaude.js`
+- `packages/identity/src/oauth/goaude.js`
+- `packages/agentsam-content/src/providers/gdrv.ts`
+
+Retired physical implementation paths are absent.
+
+Historical migration documentation may intentionally mention old
+paths in order to preserve old → new provenance.
+
+Active source/config/test/package references may not use them.
+
+## Runtime environment contract
+
+Protected runtime entries:
+
+- variables: **7**
+- secrets: **15**
+- total: **22**
+
+Runtime names and current value authority are preserved.
+
+Internal abbreviations are prohibited from becoming environment
+prefixes such as:
+
+- `CFOA_*`
+- `GCLIOA_*`
+- `GOAUDE_*`
+- `GDRV_*`
+
+Secret values were not read, printed, serialized, or committed by
+this verification.
+
+## GO lifecycle regression
+
+The lane also contains the bounded lifecycle correction discovered
+while running the verification suite:
+
+`fix(go): honor skip-deploy toolchain boundary`
+
+`--skip-deploy` now avoids Docker execution when Docker is not
+required, including the preflight path.
+
+Regression tests enforce that boundary.
+
+## Test gate
+
+Immediately prior to this closeout, the repository's standard gate
+completed successfully:
+
+`npm run test:standard`
+
+Result:
+
+- standard smoke/unit/CLI/integration/terminal sequence completed
+- integration/mock summary: 296 tests, 294 pass, 0 fail, 2 skipped
+- terminal/mock summary: 3 tests, 3 pass, 0 fail
+- overall command returned successfully to the shell
+
+Skipped tests are not failures.
+
+## Acceptance
+
+Provider-internal rename work is complete and verified.
+
+This closes the mechanical rename lane.
+
+Subsequent work—AgentSam Go deployment portability, Work Suite
+graduation, browser/public Explore work, and other feature lanes—
+should be performed as separate chronological changes.

package/docs/engineering/provider-internal-renames/README.md

@@ -0,0 +1,77 @@
+# Provider Internal Rename Lane
+
+Branch: `feat/work-suite-graduation-20261003`
+
+## Purpose
+
+This lane performs mechanical internal path cleanup before the
+Work Suite graduation begins.
+
+It intentionally separates internal implementation names from
+externally meaningful provider identities.
+
+## Planned internal names
+
+| Existing path | Internal path |
+| --- | --- |
+| `packages/connectors/cfoa/` | `packages/connectors/cfoa/` |
+| `apps/local-studio/backend/worker/gclioa.js` | `apps/local-studio/backend/worker/gclioa.js` |
+| `apps/local-studio/backend/worker/goaude.js` | `apps/local-studio/backend/worker/goaude.js` |
+| `packages/identity/src/oauth/goaude.js` | `packages/identity/src/oauth/goaude.js` |
+| `packages/agentsam-content/src/providers/gdrv.ts` | `packages/agentsam-content/src/providers/gdrv.ts` |
+
+Mnemonics:
+
+- `cfoa` = Cloudflare OAuth
+- `gclioa` = Google CLI OAuth
+- `goaude` = Google OAuth desktop/dashboard exchange
+- `gdrv` = Google Drive provider implementation
+
+## Hard boundaries
+
+These changes MUST NOT rename external/runtime contracts merely
+because their names contain Google or Cloudflare.
+
+Preserve:
+
+- provider IDs such as `cloudflare`
+- provider IDs such as `google`
+- source IDs such as `google-drive`
+- R2 / D1 capability identifiers
+- OAuth callback URLs
+- API route URLs
+- Google API URLs
+- Cloudflare API URLs
+- environment-variable names
+- persisted provider/database values
+- public SDK package names and APIs unless separately approved
+
+## Authentication authority
+
+This rename is not an authentication redesign.
+
+Existing authorities remain authoritative:
+
+- hosted Google OAuth
+- Google desktop / installed-app PKCE
+- Google CLI/cloud OAuth
+- Cloudflare OAuth
+- Local Studio hosted identity/session infrastructure
+- Local Studio desktop native identity/session infrastructure
+- provider capability grants and persisted connection records
+
+UI packages must never become credential stores.
+
+`@inneranimalmedia/agentsam-work` consumes capability-bearing host
+adapters. It does not own Google or Cloudflare authentication.
+
+## Change sequence
+
+01. Establish clean worktree and trace documentation.
+02. Rename Cloudflare connector implementation directory.
+03. Rename Google CLI OAuth implementation file.
+04. Rename Google desktop OAuth exchange implementation files.
+05. Rename Google Drive provider implementation file.
+06. Run contract/reference verification and tests.
+
+Feature work begins only after this mechanical lane is green.

package/docs/engineering/provider-internal-renames/runtime-environment-contract.json

@@ -0,0 +1,220 @@
+{
+  "allowed_environments": [
+    "production",
+    "previews",
+    "base"
+  ],
+  "entries": {
+    "AGENTSAM_API_KEY": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "AGENTSAM_BRIDGE_KEY": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "CLOUDFLARE_ACCOUNT_ID": {
+      "approved": true,
+      "classification": "protected-runtime-variable",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "variable"
+    },
+    "CLOUDFLARE_API_TOKEN": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "CLOUDFLARE_BREAK_GLASS_ADMIN_TOKEN": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "CLOUDFLARE_OAUTH_CLIENT_ID": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "CURSOR_API_KEY": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "GEMINI_API_KEY": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "GITHUB_APP_ID": {
+      "approved": true,
+      "classification": "protected-runtime-variable",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "variable"
+    },
+    "GITHUB_APP_PRIVATE_KEY": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "GITHUB_CLIENT_ID": {
+      "approved": true,
+      "classification": "protected-runtime-variable",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "variable"
+    },
+    "GITHUB_CLIENT_SECRET": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "GITHUB_WEBHOOK_SECRET": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "GOOGLE_CLIENT_ID": {
+      "approved": true,
+      "classification": "protected-runtime-variable",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "variable"
+    },
+    "GOOGLE_CLIENT_SECRET": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "GOOGLE_DESKTOP_CLIENT_ID": {
+      "approved": true,
+      "classification": "protected-runtime-variable",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "variable"
+    },
+    "GOOGLE_DESKTOP_CLIENT_SECRET": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "IAM_CLIENT_ID": {
+      "approved": true,
+      "classification": "protected-runtime-variable",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "variable"
+    },
+    "IAM_CLIENT_SECRET": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "IAM_OAUTH_ISSUER": {
+      "approved": true,
+      "classification": "protected-runtime-variable",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "variable"
+    },
+    "OPENAI_API_KEY": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    },
+    "VAULT_MASTER_KEY": {
+      "approved": true,
+      "classification": "protected-runtime-secret",
+      "may_commit_value": false,
+      "may_log_value": false,
+      "preserve_existing_value": true,
+      "preserve_name": true,
+      "type": "secret"
+    }
+  },
+  "prohibited_refactor_behavior": [
+    "rename environment variable",
+    "convert provider environment variable to internal abbreviation",
+    "commit runtime value into repository",
+    "print secret value during migration or verification",
+    "move secret into frontend/browser state",
+    "move secret into query parameters",
+    "move secret into localStorage/sessionStorage",
+    "replace existing runtime authority with package-specific credential storage"
+  ],
+  "purpose": "Protect known-good Local Studio / AgentSam runtime environment variable and secret names during provider-internal refactors.",
+  "schema": "agentsam.runtime-environment-contract.v1",
+  "status": "approved"
+}