@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
@@ -28,17 +28,11 @@
28
28
  */
29
29
 
30
30
  import { buildClient } from '../sdk';
31
- import { cellText, cleanCell } from './cells';
31
+ import { cellText, ownerCellText, sealToAgentMap, shortAddr, trustedCell } from './cells';
32
32
  import { CliError } from '../errors';
33
33
  import { emitOk, print } from '../envelope';
34
34
  import type { CommandContext } from '../types';
35
35
 
36
- /** 0xa932…9330 — human-mode display form of a 42-char address (agentSeal or owner). */
37
- function shortAddr(s: string | null | undefined): string {
38
- if (!s) return '—';
39
- return `${s.slice(0, 6)}…${s.slice(-4)}`;
40
- }
41
-
42
36
  /** The deployment phases derive_phase() can produce — the valid --phase values. */
43
37
  const PHASES = ['deploying', 'running', 'stopped', 'offline', 'failed'];
44
38
 
@@ -68,28 +62,12 @@ export async function run(ctx: CommandContext): Promise<void> {
68
62
  print('(no deployments)');
69
63
  return;
70
64
  }
71
- // Nesting annotation map, from the UNFILTERED listing (minted rows only —
72
- // unminted rows have no on-chain agentSeal). Case-folded: rows may carry
73
- // checksummed addresses from different sources. Built from `all`, not
74
- // `rows`: a --phase filter must not strip the annotation off a child row
75
- // whose parent falls outside the filtered view — the owner's identity
76
- // (agent vs human wallet) does not depend on what this view happens to show.
77
- const sealToAgent = new Map<string, string>();
78
- for (const r of all) {
79
- if (r.agentSeal && r.agentId != null) sealToAgent.set(r.agentSeal.toLowerCase(), String(r.agentId));
80
- }
81
- const ownerCell = (owner: string | null | undefined): string => {
82
- if (!owner) return '—';
83
- const agentId = sealToAgent.get(owner.toLowerCase());
84
- return agentId ? `${shortAddr(owner)} ⇄ #${agentId}` : shortAddr(owner);
85
- };
86
- // The ANNOTATION is trusted (our shortAddr + the agentId from our own
87
- // map) so it pads but never truncates — a 6-digit agentId's `⇄ #123456`
88
- // must not read as agent #1234. The ADDRESS part is attestor-supplied
89
- // (a malicious attestor, or a MITM on plain-http ATTESTOR_URL, can put
90
- // ESC bytes in it), so the cell is still cleaned — just not truncated.
91
- // At full width a space separator keeps NAME from gluing on.
92
- const trustedCell = (t: string, w: number): string => `${cleanCell(t)} `.padEnd(w);
65
+ // Nesting annotation map, built from `all`, not `rows`: a --phase filter
66
+ // must not strip the annotation off a child row whose parent falls outside
67
+ // the filtered view (./cells: sealToAgentMap). The OWNER cell pads but
68
+ // never truncates its trusted annotation (./cells: trustedCell).
69
+ const sealToAgent = sealToAgentMap(all);
70
+ const ownerCell = (owner: string | null | undefined): string => ownerCellText(owner, sealToAgent);
93
71
  // Sanitising lives in ./cells (shared with the REPL's listing — a name
94
72
  // must not be able to forge a row in either): sequence bodies stripped
95
73
  // before control bytes, newlines → space, code-point truncation.
@@ -24,7 +24,7 @@ import { buildClient } from '../sdk';
24
24
  import { CliError } from '../errors';
25
25
  import { emitOk, note, print } from '../envelope';
26
26
  import { parseAgentRef, type AgentRef } from '../ref';
27
- import { applyAssignments, assertModelPresent, parseAssignments, renderSettings } from '../settings';
27
+ import { applyAssignments, assertModelPresent, assertOthersFitFramework, parseAssignments, renderSettings } from '../settings';
28
28
  import { SettingsConflictError } from '../../Settings';
29
29
  import type { CommandContext } from '../types';
30
30
  import { changesProvider } from '../../Providers';
@@ -89,6 +89,11 @@ export async function run(ctx: CommandContext): Promise<void> {
89
89
  return;
90
90
  }
91
91
 
