@0gfoundation/0g-agentdna 0.2.1 → 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 (47) hide show
  1. package/GUIDE.md +60 -11
  2. package/PROVIDERS.md +6 -4
  3. package/PROVIDERS.zh.md +4 -3
  4. package/README.md +18 -2
  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/interactive.d.ts +71 -2
  18. package/dist/cli/commands/interactive.d.ts.map +1 -1
  19. package/dist/cli/commands/interactive.js +423 -46
  20. package/dist/cli/commands/interactive.js.map +1 -1
  21. package/dist/cli/commands/settings.d.ts.map +1 -1
  22. package/dist/cli/commands/settings.js +23 -0
  23. package/dist/cli/commands/settings.js.map +1 -1
  24. package/dist/cli/inference.d.ts +25 -0
  25. package/dist/cli/inference.d.ts.map +1 -1
  26. package/dist/cli/inference.js +67 -6
  27. package/dist/cli/inference.js.map +1 -1
  28. package/dist/cli/settings.d.ts +20 -0
  29. package/dist/cli/settings.d.ts.map +1 -1
  30. package/dist/cli/settings.js +40 -1
  31. package/dist/cli/settings.js.map +1 -1
  32. package/dist/constants.d.ts +1 -1
  33. package/dist/constants.js +1 -1
  34. package/dist/index.d.ts +4 -3
  35. package/dist/index.d.ts.map +1 -1
  36. package/dist/index.js +6 -2
  37. package/dist/index.js.map +1 -1
  38. package/package.json +1 -1
  39. package/src/AgentClient.ts +326 -9
  40. package/src/AgenticID.ts +62 -8
  41. package/src/AttestorClient.ts +206 -50
  42. package/src/cli/commands/interactive.ts +405 -51
  43. package/src/cli/commands/settings.ts +22 -1
  44. package/src/cli/inference.ts +82 -5
  45. package/src/cli/settings.ts +41 -0
  46. package/src/constants.ts +1 -1
  47. package/src/index.ts +7 -3
@@ -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.1';
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