@atlanai/sdk 0.2.4 → 0.3.1

package/dist/raw/agent/models/AgentAgentArtifactView.d.ts

@@ -21,13 +21,31 @@ import type { AgentSyncState } from './AgentSyncState';
  */
 export interface AgentAgentArtifactView {
     /**
-     * Value of the `app` field.
+     * The extension that registered the kind.
+     *
+     * `#[serde(default)]` because the registry's **L1** view omits it: `registry_http::artifact`
+     * serves `l1_view` — deliberately kind-polymorphic, deliberately without an extension name —
+     * from ranked search and from archive. Without the default, `flatten` being a whitelist made
+     * the absence a hard decode failure, so *every* extension-scoped `POST …/search` and
+     * `POST …/{id}/archive` answered `500 unexpected registry response shape` the moment a row came
+     * back. Empty result sets decoded fine, which is why it read as working.
+     *
+     * The archive case was the worse of the two: the write had already committed, so the caller saw
+     * a 500 for a request that succeeded.
+     *
+     * Serialization skips it when empty rather than emitting `""`, so a typed view built from an L1
+     * row **omits** the field exactly as the registry's own L1 row does. A client that needs it for
+     * a search hit resolves it from `kind` through `GET /kinds`, which is the same lookup the
+     * registry would do.
+     *
+     * Named `extension` until `apps-2026-09-15-the-extension-tables-are-dropped`; renamed with no
+     * alias, matching the registry's own `ArtifactView`.
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
     app?: string;
     /**
-     * Value of the `artifact_status` field.
+     *
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
@@ -39,31 +57,57 @@ export interface AgentAgentArtifactView {
      */
     commitTs: string;
     /**
-     * Value of the `content_hash_hex` field.
+     * BLAKE3 (hex) of the canonicalised per-kind properties — the artifact's `ETag`, and the
+     * `If-Match` precondition's subject. Named `_hex` for the shipped contract's sake.
+     *
+     * `#[serde(default)]` for the same reason `extension` above has one, and this is the second
+     * time that reason has cost every extension its read surface. The registry types the field
+     * `Option<String>` and **omits** it when the row's `content_hash` is NULL
+     * (`registry_http::ArtifactView`), populating it straight from the nullable column; `flatten`
+     * is a whitelist, so a bare `String` here made that omission a hard decode failure — every
+     * `skill`, `mcp` and `agent` read answered `500 unexpected registry response shape` for a
+     * request the registry had served correctly, while the registry's own `/artifacts` surface
+     * kept working and made it read as an extension bug.
+     *
+     * The absence is legitimate, which is why the fix is here and not a backfill: no write path
+     * leaves the column NULL, but the spanner→postgres mover deliberately **invalidates** every
+     * migrated hash — Spanner hashed `sha256(jcs(metadata))` and this stack hashes
+     * `blake3(write_canonical(metadata))`, so a carried-over digest could never match a
+     * recomputation. A migrated artifact has no hash until its next property write recomputes
+     * one, so a caller that wants a conditional write against it sends `*` or no `If-Match`.
+     *
+     * Skipped on the way out rather than serialized as `null`, so a typed per-kind view renders
+     * exactly the shape the registry served.
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
     contentHashHex?: string;
     /**
-     * Value of the `created_at` field.
+     *
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
     createdAt: string;
     /**
-     * Value of the `created_by` field.
+     *
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
     createdBy: string;
     /**
-     * Human-readable description.
+     *
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
     description?: string;
     /**
-     * Human-readable name.
+     * Human-readable label. The registry defaults it to `name` when a create
+     * body omits it, so it is always present on read and never null. Edit it
+     * freely without moving `name`.
+     *
+     * `#[serde(default)]` because `flatten` is a whitelist: without it, a view
+     * deserialized from a registry that predates this field would fail rather
+     * than fall back.
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
@@ -75,7 +119,7 @@ export interface AgentAgentArtifactView {
      */
     id: string;
     /**
-     * Value of the `identity` field.
+     *
      * @type {GatewayArtifactIdentityRevealView}
      * @memberof AgentAgentArtifactView
      */
@@ -87,7 +131,7 @@ export interface AgentAgentArtifactView {
      */
     isLatest: boolean;
     /**
-     * Domain discriminator for this resource.
+     *
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
@@ -223,13 +267,13 @@ export interface AgentAgentArtifactView {
      */
     sourceVersion?: string;
     /**
-     * Value of the `updated_at` field.
+     *
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
     updatedAt: string;
     /**
-     * Value of the `updated_by` field.
+     *
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
@@ -373,17 +417,19 @@ export interface AgentAgentArtifactView {
      */
     syncError?: string | null;
     /**
-     * Value of the `sync_state` field.
+     *
      * @type {AgentSyncState}
      * @memberof AgentAgentArtifactView
      */
     syncState?: AgentSyncState | null;
     /**
-     * A hash of the spec fields that map onto the remote agent config
-     * (`instructions`, `model_id`, `tools`, `max_step_count`). A re-trigger reuses
-     * the pushed version when it matches and pushes a new one when it does not,
-     * so repeated runs of an unchanged agent do not mint a version each time.
-     * Hook-owned.
+     * A hash of the spec that maps onto the remote agent config: `instructions`,
+     * `model_id`, `tools`, `max_step_count`, plus the composition edges — the
+     * sub-agent ids, and the attached skills at the head version the push would
+     * upload. A re-trigger reuses the pushed version when it matches **and**
+     * `sync_state` is `synced`, and pushes a new one otherwise, so repeated runs
+     * of an unchanged agent do not mint a version each time while a skill edit
+     * or a failed push still re-pushes. Hook-owned.
      * @type {string}
      * @memberof AgentAgentArtifactView
      */
@@ -395,7 +441,16 @@ export interface AgentAgentArtifactView {
      */
     tools?: Array<GatewayToolRef>;
     /**
-     * Value of the `permissions` field.
+     * The caller's advisory `can_*` capability matrix on a resource.
+     *
+     * Advisory only: it reflects what the caller may do, and is for a UI to gate
+     * controls on. It never authorizes a request — the platform decides that
+     * independently on every call.
+     *
+     * Deliberately an open map rather than a typed struct. The authoritative
+     * permission tables are internal to the platform core, and lifting them into the
+     * SDK would put an authorization decision surface into every extension. An
+     * extension reads this matrix; it never derives one.
      * @type {{ [key: string]: boolean; }}
      * @memberof AgentAgentArtifactView
      */
@@ -418,7 +473,7 @@ export interface AgentAgentArtifactView {
      */
     profileImageUrl?: string | null;
     /**
-     * Value of the `relationships` field.
+     *
      * @type {RegistryRelationshipsView}
      * @memberof AgentAgentArtifactView
      */

package/dist/raw/agent/models/AgentAgentCreate.d.ts

@@ -82,7 +82,7 @@ export interface AgentAgentCreate {
      */
     sourceVersion?: string;
     /**
-     * Human-readable description.
+     *
      * @type {string}
      * @memberof AgentAgentCreate
      */

package/dist/raw/agent/models/AgentAgentEnvironmentArtifactView.d.ts

@@ -15,19 +15,37 @@ import type { AgentEnvironmentPackages } from './AgentEnvironmentPackages';
 import type { RegistryRelationshipsView } from './RegistryRelationshipsView';
 import type { AgentEnvironmentType } from './AgentEnvironmentType';
 /**
- * Published representation of AgentEnvironmentArtifact.
+ *
  * @export
  * @interface AgentAgentEnvironmentArtifactView
  */
 export interface AgentAgentEnvironmentArtifactView {
     /**
-     * Value of the `app` field.
+     * The extension that registered the kind.
+     *
+     * `#[serde(default)]` because the registry's **L1** view omits it: `registry_http::artifact`
+     * serves `l1_view` — deliberately kind-polymorphic, deliberately without an extension name —
+     * from ranked search and from archive. Without the default, `flatten` being a whitelist made
+     * the absence a hard decode failure, so *every* extension-scoped `POST …/search` and
+     * `POST …/{id}/archive` answered `500 unexpected registry response shape` the moment a row came
+     * back. Empty result sets decoded fine, which is why it read as working.
+     *
+     * The archive case was the worse of the two: the write had already committed, so the caller saw
+     * a 500 for a request that succeeded.
+     *
+     * Serialization skips it when empty rather than emitting `""`, so a typed view built from an L1
+     * row **omits** the field exactly as the registry's own L1 row does. A client that needs it for
+     * a search hit resolves it from `kind` through `GET /kinds`, which is the same lookup the
+     * registry would do.
+     *
+     * Named `extension` until `apps-2026-09-15-the-extension-tables-are-dropped`; renamed with no
+     * alias, matching the registry's own `ArtifactView`.
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
     app?: string;
     /**
-     * Value of the `artifact_status` field.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
@@ -39,31 +57,57 @@ export interface AgentAgentEnvironmentArtifactView {
      */
     commitTs: string;
     /**
-     * Value of the `content_hash_hex` field.
+     * BLAKE3 (hex) of the canonicalised per-kind properties — the artifact's `ETag`, and the
+     * `If-Match` precondition's subject. Named `_hex` for the shipped contract's sake.
+     *
+     * `#[serde(default)]` for the same reason `extension` above has one, and this is the second
+     * time that reason has cost every extension its read surface. The registry types the field
+     * `Option<String>` and **omits** it when the row's `content_hash` is NULL
+     * (`registry_http::ArtifactView`), populating it straight from the nullable column; `flatten`
+     * is a whitelist, so a bare `String` here made that omission a hard decode failure — every
+     * `skill`, `mcp` and `agent` read answered `500 unexpected registry response shape` for a
+     * request the registry had served correctly, while the registry's own `/artifacts` surface
+     * kept working and made it read as an extension bug.
+     *
+     * The absence is legitimate, which is why the fix is here and not a backfill: no write path
+     * leaves the column NULL, but the spanner→postgres mover deliberately **invalidates** every
+     * migrated hash — Spanner hashed `sha256(jcs(metadata))` and this stack hashes
+     * `blake3(write_canonical(metadata))`, so a carried-over digest could never match a
+     * recomputation. A migrated artifact has no hash until its next property write recomputes
+     * one, so a caller that wants a conditional write against it sends `*` or no `If-Match`.
+     *
+     * Skipped on the way out rather than serialized as `null`, so a typed per-kind view renders
+     * exactly the shape the registry served.
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
     contentHashHex?: string;
     /**
-     * Value of the `created_at` field.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
     createdAt: string;
     /**
-     * Value of the `created_by` field.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
     createdBy: string;
     /**
-     * Human-readable description.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
     description?: string;
     /**
-     * Human-readable name.
+     * Human-readable label. The registry defaults it to `name` when a create
+     * body omits it, so it is always present on read and never null. Edit it
+     * freely without moving `name`.
+     *
+     * `#[serde(default)]` because `flatten` is a whitelist: without it, a view
+     * deserialized from a registry that predates this field would fail rather
+     * than fall back.
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
@@ -75,7 +119,7 @@ export interface AgentAgentEnvironmentArtifactView {
      */
     id: string;
     /**
-     * Value of the `identity` field.
+     *
      * @type {GatewayArtifactIdentityRevealView}
      * @memberof AgentAgentEnvironmentArtifactView
      */
@@ -87,7 +131,7 @@ export interface AgentAgentEnvironmentArtifactView {
      */
     isLatest: boolean;
     /**
-     * Domain discriminator for this resource.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
@@ -223,13 +267,13 @@ export interface AgentAgentEnvironmentArtifactView {
      */
     sourceVersion?: string;
     /**
-     * Value of the `updated_at` field.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
     updatedAt: string;
     /**
-     * Value of the `updated_by` field.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentArtifactView
      */
@@ -317,7 +361,16 @@ export interface AgentAgentEnvironmentArtifactView {
      */
     remoteEnvironmentId?: string | null;
     /**
-     * Value of the `permissions` field.
+     * The caller's advisory `can_*` capability matrix on a resource.
+     *
+     * Advisory only: it reflects what the caller may do, and is for a UI to gate
+     * controls on. It never authorizes a request — the platform decides that
+     * independently on every call.
+     *
+     * Deliberately an open map rather than a typed struct. The authoritative
+     * permission tables are internal to the platform core, and lifting them into the
+     * SDK would put an authorization decision surface into every extension. An
+     * extension reads this matrix; it never derives one.
      * @type {{ [key: string]: boolean; }}
      * @memberof AgentAgentEnvironmentArtifactView
      */
@@ -325,7 +378,7 @@ export interface AgentAgentEnvironmentArtifactView {
         [key: string]: boolean;
     } | null;
     /**
-     * Value of the `relationships` field.
+     *
      * @type {RegistryRelationshipsView}
      * @memberof AgentAgentEnvironmentArtifactView
      */

package/dist/raw/agent/models/AgentAgentEnvironmentCreate.d.ts

@@ -87,7 +87,7 @@ export interface AgentAgentEnvironmentCreate {
      */
     sourceVersion?: string;
     /**
-     * Human-readable description.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentCreate
      */

package/dist/raw/agent/models/AgentAgentEnvironmentPatch.d.ts

@@ -21,25 +21,25 @@ import type { AgentEnvironmentType } from './AgentEnvironmentType';
  */
 export interface AgentAgentEnvironmentPatch {
     /**
-     * Stable identifier of the related agent provider resource.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentPatch
      */
     agentProviderId?: string | null;
     /**
-     * Whether mcp servers.
+     *
      * @type {boolean}
      * @memberof AgentAgentEnvironmentPatch
      */
     allowMcpServers?: boolean | null;
     /**
-     * Whether package managers.
+     *
      * @type {boolean}
      * @memberof AgentAgentEnvironmentPatch
      */
     allowPackageManagers?: boolean | null;
     /**
-     * Value of the `allowed_hosts` field.
+     *
      * @type {Array<string>}
      * @memberof AgentAgentEnvironmentPatch
      */
@@ -51,25 +51,25 @@ export interface AgentAgentEnvironmentPatch {
      */
     description?: string | null;
     /**
-     * Human-readable name.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentPatch
      */
     displayName?: string | null;
     /**
-     * Value of the `environment_type` field.
+     *
      * @type {AgentEnvironmentType}
      * @memberof AgentAgentEnvironmentPatch
      */
     environmentType?: AgentEnvironmentType | null;
     /**
-     * Stable machine-readable name.
+     *
      * @type {string}
      * @memberof AgentAgentEnvironmentPatch
      */
     name?: string | null;
     /**
-     * Value of the `network_mode` field.
+     *
      * @type {AgentNetworkMode}
      * @memberof AgentAgentEnvironmentPatch
      */

package/dist/raw/agent/models/AgentAgentFrameworkArtifactView.d.ts

@@ -12,19 +12,37 @@
 import type { GatewayArtifactIdentityRevealView } from './GatewayArtifactIdentityRevealView';
 import type { RegistryRelationshipsView } from './RegistryRelationshipsView';
 /**
- * Published representation of AgentFrameworkArtifact.
+ *
  * @export
  * @interface AgentAgentFrameworkArtifactView
  */
 export interface AgentAgentFrameworkArtifactView {
     /**
-     * Value of the `app` field.
+     * The extension that registered the kind.
+     *
+     * `#[serde(default)]` because the registry's **L1** view omits it: `registry_http::artifact`
+     * serves `l1_view` — deliberately kind-polymorphic, deliberately without an extension name —
+     * from ranked search and from archive. Without the default, `flatten` being a whitelist made
+     * the absence a hard decode failure, so *every* extension-scoped `POST …/search` and
+     * `POST …/{id}/archive` answered `500 unexpected registry response shape` the moment a row came
+     * back. Empty result sets decoded fine, which is why it read as working.
+     *
+     * The archive case was the worse of the two: the write had already committed, so the caller saw
+     * a 500 for a request that succeeded.
+     *
+     * Serialization skips it when empty rather than emitting `""`, so a typed view built from an L1
+     * row **omits** the field exactly as the registry's own L1 row does. A client that needs it for
+     * a search hit resolves it from `kind` through `GET /kinds`, which is the same lookup the
+     * registry would do.
+     *
+     * Named `extension` until `apps-2026-09-15-the-extension-tables-are-dropped`; renamed with no
+     * alias, matching the registry's own `ArtifactView`.
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
     app?: string;
     /**
-     * Value of the `artifact_status` field.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
@@ -36,31 +54,57 @@ export interface AgentAgentFrameworkArtifactView {
      */
     commitTs: string;
     /**
-     * Value of the `content_hash_hex` field.
+     * BLAKE3 (hex) of the canonicalised per-kind properties — the artifact's `ETag`, and the
+     * `If-Match` precondition's subject. Named `_hex` for the shipped contract's sake.
+     *
+     * `#[serde(default)]` for the same reason `extension` above has one, and this is the second
+     * time that reason has cost every extension its read surface. The registry types the field
+     * `Option<String>` and **omits** it when the row's `content_hash` is NULL
+     * (`registry_http::ArtifactView`), populating it straight from the nullable column; `flatten`
+     * is a whitelist, so a bare `String` here made that omission a hard decode failure — every
+     * `skill`, `mcp` and `agent` read answered `500 unexpected registry response shape` for a
+     * request the registry had served correctly, while the registry's own `/artifacts` surface
+     * kept working and made it read as an extension bug.
+     *
+     * The absence is legitimate, which is why the fix is here and not a backfill: no write path
+     * leaves the column NULL, but the spanner→postgres mover deliberately **invalidates** every
+     * migrated hash — Spanner hashed `sha256(jcs(metadata))` and this stack hashes
+     * `blake3(write_canonical(metadata))`, so a carried-over digest could never match a
+     * recomputation. A migrated artifact has no hash until its next property write recomputes
+     * one, so a caller that wants a conditional write against it sends `*` or no `If-Match`.
+     *
+     * Skipped on the way out rather than serialized as `null`, so a typed per-kind view renders
+     * exactly the shape the registry served.
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
     contentHashHex?: string;
     /**
-     * Value of the `created_at` field.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
     createdAt: string;
     /**
-     * Value of the `created_by` field.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
     createdBy: string;
     /**
-     * Human-readable description.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
     description?: string;
     /**
-     * Human-readable name.
+     * Human-readable label. The registry defaults it to `name` when a create
+     * body omits it, so it is always present on read and never null. Edit it
+     * freely without moving `name`.
+     *
+     * `#[serde(default)]` because `flatten` is a whitelist: without it, a view
+     * deserialized from a registry that predates this field would fail rather
+     * than fall back.
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
@@ -72,7 +116,7 @@ export interface AgentAgentFrameworkArtifactView {
      */
     id: string;
     /**
-     * Value of the `identity` field.
+     *
      * @type {GatewayArtifactIdentityRevealView}
      * @memberof AgentAgentFrameworkArtifactView
      */
@@ -84,7 +128,7 @@ export interface AgentAgentFrameworkArtifactView {
      */
     isLatest: boolean;
     /**
-     * Domain discriminator for this resource.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
@@ -220,13 +264,13 @@ export interface AgentAgentFrameworkArtifactView {
      */
     sourceVersion?: string;
     /**
-     * Value of the `updated_at` field.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
     updatedAt: string;
     /**
-     * Value of the `updated_by` field.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkArtifactView
      */
@@ -298,7 +342,16 @@ export interface AgentAgentFrameworkArtifactView {
      */
     logoUrl?: string | null;
     /**
-     * Value of the `permissions` field.
+     * The caller's advisory `can_*` capability matrix on a resource.
+     *
+     * Advisory only: it reflects what the caller may do, and is for a UI to gate
+     * controls on. It never authorizes a request — the platform decides that
+     * independently on every call.
+     *
+     * Deliberately an open map rather than a typed struct. The authoritative
+     * permission tables are internal to the platform core, and lifting them into the
+     * SDK would put an authorization decision surface into every extension. An
+     * extension reads this matrix; it never derives one.
      * @type {{ [key: string]: boolean; }}
      * @memberof AgentAgentFrameworkArtifactView
      */
@@ -306,7 +359,7 @@ export interface AgentAgentFrameworkArtifactView {
         [key: string]: boolean;
     } | null;
     /**
-     * Value of the `relationships` field.
+     *
      * @type {RegistryRelationshipsView}
      * @memberof AgentAgentFrameworkArtifactView
      */

package/dist/raw/agent/models/AgentAgentFrameworkCreate.d.ts

@@ -84,7 +84,7 @@ export interface AgentAgentFrameworkCreate {
      */
     sourceVersion?: string;
     /**
-     * Human-readable description.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkCreate
      */

package/dist/raw/agent/models/AgentAgentFrameworkPatch.d.ts

@@ -22,19 +22,19 @@ export interface AgentAgentFrameworkPatch {
      */
     description?: string | null;
     /**
-     * Human-readable name.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkPatch
      */
     displayName?: string | null;
     /**
-     * Value of the `docs_url` field.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkPatch
      */
     docsUrl?: string | null;
     /**
-     * Value of the `homepage_url` field.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkPatch
      */
@@ -47,13 +47,13 @@ export interface AgentAgentFrameworkPatch {
      */
     languages?: Array<string> | null;
     /**
-     * Value of the `logo_url` field.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkPatch
      */
     logoUrl?: string | null;
     /**
-     * Stable machine-readable name.
+     *
      * @type {string}
      * @memberof AgentAgentFrameworkPatch
      */

package/dist/raw/agent/models/AgentAgentIdentityStatusView.d.ts

@@ -16,7 +16,7 @@
  */
 export interface AgentAgentIdentityStatusView {
     /**
-     * Stable identifier of the related client resource.
+     *
      * @type {string}
      * @memberof AgentAgentIdentityStatusView
      */

package/dist/raw/agent/models/AgentAgentMeta.d.ts

@@ -147,17 +147,19 @@ export interface AgentAgentMeta {
      */
     syncError?: string | null;
     /**
-     * Value of the `sync_state` field.
+     *
      * @type {AgentSyncState}
      * @memberof AgentAgentMeta
      */
     syncState?: AgentSyncState | null;
     /**
-     * A hash of the spec fields that map onto the remote agent config
-     * (`instructions`, `model_id`, `tools`, `max_step_count`). A re-trigger reuses
-     * the pushed version when it matches and pushes a new one when it does not,
-     * so repeated runs of an unchanged agent do not mint a version each time.
-     * Hook-owned.
+     * A hash of the spec that maps onto the remote agent config: `instructions`,
+     * `model_id`, `tools`, `max_step_count`, plus the composition edges — the
+     * sub-agent ids, and the attached skills at the head version the push would
+     * upload. A re-trigger reuses the pushed version when it matches **and**
+     * `sync_state` is `synced`, and pushes a new one otherwise, so repeated runs
+     * of an unchanged agent do not mint a version each time while a skill edit
+     * or a failed push still re-pushes. Hook-owned.
      * @type {string}
      * @memberof AgentAgentMeta
      */