@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.
- package/LICENSE +202 -0
- package/README.md +129 -0
- package/dist/client-quick-join.d.ts +38 -0
- package/dist/client-quick-join.d.ts.map +1 -0
- package/dist/client-quick-join.js +141 -0
- package/dist/client-quick-join.js.map +1 -0
- package/dist/client.d.ts +134 -0
- package/dist/client.d.ts.map +1 -0
- package/dist/client.js +190 -0
- package/dist/client.js.map +1 -0
- package/dist/errors.d.ts +126 -0
- package/dist/errors.d.ts.map +1 -0
- package/dist/errors.js +330 -0
- package/dist/errors.js.map +1 -0
- package/dist/index.d.ts +47 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +47 -0
- package/dist/index.js.map +1 -0
- package/dist/modules/a2a.d.ts +42 -0
- package/dist/modules/a2a.d.ts.map +1 -0
- package/dist/modules/a2a.js +47 -0
- package/dist/modules/a2a.js.map +1 -0
- package/dist/modules/agents.d.ts +100 -0
- package/dist/modules/agents.d.ts.map +1 -0
- package/dist/modules/agents.js +85 -0
- package/dist/modules/agents.js.map +1 -0
- package/dist/modules/auth.d.ts +49 -0
- package/dist/modules/auth.d.ts.map +1 -0
- package/dist/modules/auth.js +69 -0
- package/dist/modules/auth.js.map +1 -0
- package/dist/modules/billing.d.ts +254 -0
- package/dist/modules/billing.d.ts.map +1 -0
- package/dist/modules/billing.js +203 -0
- package/dist/modules/billing.js.map +1 -0
- package/dist/modules/clans.d.ts +73 -0
- package/dist/modules/clans.d.ts.map +1 -0
- package/dist/modules/clans.js +94 -0
- package/dist/modules/clans.js.map +1 -0
- package/dist/modules/compliance.d.ts +97 -0
- package/dist/modules/compliance.d.ts.map +1 -0
- package/dist/modules/compliance.js +227 -0
- package/dist/modules/compliance.js.map +1 -0
- package/dist/modules/cross-plane.d.ts +164 -0
- package/dist/modules/cross-plane.d.ts.map +1 -0
- package/dist/modules/cross-plane.js +195 -0
- package/dist/modules/cross-plane.js.map +1 -0
- package/dist/modules/dashboard.d.ts +130 -0
- package/dist/modules/dashboard.d.ts.map +1 -0
- package/dist/modules/dashboard.js +120 -0
- package/dist/modules/dashboard.js.map +1 -0
- package/dist/modules/degradation.d.ts +120 -0
- package/dist/modules/degradation.d.ts.map +1 -0
- package/dist/modules/degradation.js +205 -0
- package/dist/modules/degradation.js.map +1 -0
- package/dist/modules/diagnostics-checks.d.ts +32 -0
- package/dist/modules/diagnostics-checks.d.ts.map +1 -0
- package/dist/modules/diagnostics-checks.js +231 -0
- package/dist/modules/diagnostics-checks.js.map +1 -0
- package/dist/modules/diagnostics-types.d.ts +118 -0
- package/dist/modules/diagnostics-types.d.ts.map +1 -0
- package/dist/modules/diagnostics-types.js +16 -0
- package/dist/modules/diagnostics-types.js.map +1 -0
- package/dist/modules/diagnostics.d.ts +64 -0
- package/dist/modules/diagnostics.d.ts.map +1 -0
- package/dist/modules/diagnostics.js +206 -0
- package/dist/modules/diagnostics.js.map +1 -0
- package/dist/modules/discovery.d.ts +152 -0
- package/dist/modules/discovery.d.ts.map +1 -0
- package/dist/modules/discovery.js +100 -0
- package/dist/modules/discovery.js.map +1 -0
- package/dist/modules/fleets.d.ts +82 -0
- package/dist/modules/fleets.d.ts.map +1 -0
- package/dist/modules/fleets.js +33 -0
- package/dist/modules/fleets.js.map +1 -0
- package/dist/modules/lease-manager.d.ts +119 -0
- package/dist/modules/lease-manager.d.ts.map +1 -0
- package/dist/modules/lease-manager.js +242 -0
- package/dist/modules/lease-manager.js.map +1 -0
- package/dist/modules/leases.d.ts +70 -0
- package/dist/modules/leases.d.ts.map +1 -0
- package/dist/modules/leases.js +51 -0
- package/dist/modules/leases.js.map +1 -0
- package/dist/modules/operators.d.ts +176 -0
- package/dist/modules/operators.d.ts.map +1 -0
- package/dist/modules/operators.js +133 -0
- package/dist/modules/operators.js.map +1 -0
- package/dist/modules/providers.d.ts +141 -0
- package/dist/modules/providers.d.ts.map +1 -0
- package/dist/modules/providers.js +118 -0
- package/dist/modules/providers.js.map +1 -0
- package/dist/modules/quota.d.ts +102 -0
- package/dist/modules/quota.d.ts.map +1 -0
- package/dist/modules/quota.js +135 -0
- package/dist/modules/quota.js.map +1 -0
- package/dist/modules/reactions.d.ts +141 -0
- package/dist/modules/reactions.d.ts.map +1 -0
- package/dist/modules/reactions.js +122 -0
- package/dist/modules/reactions.js.map +1 -0
- package/dist/modules/register.d.ts +159 -0
- package/dist/modules/register.d.ts.map +1 -0
- package/dist/modules/register.js +239 -0
- package/dist/modules/register.js.map +1 -0
- package/dist/modules/sandbox.d.ts +106 -0
- package/dist/modules/sandbox.d.ts.map +1 -0
- package/dist/modules/sandbox.js +224 -0
- package/dist/modules/sandbox.js.map +1 -0
- package/dist/modules/streams.d.ts +81 -0
- package/dist/modules/streams.d.ts.map +1 -0
- package/dist/modules/streams.js +292 -0
- package/dist/modules/streams.js.map +1 -0
- package/dist/modules/tasks.d.ts +145 -0
- package/dist/modules/tasks.d.ts.map +1 -0
- package/dist/modules/tasks.js +165 -0
- package/dist/modules/tasks.js.map +1 -0
- package/dist/modules/telemetry.d.ts +137 -0
- package/dist/modules/telemetry.d.ts.map +1 -0
- package/dist/modules/telemetry.js +203 -0
- package/dist/modules/telemetry.js.map +1 -0
- package/dist/modules/workspace.d.ts +180 -0
- package/dist/modules/workspace.d.ts.map +1 -0
- package/dist/modules/workspace.js +157 -0
- package/dist/modules/workspace.js.map +1 -0
- package/dist/quickstart-join.d.ts +56 -0
- package/dist/quickstart-join.d.ts.map +1 -0
- package/dist/quickstart-join.js +116 -0
- package/dist/quickstart-join.js.map +1 -0
- package/dist/quickstart.d.ts +137 -0
- package/dist/quickstart.d.ts.map +1 -0
- package/dist/quickstart.js +292 -0
- package/dist/quickstart.js.map +1 -0
- package/dist/retry.d.ts +88 -0
- package/dist/retry.d.ts.map +1 -0
- package/dist/retry.js +152 -0
- package/dist/retry.js.map +1 -0
- package/dist/types.d.ts +447 -0
- package/dist/types.d.ts.map +1 -0
- package/dist/types.js +10 -0
- package/dist/types.js.map +1 -0
- package/dist/utils.d.ts +88 -0
- package/dist/utils.d.ts.map +1 -0
- package/dist/utils.js +199 -0
- package/dist/utils.js.map +1 -0
- package/package.json +215 -0
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Diagnostics + preflight client.
|
|
3
|
+
*
|
|
4
|
+
* `DiagnosticsClient.preflight()` answers the question every agent wants to
|
|
5
|
+
* ask at startup: "am I ready to do work?". It probes auth, lease state,
|
|
6
|
+
* billing envelope, platform health, and declared capabilities, and
|
|
7
|
+
* returns a structured report with per-check status + suggested auto-fixes.
|
|
8
|
+
*
|
|
9
|
+
* Unlike the other modules, diagnostics is deliberately *lenient*: a
|
|
10
|
+
* single failed check doesn't throw, because a caller almost always wants
|
|
11
|
+
* to see the full report before deciding how to react.
|
|
12
|
+
*
|
|
13
|
+
* File layout — to keep each SDK module under the 400-line ceiling
|
|
14
|
+
* (CLAUDE.md §"Agent DX Rules"), the diagnostics surface spans three files;
|
|
15
|
+
* the public API is unchanged because this file re-exports every type:
|
|
16
|
+
*
|
|
17
|
+
* - `diagnostics-types.ts` — shared type definitions.
|
|
18
|
+
* - `diagnostics-checks.ts` — the pure, `this`-free preflight checks
|
|
19
|
+
* (lease / billing / capabilities / sandbox) + auto-fix suggestion logic.
|
|
20
|
+
* - `diagnostics.ts` (this file) — the `DiagnosticsClient` class and the
|
|
21
|
+
* async, network-touching checks (auth / connectivity / platform).
|
|
22
|
+
*
|
|
23
|
+
* @packageDocumentation
|
|
24
|
+
*/
|
|
25
|
+
import type { AutoFix, CheckResult, CheckStatus, DiagnosticsClientOptions, LogLevel, LogSink, PlatformHealth, PreflightCheckName, PreflightInput, PreflightResult } from "./diagnostics-types.js";
|
|
26
|
+
export type { AutoFix, CheckResult, CheckStatus, DiagnosticsClientOptions, LogLevel, LogSink, PlatformHealth, PreflightCheckName, PreflightInput, PreflightResult };
|
|
27
|
+
/** Diagnostics + preflight client. */
|
|
28
|
+
export declare class DiagnosticsClient {
|
|
29
|
+
private readonly options;
|
|
30
|
+
private readonly logSink;
|
|
31
|
+
constructor(options: DiagnosticsClientOptions);
|
|
32
|
+
/**
|
|
33
|
+
* Run the full preflight battery. Never throws — every failure is
|
|
34
|
+
* reflected in the returned report.
|
|
35
|
+
*
|
|
36
|
+
* @example
|
|
37
|
+
* ```ts
|
|
38
|
+
* const report = await diag.preflight({ lease, billing });
|
|
39
|
+
* if (!report.ready) {
|
|
40
|
+
* console.log("issues:", report.issues);
|
|
41
|
+
* }
|
|
42
|
+
* ```
|
|
43
|
+
*/
|
|
44
|
+
preflight(input?: PreflightInput): Promise<PreflightResult>;
|
|
45
|
+
/**
|
|
46
|
+
* Emit a heartbeat — a best-effort `GET /health/live` so dashboards can
|
|
47
|
+
* correlate "agent alive" with "platform alive".
|
|
48
|
+
*
|
|
49
|
+
* Returns `true` when the platform answered, `false` otherwise. Never
|
|
50
|
+
* throws.
|
|
51
|
+
*/
|
|
52
|
+
heartbeat(): Promise<boolean>;
|
|
53
|
+
/** Call `GET /health/ready?depth=deep` and return the structured report. */
|
|
54
|
+
platformStatus(depth?: "shallow" | "deep"): Promise<PlatformHealth>;
|
|
55
|
+
/**
|
|
56
|
+
* Emit a structured log entry. Defaults to stdout JSON but can be
|
|
57
|
+
* redirected to any sink by passing `logSink` at construction.
|
|
58
|
+
*/
|
|
59
|
+
log(level: LogLevel, message: string, meta?: Record<string, unknown>): void;
|
|
60
|
+
private checkAuth;
|
|
61
|
+
private checkConnectivity;
|
|
62
|
+
private checkPlatform;
|
|
63
|
+
}
|
|
64
|
+
//# sourceMappingURL=diagnostics.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../../src/modules/diagnostics.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAUH,OAAO,KAAK,EACV,OAAO,EACP,WAAW,EACX,WAAW,EACX,wBAAwB,EACxB,QAAQ,EACR,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,eAAe,EAChB,MAAM,wBAAwB,CAAC;AAKhC,YAAY,EACV,OAAO,EACP,WAAW,EACX,WAAW,EACX,wBAAwB,EACxB,QAAQ,EACR,OAAO,EACP,cAAc,EACd,kBAAkB,EAClB,cAAc,EACd,eAAe,EAChB,CAAC;AAUF,sCAAsC;AACtC,qBAAa,iBAAiB;IAEhB,OAAO,CAAC,QAAQ,CAAC,OAAO;IADpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAU;gBACL,OAAO,EAAE,wBAAwB;IAI9D;;;;;;;;;;;OAWG;IACG,SAAS,CAAC,KAAK,GAAE,cAAmB,GAAG,OAAO,CAAC,eAAe,CAAC;IAuCrE;;;;;;OAMG;IACG,SAAS,IAAI,OAAO,CAAC,OAAO,CAAC;IAanC,4EAA4E;IACtE,cAAc,CAAC,KAAK,GAAE,SAAS,GAAG,MAAkB,GAAG,OAAO,CAAC,cAAc,CAAC;IAWpF;;;OAGG;IACH,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI;YAS7D,SAAS;YA8BT,iBAAiB;YAuBjB,aAAa;CAkB5B"}
|
|
@@ -0,0 +1,206 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Diagnostics + preflight client.
|
|
3
|
+
*
|
|
4
|
+
* `DiagnosticsClient.preflight()` answers the question every agent wants to
|
|
5
|
+
* ask at startup: "am I ready to do work?". It probes auth, lease state,
|
|
6
|
+
* billing envelope, platform health, and declared capabilities, and
|
|
7
|
+
* returns a structured report with per-check status + suggested auto-fixes.
|
|
8
|
+
*
|
|
9
|
+
* Unlike the other modules, diagnostics is deliberately *lenient*: a
|
|
10
|
+
* single failed check doesn't throw, because a caller almost always wants
|
|
11
|
+
* to see the full report before deciding how to react.
|
|
12
|
+
*
|
|
13
|
+
* File layout — to keep each SDK module under the 400-line ceiling
|
|
14
|
+
* (CLAUDE.md §"Agent DX Rules"), the diagnostics surface spans three files;
|
|
15
|
+
* the public API is unchanged because this file re-exports every type:
|
|
16
|
+
*
|
|
17
|
+
* - `diagnostics-types.ts` — shared type definitions.
|
|
18
|
+
* - `diagnostics-checks.ts` — the pure, `this`-free preflight checks
|
|
19
|
+
* (lease / billing / capabilities / sandbox) + auto-fix suggestion logic.
|
|
20
|
+
* - `diagnostics.ts` (this file) — the `DiagnosticsClient` class and the
|
|
21
|
+
* async, network-touching checks (auth / connectivity / platform).
|
|
22
|
+
*
|
|
23
|
+
* @packageDocumentation
|
|
24
|
+
*/
|
|
25
|
+
import { AuthError, NetworkError, ShardLinkError } from "../errors.js";
|
|
26
|
+
import { checkBilling, checkCapabilities, checkLease, checkSandbox, suggestAutoFix } from "./diagnostics-checks.js";
|
|
27
|
+
const defaultLogSink = (entry) => {
|
|
28
|
+
try {
|
|
29
|
+
console.log(JSON.stringify(entry));
|
|
30
|
+
}
|
|
31
|
+
catch {
|
|
32
|
+
// ignore logging failures
|
|
33
|
+
}
|
|
34
|
+
};
|
|
35
|
+
/** Diagnostics + preflight client. */
|
|
36
|
+
export class DiagnosticsClient {
|
|
37
|
+
options;
|
|
38
|
+
logSink;
|
|
39
|
+
constructor(options) {
|
|
40
|
+
this.options = options;
|
|
41
|
+
this.logSink = options.logSink ?? defaultLogSink;
|
|
42
|
+
}
|
|
43
|
+
/**
|
|
44
|
+
* Run the full preflight battery. Never throws — every failure is
|
|
45
|
+
* reflected in the returned report.
|
|
46
|
+
*
|
|
47
|
+
* @example
|
|
48
|
+
* ```ts
|
|
49
|
+
* const report = await diag.preflight({ lease, billing });
|
|
50
|
+
* if (!report.ready) {
|
|
51
|
+
* console.log("issues:", report.issues);
|
|
52
|
+
* }
|
|
53
|
+
* ```
|
|
54
|
+
*/
|
|
55
|
+
async preflight(input = {}) {
|
|
56
|
+
const [auth, connectivity, platform] = await Promise.all([
|
|
57
|
+
this.checkAuth(),
|
|
58
|
+
this.checkConnectivity(),
|
|
59
|
+
this.checkPlatform()
|
|
60
|
+
]);
|
|
61
|
+
const lease = checkLease(input);
|
|
62
|
+
const billing = checkBilling(input);
|
|
63
|
+
const capabilities = checkCapabilities(input);
|
|
64
|
+
const sandbox = checkSandbox(input);
|
|
65
|
+
const checks = {
|
|
66
|
+
auth,
|
|
67
|
+
lease,
|
|
68
|
+
billing,
|
|
69
|
+
connectivity,
|
|
70
|
+
capabilities,
|
|
71
|
+
platform,
|
|
72
|
+
sandbox
|
|
73
|
+
};
|
|
74
|
+
const issues = [];
|
|
75
|
+
const autoFixable = [];
|
|
76
|
+
for (const [name, result] of Object.entries(checks)) {
|
|
77
|
+
if (result.status === "fail") {
|
|
78
|
+
issues.push(`${name}: ${result.message ?? "failed"}`);
|
|
79
|
+
const fix = suggestAutoFix(name, result);
|
|
80
|
+
if (fix)
|
|
81
|
+
autoFixable.push(fix);
|
|
82
|
+
}
|
|
83
|
+
else if (result.status === "warn" && result.message) {
|
|
84
|
+
issues.push(`${name} (warn): ${result.message}`);
|
|
85
|
+
}
|
|
86
|
+
}
|
|
87
|
+
const ready = Object.values(checks).every((c) => c.status !== "fail");
|
|
88
|
+
return { ready, checks, issues, autoFixable };
|
|
89
|
+
}
|
|
90
|
+
/**
|
|
91
|
+
* Emit a heartbeat — a best-effort `GET /health/live` so dashboards can
|
|
92
|
+
* correlate "agent alive" with "platform alive".
|
|
93
|
+
*
|
|
94
|
+
* Returns `true` when the platform answered, `false` otherwise. Never
|
|
95
|
+
* throws.
|
|
96
|
+
*/
|
|
97
|
+
async heartbeat() {
|
|
98
|
+
try {
|
|
99
|
+
await this.options.http.request({
|
|
100
|
+
path: "/health/live",
|
|
101
|
+
operation: "diagnostics-heartbeat",
|
|
102
|
+
headers: await this.options.http.optionalAuthHeaders()
|
|
103
|
+
});
|
|
104
|
+
return true;
|
|
105
|
+
}
|
|
106
|
+
catch {
|
|
107
|
+
return false;
|
|
108
|
+
}
|
|
109
|
+
}
|
|
110
|
+
/** Call `GET /health/ready?depth=deep` and return the structured report. */
|
|
111
|
+
async platformStatus(depth = "shallow") {
|
|
112
|
+
const params = new URLSearchParams({ depth });
|
|
113
|
+
const payload = await this.options.http.request({
|
|
114
|
+
path: "/health/ready",
|
|
115
|
+
operation: "diagnostics-platform",
|
|
116
|
+
headers: await this.options.http.optionalAuthHeaders(),
|
|
117
|
+
params
|
|
118
|
+
});
|
|
119
|
+
return payload;
|
|
120
|
+
}
|
|
121
|
+
/**
|
|
122
|
+
* Emit a structured log entry. Defaults to stdout JSON but can be
|
|
123
|
+
* redirected to any sink by passing `logSink` at construction.
|
|
124
|
+
*/
|
|
125
|
+
log(level, message, meta) {
|
|
126
|
+
this.logSink({
|
|
127
|
+
level,
|
|
128
|
+
message,
|
|
129
|
+
...(meta ? { meta } : {}),
|
|
130
|
+
at: Date.now()
|
|
131
|
+
});
|
|
132
|
+
}
|
|
133
|
+
async checkAuth() {
|
|
134
|
+
if (!this.options.http.getToken) {
|
|
135
|
+
return {
|
|
136
|
+
status: "warn",
|
|
137
|
+
message: "No token provider configured; running anonymously."
|
|
138
|
+
};
|
|
139
|
+
}
|
|
140
|
+
try {
|
|
141
|
+
// Roaming preflight requires no auth but accepts it — a successful
|
|
142
|
+
// authenticated call verifies the token provider works end-to-end.
|
|
143
|
+
await this.options.discovery.getRoamingPreflight();
|
|
144
|
+
return { status: "pass" };
|
|
145
|
+
}
|
|
146
|
+
catch (error) {
|
|
147
|
+
if (error instanceof AuthError) {
|
|
148
|
+
return {
|
|
149
|
+
status: "fail",
|
|
150
|
+
message: `auth failed: ${error.code}`,
|
|
151
|
+
details: error
|
|
152
|
+
};
|
|
153
|
+
}
|
|
154
|
+
if (error instanceof ShardLinkError) {
|
|
155
|
+
return { status: "warn", message: error.message };
|
|
156
|
+
}
|
|
157
|
+
return {
|
|
158
|
+
status: "warn",
|
|
159
|
+
message: error instanceof Error ? error.message : "unexpected auth check error"
|
|
160
|
+
};
|
|
161
|
+
}
|
|
162
|
+
}
|
|
163
|
+
async checkConnectivity() {
|
|
164
|
+
try {
|
|
165
|
+
await this.options.http.request({
|
|
166
|
+
path: "/health/live",
|
|
167
|
+
operation: "diagnostics-connectivity",
|
|
168
|
+
headers: await this.options.http.optionalAuthHeaders()
|
|
169
|
+
});
|
|
170
|
+
return { status: "pass" };
|
|
171
|
+
}
|
|
172
|
+
catch (error) {
|
|
173
|
+
if (error instanceof NetworkError) {
|
|
174
|
+
return {
|
|
175
|
+
status: "fail",
|
|
176
|
+
message: `network: ${error.message}`,
|
|
177
|
+
details: error
|
|
178
|
+
};
|
|
179
|
+
}
|
|
180
|
+
return {
|
|
181
|
+
status: "warn",
|
|
182
|
+
message: error instanceof Error ? error.message : "connectivity check error"
|
|
183
|
+
};
|
|
184
|
+
}
|
|
185
|
+
}
|
|
186
|
+
async checkPlatform() {
|
|
187
|
+
try {
|
|
188
|
+
const report = await this.platformStatus("shallow");
|
|
189
|
+
if (!report.ok) {
|
|
190
|
+
return {
|
|
191
|
+
status: "fail",
|
|
192
|
+
message: "platform not ready",
|
|
193
|
+
details: report
|
|
194
|
+
};
|
|
195
|
+
}
|
|
196
|
+
return { status: "pass", details: report };
|
|
197
|
+
}
|
|
198
|
+
catch (error) {
|
|
199
|
+
return {
|
|
200
|
+
status: "warn",
|
|
201
|
+
message: error instanceof Error ? error.message : "platform status error"
|
|
202
|
+
};
|
|
203
|
+
}
|
|
204
|
+
}
|
|
205
|
+
}
|
|
206
|
+
//# sourceMappingURL=diagnostics.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"diagnostics.js","sourceRoot":"","sources":["../../src/modules/diagnostics.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,152 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Well-known discovery documents (roaming preflight, passport, MCP metadata).
|
|
3
|
+
*
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
import type { HttpContext } from "../utils.js";
|
|
7
|
+
import type { PortableAgentPassportEnvelope, RoamingAgentPreflight } from "../types.js";
|
|
8
|
+
/**
|
|
9
|
+
* The enriched A2A agent card served at `/.well-known/agent-card.json`.
|
|
10
|
+
*
|
|
11
|
+
* It is a superset of the base A2A `AgentCard` schema (consumers that only
|
|
12
|
+
* read base fields are unaffected). Only the fields agents most commonly read
|
|
13
|
+
* are typed below; `[key: string]: unknown` keeps the full A2A surface
|
|
14
|
+
* (`additionalInterfaces`, `securitySchemes`, etc.) accessible without forcing
|
|
15
|
+
* the SDK to depend on the A2A schema package.
|
|
16
|
+
*/
|
|
17
|
+
export interface EnrichedAgentCard {
|
|
18
|
+
name: string;
|
|
19
|
+
description: string;
|
|
20
|
+
protocolVersion: string;
|
|
21
|
+
version: string;
|
|
22
|
+
/** Preferred-transport endpoint URL (A2A JSON-RPC). */
|
|
23
|
+
url: string;
|
|
24
|
+
preferredTransport: string;
|
|
25
|
+
iconUrl?: string;
|
|
26
|
+
provider: {
|
|
27
|
+
organization: string;
|
|
28
|
+
url: string;
|
|
29
|
+
};
|
|
30
|
+
capabilities: {
|
|
31
|
+
streaming: boolean;
|
|
32
|
+
pushNotifications: boolean;
|
|
33
|
+
stateTransitionHistory: boolean;
|
|
34
|
+
};
|
|
35
|
+
documentationUrl?: string;
|
|
36
|
+
/** ClawSpan-specific onboarding hints (quickstart, economics, reputation). */
|
|
37
|
+
clawspan: {
|
|
38
|
+
quickstart: {
|
|
39
|
+
url: string;
|
|
40
|
+
docsUrl: string;
|
|
41
|
+
wellKnown: {
|
|
42
|
+
agentCard: string;
|
|
43
|
+
mcpServer: string;
|
|
44
|
+
roamingPreflight: string;
|
|
45
|
+
openapi: string;
|
|
46
|
+
};
|
|
47
|
+
};
|
|
48
|
+
capabilities: {
|
|
49
|
+
categories: Array<{
|
|
50
|
+
id: string;
|
|
51
|
+
label: string;
|
|
52
|
+
description: string;
|
|
53
|
+
}>;
|
|
54
|
+
taskDescriptorEndpoint: string;
|
|
55
|
+
capabilityGraphEndpoint: string;
|
|
56
|
+
};
|
|
57
|
+
[key: string]: unknown;
|
|
58
|
+
};
|
|
59
|
+
[key: string]: unknown;
|
|
60
|
+
}
|
|
61
|
+
/** A single action descriptor inside the capability graph. */
|
|
62
|
+
export interface CapabilityGraphAction {
|
|
63
|
+
action: string;
|
|
64
|
+
path: string;
|
|
65
|
+
method: string;
|
|
66
|
+
[key: string]: unknown;
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* The capability graph served at `/v1/capabilities/graph` — the richest
|
|
70
|
+
* machine-readable description of the dual-plane action surface.
|
|
71
|
+
*/
|
|
72
|
+
export interface CapabilityGraph {
|
|
73
|
+
version: string;
|
|
74
|
+
model: string;
|
|
75
|
+
protocols: {
|
|
76
|
+
mcp: Record<string, unknown>;
|
|
77
|
+
a2a: Record<string, unknown>;
|
|
78
|
+
};
|
|
79
|
+
actions: CapabilityGraphAction[];
|
|
80
|
+
contracts: string[];
|
|
81
|
+
providerExecution: {
|
|
82
|
+
billingModes: Array<"direct_agent" | "sponsor">;
|
|
83
|
+
quoteRoute: string;
|
|
84
|
+
executeRoute: string;
|
|
85
|
+
capabilities: Array<{
|
|
86
|
+
capability: string;
|
|
87
|
+
providerKey: string;
|
|
88
|
+
customerUnitPriceUsdCents: number;
|
|
89
|
+
quoteRequired: boolean;
|
|
90
|
+
fundingRequired: boolean;
|
|
91
|
+
settlementLinked: boolean;
|
|
92
|
+
}>;
|
|
93
|
+
};
|
|
94
|
+
}
|
|
95
|
+
/** Client for well-known discovery endpoints. */
|
|
96
|
+
export declare class DiscoveryClient {
|
|
97
|
+
private readonly http;
|
|
98
|
+
constructor(http: HttpContext);
|
|
99
|
+
/**
|
|
100
|
+
* Fetch the roaming-agent preflight document.
|
|
101
|
+
*
|
|
102
|
+
* This is the single entry-point for new agents — it enumerates every
|
|
103
|
+
* auth scheme, discovery URL, and economic rail the control-plane supports.
|
|
104
|
+
*
|
|
105
|
+
* @example
|
|
106
|
+
* ```ts
|
|
107
|
+
* const preflight = await discovery.getRoamingPreflight();
|
|
108
|
+
* console.log(preflight.auth.wallet.challengePath);
|
|
109
|
+
* ```
|
|
110
|
+
*/
|
|
111
|
+
getRoamingPreflight(signal?: AbortSignal): Promise<RoamingAgentPreflight>;
|
|
112
|
+
/**
|
|
113
|
+
* Fetch the public, signed passport for the given agent identity.
|
|
114
|
+
*
|
|
115
|
+
* Passports are safe to cache — the JWS in `signature.jws` lets any client
|
|
116
|
+
* verify integrity against the jwks.
|
|
117
|
+
*/
|
|
118
|
+
getPublicAgentPassport(identity: string, signal?: AbortSignal): Promise<PortableAgentPassportEnvelope>;
|
|
119
|
+
/** Fetch the public MCP server manifest. */
|
|
120
|
+
getMcpServerMetadata(signal?: AbortSignal): Promise<Record<string, unknown>>;
|
|
121
|
+
/**
|
|
122
|
+
* Fetch the enriched A2A agent card from `/.well-known/agent-card.json`.
|
|
123
|
+
*
|
|
124
|
+
* This is the richest single discovery document — it carries the base A2A
|
|
125
|
+
* card plus ClawSpan onboarding hints (quickstart URLs, capability
|
|
126
|
+
* categories, economics, reputation aggregate).
|
|
127
|
+
*
|
|
128
|
+
* @example
|
|
129
|
+
* ```ts
|
|
130
|
+
* const card = await discovery.getAgentCard();
|
|
131
|
+
* console.log(card.clawspan.capabilities.capabilityGraphEndpoint);
|
|
132
|
+
* ```
|
|
133
|
+
*/
|
|
134
|
+
getAgentCard(signal?: AbortSignal): Promise<EnrichedAgentCard>;
|
|
135
|
+
/**
|
|
136
|
+
* Fetch the dual-plane capability graph from `/v1/capabilities/graph`.
|
|
137
|
+
*
|
|
138
|
+
* The graph enumerates every action (route, method, auth, lease + pricing
|
|
139
|
+
* hints), the protocol surfaces (MCP, A2A), and the provider-execution
|
|
140
|
+
* capability catalog — everything an agent needs to plan its calls.
|
|
141
|
+
*
|
|
142
|
+
* @example
|
|
143
|
+
* ```ts
|
|
144
|
+
* const graph = await discovery.getCapabilityGraph();
|
|
145
|
+
* for (const action of graph.actions) {
|
|
146
|
+
* console.log(action.action, action.method, action.path);
|
|
147
|
+
* }
|
|
148
|
+
* ```
|
|
149
|
+
*/
|
|
150
|
+
getCapabilityGraph(signal?: AbortSignal): Promise<CapabilityGraph>;
|
|
151
|
+
}
|
|
152
|
+
//# sourceMappingURL=discovery.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/modules/discovery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,6BAA6B,EAAE,qBAAqB,EAAE,MAAM,aAAa,CAAC;AAExF;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,uDAAuD;IACvD,GAAG,EAAE,MAAM,CAAC;IACZ,kBAAkB,EAAE,MAAM,CAAC;IAC3B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE;QACR,YAAY,EAAE,MAAM,CAAC;QACrB,GAAG,EAAE,MAAM,CAAC;KACb,CAAC;IACF,YAAY,EAAE;QACZ,SAAS,EAAE,OAAO,CAAC;QACnB,iBAAiB,EAAE,OAAO,CAAC;QAC3B,sBAAsB,EAAE,OAAO,CAAC;KACjC,CAAC;IACF,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,EAAE;QACR,UAAU,EAAE;YACV,GAAG,EAAE,MAAM,CAAC;YACZ,OAAO,EAAE,MAAM,CAAC;YAChB,SAAS,EAAE;gBACT,SAAS,EAAE,MAAM,CAAC;gBAClB,SAAS,EAAE,MAAM,CAAC;gBAClB,gBAAgB,EAAE,MAAM,CAAC;gBACzB,OAAO,EAAE,MAAM,CAAC;aACjB,CAAC;SACH,CAAC;QACF,YAAY,EAAE;YACZ,UAAU,EAAE,KAAK,CAAC;gBAAE,EAAE,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE,MAAM,CAAC;gBAAC,WAAW,EAAE,MAAM,CAAA;aAAE,CAAC,CAAC;YACtE,sBAAsB,EAAE,MAAM,CAAC;YAC/B,uBAAuB,EAAE,MAAM,CAAC;SACjC,CAAC;QACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;KACxB,CAAC;IACF,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED,8DAA8D;AAC9D,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE;QACT,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC7B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAC9B,CAAC;IACF,OAAO,EAAE,qBAAqB,EAAE,CAAC;IACjC,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,iBAAiB,EAAE;QACjB,YAAY,EAAE,KAAK,CAAC,cAAc,GAAG,SAAS,CAAC,CAAC;QAChD,UAAU,EAAE,MAAM,CAAC;QACnB,YAAY,EAAE,MAAM,CAAC;QACrB,YAAY,EAAE,KAAK,CAAC;YAClB,UAAU,EAAE,MAAM,CAAC;YACnB,WAAW,EAAE,MAAM,CAAC;YACpB,yBAAyB,EAAE,MAAM,CAAC;YAClC,aAAa,EAAE,OAAO,CAAC;YACvB,eAAe,EAAE,OAAO,CAAC;YACzB,gBAAgB,EAAE,OAAO,CAAC;SAC3B,CAAC,CAAC;KACJ,CAAC;CACH;AAED,iDAAiD;AACjD,qBAAa,eAAe;IACd,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,WAAW;IAE9C;;;;;;;;;;;OAWG;IACG,mBAAmB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,qBAAqB,CAAC;IAS/E;;;;;OAKG;IACG,sBAAsB,CAC1B,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,6BAA6B,CAAC;IASzC,4CAA4C;IACtC,oBAAoB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IASlF;;;;;;;;;;;;OAYG;IACG,YAAY,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IASpE;;;;;;;;;;;;;;OAcG;IACG,kBAAkB,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,eAAe,CAAC;CAQzE"}
|
|
@@ -0,0 +1,100 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Well-known discovery documents (roaming preflight, passport, MCP metadata).
|
|
3
|
+
*
|
|
4
|
+
* @packageDocumentation
|
|
5
|
+
*/
|
|
6
|
+
/** Client for well-known discovery endpoints. */
|
|
7
|
+
export class DiscoveryClient {
|
|
8
|
+
http;
|
|
9
|
+
constructor(http) {
|
|
10
|
+
this.http = http;
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* Fetch the roaming-agent preflight document.
|
|
14
|
+
*
|
|
15
|
+
* This is the single entry-point for new agents — it enumerates every
|
|
16
|
+
* auth scheme, discovery URL, and economic rail the control-plane supports.
|
|
17
|
+
*
|
|
18
|
+
* @example
|
|
19
|
+
* ```ts
|
|
20
|
+
* const preflight = await discovery.getRoamingPreflight();
|
|
21
|
+
* console.log(preflight.auth.wallet.challengePath);
|
|
22
|
+
* ```
|
|
23
|
+
*/
|
|
24
|
+
async getRoamingPreflight(signal) {
|
|
25
|
+
return this.http.request({
|
|
26
|
+
path: "/.well-known/roaming-agent.json",
|
|
27
|
+
operation: "roaming-preflight",
|
|
28
|
+
headers: await this.http.optionalAuthHeaders(),
|
|
29
|
+
...(signal ? { signal } : {})
|
|
30
|
+
});
|
|
31
|
+
}
|
|
32
|
+
/**
|
|
33
|
+
* Fetch the public, signed passport for the given agent identity.
|
|
34
|
+
*
|
|
35
|
+
* Passports are safe to cache — the JWS in `signature.jws` lets any client
|
|
36
|
+
* verify integrity against the jwks.
|
|
37
|
+
*/
|
|
38
|
+
async getPublicAgentPassport(identity, signal) {
|
|
39
|
+
return this.http.request({
|
|
40
|
+
path: `/v1/agents/${encodeURIComponent(identity)}/passport/public`,
|
|
41
|
+
operation: "agent-passport-public",
|
|
42
|
+
headers: await this.http.optionalAuthHeaders(),
|
|
43
|
+
...(signal ? { signal } : {})
|
|
44
|
+
});
|
|
45
|
+
}
|
|
46
|
+
/** Fetch the public MCP server manifest. */
|
|
47
|
+
async getMcpServerMetadata(signal) {
|
|
48
|
+
return this.http.request({
|
|
49
|
+
path: "/.well-known/mcp/server.json",
|
|
50
|
+
operation: "mcp-server-metadata",
|
|
51
|
+
headers: await this.http.optionalAuthHeaders(),
|
|
52
|
+
...(signal ? { signal } : {})
|
|
53
|
+
});
|
|
54
|
+
}
|
|
55
|
+
/**
|
|
56
|
+
* Fetch the enriched A2A agent card from `/.well-known/agent-card.json`.
|
|
57
|
+
*
|
|
58
|
+
* This is the richest single discovery document — it carries the base A2A
|
|
59
|
+
* card plus ClawSpan onboarding hints (quickstart URLs, capability
|
|
60
|
+
* categories, economics, reputation aggregate).
|
|
61
|
+
*
|
|
62
|
+
* @example
|
|
63
|
+
* ```ts
|
|
64
|
+
* const card = await discovery.getAgentCard();
|
|
65
|
+
* console.log(card.clawspan.capabilities.capabilityGraphEndpoint);
|
|
66
|
+
* ```
|
|
67
|
+
*/
|
|
68
|
+
async getAgentCard(signal) {
|
|
69
|
+
return this.http.request({
|
|
70
|
+
path: "/.well-known/agent-card.json",
|
|
71
|
+
operation: "agent-card",
|
|
72
|
+
headers: await this.http.optionalAuthHeaders(),
|
|
73
|
+
...(signal ? { signal } : {})
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* Fetch the dual-plane capability graph from `/v1/capabilities/graph`.
|
|
78
|
+
*
|
|
79
|
+
* The graph enumerates every action (route, method, auth, lease + pricing
|
|
80
|
+
* hints), the protocol surfaces (MCP, A2A), and the provider-execution
|
|
81
|
+
* capability catalog — everything an agent needs to plan its calls.
|
|
82
|
+
*
|
|
83
|
+
* @example
|
|
84
|
+
* ```ts
|
|
85
|
+
* const graph = await discovery.getCapabilityGraph();
|
|
86
|
+
* for (const action of graph.actions) {
|
|
87
|
+
* console.log(action.action, action.method, action.path);
|
|
88
|
+
* }
|
|
89
|
+
* ```
|
|
90
|
+
*/
|
|
91
|
+
async getCapabilityGraph(signal) {
|
|
92
|
+
return this.http.request({
|
|
93
|
+
path: "/v1/capabilities/graph",
|
|
94
|
+
operation: "capability-graph",
|
|
95
|
+
headers: await this.http.optionalAuthHeaders(),
|
|
96
|
+
...(signal ? { signal } : {})
|
|
97
|
+
});
|
|
98
|
+
}
|
|
99
|
+
}
|
|
100
|
+
//# sourceMappingURL=discovery.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"discovery.js","sourceRoot":"","sources":["../../src/modules/discovery.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AA2FH,iDAAiD;AACjD,MAAM,OAAO,eAAe;IACG;IAA7B,YAA6B,IAAiB;QAAjB,SAAI,GAAJ,IAAI,CAAa;IAAG,CAAC;IAElD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,mBAAmB,CAAC,MAAoB;QAC5C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAwB;YAC9C,IAAI,EAAE,iCAAiC;YACvC,SAAS,EAAE,mBAAmB;YAC9B,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,sBAAsB,CAC1B,QAAgB,EAChB,MAAoB;QAEpB,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAgC;YACtD,IAAI,EAAE,cAAc,kBAAkB,CAAC,QAAQ,CAAC,kBAAkB;YAClE,SAAS,EAAE,uBAAuB;YAClC,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;IAED,4CAA4C;IAC5C,KAAK,CAAC,oBAAoB,CAAC,MAAoB;QAC7C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAA0B;YAChD,IAAI,EAAE,8BAA8B;YACpC,SAAS,EAAE,qBAAqB;YAChC,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;OAYG;IACH,KAAK,CAAC,YAAY,CAAC,MAAoB;QACrC,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAoB;YAC1C,IAAI,EAAE,8BAA8B;YACpC,SAAS,EAAE,YAAY;YACvB,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,KAAK,CAAC,kBAAkB,CAAC,MAAoB;QAC3C,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAkB;YACxC,IAAI,EAAE,wBAAwB;YAC9B,SAAS,EAAE,kBAAkB;YAC7B,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;CACF"}
|
|
@@ -0,0 +1,82 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fleet command-center client — CP-4 slice. Thin pass-through over
|
|
3
|
+
* `GET /v1/fleets/:fleetId/command-center`. The endpoint returns a clan's
|
|
4
|
+
* VIEW INTO ITSELF — what's forming, who's joining, what work is flowing
|
|
5
|
+
* through. It is a member-equal read surface, not a commander-only panel
|
|
6
|
+
* (see `memory/emergence_thesis_solo_operators.md`).
|
|
7
|
+
*
|
|
8
|
+
* @packageDocumentation
|
|
9
|
+
*/
|
|
10
|
+
import type { Clan } from "./clans.js";
|
|
11
|
+
import type { FlavorHints, FlavorHueFamily, OperatorProfile, OperatorReputation } from "./operators.js";
|
|
12
|
+
import type { HttpContext } from "../utils.js";
|
|
13
|
+
export type FleetActivityType = "clan_joined" | "clan_left" | "commander_emerged" | "settlement" | "delivery";
|
|
14
|
+
export interface FleetActivityEntry {
|
|
15
|
+
type: FleetActivityType;
|
|
16
|
+
occurredAt: number;
|
|
17
|
+
actorId?: string;
|
|
18
|
+
summary: string;
|
|
19
|
+
}
|
|
20
|
+
export interface FleetMemberLedgerSummary {
|
|
21
|
+
totalEarnings: number;
|
|
22
|
+
totalSpend: number;
|
|
23
|
+
taskCount: number;
|
|
24
|
+
lastActiveAt?: number;
|
|
25
|
+
}
|
|
26
|
+
/**
|
|
27
|
+
* Public-view subset of `OperatorProfile` — never exposes another operator's
|
|
28
|
+
* `createdAt`/`updatedAt`. Same shape the route emits via
|
|
29
|
+
* `publicOperatorProfile(...)`.
|
|
30
|
+
*/
|
|
31
|
+
export interface FleetMemberPublicProfile {
|
|
32
|
+
identity: string;
|
|
33
|
+
displayName?: string;
|
|
34
|
+
bio?: string;
|
|
35
|
+
domainTags: string[];
|
|
36
|
+
flavorSeed: string;
|
|
37
|
+
flavorHints?: FlavorHints;
|
|
38
|
+
reputation: OperatorReputation;
|
|
39
|
+
}
|
|
40
|
+
export interface FleetMemberView {
|
|
41
|
+
profile: FleetMemberPublicProfile;
|
|
42
|
+
ledgerSummary: FleetMemberLedgerSummary;
|
|
43
|
+
activeMatches: number;
|
|
44
|
+
}
|
|
45
|
+
export interface FleetFlavorSignature {
|
|
46
|
+
dominantHueFamilies: FlavorHueFamily[];
|
|
47
|
+
diversityScore: number;
|
|
48
|
+
}
|
|
49
|
+
export interface FleetReputationSummary {
|
|
50
|
+
score: number;
|
|
51
|
+
trend: "rising" | "stable" | "settling";
|
|
52
|
+
}
|
|
53
|
+
export interface FleetClanAggregates {
|
|
54
|
+
memberCount: number;
|
|
55
|
+
formingSince: number;
|
|
56
|
+
collectiveEarnings: number;
|
|
57
|
+
flavorSignature: FleetFlavorSignature;
|
|
58
|
+
reputation: FleetReputationSummary;
|
|
59
|
+
}
|
|
60
|
+
export interface FleetCommandCenter {
|
|
61
|
+
clan: Clan;
|
|
62
|
+
members: FleetMemberView[];
|
|
63
|
+
clanAggregates: FleetClanAggregates;
|
|
64
|
+
recentActivity: FleetActivityEntry[];
|
|
65
|
+
generatedAt: number;
|
|
66
|
+
}
|
|
67
|
+
/** Typed client over `/v1/fleets/:fleetId/command-center`. */
|
|
68
|
+
export declare class FleetsClient {
|
|
69
|
+
private readonly http;
|
|
70
|
+
constructor(http: HttpContext);
|
|
71
|
+
/**
|
|
72
|
+
* Fetch a clan's command-center aggregate. Caller must be a member of
|
|
73
|
+
* the clan (the route returns 403 otherwise).
|
|
74
|
+
*
|
|
75
|
+
* @example
|
|
76
|
+
* const view = await client.getFleetCommandCenter("clan-uuid");
|
|
77
|
+
* console.log(view.clanAggregates.flavorSignature.dominantHueFamilies);
|
|
78
|
+
*/
|
|
79
|
+
getFleetCommandCenter(fleetId: string, signal?: AbortSignal): Promise<FleetCommandCenter>;
|
|
80
|
+
}
|
|
81
|
+
export type { OperatorProfile };
|
|
82
|
+
//# sourceMappingURL=fleets.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fleets.d.ts","sourceRoot":"","sources":["../../src/modules/fleets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,eAAe,EACf,kBAAkB,EACnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAE/C,MAAM,MAAM,iBAAiB,GACzB,aAAa,GACb,WAAW,GACX,mBAAmB,GACnB,YAAY,GACZ,UAAU,CAAC;AAEf,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,iBAAiB,CAAC;IACxB,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,wBAAwB;IACvC,aAAa,EAAE,MAAM,CAAC;IACtB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;GAIG;AACH,MAAM,WAAW,wBAAwB;IACvC,QAAQ,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,EAAE,CAAC;IACrB,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,WAAW,CAAC;IAC1B,UAAU,EAAE,kBAAkB,CAAC;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,wBAAwB,CAAC;IAClC,aAAa,EAAE,wBAAwB,CAAC;IACxC,aAAa,EAAE,MAAM,CAAC;CACvB;AAED,MAAM,WAAW,oBAAoB;IACnC,mBAAmB,EAAE,eAAe,EAAE,CAAC;IACvC,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,sBAAsB;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;CACzC;AAED,MAAM,WAAW,mBAAmB;IAClC,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,kBAAkB,EAAE,MAAM,CAAC;IAC3B,eAAe,EAAE,oBAAoB,CAAC;IACtC,UAAU,EAAE,sBAAsB,CAAC;CACpC;AAED,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,eAAe,EAAE,CAAC;IAC3B,cAAc,EAAE,mBAAmB,CAAC;IACpC,cAAc,EAAE,kBAAkB,EAAE,CAAC;IACrC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED,8DAA8D;AAC9D,qBAAa,YAAY;IACX,OAAO,CAAC,QAAQ,CAAC,IAAI;gBAAJ,IAAI,EAAE,WAAW;IAE9C;;;;;;;OAOG;IACG,qBAAqB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,kBAAkB,CAAC;CAQhG;AAID,YAAY,EAAE,eAAe,EAAE,CAAC"}
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Fleet command-center client — CP-4 slice. Thin pass-through over
|
|
3
|
+
* `GET /v1/fleets/:fleetId/command-center`. The endpoint returns a clan's
|
|
4
|
+
* VIEW INTO ITSELF — what's forming, who's joining, what work is flowing
|
|
5
|
+
* through. It is a member-equal read surface, not a commander-only panel
|
|
6
|
+
* (see `memory/emergence_thesis_solo_operators.md`).
|
|
7
|
+
*
|
|
8
|
+
* @packageDocumentation
|
|
9
|
+
*/
|
|
10
|
+
/** Typed client over `/v1/fleets/:fleetId/command-center`. */
|
|
11
|
+
export class FleetsClient {
|
|
12
|
+
http;
|
|
13
|
+
constructor(http) {
|
|
14
|
+
this.http = http;
|
|
15
|
+
}
|
|
16
|
+
/**
|
|
17
|
+
* Fetch a clan's command-center aggregate. Caller must be a member of
|
|
18
|
+
* the clan (the route returns 403 otherwise).
|
|
19
|
+
*
|
|
20
|
+
* @example
|
|
21
|
+
* const view = await client.getFleetCommandCenter("clan-uuid");
|
|
22
|
+
* console.log(view.clanAggregates.flavorSignature.dominantHueFamilies);
|
|
23
|
+
*/
|
|
24
|
+
async getFleetCommandCenter(fleetId, signal) {
|
|
25
|
+
return this.http.request({
|
|
26
|
+
path: `/v1/fleets/${encodeURIComponent(fleetId)}/command-center`,
|
|
27
|
+
operation: "fleet-command-center-get",
|
|
28
|
+
headers: await this.http.requiredAuthHeaders(),
|
|
29
|
+
...(signal ? { signal } : {})
|
|
30
|
+
});
|
|
31
|
+
}
|
|
32
|
+
}
|
|
33
|
+
//# sourceMappingURL=fleets.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"fleets.js","sourceRoot":"","sources":["../../src/modules/fleets.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AA+EH,8DAA8D;AAC9D,MAAM,OAAO,YAAY;IACM;IAA7B,YAA6B,IAAiB;QAAjB,SAAI,GAAJ,IAAI,CAAa;IAAG,CAAC;IAElD;;;;;;;OAOG;IACH,KAAK,CAAC,qBAAqB,CAAC,OAAe,EAAE,MAAoB;QAC/D,OAAO,IAAI,CAAC,IAAI,CAAC,OAAO,CAAqB;YAC3C,IAAI,EAAE,cAAc,kBAAkB,CAAC,OAAO,CAAC,iBAAiB;YAChE,SAAS,EAAE,0BAA0B;YACrC,OAAO,EAAE,MAAM,IAAI,CAAC,IAAI,CAAC,mBAAmB,EAAE;YAC9C,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC9B,CAAC,CAAC;IACL,CAAC;CACF"}
|