92
+ // Before anything is signed: a 0g-harness switch in others= for an agent that runs
93
+ // another framework does nothing there, or worse (cli/settings.ts).
94
+ if (assignments.some((a) => a.key === 'others' && a.value !== undefined)) {
95
+ assertOthersFitFramework(assignments, await frameworkOf(ctx.env.attestorUrl, sealId));
96
+ }
92
97
  const next = applyAssignments(current, assignments);
93
98
  // Before anything is signed: a document with no model is the one state the
94
99
  // container cannot boot from and last-known-good cannot cover.
@@ -171,6 +176,22 @@ export async function run(ctx: CommandContext): Promise<void> {
171
176
  );
172
177
  }
173
178
 
179
+ /**
180
+ * The framework the deployment row records, or undefined when it cannot be
181
+ * read (a legacy row, an unreachable attestor): the check it feeds then lets
182
+ * the write through.
183
+ */
184
+ async function frameworkOf(attestorUrl: string | undefined, sealId: string): Promise<string | undefined> {
185
+ if (!attestorUrl) return undefined;
186
+ try {
187
+ const r = await fetch(`${attestorUrl}/deployment/${sealId}`, { signal: AbortSignal.timeout(5000) });
188
+ if (!r.ok) return undefined;
189
+ return ((await r.json()) as { framework?: string | null }).framework ?? undefined;
190
+ } catch {
191
+ return undefined;
192
+ }
193
+ }
194
+
174
195
  /**
175
196
  * The running container's serve base, or undefined when there is nothing live
176
197
  * to push to.
@@ -3,6 +3,10 @@ import type { Hash } from 'viem';
3
3
  import { inferenceKeyFromEnv, loadApiKey } from './config';
4
4
  import { CliError } from './errors';
5
5
  import { requiresMintFirst } from '../Providers';
6
+ import {
7
+ DEFAULT_PERSONA_INFERENCE, deploymentFactsOf, needsDefaultSettings, storeDefaultSettings,
8
+ type DeploymentFacts,
9
+ } from '../AttestorClient';
6
10
 
7
11
  /** Deploy using the current registry's routing requirements. Called after
8
12
  * the wizard's prompts/preflight so an edited compute route is rechecked. */
@@ -22,12 +26,15 @@ export async function deployWithInference(ag: AgenticID, params: {
22
26
  ...(params.provision && !mintFirst ? { sandbox: { apiKey: params.apiKey! } } : {}),
23
27
  });
24
28
  const mint = await ag.agent.waitForMint(deployment.sealId, { timeoutMs: 180000 });
25
- if (mintFirst) {
29
+ // A mint-only agent also keeps the chosen pin as its settings document, so
30
+ // the container a later reset starts boots on it whatever happens to the
31
+ // copy in the minted persona.
32
+ if (mintFirst || !params.provision) {
26
33
  await ag.agent.setSettings(deployment.sealId, { provider: params.provider, model: params.model }, { baseVersion: 0 });
27
- if (params.provision) await ag.agent.start(deployment.sealId, {
28
- provider: params.provider, framework: params.framework, apiKey: params.apiKey, secretEnv: 'sealed',
29
- });
30
34
  }
35
+ if (mintFirst && params.provision) await ag.agent.start(deployment.sealId, {
36
+ provider: params.provider, framework: params.framework, apiKey: params.apiKey, secretEnv: 'sealed',
37
+ });
31
38
  return { deployment, agentId: String((mint as { agentId?: unknown }).agentId ?? mint) };
32
39
  }
33
40
 
