@shardlink/agent-sdk 0.1.0

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 (143) hide show
  1. package/LICENSE +202 -0
  2. package/README.md +129 -0
  3. package/dist/client-quick-join.d.ts +38 -0
  4. package/dist/client-quick-join.d.ts.map +1 -0
  5. package/dist/client-quick-join.js +141 -0
  6. package/dist/client-quick-join.js.map +1 -0
  7. package/dist/client.d.ts +134 -0
  8. package/dist/client.d.ts.map +1 -0
  9. package/dist/client.js +190 -0
  10. package/dist/client.js.map +1 -0
  11. package/dist/errors.d.ts +126 -0
  12. package/dist/errors.d.ts.map +1 -0
  13. package/dist/errors.js +330 -0
  14. package/dist/errors.js.map +1 -0
  15. package/dist/index.d.ts +47 -0
  16. package/dist/index.d.ts.map +1 -0
  17. package/dist/index.js +47 -0
  18. package/dist/index.js.map +1 -0
  19. package/dist/modules/a2a.d.ts +42 -0
  20. package/dist/modules/a2a.d.ts.map +1 -0
  21. package/dist/modules/a2a.js +47 -0
  22. package/dist/modules/a2a.js.map +1 -0
  23. package/dist/modules/agents.d.ts +100 -0
  24. package/dist/modules/agents.d.ts.map +1 -0
  25. package/dist/modules/agents.js +85 -0
  26. package/dist/modules/agents.js.map +1 -0
  27. package/dist/modules/auth.d.ts +49 -0
  28. package/dist/modules/auth.d.ts.map +1 -0
  29. package/dist/modules/auth.js +69 -0
  30. package/dist/modules/auth.js.map +1 -0
  31. package/dist/modules/billing.d.ts +254 -0
  32. package/dist/modules/billing.d.ts.map +1 -0
  33. package/dist/modules/billing.js +203 -0
  34. package/dist/modules/billing.js.map +1 -0
  35. package/dist/modules/clans.d.ts +73 -0
  36. package/dist/modules/clans.d.ts.map +1 -0
  37. package/dist/modules/clans.js +94 -0
  38. package/dist/modules/clans.js.map +1 -0
  39. package/dist/modules/compliance.d.ts +97 -0
  40. package/dist/modules/compliance.d.ts.map +1 -0
  41. package/dist/modules/compliance.js +227 -0
  42. package/dist/modules/compliance.js.map +1 -0
  43. package/dist/modules/cross-plane.d.ts +164 -0
  44. package/dist/modules/cross-plane.d.ts.map +1 -0
  45. package/dist/modules/cross-plane.js +195 -0
  46. package/dist/modules/cross-plane.js.map +1 -0
  47. package/dist/modules/dashboard.d.ts +130 -0
  48. package/dist/modules/dashboard.d.ts.map +1 -0
  49. package/dist/modules/dashboard.js +120 -0
  50. package/dist/modules/dashboard.js.map +1 -0
  51. package/dist/modules/degradation.d.ts +120 -0
  52. package/dist/modules/degradation.d.ts.map +1 -0
  53. package/dist/modules/degradation.js +205 -0
  54. package/dist/modules/degradation.js.map +1 -0
  55. package/dist/modules/diagnostics-checks.d.ts +32 -0
  56. package/dist/modules/diagnostics-checks.d.ts.map +1 -0
  57. package/dist/modules/diagnostics-checks.js +231 -0
  58. package/dist/modules/diagnostics-checks.js.map +1 -0
  59. package/dist/modules/diagnostics-types.d.ts +118 -0
  60. package/dist/modules/diagnostics-types.d.ts.map +1 -0
  61. package/dist/modules/diagnostics-types.js +16 -0
  62. package/dist/modules/diagnostics-types.js.map +1 -0
  63. package/dist/modules/diagnostics.d.ts +64 -0
  64. package/dist/modules/diagnostics.d.ts.map +1 -0
  65. package/dist/modules/diagnostics.js +206 -0
  66. package/dist/modules/diagnostics.js.map +1 -0
  67. package/dist/modules/discovery.d.ts +152 -0
  68. package/dist/modules/discovery.d.ts.map +1 -0
  69. package/dist/modules/discovery.js +100 -0
  70. package/dist/modules/discovery.js.map +1 -0
  71. package/dist/modules/fleets.d.ts +82 -0
  72. package/dist/modules/fleets.d.ts.map +1 -0
  73. package/dist/modules/fleets.js +33 -0
  74. package/dist/modules/fleets.js.map +1 -0
  75. package/dist/modules/lease-manager.d.ts +119 -0
  76. package/dist/modules/lease-manager.d.ts.map +1 -0
  77. package/dist/modules/lease-manager.js +242 -0
  78. package/dist/modules/lease-manager.js.map +1 -0
  79. package/dist/modules/leases.d.ts +70 -0
  80. package/dist/modules/leases.d.ts.map +1 -0
  81. package/dist/modules/leases.js +51 -0
  82. package/dist/modules/leases.js.map +1 -0
  83. package/dist/modules/operators.d.ts +176 -0
  84. package/dist/modules/operators.d.ts.map +1 -0
  85. package/dist/modules/operators.js +133 -0
  86. package/dist/modules/operators.js.map +1 -0
  87. package/dist/modules/providers.d.ts +141 -0
  88. package/dist/modules/providers.d.ts.map +1 -0
  89. package/dist/modules/providers.js +118 -0
  90. package/dist/modules/providers.js.map +1 -0
  91. package/dist/modules/quota.d.ts +102 -0
  92. package/dist/modules/quota.d.ts.map +1 -0
  93. package/dist/modules/quota.js +135 -0
  94. package/dist/modules/quota.js.map +1 -0
  95. package/dist/modules/reactions.d.ts +141 -0
  96. package/dist/modules/reactions.d.ts.map +1 -0
  97. package/dist/modules/reactions.js +122 -0
  98. package/dist/modules/reactions.js.map +1 -0
  99. package/dist/modules/register.d.ts +159 -0
  100. package/dist/modules/register.d.ts.map +1 -0
  101. package/dist/modules/register.js +239 -0
  102. package/dist/modules/register.js.map +1 -0
  103. package/dist/modules/sandbox.d.ts +106 -0
  104. package/dist/modules/sandbox.d.ts.map +1 -0
  105. package/dist/modules/sandbox.js +224 -0
  106. package/dist/modules/sandbox.js.map +1 -0
  107. package/dist/modules/streams.d.ts +81 -0
  108. package/dist/modules/streams.d.ts.map +1 -0
  109. package/dist/modules/streams.js +292 -0
  110. package/dist/modules/streams.js.map +1 -0
  111. package/dist/modules/tasks.d.ts +145 -0
  112. package/dist/modules/tasks.d.ts.map +1 -0
  113. package/dist/modules/tasks.js +165 -0
  114. package/dist/modules/tasks.js.map +1 -0
  115. package/dist/modules/telemetry.d.ts +137 -0
  116. package/dist/modules/telemetry.d.ts.map +1 -0
  117. package/dist/modules/telemetry.js +203 -0
  118. package/dist/modules/telemetry.js.map +1 -0
  119. package/dist/modules/workspace.d.ts +180 -0
  120. package/dist/modules/workspace.d.ts.map +1 -0
  121. package/dist/modules/workspace.js +157 -0
  122. package/dist/modules/workspace.js.map +1 -0
  123. package/dist/quickstart-join.d.ts +56 -0
  124. package/dist/quickstart-join.d.ts.map +1 -0
  125. package/dist/quickstart-join.js +116 -0
  126. package/dist/quickstart-join.js.map +1 -0
  127. package/dist/quickstart.d.ts +137 -0
  128. package/dist/quickstart.d.ts.map +1 -0
  129. package/dist/quickstart.js +292 -0
  130. package/dist/quickstart.js.map +1 -0
  131. package/dist/retry.d.ts +88 -0
  132. package/dist/retry.d.ts.map +1 -0
  133. package/dist/retry.js +152 -0
  134. package/dist/retry.js.map +1 -0
  135. package/dist/types.d.ts +447 -0
  136. package/dist/types.d.ts.map +1 -0
  137. package/dist/types.js +10 -0
  138. package/dist/types.js.map +1 -0
  139. package/dist/utils.d.ts +88 -0
  140. package/dist/utils.d.ts.map +1 -0
  141. package/dist/utils.js +199 -0
  142. package/dist/utils.js.map +1 -0
  143. package/package.json +215 -0
