@inneranimalmedia/agentsam-sdk 2.6.0 → 2.6.2

package/packages/identity/src/contracts/auth-config.js

@@ -1,20 +1,9 @@
 /**
  * Canonical AgentSam identity/auth environment contract.
  *
- * The SDK owns these public names. Host applications consume this contract and
- * may provide storage/verification adapters without inventing competing aliases.
- *
- * Canonical variables:
- *   IAM_OAUTH_ISSUER      public authorization-server authority (issuer)
- *   IAM_CLIENT_ID         OAuth client id
- *   IAM_CLIENT_SECRET     OAuth client secret
- *   IAM_ORIGIN            deprecated alias of IAM_OAUTH_ISSUER (migration window)
- *   AGENTSAM_SDK_KEY      account/delegated sdk_* bearer
- *   AGENTSAM_BRIDGE_KEY   machine/integration credential
- *
- * Migration-only fallbacks:
- *   IAM_ORIGIN            -> IAM_OAUTH_ISSUER
- *   AGENTSAM_SDK_TOKEN    -> AGENTSAM_SDK_KEY
+ * Browser login sessions and reusable API credentials are intentionally
+ * separate: login sessions are opaque, machine-local session state while
+ * AGENTSAM_API_KEY is an explicit delegated account credential.
  */
 
 export const DEFAULT_IAM_OAUTH_ISSUER = 'https://inneranimalmedia.com';
@@ -26,17 +15,12 @@ export const AGENTSAM_AUTH_ENV = Object.freeze({
   iamOrigin: 'IAM_ORIGIN',
   iamClientId: 'IAM_CLIENT_ID',
   iamClientSecret: 'IAM_CLIENT_SECRET',
-  sdkKey: 'AGENTSAM_SDK_KEY',
+  apiKey: 'AGENTSAM_API_KEY',
   bridgeKey: 'AGENTSAM_BRIDGE_KEY',
 });
 
