@0gfoundation/0g-agentdna 0.2.0 → 0.2.2

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 (56) hide show
  1. package/GUIDE.md +64 -15
  2. package/PROVIDERS.md +6 -4
  3. package/PROVIDERS.zh.md +4 -3
  4. package/README.md +19 -3
  5. package/dist/AgentClient.d.ts +175 -2
  6. package/dist/AgentClient.d.ts.map +1 -1
  7. package/dist/AgentClient.js +166 -7
  8. package/dist/AgentClient.js.map +1 -1
  9. package/dist/AgenticID.d.ts +45 -6
  10. package/dist/AgenticID.d.ts.map +1 -1
  11. package/dist/AgenticID.js +40 -10
  12. package/dist/AgenticID.js.map +1 -1
  13. package/dist/AttestorClient.d.ts +66 -1
  14. package/dist/AttestorClient.d.ts.map +1 -1
  15. package/dist/AttestorClient.js +161 -32
  16. package/dist/AttestorClient.js.map +1 -1
  17. package/dist/cli/commands/cells.d.ts +29 -1
  18. package/dist/cli/commands/cells.d.ts.map +1 -1
  19. package/dist/cli/commands/cells.js +48 -1
  20. package/dist/cli/commands/cells.js.map +1 -1
  21. package/dist/cli/commands/interactive.d.ts +84 -7
  22. package/dist/cli/commands/interactive.d.ts.map +1 -1
  23. package/dist/cli/commands/interactive.js +453 -58
  24. package/dist/cli/commands/interactive.js.map +1 -1
  25. package/dist/cli/commands/list.d.ts.map +1 -1
  26. package/dist/cli/commands/list.js +7 -31
  27. package/dist/cli/commands/list.js.map +1 -1
  28. package/dist/cli/commands/settings.d.ts.map +1 -1
  29. package/dist/cli/commands/settings.js +23 -0
  30. package/dist/cli/commands/settings.js.map +1 -1
  31. package/dist/cli/inference.d.ts +25 -0
  32. package/dist/cli/inference.d.ts.map +1 -1
  33. package/dist/cli/inference.js +67 -6
  34. package/dist/cli/inference.js.map +1 -1
  35. package/dist/cli/settings.d.ts +20 -0
  36. package/dist/cli/settings.d.ts.map +1 -1
  37. package/dist/cli/settings.js +40 -1
  38. package/dist/cli/settings.js.map +1 -1
  39. package/dist/constants.d.ts +1 -1
  40. package/dist/constants.js +1 -1
  41. package/dist/index.d.ts +4 -3
  42. package/dist/index.d.ts.map +1 -1
  43. package/dist/index.js +6 -2
  44. package/dist/index.js.map +1 -1
  45. package/package.json +1 -1
  46. package/src/AgentClient.ts +326 -9
  47. package/src/AgenticID.ts +62 -8
  48. package/src/AttestorClient.ts +206 -50
  49. package/src/cli/commands/cells.ts +47 -1
  50. package/src/cli/commands/interactive.ts +441 -64
  51. package/src/cli/commands/list.ts +7 -29
  52. package/src/cli/commands/settings.ts +22 -1
  53. package/src/cli/inference.ts +82 -5
  54. package/src/cli/settings.ts +41 -0
  55. package/src/constants.ts +1 -1
  56. package/src/index.ts +7 -3
@@ -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', {
@@ -1,7 +1,9 @@
1
1
  /**
2
2
  * @file cells.ts
3
3
  * @description Shared cell sanitising for human-mode listings — used by
4
- * `list` and the REPL's own listing so a name cannot forge a row in EITHER.
4
+ * `list` and the REPL's own listing so a name cannot forge a row in EITHER —
5
+ * and the OWNER cell's nesting annotation, so both listings show an
6
+ * agent-owned agent the same way.
5
7
  *
6
8
  * Untrusted cells (NAME is owner-controlled JSON; PHASE/FRAMEWORK come from
7
9
  * the attestor) must not be able to forge a table. Order matters:
@@ -59,3 +61,47 @@ export function cellText(v: unknown, w: number): string {
59
61
  if (cps.length >= w) return `${cps.slice(0, Math.max(0, w - 2)).join('')}…`.padEnd(w);
60
62
  return t.padEnd(w);
61
63
  }
64
+
65
+ /** 0xa932…9330 — display form of a 42-char address (agentSeal or owner). */
66
+ export function shortAddr(s: string | null | undefined): string {
67
+ if (!s) return '—';
68
+ return `${s.slice(0, 6)}…${s.slice(-4)}`;
69
+ }
70
+
71
+ /**
72
+ * agentSeal → agentId for the nesting annotation, from MINTED rows (unminted
73
+ * rows have no on-chain agentSeal). Case-folded: rows may carry checksummed
74
+ * addresses from different sources. Build it from the UNFILTERED listing: a
75
+ * filtered view must not strip the annotation off a child row whose parent it
76
+ * hides — the owner's identity (agent vs human wallet) does not depend on
77
+ * what the view happens to show.
78
+ */
79
+ export function sealToAgentMap(
80
+ rows: ReadonlyArray<{ agentId: bigint | number | null; agentSeal?: string | null }>,
81
+ ): Map<string, string> {
82
+ const map = new Map<string, string>();
83
+ for (const r of rows) {
84
+ if (r.agentSeal && r.agentId != null) map.set(r.agentSeal.toLowerCase(), String(r.agentId));
85
+ }
86
+ return map;
87
+ }
88
+
89
+ /** OWNER cell text: the short address, plus `⇄ #<agentId>` when the owner is
90
+ * another listed agent's seal (an agent-owned agent). Zero chain reads. */
91
+ export function ownerCellText(owner: string | null | undefined, sealToAgent: ReadonlyMap<string, string>): string {
92
+ if (!owner) return '—';
93
+ const agentId = sealToAgent.get(owner.toLowerCase());
94
+ return agentId ? `${shortAddr(owner)} ⇄ #${agentId}` : shortAddr(owner);
95
+ }
96
+
97
+ /**
98
+ * A cell whose ANNOTATION is trusted (our shortAddr + the agentId from our
99
+ * own map): it pads but never truncates — a 6-digit agentId's `⇄ #123456`
100
+ * must not read as agent #1234. The ADDRESS part is attestor-supplied (a
101
+ * malicious attestor, or a MITM on plain-http ATTESTOR_URL, can put ESC
102
+ * bytes in it), so the cell is still cleaned. The trailing space keeps a
103
+ * full-width cell from gluing onto the next column.
104
+ */
105
+ export function trustedCell(t: string, w: number): string {
106
+ return `${cleanCell(t)} `.padEnd(w);
107
+ }