@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.
- package/GUIDE.md +67 -18
- package/MIGRATION.md +8 -0
- package/MIGRATION.zh.md +5 -0
- package/PROVIDERS.md +6 -4
- package/PROVIDERS.zh.md +4 -3
- package/README.md +20 -4
- package/dist/AgentClient.d.ts +175 -2
- package/dist/AgentClient.d.ts.map +1 -1
- package/dist/AgentClient.js +166 -7
- package/dist/AgentClient.js.map +1 -1
- package/dist/AgenticID.d.ts +47 -7
- package/dist/AgenticID.d.ts.map +1 -1
- package/dist/AgenticID.js +44 -13
- package/dist/AgenticID.js.map +1 -1
- package/dist/AgenticIDClient.d.ts +1 -1
- package/dist/AgenticIDClient.js +1 -1
- package/dist/AttestorClient.d.ts +67 -2
- package/dist/AttestorClient.d.ts.map +1 -1
- package/dist/AttestorClient.js +162 -33
- package/dist/AttestorClient.js.map +1 -1
- package/dist/ReputationClient.d.ts +1 -1
- package/dist/ReputationClient.js +1 -1
- package/dist/SandboxClient.d.ts +1 -1
- package/dist/SandboxClient.js +1 -1
- package/dist/cli/commands/doctor.d.ts.map +1 -1
- package/dist/cli/commands/doctor.js +8 -2
- package/dist/cli/commands/doctor.js.map +1 -1
- package/dist/cli/commands/interactive.d.ts +71 -2
- package/dist/cli/commands/interactive.d.ts.map +1 -1
- package/dist/cli/commands/interactive.js +423 -46
- package/dist/cli/commands/interactive.js.map +1 -1
- package/dist/cli/commands/settings.d.ts.map +1 -1
- package/dist/cli/commands/settings.js +23 -0
- package/dist/cli/commands/settings.js.map +1 -1
- package/dist/cli/config.d.ts +10 -0
- package/dist/cli/config.d.ts.map +1 -1
- package/dist/cli/config.js +38 -0
- package/dist/cli/config.js.map +1 -1
- package/dist/cli/env.js +1 -1
- package/dist/cli/env.js.map +1 -1
- package/dist/cli/inference.d.ts +25 -0
- package/dist/cli/inference.d.ts.map +1 -1
- package/dist/cli/inference.js +67 -6
- package/dist/cli/inference.js.map +1 -1
- package/dist/cli/main.js +12 -2
- package/dist/cli/main.js.map +1 -1
- package/dist/cli/sdk.d.ts +1 -1
- package/dist/cli/sdk.js +1 -1
- package/dist/cli/settings.d.ts +20 -0
- package/dist/cli/settings.d.ts.map +1 -1
- package/dist/cli/settings.js +40 -1
- package/dist/cli/settings.js.map +1 -1
- package/dist/constants.d.ts +3 -3
- package/dist/constants.js +2 -2
- package/dist/context.d.ts +2 -2
- package/dist/context.d.ts.map +1 -1
- package/dist/context.js +1 -1
- package/dist/index.d.ts +4 -3
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +6 -2
- package/dist/index.js.map +1 -1
- package/dist/secretEnv.js +1 -1
- package/dist/secretEnv.js.map +1 -1
- package/dist/types.d.ts +1 -1
- package/dist/types.js +1 -1
- package/package.json +1 -1
- package/src/AgentClient.ts +326 -9
- package/src/AgenticID.ts +66 -11
- package/src/AgenticIDClient.ts +1 -1
- package/src/AttestorClient.ts +207 -51
- package/src/ReputationClient.ts +1 -1
- package/src/SandboxClient.ts +1 -1
- package/src/cli/commands/doctor.ts +8 -2
- package/src/cli/commands/interactive.ts +405 -51
- package/src/cli/commands/settings.ts +22 -1
- package/src/cli/config.ts +36 -0
- package/src/cli/env.ts +1 -1
- package/src/cli/inference.ts +82 -5
- package/src/cli/main.ts +13 -3
- package/src/cli/sdk.ts +1 -1
- package/src/cli/settings.ts +41 -0
- package/src/constants.ts +3 -3
- package/src/context.ts +2 -2
- package/src/index.ts +7 -3
- package/src/secretEnv.ts +1 -1
- 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
|
-
`[
|
|
437
|
-
'this handle has NO owner ops (chat/logs) although this
|
|
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
|
-
*
|
|
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
|
|
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
|
|
879
|
-
//
|
|
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;
|
package/src/AgenticIDClient.ts
CHANGED
|
@@ -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 `
|
|
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
|
|
package/src/AttestorClient.ts
CHANGED
|
@@ -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 `
|
|
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 ?? {
|
|
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).
|
|
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(
|
|
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/
|
|
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
|
-
|
|
416
|
-
|
|
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
|
-
|
|
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
|
-
|
|
863
|
-
|
|
864
|
-
|
|
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
|
-
|
|
867
|
-
|
|
868
|
-
|
|
869
|
-
|
|
870
|
-
|
|
871
|
-
|
|
872
|
-
|
|
873
|
-
|
|
874
|
-
|
|
875
|
-
|
|
876
|
-
|
|
877
|
-
|
|
878
|
-
|
|
879
|
-
|
|
880
|
-
|
|
881
|
-
|
|
882
|
-
|
|
883
|
-
|
|
884
|
-
|
|
885
|
-
|
|
886
|
-
|
|
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,
|
|
1322
|
+
? await this.sandboxEnvelope(params.sandbox, params.envelopeTtlSec ?? 180, framework)
|
|
1167
1323
|
: undefined;
|
|
1168
1324
|
|
|
1169
1325
|
return this.post('/deploy', {
|
package/src/ReputationClient.ts
CHANGED
|
@@ -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 `
|
|
116
|
+
* VerifiedFeedbackRegistry). Consumers use the `AgentDNA` facade's
|
|
117
117
|
* `reputation` namespace, not this directly.
|
|
118
118
|
*/
|
|
119
119
|
export class ReputationClient {
|
package/src/SandboxClient.ts
CHANGED
|
@@ -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 `
|
|
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://
|
|
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
|
-
|
|
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',
|