@inneranimalmedia/agentsam-sdk 2.6.9 → 2.6.11

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"
+}

package/docs/engineering/test-diagnostics/go-cli-test-hang-20261003.md

@@ -0,0 +1,49 @@
+# CLI `go.test.mjs` Hang Diagnostic
+
+Recorded: `2026-10-04T03:26:23.680511+00:00`
+
+Branch: `feat/work-suite-graduation-20261003`
+
+## Prior isolation
+
+The complete CLI file diagnostic found:
+
+- 20 CLI test files pass independently
+- `test/cli/go.test.mjs` alone exceeds 30 seconds
+- no other CLI test file times out
+
+## Force-exit diagnostic
+
+Result: **TIMEOUT**
+
+Duration: **15.02s**
+
+Diagnosis: **SPECIFIC_TEST_TIMEOUT**
+
+Node `--test-force-exit` was used only as a diagnostic.
+It is not an accepted permanent fix for the test suite.
+
+## Per-test isolation
+
+- PASS | 0.37s | discoverGoRuntime finds agentsam-go-worker without inventing a sibling
+- PASS | 0.24s | ensureProductContract refuses missing product roots instead of scaffolding siblings
+- PASS | 1.49s | buildGoProduct emits build receipt after go test/vet/build
+- PASS | 0.94s | agentsam go build --json exposes only portable build paths
+- TIMEOUT | 12.01s | agentsam go --cloudflare agentsam-go-worker --skip-deploy is idempotent
+- PASS | 0.48s | agentsam go status --json reports discovery
+
+## Active resource probe
+
+Not applicable for this diagnosis branch.
+
+## Acceptance
+
+The permanent correction must:
+
+- close/await resources created by the test or implementation
+- preserve GO/GOAP runtime behavior
+- preserve timeout/queue semantics
+- not add `--test-force-exit` to the normal test command
+- allow `node --test test/cli/go.test.mjs` to terminate normally
+- allow `npm run test:cli` to terminate normally
+- allow `npm run test:standard` to terminate normally

package/docs/engineering/test-diagnostics/go-skip-deploy-docker-fix.md

@@ -0,0 +1,90 @@
+# AgentSam Go `--skip-deploy` lifecycle fix
+
+## Symptom
+
+`npm run test:standard` appeared to hang during the CLI suite.
+
+File-level isolation identified:
+
+`test/cli/go.test.mjs`
+
+and test-level isolation identified:
+
+`agentsam go --cloudflare agentsam-go-worker --skip-deploy is idempotent`
+
+## Root cause
+
+This was not R2, D1, Wrangler, Cloudflare OAuth, or a remote
+registry request.
+
+The command stalled before the Go build began.
+
+`preflightToolchain({ requireDocker: false })` still executed:
+
+`docker info`
+
+and only ignored a failed Docker result after the command returned.
+
+On this development machine, `docker info` did not return while the
+Docker daemon was unavailable/stalled.
+
+Therefore the meaning of `requireDocker: false` was incorrect:
+
+Docker was logically optional but still physically executed.
+
+A second unconditional Docker probe also existed later inside
+`deployGoCloudflare()`.
+
+## Correct contract
+
+For:
+
+`agentsam go --cloudflare agentsam-go-worker --skip-deploy`
+
+the runtime may:
+
+- discover the AgentSam Go product
+- inspect Go/Wrangler tooling needed for local validation
+- run Go test/vet/build
+- probe the native Go runtime
+- write temporary/local build receipts
+- write local product validation evidence
+
+It must not:
+
+- execute Docker
+- build or inspect a container
+- resolve Cloudflare deployment identity
+- deploy with Wrangler
+- perform live deployment health probes
+- publish the official InnerAnimalMedia product registry
+- write product state to R2
+- perform a remote D1 product-registry upsert
+
+## Local storage behavior
+
+The test supplies a temporary `stateRoot`.
+
+Under `skipDeploy`, `deployGoCloudflare()` writes local validation
+receipt/product evidence into that supplied state root.
+
+The remote official registry lane remains isolated and reports:
+
+`self_host_registry_isolated`
+
+## Fix
+
+1. `preflightToolchain()` now accepts an injectable spawn authority.
+2. Docker is executed only when `requireDocker === true`.
+3. When Docker is unnecessary, the stable check result is:
+   `docker / ok / skipped:not-required`.
+4. `deployGoCloudflare()` independently skips its Docker probe when
+   `skipDeploy === true`.
+5. Regression tests throw immediately if either skip path attempts
+   to execute Docker or another deployment spawn.
+
+## Test-runner policy
+
+No `--test-force-exit` workaround is used.
+
+The code must terminate naturally with all lifecycle boundaries intact.

package/docs/knowledge-service-verification.md

@@ -10,12 +10,12 @@ command from the isolated worktree, invoked as `node src/cli.js dockerize`:
 
 ```sh
 node src/cli.js dockerize --type knowledge_service --name agentsam-knowledge \
-  --repository sdk=/Users/samprimeaux/agentsam-sdk \
-  --repository app=/Users/samprimeaux/inneranimalmedia \
+  --repository sdk=repo://agentsam-sdk \
+  --repository app=repo://inneranimalmedia \
   --port 8792 --no-register-tag
 ```
 
-- Checkout: `/Users/samprimeaux/agent-worktrees/knowledge-service/agentsam-sdk`
+- Checkout: `worktree://knowledge-service/agentsam-sdk`
 - Container/image: `agentsam-knowledge` / `agentsam-knowledge:7c108871c3`
 - API: `http://127.0.0.1:8792`; authenticated routes; `/healthz` reports liveness
 - Data: named Docker volume `agentsam-knowledge-data`