@@ -47,7 +54,77 @@ export function requireConfiguredInferenceKey(provider: string, env: NodeJS.Proc
47
54
  /** A failed owner settings read must not select a different provider or key. */
48
55
  export async function agentInferenceProvider(ag: AgenticID, sealId: Hash): Promise<string> {
49
56
  const { settings } = await ag.agent.getSettings(sealId);
50
- const provider = settings?.provider ?? '0g-compute';
57
+ return checkedProvider(settings?.provider ?? '0g-compute');
58
+ }
59
+
60
+ export type { DeploymentFacts };
61
+
62
+ /** Read {@link DeploymentFacts} from the public `/deployment/:sealId`. */
63
+ export async function readDeploymentFacts(attestorUrl: string, sealId: Hash): Promise<DeploymentFacts> {
64
+ let row: Record<string, unknown>;
65
+ try {
66
+ const r = await fetch(`${attestorUrl.replace(/\/$/, '')}/deployment/${sealId}`, { signal: AbortSignal.timeout(10_000) });
67
+ if (!r.ok) throw new Error(`HTTP ${r.status}`);
68
+ row = (await r.json()) as typeof row;
69
+ } catch (e) {
70
+ throw new CliError('UNKNOWN', `cannot read /deployment/${sealId}: ${e instanceof Error ? e.message : String(e)}`, {
71
+ remedy: 'check the attestor is reachable, then repeat the command',
72
+ });
73
+ }
74
+ return deploymentFactsOf(row);
75
+ }
76
+
77
+ /** The provider a reset uses, and the settings document it stores first. */
78
+ export interface ResetInferencePlan {
79
+ provider: string;
80
+ /** Stored as the agent's first settings document before the reset. */
81
+ seed?: { provider: string; model: string };
82
+ /** Said to the owner when the agent has no settings document and keeps none. */
83
+ note?: string;
84
+ }
85
+
86
+ /**
87
+ * The provider a reset uses, and whether the default model is stored first:
88
+ * the SDK's rule ({@link needsDefaultSettings}, which `start` and `reset`
89
+ * also apply). Nothing is written here; {@link applyResetInference} stores the
90
+ * document once the owner has passed the reset's prompts, so a reset
91
+ * cancelled at a prompt writes nothing.
92
+ */
93
+ export async function resetInferencePlan(ag: AgenticID, sealId: Hash, facts: DeploymentFacts): Promise<ResetInferencePlan> {
94
+ const { settings, version } = await ag.agent.getSettings(sealId);
95
+ if (settings === null && version === 0) {
96
+ if (needsDefaultSettings(facts, version)) {
97
+ const seed = { ...DEFAULT_PERSONA_INFERENCE };
98
+ return { provider: seed.provider, seed };
99
+ }
100
+ return {
101
+ provider: '0g-compute',
102
+ note: 'no settings yet: the container uses the model chosen at mint (change it with settings)\n',
103
+ };
104
+ }
105
+ return { provider: checkedProvider(settings?.provider ?? '0g-compute') };
106
+ }
107
+
108
+ /** Store a plan's settings document (see {@link resetInferencePlan}). */
109
+ export async function applyResetInference(
110
+ ag: AgenticID,
111
+ sealId: Hash,
112
+ plan: ResetInferencePlan,
113
+ note: (line: string) => void,
114
+ ): Promise<void> {
115
+ if (plan.seed) {
116
+ // A document written since the plan was made is kept, not replaced.
117
+ if (await storeDefaultSettings(ag.agent, sealId)) {
118
+ note(`no settings yet: set provider=${plan.seed.provider} model=${plan.seed.model} (change them with settings)\n`);
119
+ } else {
120
+ note('settings were written meanwhile: kept\n');
121
+ }
122
+ } else if (plan.note) {
123
+ note(plan.note);
124
+ }
125
+ }
126
+
127
+ function checkedProvider(provider: string): string {
51
128
  if (!/^[a-z0-9][a-z0-9-]{0,63}$/.test(provider)) throw new CliError('BAD_FLAG', 'invalid inference provider ID');
52
129
  return provider;
53
130
  }
@@ -90,6 +90,47 @@ export function parseAssignments(args: string[]): Assignment[] {
90
90
  return out;
91
91
  }
92
92
 
93
+ /** `others` keys only the 0g-harness adapter reads (sealed `harness/settings.go`). */
94
+ export const HARNESS_ONLY_KEYS = ['toolJobs', 'subagents', 'schedule', 'maxParallelToolCalls'] as const;
95
+
96
+ /**
97
+ * Whether `framework` names the 0g-harness adapter. `dsh` is its name before
98
+ * AgentDNA 1.4, and an attestor not yet upgraded still reports it in
99
+ * deployment rows and `/config` (sealed reads the old name the same way,
100
+ * `legacyFrameworkName`). The 1.3 `dsh` adapter reads `toolJobs` and
101
+ * `maxParallelToolCalls` and ignores `others` keys it does not know.
102
+ */
103
+ export function isHarnessFramework(framework: string | null | undefined): boolean {
104
+ return framework === '0g-harness' || framework === 'dsh';
105
+ }
106
+
107
+ /**
108
+ * Refuse 0g-harness switches in `others=` for an agent known to run another
109
+ * framework, before anything is signed. There `others` is that framework's
110
+ * own configuration, so the switch does nothing, and openclaw goes further:
111
+ * it refuses a key it does not know, and the adapter then drops the whole
112
+ * `others` section, the owner's other keys with it. An unknown framework (a
113
+ * legacy row) is not refused: nothing says the write is wrong, and neither is
114
+ * `dsh`, the harness's name on a network that still runs AgentDNA 1.3.
115
+ */
116
+ export function assertOthersFitFramework(assignments: Assignment[], framework: string | null | undefined): void {
117
+ if (!framework || isHarnessFramework(framework)) return;
118
+ const others = assignments.find((a) => a.key === 'others')?.value;
119
+ if (!others || typeof others !== 'object' || Array.isArray(others)) return;
120
+ const hits = HARNESS_ONLY_KEYS.filter((k) => Object.prototype.hasOwnProperty.call(others, k));
121
+ if (!hits.length) return;
122
+ const named = hits.map((k) => `"${k}"`).join(', ');
123
+ const plural = hits.length > 1;
124
+ throw new CliError(
125
+ 'BAD_FLAG',
126
+ `${named} ${plural ? 'are 0g-harness switches' : 'is a 0g-harness switch'}; this agent runs ${framework}, which does not read ${plural ? 'them' : 'it'}` +
127
+ (framework === 'openclaw'
128
+ ? ' (openclaw refuses keys it does not know, and the whole others section is then dropped)'
129
+ : ''),
130
+ { remedy: `leave ${plural ? 'them' : 'it'} out of others=: background jobs, subagents and reminders are 0g-harness features` },
131
+ );
132
+ }
133
+
93
134
  /** Merge assignments onto the stored document, producing the document to write. */
94
135
  export function applyAssignments(base: SettingsDoc | null, assignments: Assignment[]): SettingsDoc {
95
136
  const doc: SettingsDoc = { ...(base ?? {}) };
package/src/constants.ts CHANGED
@@ -103,4 +103,4 @@ export const RECEIPT_WAIT = {
103
103
 
104
104
  /** This SDK's own version. Kept in lockstep with package.json by a test —
105
105
  * a runtime package.json read would break browser bundles, so a constant. */
106
- export const SDK_VERSION = '0.2.0';
106
+ export const SDK_VERSION = '0.2.2';
package/src/index.ts CHANGED
@@ -27,11 +27,15 @@ if (typeof (globalThis as { fetch?: unknown }).fetch !== 'function') {
27
27
 
28
28
  // ── Facade + namespaces ──
29
29
  export { AgenticID as AgentDNA, AgenticID, AgentApi, AdminApi, ReputationApi } from './AgenticID';
30
- export type { DeployAccepted, WaitLevel } from './AgenticID';
30
+ export type { ContainerStatus, DeployAccepted, WaitLevel } from './AgenticID';
31
31
  export { makeAgentClient } from './AgentClient';
32
- export type { AgentClient, AgentServiceEntry, AgentRoute, ChatMessage, ChatCompletion, AgentTask } from './AgentClient';
32
+ export type {
33
+ AgentClient, AgentServiceEntry, AgentRoute, ChatMessage, ChatCompletion, AgentTask,
34
+ AgentTaskInfo, AgentTaskStop, AgentInbox, AgentInboxMessage, AgentSchedule, AgentEvent,
35
+ } from './AgentClient';
33
36
  export { mcpServices } from './AgentClient';
34
- export { defaultIData } from './AttestorClient';
37
+ export { defaultIData, DEFAULT_PERSONA_INFERENCE, deploymentFactsOf, needsDefaultSettings, storeDefaultSettings } from './AttestorClient';
38
+ export type { DeploymentFacts } from './AttestorClient';
35
39
  export type { DefaultIDataParams } from './AttestorClient';
36
40
  export type { AgenticIDConfig as AgentDNAConfig, AgenticIDConfig } from './context';
37
41