@0gfoundation/0g-agentdna 0.2.1 → 0.2.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/GUIDE.md +67 -18
  2. package/MIGRATION.md +8 -0
  3. package/MIGRATION.zh.md +5 -0
  4. package/PROVIDERS.md +6 -4
  5. package/PROVIDERS.zh.md +4 -3
  6. package/README.md +20 -4
  7. package/dist/AgentClient.d.ts +175 -2
  8. package/dist/AgentClient.d.ts.map +1 -1
  9. package/dist/AgentClient.js +166 -7
  10. package/dist/AgentClient.js.map +1 -1
  11. package/dist/AgenticID.d.ts +47 -7
  12. package/dist/AgenticID.d.ts.map +1 -1
  13. package/dist/AgenticID.js +44 -13
  14. package/dist/AgenticID.js.map +1 -1
  15. package/dist/AgenticIDClient.d.ts +1 -1
  16. package/dist/AgenticIDClient.js +1 -1
  17. package/dist/AttestorClient.d.ts +67 -2
  18. package/dist/AttestorClient.d.ts.map +1 -1
  19. package/dist/AttestorClient.js +162 -33
  20. package/dist/AttestorClient.js.map +1 -1
  21. package/dist/ReputationClient.d.ts +1 -1
  22. package/dist/ReputationClient.js +1 -1
  23. package/dist/SandboxClient.d.ts +1 -1
  24. package/dist/SandboxClient.js +1 -1
  25. package/dist/cli/commands/doctor.d.ts.map +1 -1
  26. package/dist/cli/commands/doctor.js +8 -2
  27. package/dist/cli/commands/doctor.js.map +1 -1
  28. package/dist/cli/commands/interactive.d.ts +71 -2
  29. package/dist/cli/commands/interactive.d.ts.map +1 -1
  30. package/dist/cli/commands/interactive.js +423 -46
  31. package/dist/cli/commands/interactive.js.map +1 -1
  32. package/dist/cli/commands/settings.d.ts.map +1 -1
  33. package/dist/cli/commands/settings.js +23 -0
  34. package/dist/cli/commands/settings.js.map +1 -1
  35. package/dist/cli/config.d.ts +10 -0
  36. package/dist/cli/config.d.ts.map +1 -1
  37. package/dist/cli/config.js +38 -0
  38. package/dist/cli/config.js.map +1 -1
  39. package/dist/cli/env.js +1 -1
  40. package/dist/cli/env.js.map +1 -1
  41. package/dist/cli/inference.d.ts +25 -0
  42. package/dist/cli/inference.d.ts.map +1 -1
  43. package/dist/cli/inference.js +67 -6
  44. package/dist/cli/inference.js.map +1 -1
  45. package/dist/cli/main.js +12 -2
  46. package/dist/cli/main.js.map +1 -1
  47. package/dist/cli/sdk.d.ts +1 -1
  48. package/dist/cli/sdk.js +1 -1
  49. package/dist/cli/settings.d.ts +20 -0
  50. package/dist/cli/settings.d.ts.map +1 -1
  51. package/dist/cli/settings.js +40 -1
  52. package/dist/cli/settings.js.map +1 -1
  53. package/dist/constants.d.ts +3 -3
  54. package/dist/constants.js +2 -2
  55. package/dist/context.d.ts +2 -2
  56. package/dist/context.d.ts.map +1 -1
  57. package/dist/context.js +1 -1
  58. package/dist/index.d.ts +4 -3
  59. package/dist/index.d.ts.map +1 -1
  60. package/dist/index.js +6 -2
  61. package/dist/index.js.map +1 -1
  62. package/dist/secretEnv.js +1 -1
  63. package/dist/secretEnv.js.map +1 -1
  64. package/dist/types.d.ts +1 -1
  65. package/dist/types.js +1 -1
  66. package/package.json +1 -1
  67. package/src/AgentClient.ts +326 -9
  68. package/src/AgenticID.ts +66 -11
  69. package/src/AgenticIDClient.ts +1 -1
  70. package/src/AttestorClient.ts +207 -51
  71. package/src/ReputationClient.ts +1 -1
  72. package/src/SandboxClient.ts +1 -1
  73. package/src/cli/commands/doctor.ts +8 -2
  74. package/src/cli/commands/interactive.ts +405 -51
  75. package/src/cli/commands/settings.ts +22 -1
  76. package/src/cli/config.ts +36 -0
  77. package/src/cli/env.ts +1 -1
  78. package/src/cli/inference.ts +82 -5
  79. package/src/cli/main.ts +13 -3
  80. package/src/cli/sdk.ts +1 -1
  81. package/src/cli/settings.ts +41 -0
  82. package/src/constants.ts +3 -3
  83. package/src/context.ts +2 -2
  84. package/src/index.ts +7 -3
  85. package/src/secretEnv.ts +1 -1
  86. package/src/types.ts +1 -1
