@inneranimalmedia/agentsam-sdk 2.6.10 → 2.6.11

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`