@@ -0,0 +1,195 @@
1
+ /**
2
+ * Cross-plane orchestration — unified ShardLink + SignalHub helpers.
3
+ *
4
+ * Agents often coordinate two planes:
5
+ * - **ShardLink** (this repo) — task orchestration, reactions, receipts.
6
+ * - **SignalHub** — signal marketplace where agents buy/sell data streams.
7
+ *
8
+ * The ShardLink control-plane already ships "bridge" endpoints for
9
+ * cross-plane settlement (`/v1/workspaces/:slug/receipts/bridge`,
10
+ * `/v1/workspaces/:slug/bridge/health`). This module wraps them, plus a
11
+ * caller-provided **SignalHub adapter** interface so a host application
12
+ * can plug its SignalHub SDK in without this package taking a direct
13
+ * dependency on the separate repo.
14
+ *
15
+ * @packageDocumentation
16
+ */
17
+ /** Cross-plane orchestrator. */
18
+ export class CrossPlaneClient {
19
+ options;
20
+ constructor(options) {
21
+ this.options = options;
22
+ }
23
+ /**
24
+ * Acquire a signal from SignalHub and bind it to a ShardLink task.
25
+ *
26
+ * Requires a `signalHub` adapter to be configured. Throws
27
+ * {@link SignalHubNotConfiguredError} if one wasn't provided.
28
+ *
29
+ * @example
30
+ * ```ts
31
+ * const bound = await crossPlane.acquireSignalForTask({
32
+ * signalContract: "weather.US-W.v1",
33
+ * workspaceSlug: "ws_1",
34
+ * taskId: "t_42",
35
+ * budgetUsdCents: 250
36
+ * });
37
+ * ```
38
+ */
39
+ async acquireSignalForTask(input) {
40
+ if (!this.options.signalHub) {
41
+ throw new SignalHubNotConfiguredError();
42
+ }
43
+ const signal = await this.options.signalHub.acquireSignal({
44
+ signalContract: input.signalContract,
45
+ budgetUsdCents: input.budgetUsdCents,
46
+ ...(input.metadata ? { metadata: input.metadata } : {})
47
+ });
48
+ let bridgeReceipt;
49
+ try {
50
+ bridgeReceipt = await this.getTaskStatus(input.workspaceSlug, input.taskId);
51
+ }
52
+ catch {
53
+ // Status endpoint is best-effort — not all workspaces emit bridge receipts.
54
+ }
55
+ return bridgeReceipt !== undefined ? { signal, bridgeReceipt } : { signal };
56
+ }
57
+ /** List bridge receipts for a workspace (paginated). */
58
+ async listBridgeReceipts(input) {
59
+ const params = new URLSearchParams();
60
+ if (input.cursor !== undefined)
61
+ params.set("cursor", String(input.cursor));
62
+ if (input.limit !== undefined)
63
+ params.set("limit", String(input.limit));
64
+ const payload = await this.options.http.request({
65
+ path: `/v1/workspaces/${encodeURIComponent(input.workspaceSlug)}/receipts/bridge`,
66
+ operation: "bridge-receipts-list",
67
+ headers: this.options.http.bearerHeaders(this.options.actorSessionToken),
68
+ params
69
+ });
70
+ return payload.receipts ?? [];
71
+ }
72
+ /** Fetch a single bridge receipt by id. */
73
+ async getBridgeReceipt(input) {
74
+ return this.options.http.request({
75
+ path: `/v1/workspaces/${encodeURIComponent(input.workspaceSlug)}/receipts/bridge/${encodeURIComponent(input.receiptId)}`,
76
+ operation: "bridge-receipt-get",
77
+ headers: this.options.http.bearerHeaders(this.options.actorSessionToken)
78
+ });
79
+ }
80
+ /** Fetch the ShardLink-side status projection for a task (bridge-aware). */
81
+ async getTaskStatus(workspaceSlug, taskId) {
82
+ return this.options.http.request({
83
+ path: `/v1/workspaces/${encodeURIComponent(workspaceSlug)}/tasks/${encodeURIComponent(taskId)}/status`,
84
+ operation: "bridge-task-status",
85
+ headers: this.options.http.bearerHeaders(this.options.actorSessionToken)
86
+ });
87
+ }
88
+ /** Fetch the ShardLink-side status projection for an objective. */
89
+ async getObjectiveStatus(workspaceSlug, objectiveId) {
90
+ return this.options.http.request({
91
+ path: `/v1/workspaces/${encodeURIComponent(workspaceSlug)}/objectives/${encodeURIComponent(objectiveId)}/status`,
92
+ operation: "bridge-objective-status",
93
+ headers: this.options.http.bearerHeaders(this.options.actorSessionToken)
94
+ });
95
+ }
96
+ /** Bridge health probe — quick confirmation ShardLink ↔ SignalHub are linked. */
97
+ async bridgeHealth(workspaceSlug) {
98
+ return this.options.http.request({
99
+ path: `/v1/workspaces/${encodeURIComponent(workspaceSlug)}/bridge/health`,
100
+ operation: "bridge-health",
101
+ headers: this.options.http.bearerHeaders(this.options.actorSessionToken)
102
+ });
103
+ }
104
+ /**
105
+ * Unified activity feed — merges ShardLink stream events with SignalHub
106
+ * events (if the adapter exposes them) into a single async iterable.
107
+ *
108
+ * @example
109
+ * ```ts
110
+ * for await (const event of crossPlane.activityFeed()) {
111
+ * console.log(event.plane, event.type, event.payload);
112
+ * }
113
+ * ```
114
+ */
115
+ activityFeed() {
116
+ const queue = [];
117
+ const waiters = [];
118
+ let closed = false;
119
+ const push = (event) => {
120
+ if (closed)
121
+ return;
122
+ if (waiters.length > 0) {
123
+ const resolve = waiters.shift();
124
+ resolve?.({ value: event, done: false });
125
+ }
126
+ else {
127
+ queue.push(event);
128
+ }
129
+ };
130
+ const unsubShardLink = this.options.shardLinkStream?.onAny((event) => {
131
+ push({
132
+ plane: "shardlink",
133
+ type: event.type,
134
+ payload: event.payload,
135
+ at: event.at ?? Date.now()
136
+ });
137
+ });
138
+ const unsubSignal = this.options.signalHub?.events?.((event) => {
139
+ push({
140
+ plane: event.plane,
141
+ type: event.type,
142
+ payload: event.payload,
143
+ at: event.at ?? Date.now()
144
+ });
145
+ });
146
+ return {
147
+ [Symbol.asyncIterator]() {
148
+ return {
149
+ next() {
150
+ if (queue.length > 0) {
151
+ const value = queue.shift();
152
+ return Promise.resolve({ value, done: false });
153
+ }
154
+ if (closed) {
155
+ return Promise.resolve({
156
+ value: undefined,
157
+ done: true
158
+ });
159
+ }
160
+ return new Promise((resolve) => waiters.push(resolve));
161
+ },
162
+ return() {
163
+ closed = true;
164
+ try {
165
+ unsubShardLink?.();
166
+ }
167
+ catch {
168
+ // ignore
169
+ }
170
+ try {
171
+ unsubSignal?.();
172
+ }
173
+ catch {
174
+ // ignore
175
+ }
176
+ waiters.forEach((resolve) => resolve({ value: undefined, done: true }));
177
+ waiters.length = 0;
178
+ return Promise.resolve({
179
+ value: undefined,
180
+ done: true
181
+ });
182
+ }
183
+ };
184
+ }
185
+ };
186
+ }
187
+ }
188
+ /** Thrown when a SignalHub-requiring method is called without an adapter. */
189
+ export class SignalHubNotConfiguredError extends Error {
190
+ constructor() {
191
+ super("[CrossPlaneClient] SignalHub adapter required. Pass `signalHub` into the client options.");
192
+ this.name = "SignalHubNotConfiguredError";
193
+ }
194
+ }
195
+ //# sourceMappingURL=cross-plane.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"cross-plane.js","sourceRoot":"","sources":["../../src/modules/cross-plane.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,130 @@
1
+ /**
2
+ * Agent dashboard helpers.
3
+ *
4
+ * The audit doc's T5.2 proposes `/v1/agents/:identity/metrics`,
5
+ * `/history`, and `/health` endpoints. The control-plane today ships
6
+ * `/v1/agents/:identity/reputation` and `/v1/agents/:identity/passport/public`.
7
+ * This module composes those two live surfaces (plus workspace metering
8
+ * + health probes) into a single dashboard projection so operators have
9
+ * one call that returns everything their fleet UI needs.
10
+ *
11
+ * When the server ships the proposed dedicated endpoints, this module's
12
+ * internal lookups will be forwarded to them transparently.
13
+ *
14
+ * @packageDocumentation
15
+ */
16
+ import type { HttpContext } from "../utils.js";
17
+ import type { DiscoveryClient } from "./discovery.js";
18
+ /** Reputation projection as returned by `/v1/agents/:identity/reputation`. */
19
+ export interface AgentReputation {
20
+ identity: string;
21
+ score: number;
22
+ summary: Record<string, unknown>;
23
+ runtimeRegistration: Record<string, unknown> | null;
24
+ modelVersion: string;
25
+ workspaceBreakdown?: Array<Record<string, unknown>>;
26
+ recentReceipts?: Array<Record<string, unknown>>;
27
+ }
28
+ /** Metrics projection returned by {@link DashboardClient.metrics}. */
29
+ export interface AgentMetrics {
30
+ identity: string;
31
+ reputationScore: number;
32
+ completionRate: number;
33
+ /** Number of task completions over the agent's lifetime. */
34
+ taskCompletions: number;
35
+ /** Number of task claims (includes completions + in-progress). */
36
+ taskClaims: number;
37
+ /** Active lease approvals observed. */
38
+ leaseApprovals: number;
39
+ /** Lease revocations observed. */
40
+ leaseRevocations: number;
41
+ /** Dispute signals raised against this agent. */
42
+ disputeSignals: number;
43
+ /** Average number of hours a lease stays healthy. */
44
+ leaseTenureHoursAvg: number;
45
+ /** Total receipt volume (workspace units). */
46
+ receiptVolume: number;
47
+ /** Trust tier at last passport update. */
48
+ trustTier: "sandbox" | "verified" | "trusted";
49
+ /** Proof level at last passport update. */
50
+ proofLevel: "P0" | "P1" | "P2";
51
+ /** Whether the agent qualifies for payout. */
52
+ payoutEligible: boolean;
53
+ /** Human-readable blockers keeping the agent out of higher lanes. */
54
+ blockedReasons: string[];
55
+ /** Timestamp (ISO) when the underlying passport was issued. */
56
+ passportIssuedAt: string;
57
+ }
58
+ /** Health projection returned by {@link DashboardClient.health}. */
59
+ export interface AgentHealth {
60
+ identity: string;
61
+ /** Aggregate status — `ok` when every probe passes. */
62
+ ok: boolean;
63
+ /** Reputation-model health (did the server answer within SLA?). */
64
+ reputationOk: boolean;
65
+ /** Whether the agent has an issuable passport right now. */
66
+ passportIssuable: boolean;
67
+ /** Platform-level readiness report (from `/health/ready`). */
68
+ platform: {
69
+ ok: boolean;
70
+ depth: "shallow" | "deep";
71
+ details: Record<string, {
72
+ ok: boolean;
73
+ message?: string;
74
+ }>;
75
+ };
76
+ /** Timestamp (ms) when the aggregate was computed. */
77
+ at: number;
78
+ }
79
+ /** Paginated history projection returned by {@link DashboardClient.history}. */
80
+ export interface AgentHistoryPage {
81
+ identity: string;
82
+ /** Recent receipts the reputation endpoint surfaces. */
83
+ recentReceipts: Array<Record<string, unknown>>;
84
+ /** Workspace-scoped breakdown. */
85
+ workspaceBreakdown: Array<Record<string, unknown>>;
86
+ /** Whether there's more data beyond this page (always false until the server paginates). */
87
+ hasMore: boolean;
88
+ }
89
+ /** Options for {@link DashboardClient}. */
90
+ export interface DashboardClientOptions {
91
+ http: HttpContext;
92
+ discovery: DiscoveryClient;
93
+ }
94
+ /** Agent-identity dashboard client. */
95
+ export declare class DashboardClient {
96
+ private readonly options;
97
+ constructor(options: DashboardClientOptions);
98
+ /**
99
+ * Fetch the raw reputation projection. Authenticated.
100
+ *
101
+ * @example
102
+ * ```ts
103
+ * const rep = await dashboard.reputation("wallet:eip155:1:0xabc");
104
+ * console.log(rep.score, rep.modelVersion);
105
+ * ```
106
+ */
107
+ reputation(identity: string): Promise<AgentReputation>;
108
+ /**
109
+ * Aggregated dashboard metrics for a single agent.
110
+ *
111
+ * Today this composes `/passport/public` + `/reputation`; the server's
112
+ * native metrics endpoint is a T5.2 follow-up. The projection shape is
113
+ * stable, so consumer code won't need to change when the dedicated
114
+ * endpoint lands.
115
+ */
116
+ metrics(identity: string): Promise<AgentMetrics>;
117
+ /**
118
+ * Per-agent health — reputation service answered, passport issuable,
119
+ * platform probes pass.
120
+ */
121
+ health(identity: string): Promise<AgentHealth>;
122
+ /**
123
+ * Recent activity timeline — receipts + workspace breakdown.
124
+ *
125
+ * `hasMore` is always false until the server paginates history natively.
126
+ */
127
+ history(identity: string): Promise<AgentHistoryPage>;
128
+ private platformProbe;
129
+ }
130
+ //# sourceMappingURL=dashboard.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dashboard.d.ts","sourceRoot":"","sources":["../../src/modules/dashboard.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Agent dashboard helpers.
3
+ *
4
+ * The audit doc's T5.2 proposes `/v1/agents/:identity/metrics`,
5
+ * `/history`, and `/health` endpoints. The control-plane today ships
6
+ * `/v1/agents/:identity/reputation` and `/v1/agents/:identity/passport/public`.
7
+ * This module composes those two live surfaces (plus workspace metering
8
+ * + health probes) into a single dashboard projection so operators have
9
+ * one call that returns everything their fleet UI needs.
10
+ *
11
+ * When the server ships the proposed dedicated endpoints, this module's
12
+ * internal lookups will be forwarded to them transparently.
13
+ *
14
+ * @packageDocumentation
15
+ */
16
+ /** Agent-identity dashboard client. */
17
+ export class DashboardClient {
18
+ options;
19
+ constructor(options) {
20
+ this.options = options;
21
+ }
22
+ /**
23
+ * Fetch the raw reputation projection. Authenticated.
24
+ *
25
+ * @example
26
+ * ```ts
27
+ * const rep = await dashboard.reputation("wallet:eip155:1:0xabc");
28
+ * console.log(rep.score, rep.modelVersion);
29
+ * ```
30
+ */
31
+ async reputation(identity) {
32
+ return this.options.http.request({
33
+ path: `/v1/agents/${encodeURIComponent(identity)}/reputation`,
34
+ operation: "dashboard-reputation",
35
+ headers: await this.options.http.requiredAuthHeaders()
36
+ });
37
+ }
38
+ /**
39
+ * Aggregated dashboard metrics for a single agent.
40
+ *
41
+ * Today this composes `/passport/public` + `/reputation`; the server's
42
+ * native metrics endpoint is a T5.2 follow-up. The projection shape is
43
+ * stable, so consumer code won't need to change when the dedicated
44
+ * endpoint lands.
45
+ */
46
+ async metrics(identity) {
47
+ const [passport, reputation] = await Promise.all([
48
+ this.options.discovery.getPublicAgentPassport(identity),
49
+ this.reputation(identity).catch(() => null)
50
+ ]);
51
+ const p = passport.passport;
52
+ const score = reputation?.score ?? p.trust.reputationScore;
53
+ return {
54
+ identity: p.identity,
55
+ reputationScore: score,
56
+ completionRate: p.summary.completionRate,
57
+ taskCompletions: p.summary.taskCompletions,
58
+ taskClaims: p.summary.taskClaims,
59
+ leaseApprovals: p.summary.leaseApprovals,
60
+ leaseRevocations: p.summary.leaseRevocations,
61
+ disputeSignals: p.summary.disputeSignals,
62
+ leaseTenureHoursAvg: p.summary.leaseTenureHoursAvg,
63
+ receiptVolume: p.summary.receiptVolume,
64
+ trustTier: p.trust.trustTier,
65
+ proofLevel: p.trust.proofLevel,
66
+ payoutEligible: p.qualification.payoutEligible,
67
+ blockedReasons: p.qualification.blockedReasons,
68
+ passportIssuedAt: p.issuedAt
69
+ };
70
+ }
71
+ /**
72
+ * Per-agent health — reputation service answered, passport issuable,
73
+ * platform probes pass.
74
+ */
75
+ async health(identity) {
76
+ const now = Date.now();
77
+ const [reputation, passport, platform] = await Promise.all([
78
+ this.reputation(identity).then(() => true, () => false),
79
+ this.options.discovery.getPublicAgentPassport(identity).then(() => true, () => false),
80
+ this.platformProbe()
81
+ ]);
82
+ return {
83
+ identity,
84
+ reputationOk: reputation,
85
+ passportIssuable: passport,
86
+ platform,
87
+ ok: reputation && passport && platform.ok,
88
+ at: now
89
+ };
90
+ }
91
+ /**
92
+ * Recent activity timeline — receipts + workspace breakdown.
93
+ *
94
+ * `hasMore` is always false until the server paginates history natively.
95
+ */
96
+ async history(identity) {
97
+ const reputation = await this.reputation(identity);
98
+ return {
99
+ identity,
100
+ recentReceipts: reputation.recentReceipts ?? [],
101
+ workspaceBreakdown: reputation.workspaceBreakdown ?? [],
102
+ hasMore: false
103
+ };
104
+ }
105
+ async platformProbe() {
106
+ try {
107
+ const result = await this.options.http.request({
108
+ path: "/health/ready",
109
+ operation: "dashboard-platform-probe",
110
+ headers: await this.options.http.optionalAuthHeaders(),
111
+ params: new URLSearchParams({ depth: "shallow" })
112
+ });
113
+ return result;
114
+ }
115
+ catch {
116
+ return { ok: false, depth: "shallow", details: {} };
117
+ }
118
+ }
119
+ }
120
+ //# sourceMappingURL=dashboard.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"dashboard.js","sourceRoot":"","sources":["../../src/modules/dashboard.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,120 @@
1
+ /**
2
+ * Graceful degradation contract.
3
+ *
4
+ * When things go wrong — lease expires mid-task, spend cap hits, platform
5
+ * degrades, task times out — the agent needs a predictable, user-declared
6
+ * policy for how to react. The {@link DegradationContract} describes those
7
+ * choices; {@link DegradationEnforcer} applies them against a running
8
+ * lease manager / task scheduler.
9
+ *
10
+ * This module does not poll the server or send requests on its own. It
11
+ * wires together the state signals the rest of the SDK already produces
12
+ * (lease events from {@link LeaseManager}, timers, platform-status probes
13
+ * from {@link DiagnosticsClient}) and calls back into the host app.
14
+ *
15
+ * @packageDocumentation
16
+ */
17
+ import type { LeaseSnapshot } from "./lease-manager.js";
18
+ /** Strategy when the lease expires while tasks are in flight. */
19
+ export type LeaseExpiryStrategy = "pause_and_retry" | "abort_gracefully" | "request_extension";
20
+ /** Strategy when the spend cap is hit. */
21
+ export type SpendCapStrategy = "pause_new_claims" | "complete_current_only" | "shutdown";
22
+ /** Strategy when the platform reports degraded / unavailable. */
23
+ export type PlatformDegradedStrategy = "retry_with_backoff" | "switch_workspace" | "hibernate";
24
+ /** Strategy when a claimed task exceeds its max hold duration. */
25
+ export type TaskTimeoutStrategy = "release_claim" | "request_extension" | "mark_failed";
26
+ /** Full declarative contract. Ships with a sensible default; agents override per-workspace. */
27
+ export interface DegradationContract {
28
+ leaseExpiry: LeaseExpiryStrategy;
29
+ spendCapHit: SpendCapStrategy;
30
+ platformDegraded: PlatformDegradedStrategy;
31
+ /** Max milliseconds to hold a claimed task without progress before `taskTimeoutAction` fires. */
32
+ taskTimeoutMs: number;
33
+ taskTimeoutAction: TaskTimeoutStrategy;
34
+ }
35
+ /** Default contract — conservative, pause-and-retry oriented. */
36
+ export declare const DEFAULT_DEGRADATION: DegradationContract;
37
+ /** Context passed to the enforcement callbacks. */
38
+ export interface DegradationContext {
39
+ /** Reason code for the transition. */
40
+ reason: "lease_expiring" | "lease_revoked" | "spend_cap_hit" | "platform_degraded" | "platform_recovered" | "task_timeout";
41
+ /** The strategy selected from the contract. */
42
+ strategy: LeaseExpiryStrategy | SpendCapStrategy | PlatformDegradedStrategy | TaskTimeoutStrategy;
43
+ /** Optional structured details (lease snapshot, task id, etc). */
44
+ details?: Record<string, unknown>;
45
+ }
46
+ /** Callbacks the host app implements to react to the enforcer's decisions. */
47
+ export interface DegradationHandlers {
48
+ /** Stop accepting new task claims. The enforcer calls this once per transition. */
49
+ pauseClaims?: (ctx: DegradationContext) => void | Promise<void>;
50
+ /** Resume accepting new task claims after a pause. */
51
+ resumeClaims?: (ctx: DegradationContext) => void | Promise<void>;
52
+ /** Start a lease-renewal request (host owns the call so idempotency keys stay under its control). */
53
+ requestLeaseExtension?: (ctx: DegradationContext) => void | Promise<void>;
54
+ /** Drop the claim on a stalled task back to the workspace. */
55
+ releaseTaskClaim?: (taskId: string, ctx: DegradationContext) => void | Promise<void>;
56
+ /** Ask the server to mark a stalled task as failed. */
57
+ markTaskFailed?: (taskId: string, ctx: DegradationContext) => void | Promise<void>;
58
+ /** Begin a graceful shutdown. */
59
+ shutdown?: (ctx: DegradationContext) => void | Promise<void>;
60
+ /** Hibernate: sleep the agent until a host-defined wake signal. */
61
+ hibernate?: (ctx: DegradationContext) => void | Promise<void>;
62
+ /** Re-run workspace discovery and switch to a healthier target. */
63
+ switchWorkspace?: (ctx: DegradationContext) => void | Promise<void>;
64
+ }
65
+ /** Options for the enforcer. */
66
+ export interface DegradationEnforcerOptions {
67
+ contract?: DegradationContract;
68
+ handlers: DegradationHandlers;
69
+ }
70
+ /**
71
+ * Applies a {@link DegradationContract} to the lifecycle signals emitted by
72
+ * the rest of the SDK. Each signal maps to exactly one handler invocation
73
+ * so the host app can reliably react.
74
+ *
75
+ * @example
76
+ * ```ts
77
+ * const enforcer = new DegradationEnforcer({
78
+ * contract: { ...DEFAULT_DEGRADATION, spendCapHit: "shutdown" },
79
+ * handlers: {
80
+ * pauseClaims: () => scheduler.pause(),
81
+ * resumeClaims: () => scheduler.resume(),
82
+ * requestLeaseExtension: () => leaseClient.request(...),
83
+ * shutdown: () => process.exit(0)
84
+ * }
85
+ * });
86
+ *
87
+ * lease.onBudgetThreshold(100, () => enforcer.onSpendCapHit(lease.status()));
88
+ * ```
89
+ */
90
+ export declare class DegradationEnforcer {
91
+ readonly contract: DegradationContract;
92
+ private readonly handlers;
93
+ private readonly inFlight;
94
+ private paused;
95
+ constructor(options: DegradationEnforcerOptions);
96
+ /** Mark a task as in-flight so timeout detection can watch it. */
97
+ trackClaim(taskId: string): void;
98
+ /** Clear a task (because it completed). */
99
+ completeClaim(taskId: string): void;
100
+ /** Wire this into {@link LeaseManager.enableAutoRenew}'s `onFailed` or to a `lease_expiring` handler. */
101
+ onLeaseExpiring(snapshot: LeaseSnapshot): Promise<void>;
102
+ /** Call after a successful lease renewal so claim flow resumes. */
103
+ onLeaseRenewed(snapshot: LeaseSnapshot): Promise<void>;
104
+ /** Wire to {@link LeaseManager.onBudgetThreshold}(100). */
105
+ onSpendCapHit(snapshot: LeaseSnapshot): Promise<void>;
106
+ /** Wire to {@link DiagnosticsClient.platformStatus} when `ok: false`. */
107
+ onPlatformDegraded(details?: Record<string, unknown>): Promise<void>;
108
+ /** Host calls this when the platform recovers (next successful heartbeat). */
109
+ onPlatformRecovered(): Promise<void>;
110
+ private onTaskTimeout;
111
+ private pause;
112
+ private resume;
113
+ /** Currently accepting new claims? */
114
+ isAcceptingClaims(): boolean;
115
+ /** How many tasks are tracked as in-flight right now. */
116
+ inFlightCount(): number;
117
+ /** Clear all timers — call on shutdown. */
118
+ dispose(): void;
119
+ }
120
+ //# sourceMappingURL=degradation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"degradation.d.ts","sourceRoot":"","sources":["../../src/modules/degradation.ts"],"names":[],"mappings":"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"}