-export const AGENTSAM_AUTH_LEGACY_ENV = Object.freeze({
-  iamOrigin: 'IAM_ORIGIN',
-  sdkKey: 'AGENTSAM_SDK_TOKEN',
-});
-
 export const AGENTSAM_AUTH_CONTRACT = Object.freeze({
-  version: 1,
+  version: 2,
   authority: 'agentsam-sdk',
   iam: Object.freeze({
     issuer: AGENTSAM_AUTH_ENV.iamIssuer,
@@ -44,24 +28,23 @@ export const AGENTSAM_AUTH_CONTRACT = Object.freeze({
     clientId: AGENTSAM_AUTH_ENV.iamClientId,
     clientSecret: AGENTSAM_AUTH_ENV.iamClientSecret,
   }),
-  sdk: Object.freeze({
-    env: AGENTSAM_AUTH_ENV.sdkKey,
-    tokenPrefix: 'sdk_',
+  apiKey: Object.freeze({
+    env: AGENTSAM_AUTH_ENV.apiKey,
+    tokenPrefix: 'aak_',
     authorizationScheme: 'Bearer',
     subject: 'account/delegated',
-    durableStore: 'agentsam_sdk_tokens',
+    durableStore: 'agentsam_api_credentials',
+  }),
+  browserSession: Object.freeze({
+    storage: '~/.agentsam/auth/session.json',
+    subject: 'interactive/user',
+    reusableApiCredential: false,
   }),
   bridge: Object.freeze({
     env: AGENTSAM_AUTH_ENV.bridgeKey,
     subject: 'machine/integration',
-    sdkTokenType: 'integration',
     userAuth: false,
   }),
-  compatibility: Object.freeze({
-    iamOriginFallback: AGENTSAM_AUTH_LEGACY_ENV.iamOrigin,
-    iamIssuerCanonical: AGENTSAM_AUTH_ENV.iamIssuer,
-    sdkKeyFallback: AGENTSAM_AUTH_LEGACY_ENV.sdkKey,
-  }),
 });
 
 function clean(value) {
@@ -84,24 +67,24 @@ export function resolveIamOrigin(env = {}, explicit = '') {
   return resolveIamIssuer(env, explicit);
 }
 
-/** Resolve account/delegated SDK bearer; canonical name wins over legacy. */
-export function resolveSdkKey(env = {}, explicit = '') {
-  return clean(explicit || env?.AGENTSAM_SDK_KEY || env?.AGENTSAM_SDK_TOKEN);
+/** Resolve the reusable delegated account API credential. */
+export function resolveApiKey(env = {}, explicit = '') {
+  return clean(explicit || env?.AGENTSAM_API_KEY);
 }
 
-/** Resolve machine/integration bridge credential. No user-SDK alias is accepted. */
+/** Resolve machine/integration bridge credential. No account API-key alias is accepted. */
 export function resolveBridgeKey(env = {}, explicit = '') {
   return clean(explicit || env?.AGENTSAM_BRIDGE_KEY);
 }
 
-export function isSdkKey(value) {
-  return clean(value).startsWith(AGENTSAM_AUTH_CONTRACT.sdk.tokenPrefix);
+export function isApiKey(value) {
+  return clean(value).startsWith(AGENTSAM_AUTH_CONTRACT.apiKey.tokenPrefix);
 }
 
-/** Build the public bearer header for an SDK key. */
-export function buildSdkAuthorizationHeaders(key, headers = {}) {
+/** Build the public bearer header for an AgentSam account API key. */
+export function buildApiAuthorizationHeaders(key, headers = {}) {
   const resolved = clean(key);
-  if (!isSdkKey(resolved)) throw new Error('AGENTSAM_SDK_KEY_required');
+  if (!isApiKey(resolved)) throw new Error('AGENTSAM_API_KEY_required');
   return {
     ...headers,
     Authorization: `Bearer ${resolved}`,

package/packages/identity/tests/auth-config.test.mjs

@@ -2,10 +2,10 @@ import assert from 'node:assert/strict';
 import { describe, it } from 'node:test';
 import {
   AGENTSAM_AUTH_CONTRACT,
-  buildSdkAuthorizationHeaders,
+  buildApiAuthorizationHeaders,
+  resolveApiKey,
   resolveBridgeKey,
   resolveIamOrigin,
-  resolveSdkKey,
 } from '../src/contracts/auth-config.js';
 
 describe('auth configuration contract', () => {
@@ -20,42 +20,33 @@ describe('auth configuration contract', () => {
   });
 
   it('accepts IAM_ORIGIN as migration-only fallback', () => {
-    assert.equal(
-      resolveIamOrigin({ IAM_ORIGIN: 'https://legacy.example.test/' }),
-      'https://legacy.example.test',
-    );
+    assert.equal(resolveIamOrigin({ IAM_ORIGIN: 'https://legacy.example.test/' }), 'https://legacy.example.test');
   });
 
   it('defaults issuer when neither IAM_OAUTH_ISSUER nor IAM_ORIGIN exists', () => {
     assert.equal(resolveIamOrigin({}), 'https://inneranimalmedia.com');
   });
 
-  it('prefers AGENTSAM_SDK_KEY over AGENTSAM_SDK_TOKEN', () => {
-    assert.equal(
-      resolveSdkKey({
-        AGENTSAM_SDK_KEY: 'sdk_new',
-        AGENTSAM_SDK_TOKEN: 'sdk_old',
-      }),
-      'sdk_new',
-    );
-    assert.equal(resolveSdkKey({ AGENTSAM_SDK_TOKEN: 'sdk_old' }), 'sdk_old');
+  it('resolves only AGENTSAM_API_KEY for delegated account API auth', () => {
+    assert.equal(resolveApiKey({ AGENTSAM_API_KEY: 'aak_new' }), 'aak_new');
+    assert.equal(resolveApiKey({ AGENTSAM_SDK_KEY: 'sdk_old' }), '');
+    assert.equal(AGENTSAM_AUTH_CONTRACT.apiKey.durableStore, 'agentsam_api_credentials');
   });
 
-  it('never aliases bridge machine trust to a user SDK key', () => {
+  it('never aliases bridge machine trust to an account API key', () => {
     assert.equal(
-      resolveBridgeKey({ AGENTSAM_BRIDGE_KEY: 'bridge_machine', AGENTSAM_SDK_KEY: 'sdk_user' }),
+      resolveBridgeKey({ AGENTSAM_BRIDGE_KEY: 'bridge_machine', AGENTSAM_API_KEY: 'aak_user' }),
       'bridge_machine',
     );
-    assert.equal(resolveBridgeKey({ AGENTSAM_SDK_KEY: 'sdk_user' }), '');
+    assert.equal(resolveBridgeKey({ AGENTSAM_API_KEY: 'aak_user' }), '');
     assert.equal(AGENTSAM_AUTH_CONTRACT.bridge.userAuth, false);
-    assert.equal(AGENTSAM_AUTH_CONTRACT.bridge.sdkTokenType, 'integration');
   });
 
-  it('builds Bearer authorization only for sdk_ keys', () => {
-    assert.deepEqual(buildSdkAuthorizationHeaders('sdk_abc', { Accept: 'application/json' }), {
+  it('builds Bearer authorization only for aak_ API keys', () => {
+    assert.deepEqual(buildApiAuthorizationHeaders('aak_abc', { Accept: 'application/json' }), {
       Accept: 'application/json',
-      Authorization: 'Bearer sdk_abc',
+      Authorization: 'Bearer aak_abc',
     });
-    assert.throws(() => buildSdkAuthorizationHeaders('bridge_machine'), /AGENTSAM_SDK_KEY_required/);
+    assert.throws(() => buildApiAuthorizationHeaders('bridge_machine'), /AGENTSAM_API_KEY_required/);
   });
 });

package/protocol/COMPANY_REPOSITORY_GRAPH_V1.md

@@ -0,0 +1,91 @@
+# AgentSam Company Repository Graph v1
+
+This protocol defines the portable vocabulary for company-wide repository identity, public contracts, dependency edges, and Merkle evidence. It does not make the SDK a global database.
+
+## Authority split
+
+- `agentsam-sdk` defines schemas, enums, builders, Merkle formats, and receipt semantics.
+- The authenticated host owns `account_id` and persists the operational graph.
+- `code_repositories` is the canonical repository registry.
+- `agentsam_repository_contracts` records what a repository provides.
+- `agentsam_repository_dependencies` records what a repository consumes and the policy attached to that edge.
+- `agentsam_fs_merkle_snapshots` indexes exact repository states; full manifests may live in object storage.
+- Deployment and deployment-health tables record whether a source state reached production and whether it remains healthy.
+- MCP may expose graph queries; ExecOS may emit execution evidence. Neither becomes the ownership authority.
+
+## Ownership law
+
+Persisted company graph records use `account_id` as ownership SSOT. `tenant_id`, `workspace_id`, `user_id`, and `owner_user_id` are not part of this protocol.
+
+Portable repository identity is deliberately different: a checked-in repository identity must not embed an account identifier. The host binds its stable `repository_id` to an authenticated `account_id` in the registry.
+
+## Canonical repository identity
+
+A Git remote is evidence, not authority. The SDK must not derive the canonical `repository_id` from `owner/repo`, a checkout path, a workspace, or a provider URL. Persistence callers provide the `repository_id` from the host registry.
+
+## Graph levels
+
+```text
+code_repositories
+  repository identity / company role
+        |
+        +-- agentsam_repository_contracts
+        |     what this repository provides
+        |
+        +-- agentsam_repository_dependencies
+              what this repository consumes
+                    |
+                    +-- Merkle / AST / Git evidence
+                    |
+                    +-- deployments / deployment health
+```
+
+`codebase_dep_edges` remains an intra-repository code graph. `agentsam_repository_dependencies` is a cross-repository company graph. They are not interchangeable.
+
+## Contract records
+
+Contract types are:
+
+`api | schema | runtime | cli | event | receipt | package`
+
+Statuses are:
+
+`active | deprecated | retired`
+
+A contract record carries a stable `contract_key`, explicit version, manifest path when one exists, and `contract_hash`. The hash is the semantic identity consumers can pin independently of a Git branch name.
+
+## Dependency records
+
+Dependency types are:
+
+`runtime | build | contract | package | deploy | tool | data`
+
+Criticality is:
+
+`informational | compatible | strict | critical`
+
+Failure policy is:
+
+`warn | block_certification | block_deploy | degrade`
+
+The dependency graph supplies the meaning a Merkle tree cannot infer by itself: who consumes a changed contract and what should happen if the requirement is violated.
+
+## Merkle persistence v2
+
+Company persistence uses:
+
+```text
+account_id + repository_id + snapshot_id
+```
+
+Object keys are:
+
+```text
+agentsam_fs_merkle_snapshots/<account_id>/<repository_id>/<snapshot_id>.json
+```
+
+The content root, metadata root, and policy hash remain separate authorities. A future contract/dependency aggregate root may be layered above these records without changing the content Merkle format.
+
+## Certification
+
+Version 1 intentionally does not require a separate certifications table. A host can derive an initial certification decision from repository identity, contract hashes, dependency requirements, Merkle roots, verification results, deployments, and deployment health. A persistent certification ledger can be added when there is a real need to preserve compatibility statements across an exact set of repository roots.

package/protocol/MERKLE_PERSISTENCE_V1.md

@@ -1,5 +1,7 @@
 # AgentSam Merkle Persistence v1
 
+> Superseded for current company persistence by `MERKLE_PERSISTENCE_V2.md`. V1 is retained only as the historical contract shipped before the account/repository hard cut.
+
 Persistence is a host concern layered on top of the portable Merkle protocol. The SDK exposes the canonical table name, storage prefix, logical asset binding, storage-key helper, and portable SQL schema without owning a customer's database or cloud credentials.
 
 ## Authority split

package/protocol/MERKLE_PERSISTENCE_V2.md

@@ -0,0 +1,40 @@
+# AgentSam Merkle Persistence v2
+
+Persistence is a host concern layered on top of the portable Merkle protocol. Version 2 hard-cuts persisted ownership to `account_id + repository_id` and removes user/workspace/tenant ownership aliases.
+
+## Authority split
+
+```text
+root_hash       = filesystem/content authority
+metadata_root   = semantic/index authority
+policy_hash     = capture-scope authority
+account_id      = authenticated ownership authority
+repository_id   = canonical repository-registry identity
+```
+
+A checkout path, workspace, or user identity must never become `repository_id`. For registered Git repositories, the SDK may derive the canonical provider identity directly from the Git remote (for example `github:owner/repo`), matching the `code_repositories.id` convention; local repositories may fall back to the committed project manifest.
+
+The optional searchable index table remains `agentsam_fs_merkle_snapshots`. Full manifests may be stored under the provider-neutral object prefix `agentsam_fs_merkle_snapshots/`.
+
+Typical keys are:
+
+```text
+agentsam_fs_merkle_snapshots/<account_id>/<repository_id>/<snapshot_id>.json
+```
+
+The hosting application chooses physical storage and database bindings. The SDK never owns cloud credentials and never invents account or repository authority.
+
+## CLI publication
+
+```sh
+agentsam login
+agentsam merkle snapshot . --semantic --out .agentsam/merkle.json
+agentsam merkle persist .agentsam/merkle.json \
+  --wrangler-config path/to/wrangler.toml \
+  --capture-kind deploy \
+  --deployment-id "$DEPLOYMENT_ID"
+```
+
+The CLI reads `account_id` from the authenticated local AgentSam session and resolves `repository_id` from Git/provider identity, with the committed project manifest as fallback for local repositories. Programmatic hosts still pass authenticated `account_id + repository_id` directly to `buildMerklePersistencePlan`. For non-deploy captures, execution provenance remains required through a connection or runtime lease. `--dry-run` emits the exact storage/index plan without writes; `--r2-only` uploads the manifest without a D1 index write.
+
+Version 1 used `owner_user_id` / `repo_id` and is superseded for current company persistence.

package/protocol/repository/repository-contract.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/repository/repository-contract.schema.json",
+  "title": "AgentSam Repository Contract Record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "account_id", "repository_id", "contract_key", "contract_version", "contract_type", "name", "contract_hash", "status"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "account_id": { "type": "string", "minLength": 1 },
+    "repository_id": { "type": "string", "minLength": 1 },
+    "contract_key": { "type": "string", "minLength": 1 },
+    "contract_version": { "type": "string", "minLength": 1 },
+    "contract_type": { "enum": ["api", "schema", "runtime", "cli", "event", "receipt", "package"] },
+    "name": { "type": "string", "minLength": 1 },
+    "description": { "type": ["string", "null"] },
+    "manifest_path": { "type": ["string", "null"] },
+    "contract_hash": { "type": "string", "minLength": 1 },
+    "status": { "enum": ["active", "deprecated", "retired"] },
+    "created_at": { "type": ["integer", "null"], "minimum": 0 },
+    "updated_at": { "type": ["integer", "null"], "minimum": 0 }
+  }
+}

package/protocol/repository/repository-dependency.schema.json

@@ -0,0 +1,24 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/repository/repository-dependency.schema.json",
+  "title": "AgentSam Repository Dependency Record",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "id", "account_id", "source_repository_id", "target_repository_id", "dependency_type", "criticality", "failure_policy"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "id": { "type": "string", "minLength": 1 },
+    "account_id": { "type": "string", "minLength": 1 },
+    "source_repository_id": { "type": "string", "minLength": 1 },
+    "target_repository_id": { "type": "string", "minLength": 1 },
+    "dependency_type": { "enum": ["runtime", "build", "contract", "package", "deploy", "tool", "data"] },
+    "contract_id": { "type": ["string", "null"] },
+    "criticality": { "enum": ["informational", "compatible", "strict", "critical"] },
+    "required_version": { "type": ["string", "null"] },
+    "required_contract_hash": { "type": ["string", "null"] },
+    "failure_policy": { "enum": ["warn", "block_certification", "block_deploy", "degrade"] },
+    "description": { "type": ["string", "null"] },
+    "created_at": { "type": ["integer", "null"], "minimum": 0 },
+    "updated_at": { "type": ["integer", "null"], "minimum": 0 }
+  }
+}

package/protocol/repository/repository-identity.schema.json

@@ -0,0 +1,17 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://schemas.inneranimalmedia.com/agentsam/repository/repository-identity.schema.json",
+  "title": "AgentSam Repository Identity",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "repository_id", "full_name", "role", "default_branch", "status"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "repository_id": { "type": "string", "minLength": 1 },
+    "full_name": { "type": "string", "minLength": 1 },
+    "role": { "type": "string", "minLength": 1 },
+    "default_branch": { "type": "string", "minLength": 1 },
+    "canonical_url": { "type": ["string", "null"] },
+    "status": { "enum": ["active", "archived", "disabled"] }
+  }
+}

package/protocol/rpc/v1/common.proto

@@ -0,0 +1,16 @@
+syntax = "proto3";
+
+package agentsam.knowledge.v1;
+
+message JobId {
+  string value = 1;
+}
+
+message RepositoryRef {
+  string alias = 1;
+  string repository_id = 2;
+}
+
+message StringList {
+  repeated string values = 1;
+}

package/protocol/rpc/v1/errors.proto

@@ -0,0 +1,35 @@
+syntax = "proto3";
+
+package agentsam.knowledge.v1;
+
+// Numeric values intentionally match google.rpc.Code / gRPC canonical status codes.
+enum ErrorCode {
+  ERROR_CODE_OK = 0;
+  ERROR_CODE_CANCELLED = 1;
+  ERROR_CODE_UNKNOWN = 2;
+  ERROR_CODE_INVALID_ARGUMENT = 3;
+  ERROR_CODE_DEADLINE_EXCEEDED = 4;
+  ERROR_CODE_NOT_FOUND = 5;
+  ERROR_CODE_ALREADY_EXISTS = 6;
+  ERROR_CODE_PERMISSION_DENIED = 7;
+  ERROR_CODE_RESOURCE_EXHAUSTED = 8;
+  ERROR_CODE_FAILED_PRECONDITION = 9;
+  ERROR_CODE_ABORTED = 10;
+  ERROR_CODE_OUT_OF_RANGE = 11;
+  ERROR_CODE_UNIMPLEMENTED = 12;
+  ERROR_CODE_INTERNAL = 13;
+  ERROR_CODE_UNAVAILABLE = 14;
+  ERROR_CODE_DATA_LOSS = 15;
+  ERROR_CODE_UNAUTHENTICATED = 16;
+}
+
+message ErrorDetail {
+  ErrorCode code = 1;
+  string message = 2;
+  bool retryable = 3;
+  string reason = 4;
+  optional uint32 http_status = 5;
+  optional uint32 retry_after_ms = 6;
+  optional string provider = 7;
+  optional string provider_code = 8;
+}

package/protocol/rpc/v1/knowledge.proto

@@ -0,0 +1,77 @@
+syntax = "proto3";
+
+package agentsam.knowledge.v1;
+
+import "google/protobuf/timestamp.proto";
+import "common.proto";
+import "errors.proto";
+
+service KnowledgeService {
+  rpc ListRepositories(ListRepositoriesRequest) returns (ListRepositoriesResponse);
+  rpc SubmitJob(SubmitJobRequest) returns (Job);
+  rpc GetJob(GetJobRequest) returns (Job);
+  rpc WatchJob(WatchJobRequest) returns (stream JobEvent);
+}
+
+message ListRepositoriesRequest {}
+
+message ListRepositoriesResponse {
+  repeated RepositoryRef repositories = 1;
+  bool embeddings_enabled = 2;
+}
+
+enum JobOperation {
+  JOB_OPERATION_UNSPECIFIED = 0;
+  JOB_OPERATION_INDEX = 1;
+  JOB_OPERATION_PLAN = 2;
+  JOB_OPERATION_SEARCH = 3;
+}
+
+enum JobStatus {
+  JOB_STATUS_UNSPECIFIED = 0;
+  JOB_STATUS_QUEUED = 1;
+  JOB_STATUS_RUNNING = 2;
+  JOB_STATUS_COMPLETED = 3;
+  JOB_STATUS_FAILED = 4;
+}
+
+message SubmitJobRequest {
+  string repository = 1;
+  JobOperation operation = 2;
+  optional string scope = 3;
+  StringList include = 4;
+  StringList exclude = 5;
+  optional bool embed = 6;
+  optional bool semantic = 7;
+  optional string query = 8;
+  optional uint32 top_k = 9;
+  optional uint32 token_budget = 10;
+  optional string generation_id = 11;
+  optional uint32 max_inputs = 12;
+  optional uint32 max_characters = 13;
+  optional string idempotency_key = 14;
+}
+
+message GetJobRequest {
+  JobId job_id = 1;
+}
+
+message WatchJobRequest {
+  JobId job_id = 1;
+}
+
+message Job {
+  JobId id = 1;
+  JobStatus status = 2;
+  uint32 attempts = 3;
+  google.protobuf.Timestamp created_at = 4;
+  google.protobuf.Timestamp updated_at = 5;
+  string result_json = 6;
+  ErrorDetail failure = 7;
+}
+
+message JobEvent {
+  Job job = 1;
+  google.protobuf.Timestamp observed_at = 2;
+  uint64 sequence = 3;
+}