package/src/AgenticID.ts CHANGED
@@ -98,6 +98,30 @@ function acceptedOf(res: DeployCloneResponse): DeployAccepted {
98
98
 
99
99
  /** Agent lifecycle (deploy / clone / transfer) + reads. Seal-bound today; the
100
100
  * seal branch is reserved for non-seal agents. */
101
+ /**
102
+ * What an agent's current container last reported to the attestor
103
+ * (`POST /status`), as carried on its deployment row. `level` is `starting`,
104
+ * `running`, `warning`, `error` or `stopping`; `reason` is the container's
105
+ * explanation for a `warning` / `error` / `stopping` report, null when it gave
106
+ * none; `at` is when the attestor accepted the report (ISO 8601).
107
+ */
108
+ export interface ContainerStatus {
109
+ level: string;
110
+ reason: string | null;
111
+ at: string;
112
+ }
113
+
114
+ /** Read a row's `container_status`; null when absent or malformed. */
115
+ function containerStatusOf(raw: unknown): ContainerStatus | null {
116
+ const s = raw as { level?: unknown; reason?: unknown; at?: unknown } | null | undefined;
117
+ if (!s || typeof s !== 'object' || typeof s.level !== 'string') return null;
118
+ return {
119
+ level: s.level,
120
+ reason: typeof s.reason === 'string' ? s.reason : null,
121
+ at: typeof s.at === 'string' ? s.at : '',
122
+ };
123
+ }
124
+
101
125
  export class AgentApi {
102
126
  private readonly id: AgenticIDClient;
103
127
  private readonly attestor: AttestorClient;
@@ -433,8 +457,8 @@ export class AgentApi {
433
457
  }
434
458
  if (agentId === undefined && this.hasAccount()) {
435
459
  console.warn(
436
- `[agentic-sdk] client(${base}): /hello carried no X-Agent-Proof, so the agentId is unknown — ` +
437
- 'this handle has NO owner ops (chat/logs) although this AgenticID holds a key. ' +
460
+ `[0g-agentdna] client(${base}): /hello carried no X-Agent-Proof, so the agentId is unknown — ` +
461
+ 'this handle has NO owner ops (chat/logs) although this AgentDNA client holds a key. ' +
438
462
  'Pass { agentId } (or call client(agentId)) to connect as the owner.',
439
463
  );
440
464
  }
@@ -620,8 +644,8 @@ export class AgentApi {
620
644
  * Compact the agent's ONE persisted conversation in place: the framework's
621
645
  * own compaction replaces the older history with a summary and keeps the
622
646
  * newest part verbatim (how much is the framework's: openclaw ~20K tokens,
623
- * dsh only its newest item), so later requests carry less of it while the
624
- * conversation goes on — the middle ground between doing nothing and
647
+ * 0g-harness only its newest item), so later requests carry less of it
648
+ * while the conversation goes on — the middle ground between doing nothing and
625
649
  * {@link clearConversation}. No restart. The summary takes one or more
626
650
  * model calls, so this can take minutes — longer than Node's fetch waits
627
651
  * for an answer (300s). A connection dropped or timed out meanwhile does not
@@ -802,14 +826,23 @@ export class AgentApi {
802
826
  * row is currently failed (any pipeline stage) or offline due to a
803
827
  * genuine container failure; recovered rows report null.
804
828
  *
829
+ * `containerStatus` is what the agent's current container last reported
830
+ * (`{ level, reason, at }`, owner listing only; null until that container
831
+ * reports, and from attestors that predate the field). `phase` shows a
832
+ * `warning` as `running`: the agent is up but needs the owner, for example
833
+ * because its settings give it no model (`reason` says so; write them with
834
+ * {@link AgentApi.setSettings}, then {@link AgentApi.pushSettingsToContainer}
835
+ * applies them to the running container). Check it when a running agent
836
+ * does not answer.
837
+ *
805
838
  * When `phase` is `"failed"`, try {@link AgentApi.retry} FIRST — it resumes
806
839
  * the failed stages on the same identity. Redeploying instead orphans the
807
840
  * already-minted agent; reset only helps once the container stage is
808
841
  * reached.
809
842
  *
810
843
  * This is the PUBLIC listing: the attestor returns only non-sensitive fields
811
- * for an unauthenticated GET (issue #64), so `sandboxId` and
812
- * `lastProvisionError` come back **null** here. No tier carries the owner's
844
+ * for an unauthenticated GET (issue #64), so `sandboxId`,
845
+ * `lastProvisionError` and `containerStatus` come back **null** here. No tier carries the owner's
813
846
  * settings document — read it with {@link AgentApi.getSettings}, which is
814
847
  * owner-signed. `agentId`/`sealId`/`phase`/`url`/`name` are still
815
848
  * present, and `owner` and `agentSeal` appear for MINTED rows (both
@@ -826,6 +859,7 @@ export class AgentApi {
826
859
  sandboxId: string | null; url: string | null; owner: Address | null; name: string | null;
827
860
  agentSeal: Address | null;
828
861
  createdAt: string | null; lastProvisionError: string | null;
862
+ containerStatus: ContainerStatus | null;
829
863
  }>> {
830
864
  // slim=1 drops the embedded avatar data-URIs (~95% of the payload); servers
831
865
  // predating the param ignore it.
@@ -836,7 +870,7 @@ export class AgentApi {
836
870
  /**
837
871
  * Owner-scoped, authenticated listing — your own agents WITH the fields the
838
872
  * public {@link AgentApi.listDeployments} withholds (`sandboxId`,
839
- * `lastProvisionError`, stages). Signs `0GDeployments:<owner>:<ts>` with
873
+ * `lastProvisionError`, `containerStatus`, stages). Signs `0GDeployments:<owner>:<ts>` with
840
874
  * `ctx.account` and sends it as `X-Auth-Message`/`X-Auth-Signature`; the
841
875
  * attestor verifies the signer controls `<owner>` before returning its rows.
842
876
  * Requires a wallet. This is how you get a container's `sandboxId` for
@@ -860,13 +894,14 @@ export class AgentApi {
860
894
  * {@link AgentApi.listMyDeployments}; whatever the tier omits simply
861
895
  * comes through as null — public tier: owner/agentSeal only on minted
862
896
  * rows (agentSeal only from attestors carrying the field),
863
- * sandboxId/lastProvisionError never; owner tier: everything present
897
+ * sandboxId/lastProvisionError/containerStatus never; owner tier: everything present
864
898
  * for your own rows, including unminted ones. */
865
899
  private normalizeDeploymentRow(r: Record<string, unknown>): {
866
900
  agentId: bigint | null; sealId: Hash; phase: string; framework: string | null;
867
901
  sandboxId: string | null; url: string | null; owner: Address | null; name: string | null;
868
902
  agentSeal: Address | null;
869
903
  createdAt: string | null; lastProvisionError: string | null;
904
+ containerStatus: ContainerStatus | null;
870
905
  } {
871
906
  const card = (r.agent_card as Record<string, unknown>) ?? {};
872
907
  // The card's url points at the /hello card endpoint; the base (origin)
@@ -875,8 +910,9 @@ export class AgentApi {
875
910
  try { url = card.url ? new URL(card.url as string).origin : null; } catch { /* malformed → null */ }
876
911
  // Failure reasons live on the per-track stage objects
877
912
  // (storage/mint/container_stage.reason); last_provision_error is a
878
- // sticky DB column (only set, never cleared) so it is only consulted
879
- // for phase=failed, as a backstop — same gating and priority as the
913
+ // sticky DB column (cleared only by the next accepted /provision or a
914
+ // new container's boot ticket) so it is only consulted for
915
+ // phase=failed, as a backstop — same gating and priority as the
880
916
  // attestor console's failureReason(). phase=offline surfaces only a
881
917
  // genuine container failure (a clean owner stop carries no reason);
882
918
  // recovered rows report null rather than a stale sticky error. (These
@@ -908,6 +944,7 @@ export class AgentApi {
908
944
  name: (card.name as string) ?? null,
909
945
  createdAt: (r.created_at as string) ?? null,
910
946
  lastProvisionError: failureReason,
947
+ containerStatus: containerStatusOf(r.container_status),
911
948
  // No `settings`: the owner's configuration document is owner-gated on
912
949
  // READ as well as write and is served only by {@link getSettings}. No
913
950
  // listing tier carries it, so advertising it here would have meant a
@@ -933,6 +970,13 @@ export class AgentApi {
933
970
  * supplies the key, pass its {@link sealApiKey} output as
934
971
  * `sealedSecretEnv` instead of `apiKey`, so the key never reaches the
935
972
  * signer at all.
973
+ *
974
+ * Both shapes, like {@link reset}, first store the default model
975
+ * (`DEFAULT_PERSONA_INFERENCE`) as the agent's settings document when it
976
+ * has none and could boot without a model: a clone, or an agent that has
977
+ * provisioned before (`needsDefaultSettings`). That write is one more
978
+ * owner signature, made after every check that can refuse the call; an
979
+ * existing document is never replaced.
936
980
  */
937
981
  start(sealId: Hash, sandboxId: string): Promise<void>;
938
982
  start(sealId: Hash, opts?: { provider?: string; framework?: string; sealedImage?: string; apiKey?: string; sealedSecretEnv?: string; secretEnv?: SecretEnvMode }): Promise<void>;
@@ -954,6 +998,16 @@ export class AgentApi {
954
998
  * signed envelope in clear (`secretEnv`, default `'auto'`; `'sealed'`
955
999
  * refuses the clear path). The attestor keeps no reusable copy, which
956
1000
  * is WHY it must be passed again on every recreate.
1001
+ *
1002
+ * An agent with no settings document boots on the model pinned in its
1003
+ * minted persona, which leaves the chain at its first commit. So when the
1004
+ * agent has none and is a clone or has provisioned before
1005
+ * (`needsDefaultSettings`), the default model (`DEFAULT_PERSONA_INFERENCE`,
1006
+ * 0g-compute) is stored as its first document before the envelope is
1007
+ * signed (one more owner signature, after every check that can refuse the
1008
+ * call); an existing document is never replaced. Such an agent cannot be
1009
+ * reset onto another `provider` until its settings name one: write them
1010
+ * with {@link setSettings} first.
957
1011
  */
958
1012
  reset(sealId: Hash, opts?: { provider?: string; framework?: string; sealedImage?: string; apiKey?: string; sealedSecretEnv?: string; secretEnv?: SecretEnvMode }): Promise<void> {
959
1013
  return this.attestor.lifecycle('reset', { sealId, provider: opts?.provider, framework: opts?.framework, sealedImage: opts?.sealedImage, apiKey: opts?.apiKey, sealedSecretEnv: opts?.sealedSecretEnv, secretEnv: opts?.secretEnv });
@@ -1227,7 +1281,6 @@ export class ReputationApi {
1227
1281
  waitForTransaction(txHash: Hash): Promise<TransactionReceipt> { return this.rep.waitForTransaction(txHash); }
1228
1282
  }
1229
1283
 
1230
- /** The AgenticID SDK entry point. */
1231
1284
  /** Attestor-wide operations, authorized by its current Tapp owner. */
1232
1285
  export class AdminApi {
1233
1286
  constructor(private readonly attestor: AttestorClient) {}
@@ -1239,6 +1292,8 @@ export class AdminApi {
1239
1292
  publishSignedProviders(update: { document: string; signature: `0x${string}` }) { return this.attestor.publishSignedProviders(update); }
1240
1293
  }
1241
1294
 
1295
+ /** The AgentDNA SDK entry point, exported as `AgentDNA` (`AgenticID` is the
1296
+ * legacy alias). */
1242
1297
  export class AgenticID {
1243
1298
  readonly agent: AgentApi;
1244
1299
  readonly admin: AdminApi;
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @file AgenticIDClient.ts
3
3
  * @description Internal client for the AgenticID contract (seal-bound transfer +
4
- * the reads that transfer/clone/reputation use). Consumers use the `AgenticID`
4
+ * the reads that transfer/clone/reputation use). Consumers use the `AgentDNA`
5
5
  * facade's `agent` namespace, not this directly.
6
6
  */
7
7
 
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @file AttestorClient.ts
3
3
  * @description Internal client for attestor HTTP endpoints: seal-bound deploy +
4
- * clone. Consumers use the `AgenticID` facade's `agent` namespace.
4
+ * clone. Consumers use the `AgentDNA` facade's `agent` namespace.
5
5
  *
6
6
  * Neither is an on-chain call. The owner signs a canonical envelope (EIP-191) and
7
7
  * POSTs it; the attestor verifies the signer and drives the mint. Deploy also
@@ -16,7 +16,7 @@ import { SDK_VERSION } from './constants';
16
16
  import { agenticIDAbi, cloneGateAbi, tappRegistryAbi } from './abi';
17
17
  import {
18
18
  canonicalSettings, modelAdvisory, settingsAuthMessage, SettingsConflictError, sha256Hex,
19
- type SettingsDoc,
19
+ THINKING_LEVELS, type SettingsDoc,
20
20
  } from './Settings';
21
21
  import {
22
22
  SECRET_ENV_SCHEME,
@@ -81,6 +81,58 @@ export interface IDataInput {
81
81
  extra?: Record<string, unknown>;
82
82
  }
83
83
 
84
+ /** The persona inference pin a fresh deploy starts from (the 0G router's own model). */
85
+ export const DEFAULT_PERSONA_INFERENCE = { provider: '0g-compute', model: '0gm-1.0-35b-a3b' } as const;
86
+
87
+ /** What an agent's public deployment row says about its history, for
88
+ * {@link needsDefaultSettings}. */
89
+ export interface DeploymentFacts {
90
+ /** A container of this agent has provisioned before (`provisioned_at`). */
91
+ provisioned: boolean;
92
+ /** The agent is a clone (`clone_params`). */
93
+ clone: boolean;
94
+ }
95
+
96
+ /** Read {@link DeploymentFacts} from a raw `GET /deployment/:sealId` row. */
97
+ export function deploymentFactsOf(row: Record<string, unknown>): DeploymentFacts {
98
+ return { provisioned: !!row.provisioned_at, clone: row.clone_params != null };
99
+ }
100
+
101
+ /**
102
+ * Whether a start or reset must first store {@link DEFAULT_PERSONA_INFERENCE}
103
+ * as the agent's settings document. `settingsVersion` is the document's
104
+ * version (0: the agent has none).
105
+ *
106
+ * An agent with no settings document boots on the model pinned in its minted
107
+ * persona while that pin is on chain, and its container then stores the pin
108
+ * as the agent's settings. The pin leaves the chain at the agent's first
109
+ * commit, so an agent that has provisioned before, or a clone (whose source
110
+ * may have committed), would come up with no model: only those get the
111
+ * default. An agent that has a document keeps it.
112
+ */
113
+ export function needsDefaultSettings(facts: DeploymentFacts, settingsVersion: number): boolean {
114
+ return settingsVersion === 0 && (facts.provisioned || facts.clone);
115
+ }
116
+
117
+ /**
118
+ * Store {@link DEFAULT_PERSONA_INFERENCE} as the agent's FIRST settings
119
+ * document (owner-signed, `baseVersion: 0`). Returns false when the agent
120
+ * already has one (the write is refused with a version conflict): that
121
+ * document is kept, never overwritten.
122
+ */
123
+ export async function storeDefaultSettings(
124
+ api: { setSettings(sealId: `0x${string}`, settings: SettingsDoc, opts: { baseVersion: number }): Promise<unknown> },
125
+ sealId: `0x${string}`,
126
+ ): Promise<boolean> {
127
+ try {
128
+ await api.setSettings(sealId, { ...DEFAULT_PERSONA_INFERENCE }, { baseVersion: 0 });
129
+ return true;
130
+ } catch (e) {
131
+ if (e instanceof SettingsConflictError) return false;
132
+ throw e;
133
+ }
134
+ }
135
+
84
136
  /** Inputs for {@link defaultIData}. */
85
137
  export interface DefaultIDataParams {
86
138
  /** Framework name for the binding; default "openclaw". */
@@ -115,13 +167,21 @@ export function defaultIData(p: DefaultIDataParams): IDataInput[] {
115
167
  role: 'persona',
116
168
  plaintext: {
117
169
  system_prompt: `You are ${p.name}. ${p.description}\n`,
118
- inference: p.inference ?? { provider: '0g-compute', model: '0gm-1.0-35b-a3b' },
170
+ inference: p.inference ?? { ...DEFAULT_PERSONA_INFERENCE },
119
171
  },
120
172
  extra: {},
121
173
  },
122
174
  ];
123
175
  }
124
176
 
177
+ /** The name in an iData's `role="framework"` binding, as the attestor reads
178
+ * it (`plaintext.name`, trimmed); undefined when there is none. */
179
+ function iDataFramework(iData: IDataInput[]): string | undefined {
180
+ const binding = iData.find((entry) => entry.role === 'framework')?.plaintext as { name?: unknown } | undefined;
181
+ const name = typeof binding?.name === 'string' ? binding.name.trim() : '';
182
+ return name || undefined;
183
+ }
184
+
125
185
  export interface DeployParams {
126
186
  /**
127
187
  * Idempotency key. Optional — the SDK generates a random one per call. Pass
@@ -150,7 +210,9 @@ export interface DeployParams {
150
210
  * need to know a framework's image. CLIENT-SIDE for the binding: it feeds
151
211
  * `defaultIData()` when `iData` is omitted — the on-chain binding inside
152
212
  * i_data is the single source of truth (validated against `GET /config`'s
153
- * `frameworks[]` before mint). Ignored when you pass your own `iData`.
213
+ * `frameworks[]` before mint). With your own `iData`, the image follows
214
+ * that iData's `role="framework"` binding; you may omit this, and a value
215
+ * that names another framework is refused before anything is signed.
154
216
  */
155
217
  framework?: string;
156
218
  /** Inference pin for the SDK-built default persona (defaults to
@@ -388,6 +450,41 @@ export class AttestorClient {
388
450
  };
389
451
  }
390
452
 
453
+ /**
454
+ * The agent's public deployment row (`GET /deployment/:sealId`). An
455
+ * unreadable row refuses, naming `purpose`: the call that needs it posts to
456
+ * the same attestor anyway, and guessing past it is how an agent boots on
457
+ * the wrong image or without a model.
458
+ */
459
+ private async deploymentRow(sealId: `0x${string}`, purpose: string): Promise<Record<string, unknown>> {
460
+ try {
461
+ const r = await fetch(`${this.baseUrl()}/deployment/${sealId}`, {
462
+ signal: AbortSignal.timeout(10_000),
463
+ });
464
+ if (!r.ok) throw new Error(`HTTP ${r.status}`);
465
+ const row = (await r.json()) as unknown;
466
+ if (!row || typeof row !== 'object') throw new Error('not a JSON object');
467
+ return row as Record<string, unknown>;
468
+ } catch (e) {
469
+ throw new Error(
470
+ `cannot read /deployment/${sealId} to ${purpose} (${errMsg(e)}); ` +
471
+ "retry, or pass `framework` (or `sealedImage`) explicitly",
472
+ );
473
+ }
474
+ }
475
+
476
+ /**
477
+ * The settings document a start or reset of this agent stores before it
478
+ * signs, per {@link needsDefaultSettings}, or null. Reads the row's
479
+ * `settings_version`; a row without it (an attestor that predates the
480
+ * settings channel) gets nothing stored.
481
+ */
482
+ private defaultSettingsFor(row: Record<string, unknown>): { provider: string; model: string } | null {
483
+ const version = row.settings_version;
484
+ if (typeof version !== 'number') return null;
485
+ return needsDefaultSettings(deploymentFactsOf(row), version) ? { ...DEFAULT_PERSONA_INFERENCE } : null;
486
+ }
487
+
391
488
  /**
392
489
  * Resolve the sealed image name: an explicit value wins; otherwise the
393
490
  * image `GET /config` declares for `framework` (frameworks whose runtime
@@ -397,13 +494,18 @@ export class AttestorClient {
397
494
  * create envelope makes the provider fail ("sealed containers require an
398
495
  * image or snapshot"), so /config is the source of truth.
399
496
  */
400
- private async resolveSealedImage(explicit?: string, framework?: string, sealId?: `0x${string}`): Promise<string> {
497
+ private async resolveSealedImage(
498
+ explicit?: string,
499
+ framework?: string,
500
+ sealId?: `0x${string}`,
501
+ row?: { framework?: unknown },
502
+ ): Promise<string> {
401
503
  if (explicit) return explicit;
402
504
  let fw = framework;
403
505
  // An existing agent already knows what it is: its deployment row records
404
506
  // the framework. Without this read, a bare reset/start/retry of a
405
- // hermes/prime/dsh agent fell back to the DEFAULT (openclaw) image and
406
- // booted a container without its framework installed (observed live,
507
+ // hermes/prime/0g-harness agent fell back to the DEFAULT (openclaw) image
508
+ // and booted a container without its framework installed (observed live,
407
509
  // agent 452) — the CLI wizard papered over it by asking; the SDK is the
408
510
  // right place for the lookup. An UNREADABLE row refuses rather than
409
511
  // falling through: silently choosing the default image re-creates the
@@ -412,27 +514,25 @@ export class AttestorClient {
412
514
  // never-provisioned agent) still gets the default — that is data, not a
413
515
  // failed read.
414
516
  if (!fw && sealId) {
415
- let row: { framework?: string | null };
416
- try {
417
- const r = await fetch(`${this.baseUrl()}/deployment/${sealId}`, {
418
- signal: AbortSignal.timeout(10_000),
419
- });
420
- if (!r.ok) throw new Error(`HTTP ${r.status}`);
421
- row = (await r.json()) as { framework?: string | null };
422
- } catch (e) {
423
- throw new Error(
424
- `cannot read /deployment/${sealId} to pick the sealed image (${errMsg(e)}); ` +
425
- "retry, or pass `framework` (or `sealedImage`) explicitly",
426
- );
427
- }
428
- fw = row.framework ?? undefined;
517
+ const known = row ?? (await this.deploymentRow(sealId, 'pick the sealed image'));
518
+ fw = typeof known.framework === 'string' ? known.framework : undefined;
429
519
  }
430
520
  // Rides the instance's memoized /config (review #154 N3a) — this was the
431
521
  // one remaining uncached fetch on the deploy/reset/first-start path.
432
522
  const cfg: any = await this.attestorConfig();
433
523
  if (fw && Array.isArray(cfg?.frameworks)) {
434
524
  const entry = cfg.frameworks.find((f: any) => f?.name === fw);
435
- if (entry?.image) return entry.image;
525
+ // A framework this attestor does not offer has no image here. The
526
+ // default snapshot belongs to another framework, and booting the agent
527
+ // on it fails only once the container is up, so refuse instead.
528
+ if (!entry) {
529
+ const offered = cfg.frameworks.map((f: any) => f?.name).filter(Boolean).join(', ');
530
+ throw new Error(
531
+ `framework "${fw}" is not offered by this attestor (GET /config frameworks: ${offered || 'none'}); ` +
532
+ 'pass `framework` (or `sealedImage`) explicitly, or ask the operator to configure it',
533
+ );
534
+ }
535
+ if (entry.image) return entry.image;
436
536
  }
437
537
  return (cfg && cfg.sandbox_snapshot) || '';
438
538
  }
@@ -822,6 +922,16 @@ export class AttestorClient {
822
922
  * the way to force a fresh boot (e.g. after a new sealed image, or
823
923
  * stuck-state recovery). All are owner-signed; the attestor + sandbox
824
924
  * both re-verify.
925
+ *
926
+ * `start` and `reset` first read the agent's public deployment row. When
927
+ * the agent has no settings document and is a clone or has provisioned
928
+ * before ({@link needsDefaultSettings}), the boot would come up with no
929
+ * model, so {@link DEFAULT_PERSONA_INFERENCE} is stored as its first
930
+ * document (one more owner signature) before the envelope is signed. That
931
+ * write comes after every check that can refuse the call, so a refused
932
+ * call writes nothing; a document that already exists is never replaced.
933
+ * Such an agent cannot be started on another `provider` until its settings
934
+ * name one: the call refuses before anything is written or signed.
825
935
  */
826
936
  async lifecycle(
827
937
  op: 'stop' | 'start' | 'reset',
@@ -855,40 +965,66 @@ export class AttestorClient {
855
965
  ): Promise<void> {
856
966
  const { account } = requireWallet(this.ctx);
857
967
  const ttl = params.envelopeTtlSec ?? 180;
858
- let envelope;
859
968
  // `reset`, OR a first-time `start` of a never-provisioned (mint-only)
860
969
  // agent: both spin a FRESH container via the `create` envelope. A `start`
861
970
  // WITH a sandboxId resumes an existing (stopped) container instead.
862
- if (op === 'reset' || (op === 'start' && !params.sandboxId)) {
863
- if (params.provider && params.provider !== '0g-compute' && !params.apiKey && params.sealedSecretEnv === undefined) {
864
- throw new SecretEnvRefusedError('invalid_input', `reset/start for ${params.provider} requires its API key`);
971
+ const create = op === 'reset' || (op === 'start' && !params.sandboxId);
972
+ if (!create && !params.sandboxId) throw new Error(`${op}: sandboxId is required`);
973
+ if (create && params.provider && params.provider !== '0g-compute' && !params.apiKey && params.sealedSecretEnv === undefined) {
974
+ throw new SecretEnvRefusedError('invalid_input', `reset/start for ${params.provider} requires its API key`);
975
+ }
976
+ // Every boot a start or reset brings about is served the agent's settings
977
+ // document, so an agent that would boot with no model gets the default
978
+ // one stored first (see needsDefaultSettings). The row is read, and every
979
+ // check below that can refuse runs, before anything is written or signed.
980
+ let seed: { provider: string; model: string } | null = null;
981
+ let row: Record<string, unknown> | undefined;
982
+ if (op !== 'stop') {
983
+ row = await this.deploymentRow(
984
+ params.sealId,
985
+ create && !params.sealedImage && !params.framework
986
+ ? "pick the sealed image and check the agent's settings"
987
+ : "check the agent's settings",
988
+ );
989
+ seed = this.defaultSettingsFor(row);
990
+ if (seed && params.provider && params.provider !== seed.provider) {
991
+ throw new Error(
992
+ `${op}: agent ${params.sealId} has no settings document and could boot with no model; ` +
993
+ `write its settings (provider ${params.provider} and a model) with setSettings first`,
994
+ );
865
995
  }
866
- const snapshot = await this.resolveSealedImage(params.sealedImage, params.framework, params.sealId);
867
- envelope = await this.signEnvelope(
868
- 'create',
869
- '',
870
- {
871
- snapshot,
872
- sealed: true,
873
- ...(params.apiKey || params.sealedSecretEnv !== undefined
874
- ? {
875
- env: await this.sandboxEnv({
876
- sealId: params.sealId,
877
- provider: params.provider,
878
- image: snapshot,
879
- apiKey: params.apiKey,
880
- sealedSecretEnv: params.sealedSecretEnv,
881
- mode: params.secretEnv,
882
- }),
883
- }
884
- : {}),
885
- },
886
- ttl,
996
+ }
997
+ let action: string = op;
998
+ let resourceId = params.sandboxId ?? '';
999
+ let payload: Record<string, unknown> = {};
1000
+ if (create) {
1001
+ const snapshot = await this.resolveSealedImage(params.sealedImage, params.framework, params.sealId, row);
1002
+ action = 'create';
1003
+ resourceId = '';
1004
+ payload = {
1005
+ snapshot,
1006
+ sealed: true,
1007
+ ...(params.apiKey || params.sealedSecretEnv !== undefined
1008
+ ? {
1009
+ env: await this.sandboxEnv({
1010
+ sealId: params.sealId,
1011
+ provider: params.provider,
1012
+ image: snapshot,
1013
+ apiKey: params.apiKey,
1014
+ sealedSecretEnv: params.sealedSecretEnv,
1015
+ mode: params.secretEnv,
1016
+ }),
1017
+ }
1018
+ : {}),
1019
+ };
1020
+ }
1021
+ if (seed) {
1022
+ await storeDefaultSettings(
1023
+ { setSettings: (sealId, settings, opts) => this.setSettings({ sealId, settings, baseVersion: opts.baseVersion }) },
1024
+ params.sealId,
887
1025
  );
888
- } else {
889
- if (!params.sandboxId) throw new Error(`${op}: sandboxId is required`);
890
- envelope = await this.signEnvelope(op, params.sandboxId, {}, ttl);
891
1026
  }
1027
+ const envelope = await this.signEnvelope(action, resourceId, payload, ttl);
892
1028
  // A no-sandboxId `start` still POSTs /start; the attestor dispatches on the
893
1029
  // envelope action (create → fresh provision, start → resume).
894
1030
  const path = op === 'reset' ? '/reset' : `/${op}`;
@@ -990,6 +1126,14 @@ export class AttestorClient {
990
1126
  onWarn?: (warning: string) => void;
991
1127
  }): Promise<{ version: number }> {
992
1128
  const { walletClient, account } = requireWallet(this.ctx);
1129
+ // The container refuses any other level (Go settings.Levels, compared
1130
+ // case-insensitively); storing one would only fail the live push and
1131
+ // then reach the next boot.
1132
+ const thinking = params.settings.thinking as string | undefined;
1133
+ if (thinking !== undefined && thinking.trim() !== ''
1134
+ && !(THINKING_LEVELS as readonly string[]).includes(thinking.trim().toLowerCase())) {
1135
+ throw new Error(`setSettings: thinking must be one of ${THINKING_LEVELS.join('|')}, got "${thinking}"`);
1136
+ }
993
1137
  if (params.settings.provider) await this.assertProviderSupported(params.settings.provider, { sealId: params.sealId });
994
1138
  if (params.onWarn) {
995
1139
  for (const w of await modelAdvisory(params.settings, await this.providerDefinition(params.settings.provider ?? '0g-compute'))) params.onWarn(w);
@@ -1147,6 +1291,18 @@ export class AttestorClient {
1147
1291
  inference: params.inference,
1148
1292
  });
1149
1293
  const iData = source.map((d) => ({ role: d.role, plaintext: d.plaintext, extra: d.extra ?? {} }));
1294
+ // The create envelope's image follows the framework the agent is minted
1295
+ // with: a caller's own iData binds it, and the default snapshot belongs
1296
+ // to openclaw, so signing it for a hermes binding would boot the agent
1297
+ // on an image without its runtime.
1298
+ const bound = params.iData?.length ? iDataFramework(params.iData) : undefined;
1299
+ if (bound && params.framework && params.framework !== bound) {
1300
+ throw new Error(
1301
+ `framework "${params.framework}" disagrees with the iData's framework binding "${bound}"; ` +
1302
+ 'omit `framework` or bind the same name',
1303
+ );
1304
+ }
1305
+ const framework = bound ?? params.framework;
1150
1306
 
1151
1307
  // Owner canonical — must match CanonicalDeploy (order is irrelevant; the
1152
1308
  // attestor deserializes then re-checks each field).
@@ -1163,7 +1319,7 @@ export class AttestorClient {
1163
1319
  // Provision only when a sandbox is given; omit it → mint-only deploy
1164
1320
  // (attestor mints, no container — the agent lands Offline).
1165
1321
  const sandbox_envelope = params.sandbox
1166
- ? await this.sandboxEnvelope(params.sandbox, params.envelopeTtlSec ?? 180, params.framework)
1322
+ ? await this.sandboxEnvelope(params.sandbox, params.envelopeTtlSec ?? 180, framework)
1167
1323
  : undefined;
1168
1324
 
1169
1325
  return this.post('/deploy', {
@@ -113,7 +113,7 @@ function assertFeedbackValueInRange(value: bigint, valueDecimals: number): void
113
113
 
114
114
  /**
115
115
  * Internal client for the reputation pair (canonical ERC-8004 registry +
116
- * VerifiedFeedbackRegistry). Consumers use the `AgenticID` facade's
116
+ * VerifiedFeedbackRegistry). Consumers use the `AgentDNA` facade's
117
117
  * `reputation` namespace, not this directly.
118
118
  */
119
119
  export class ReputationClient {
@@ -1,7 +1,7 @@
1
1
  /**
2
2
  * @file SandboxClient.ts
3
3
  * @description Internal client for trust-root ack (TappRegistry) + prepaid
4
- * sandbox balance (SandboxServing). Surfaced on the `AgenticID` facade as
4
+ * sandbox balance (SandboxServing). Surfaced on the `AgentDNA` facade as
5
5
  * top-level ops (`ack`/`ackStatus`/`deposit`/`getBalance`) — none is scoped to a
6
6
  * single agent. (Agent-seal gas top-up lives on the `agent` namespace.)
7
7
  *
@@ -16,6 +16,7 @@ import { privateKeyToAccount } from 'viem/accounts';
16
16
  import { MIN_SANDBOX_BALANCE_WEI, type AgenticID } from '../../AgenticID';
17
17
  import { RPC_URL } from '../../constants';
18
18
  import { buildClient } from '../sdk';
19
+ import { renamedAttestor } from '../config';
19
20
  import { CliError, type ErrorCode } from '../errors';
20
21
  import { emitOk, print } from '../envelope';
21
22
  import type { CommandContext } from '../types';
@@ -63,12 +64,17 @@ export async function run(ctx: CommandContext): Promise<void> {
63
64
  checks.push({
64
65
  name: 'attestor', status: 'fail', code: 'MISSING_ATTESTOR_URL',
65
66
  detail: 'AGENTIC_ATTESTOR_URL is not set',
66
- remedy: 'export AGENTIC_ATTESTOR_URL=https://agenticid.0g.ai # or your own attestor',
67
+ remedy: 'export AGENTIC_ATTESTOR_URL=https://agentdna.0g.ai # or your own attestor',
67
68
  });
68
69
  } else {
69
70
  try {
70
71
  cfg = await fetchJson(`${env.attestorUrl}/config`);
71
- checks.push({ name: 'attestor', status: 'pass', detail: env.attestorUrl });
72
+ // A saved earlier name was moved at startup; one set in the env stays.
73
+ const current = renamedAttestor(env.attestorUrl);
74
+ checks.push({
75
+ name: 'attestor', status: 'pass',
76
+ detail: current ? `${env.attestorUrl} (now ${current}; the earlier name still answers — update AGENTIC_ATTESTOR_URL)` : env.attestorUrl,
77
+ });
72
78
  } catch (e) {
73
79
  checks.push({
74
80
  name: 'attestor', status: 'fail', code: 'ATTESTOR_UNREACHABLE',