@prefactor/pi 0.0.0-stage → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (56) hide show
  1. package/README.md +226 -2
  2. package/dist/commands.d.ts +32 -0
  3. package/dist/commands.d.ts.map +1 -0
  4. package/dist/commands.js +395 -0
  5. package/dist/commands.js.map +1 -0
  6. package/dist/credentials.d.ts +67 -0
  7. package/dist/credentials.d.ts.map +1 -0
  8. package/dist/credentials.js +120 -0
  9. package/dist/credentials.js.map +1 -0
  10. package/dist/data-risk.d.ts +11 -0
  11. package/dist/data-risk.d.ts.map +1 -0
  12. package/dist/data-risk.js +125 -0
  13. package/dist/data-risk.js.map +1 -0
  14. package/dist/device-login.d.ts +45 -0
  15. package/dist/device-login.d.ts.map +1 -0
  16. package/dist/device-login.js +163 -0
  17. package/dist/device-login.js.map +1 -0
  18. package/dist/extension.d.ts +44 -0
  19. package/dist/extension.d.ts.map +1 -0
  20. package/dist/extension.js +204 -0
  21. package/dist/extension.js.map +1 -0
  22. package/dist/index.cjs +1805 -0
  23. package/dist/index.cjs.map +22 -0
  24. package/dist/index.d.ts +19 -0
  25. package/dist/index.d.ts.map +1 -0
  26. package/dist/index.js +1772 -0
  27. package/dist/index.js.map +22 -0
  28. package/dist/prefactor-api.d.ts +38 -0
  29. package/dist/prefactor-api.d.ts.map +1 -0
  30. package/dist/prefactor-api.js +63 -0
  31. package/dist/prefactor-api.js.map +1 -0
  32. package/dist/prefactor-session.d.ts +126 -0
  33. package/dist/prefactor-session.d.ts.map +1 -0
  34. package/dist/prefactor-session.js +274 -0
  35. package/dist/prefactor-session.js.map +1 -0
  36. package/dist/recorder.d.ts +54 -0
  37. package/dist/recorder.d.ts.map +1 -0
  38. package/dist/recorder.js +70 -0
  39. package/dist/recorder.js.map +1 -0
  40. package/dist/schema.d.ts +54 -0
  41. package/dist/schema.d.ts.map +1 -0
  42. package/dist/schema.js +220 -0
  43. package/dist/schema.js.map +1 -0
  44. package/dist/session-tracer.d.ts +144 -0
  45. package/dist/session-tracer.d.ts.map +1 -0
  46. package/dist/session-tracer.js +390 -0
  47. package/dist/session-tracer.js.map +1 -0
  48. package/dist/tool-definitions.d.ts +17 -0
  49. package/dist/tool-definitions.d.ts.map +1 -0
  50. package/dist/tool-definitions.js +69 -0
  51. package/dist/tool-definitions.js.map +1 -0
  52. package/dist/version.d.ts +3 -0
  53. package/dist/version.d.ts.map +1 -0
  54. package/dist/version.js +4 -0
  55. package/dist/version.js.map +1 -0
  56. package/package.json +54 -4
@@ -0,0 +1 @@
1
+ {"version":3,"file":"prefactor-session.d.ts","sourceRoot":"","sources":["../src/prefactor-session.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,274 @@
1
+ import { AgentInstanceClient, AgentSpanClient, buildRuntimeEnvironment, getLogger, HttpClient, serializeValue, } from '@prefactor/core';
2
+ const logger = getLogger('pi');
3
+ const RETRY_ON_STATUS_CODES = [429, ...Array.from({ length: 100 }, (_, index) => 500 + index)];
4
+ const DEFAULT_SHUTDOWN_TIMEOUT_MS = 10_000;
5
+ /**
6
+ * Creates the HTTP requester used for Prefactor API calls made by the extension.
7
+ */
8
+ export function createHttpClient(apiUrl, apiToken, sdkHeaderEntry) {
9
+ const config = {
10
+ apiUrl,
11
+ apiToken,
12
+ agentIdentifier: 'pi',
13
+ requestTimeout: 30_000,
14
+ maxRetries: 3,
15
+ initialRetryDelay: 1_000,
16
+ maxRetryDelay: 10_000,
17
+ retryMultiplier: 2,
18
+ retryOnStatusCodes: RETRY_ON_STATUS_CODES,
19
+ };
20
+ return new HttpClient(config, {}, sdkHeaderEntry);
21
+ }
22
+ /**
23
+ * Reads the agent id of an agent-deployment token from `GET /api/v1/ping`.
24
+ */
25
+ export async function fetchAgentId(client) {
26
+ const response = await client.request('/api/v1/ping', { method: 'GET' });
27
+ const agentId = response.details?.agent_id;
28
+ if (!agentId) {
29
+ throw new Error('GET /api/v1/ping did not return an agent_id for this token');
30
+ }
31
+ return agentId;
32
+ }
33
+ /**
34
+ * One Prefactor agent instance and its spans.
35
+ *
36
+ * Every call returns at once and queues its request, so pi is never held up by the network. The
37
+ * queue sends requests one at a time in call order, so a parent span is created before its
38
+ * children and finished after them. Each span is sent as soon as it starts or finishes, so a
39
+ * session ended without `session_shutdown` loses only the spans still open. Shutdown waits for
40
+ * queued requests only up to a deadline, so an unreachable API cannot hold up pi's exit.
41
+ */
42
+ export class PrefactorSession {
43
+ instanceClient;
44
+ spanClient;
45
+ instanceId;
46
+ tail = Promise.resolve();
47
+ onError;
48
+ shutdownTimeoutMs;
49
+ errorReported = false;
50
+ startState = 'pending';
51
+ finished = false;
52
+ lastError = null;
53
+ constructor(options, httpClient) {
54
+ const client = this.trackRequests(httpClient ?? createHttpClient(options.apiUrl, options.apiToken, options.sdkHeaderEntry));
55
+ this.instanceClient = new AgentInstanceClient(client);
56
+ this.spanClient = new AgentSpanClient(client);
57
+ this.onError = options.onError;
58
+ this.shutdownTimeoutMs = options.shutdownTimeoutMs ?? DEFAULT_SHUTDOWN_TIMEOUT_MS;
59
+ const startedAt = new Date().toISOString();
60
+ this.instanceId = this.enqueue(async () => {
61
+ const registerPayload = {
62
+ agent_id: options.agentId ?? (await fetchAgentId(client)),
63
+ agent_version: {
64
+ ...options.agentVersion,
65
+ runtime_environment: buildRuntimeEnvironment(options.sdkHeaderEntry),
66
+ },
67
+ agent_schema_version: options.agentSchemaVersion,
68
+ ...(options.externalIdentifier !== undefined
69
+ ? { external_identifier: options.externalIdentifier }
70
+ : {}),
71
+ };
72
+ const response = await this.instanceClient.register(registerPayload);
73
+ const id = response.details.id;
74
+ await this.instanceClient.start(id, { timestamp: startedAt });
75
+ return id;
76
+ });
77
+ void this.instanceId.then((id) => {
78
+ this.startState = id === null ? 'failed' : 'started';
79
+ });
80
+ }
81
+ /** Whether the agent instance has started. A session that failed to start records nothing. */
82
+ getStartState() {
83
+ return this.startState;
84
+ }
85
+ /** Resolves once starting the agent instance has succeeded (`true`) or failed (`false`). */
86
+ async whenStartSettled() {
87
+ return (await this.instanceId) !== null;
88
+ }
89
+ /**
90
+ * Error from the most recent failed request or operation, or `null` when the last request sent
91
+ * succeeded. Operations skipped because an earlier one failed do not clear it.
92
+ */
93
+ getLastError() {
94
+ return this.lastError;
95
+ }
96
+ /**
97
+ * Creates an active span now and returns a handle to finish it later.
98
+ */
99
+ startSpan(options) {
100
+ const startedAt = options.startedAt ?? Date.now();
101
+ return {
102
+ startedAt,
103
+ id: this.enqueue(() => this.createSpan({
104
+ ...options,
105
+ startedAt,
106
+ status: 'active',
107
+ finishedAt: null,
108
+ resultPayload: undefined,
109
+ })),
110
+ };
111
+ }
112
+ /**
113
+ * Creates a span that has already finished, in one request.
114
+ */
115
+ recordSpan(options) {
116
+ const startedAt = options.startedAt ?? Date.now();
117
+ return { startedAt, id: this.enqueue(() => this.createSpan({ ...options, startedAt })) };
118
+ }
119
+ /**
120
+ * Finishes a span created with {@link startSpan} at `finishedAt`, or now when it is omitted.
121
+ * The finish time is never earlier than the span's start time.
122
+ */
123
+ finishSpan(span, status, resultPayload, finishedAt = Date.now()) {
124
+ const timestamp = new Date(Math.max(finishedAt, span.startedAt)).toISOString();
125
+ this.enqueue(async () => {
126
+ const id = await span.id;
127
+ if (!id) {
128
+ return;
129
+ }
130
+ await this.spanClient.finish(id, timestamp, {
131
+ status,
132
+ result_payload: resultPayload,
133
+ });
134
+ });
135
+ }
136
+ /**
137
+ * Records a quality payload on the agent instance for a named quality schema. A null payload
138
+ * removes the recorded value for that name.
139
+ */
140
+ recordQuality(name, payload) {
141
+ const sent = snapshot(payload);
142
+ this.enqueue(async () => {
143
+ const instanceId = await this.instanceId;
144
+ if (instanceId) {
145
+ await this.instanceClient.recordQuality(instanceId, { name, payload: sent });
146
+ }
147
+ });
148
+ }
149
+ /**
150
+ * Raises a named alert on the agent instance, timestamped now.
151
+ */
152
+ raiseAlert(name, severity, payload) {
153
+ const raisedAt = new Date().toISOString();
154
+ const sent = snapshot(payload);
155
+ this.enqueue(async () => {
156
+ const instanceId = await this.instanceId;
157
+ if (instanceId) {
158
+ await this.instanceClient.raiseAlert(instanceId, {
159
+ name,
160
+ severity,
161
+ payload: sent,
162
+ raised_at: raisedAt,
163
+ });
164
+ }
165
+ });
166
+ }
167
+ /**
168
+ * Finishes the agent instance with `status` after every queued request, and waits for it to be
169
+ * sent, but no longer than the shutdown timeout. Requests still queued after the timeout keep
170
+ * running in the background. Calling it more than once has no further effect.
171
+ */
172
+ async finish(status = 'complete') {
173
+ if (this.finished) {
174
+ return;
175
+ }
176
+ this.finished = true;
177
+ const timestamp = new Date().toISOString();
178
+ const sent = this.enqueue(async () => {
179
+ const instanceId = await this.instanceId;
180
+ if (instanceId) {
181
+ await this.instanceClient.finish(instanceId, { status, timestamp });
182
+ }
183
+ return true;
184
+ });
185
+ let timer;
186
+ const timedOut = new Promise((resolve) => {
187
+ timer = setTimeout(() => resolve(false), this.shutdownTimeoutMs);
188
+ timer.unref?.();
189
+ });
190
+ try {
191
+ if ((await Promise.race([sent, timedOut])) === false) {
192
+ logger.debug(`Stopped waiting for Prefactor requests after ${this.shutdownTimeoutMs} ms at shutdown`);
193
+ }
194
+ }
195
+ finally {
196
+ clearTimeout(timer);
197
+ }
198
+ }
199
+ /**
200
+ * Waits until every request queued so far has been sent.
201
+ */
202
+ async flush() {
203
+ await this.tail;
204
+ }
205
+ async createSpan(options) {
206
+ const instanceId = await this.instanceId;
207
+ const parentId = options.parent ? await options.parent.id : null;
208
+ if (!instanceId || (options.parent && !parentId)) {
209
+ return null;
210
+ }
211
+ const response = await this.spanClient.create({
212
+ details: {
213
+ agent_instance_id: instanceId,
214
+ schema_name: options.schemaName,
215
+ status: options.status,
216
+ payload: options.payload,
217
+ ...(options.resultPayload ? { result_payload: options.resultPayload } : {}),
218
+ parent_span_id: parentId,
219
+ started_at: new Date(options.startedAt ?? Date.now()).toISOString(),
220
+ finished_at: options.finishedAt === null ? null : new Date(options.finishedAt).toISOString(),
221
+ },
222
+ });
223
+ return response.details.id;
224
+ }
225
+ /**
226
+ * Queues a request behind every earlier one. Failures are logged and resolve to `null`, because
227
+ * instrumentation must never break pi. The returned promise never rejects, so the queue keeps
228
+ * running after any failure.
229
+ */
230
+ enqueue(operation) {
231
+ const promise = this.tail.then(operation).then((value) => value, (error) => {
232
+ this.lastError = error;
233
+ logger.debug('Prefactor request failed', error);
234
+ if (!this.errorReported) {
235
+ this.errorReported = true;
236
+ try {
237
+ this.onError?.(error);
238
+ }
239
+ catch (callbackError) {
240
+ logger.debug('Prefactor onError callback failed', callbackError);
241
+ }
242
+ }
243
+ return null;
244
+ });
245
+ this.tail = promise;
246
+ return promise;
247
+ }
248
+ /**
249
+ * Wraps a requester so that `lastError` reflects the outcome of the last request actually sent.
250
+ */
251
+ trackRequests(client) {
252
+ return {
253
+ request: async (...args) => {
254
+ try {
255
+ const response = await client.request(...args);
256
+ this.lastError = null;
257
+ return response;
258
+ }
259
+ catch (error) {
260
+ this.lastError = error;
261
+ throw error;
262
+ }
263
+ },
264
+ };
265
+ }
266
+ }
267
+ /**
268
+ * Deep-copies a payload when it is queued, so later changes the caller makes to the object are
269
+ * not sent.
270
+ */
271
+ function snapshot(payload) {
272
+ return serializeValue(payload, null);
273
+ }
274
+ //# sourceMappingURL=prefactor-session.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"prefactor-session.js","sourceRoot":"","sources":["../src/prefactor-session.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,54 @@
1
+ import { type AlertSeverity } from '@prefactor/core';
2
+ import type { PrefactorSession, SpanStatus } from './prefactor-session.js';
3
+ import type { SessionTracer } from './session-tracer.js';
4
+ /** A span started with {@link PrefactorRecorder.startSpan}. */
5
+ export interface PrefactorSpan {
6
+ /** Finishes the span as complete. Later calls to `complete` or `fail` have no effect. */
7
+ complete(result?: Record<string, unknown>): void;
8
+ /** Finishes the span as failed. Later calls to `complete` or `fail` have no effect. */
9
+ fail(result?: Record<string, unknown>): void;
10
+ }
11
+ /** Options for {@link PrefactorRecorder.startSpan}. */
12
+ export interface StartPrefactorSpanOptions {
13
+ /** One of the span types given in the extension's `spanTypeSchemas` option. */
14
+ schemaName: string;
15
+ payload?: Record<string, unknown>;
16
+ /**
17
+ * The span to nest under: another span from this recorder, or the span of a running tool call
18
+ * given by its id. Without one, or when that tool call is not running, the span nests under
19
+ * the open assistant turn, else under the session span.
20
+ */
21
+ parent?: PrefactorSpan | {
22
+ toolCallId: string;
23
+ };
24
+ }
25
+ /**
26
+ * Adds to what the extension records for one pi session. Calls never throw and never wait for
27
+ * the network; failures are logged. After the session shuts down, calls record nothing.
28
+ */
29
+ export interface PrefactorRecorder {
30
+ /** Starts a span in the session's span tree. */
31
+ startSpan(options: StartPrefactorSpanOptions): PrefactorSpan;
32
+ /**
33
+ * Records a quality payload on the session's agent instance for a schema in the extension's
34
+ * `qualitySchemas` option. A null payload removes the recorded value for that name.
35
+ */
36
+ recordQuality(name: string, payload: Record<string, unknown> | null): void;
37
+ /** Raises an alert on the session's agent instance, for a schema in `alertSchemas`. */
38
+ raiseAlert(name: string, severity: AlertSeverity, payload: Record<string, unknown>): void;
39
+ /**
40
+ * Sets the status the agent instance finishes with when the session shuts down. The last call
41
+ * wins. Without a call, the instance finishes as complete.
42
+ */
43
+ setFinishStatus(status: SpanStatus): void;
44
+ }
45
+ /**
46
+ * Creates the recorder for one session, a function that stops it when the session shuts down,
47
+ * and a function that returns the status set for the agent instance's finish.
48
+ */
49
+ export declare function createRecorder(session: PrefactorSession, tracer: SessionTracer): {
50
+ recorder: PrefactorRecorder;
51
+ stop: () => void;
52
+ finishStatus: () => SpanStatus;
53
+ };
54
+ //# sourceMappingURL=recorder.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,aAAa,EAAa,MAAM,iBAAiB,CAAC;AAChE,OAAO,KAAK,EAAE,gBAAgB,EAAc,UAAU,EAAE,MAAM,wBAAwB,CAAC;AACvF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAIzD,+DAA+D;AAC/D,MAAM,WAAW,aAAa;IAC5B,yFAAyF;IACzF,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IACjD,uFAAuF;IACvF,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC9C;AAED,uDAAuD;AACvD,MAAM,WAAW,yBAAyB;IACxC,+EAA+E;IAC/E,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAClC;;;;OAIG;IACH,MAAM,CAAC,EAAE,aAAa,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;CACjD;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,gDAAgD;IAChD,SAAS,CAAC,OAAO,EAAE,yBAAyB,GAAG,aAAa,CAAC;IAC7D;;;OAGG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC;IAC3E,uFAAuF;IACvF,UAAU,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAC1F;;;OAGG;IACH,eAAe,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI,CAAC;CAC3C;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAC5B,OAAO,EAAE,gBAAgB,EACzB,MAAM,EAAE,aAAa,GACpB;IAAE,QAAQ,EAAE,iBAAiB,CAAC;IAAC,IAAI,EAAE,MAAM,IAAI,CAAC;IAAC,YAAY,EAAE,MAAM,UAAU,CAAA;CAAE,CAiEnF"}
@@ -0,0 +1,70 @@
1
+ import { getLogger } from '@prefactor/core';
2
+ const logger = getLogger('pi');
3
+ /**
4
+ * Creates the recorder for one session, a function that stops it when the session shuts down,
5
+ * and a function that returns the status set for the agent instance's finish.
6
+ */
7
+ export function createRecorder(session, tracer) {
8
+ let stopped = false;
9
+ let finishStatus = 'complete';
10
+ const handles = new WeakMap();
11
+ const run = (name, action) => {
12
+ if (stopped) {
13
+ logger.warn(`Prefactor ${name} called after the pi session shut down; nothing recorded`);
14
+ return;
15
+ }
16
+ try {
17
+ action();
18
+ }
19
+ catch (error) {
20
+ logger.warn(`Prefactor ${name} failed`, error);
21
+ }
22
+ };
23
+ const recorder = {
24
+ startSpan(options) {
25
+ let handle;
26
+ run('startSpan', () => {
27
+ const parent = options.parent;
28
+ handle = tracer.startCustomSpan({
29
+ schemaName: options.schemaName,
30
+ payload: options.payload ?? {},
31
+ ...(parent && 'toolCallId' in parent
32
+ ? { toolCallId: parent.toolCallId }
33
+ : { parent: parent ? handles.get(parent) : undefined }),
34
+ });
35
+ });
36
+ const finish = (status, result = {}) => run(status === 'complete' ? 'complete' : 'fail', () => {
37
+ if (handle) {
38
+ tracer.finishCustomSpan(handle, status, result);
39
+ }
40
+ });
41
+ const span = {
42
+ complete: (result) => finish('complete', result),
43
+ fail: (result) => finish('failed', result),
44
+ };
45
+ if (handle) {
46
+ handles.set(span, handle);
47
+ }
48
+ return span;
49
+ },
50
+ recordQuality(name, payload) {
51
+ run('recordQuality', () => session.recordQuality(name, payload));
52
+ },
53
+ raiseAlert(name, severity, payload) {
54
+ run('raiseAlert', () => session.raiseAlert(name, severity, payload));
55
+ },
56
+ setFinishStatus(status) {
57
+ run('setFinishStatus', () => {
58
+ finishStatus = status;
59
+ });
60
+ },
61
+ };
62
+ return {
63
+ recorder,
64
+ stop: () => {
65
+ stopped = true;
66
+ },
67
+ finishStatus: () => finishStatus,
68
+ };
69
+ }
70
+ //# sourceMappingURL=recorder.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"recorder.js","sourceRoot":"","sources":["../src/recorder.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,54 @@
1
+ import type { AgentSchemaVersion, AlertSchema, DataRisk, JsonSchema, QualitySchema, SpanTypeSchema } from '@prefactor/core';
2
+ /** Version stamped as `_version` on every `$agent:*` payload and result, as Prefactor does. */
3
+ export declare const AGENT_SPAN_VERSION = 1;
4
+ /** Span type prefix for tool executions. */
5
+ export declare const TOOL_SPAN_PREFIX = "$agent:tool:";
6
+ /**
7
+ * Span type for tools added after the session started, which have no span type of their own.
8
+ * pi tool names cannot contain `:`, so this name never collides with a tool's own span type.
9
+ */
10
+ export declare const FALLBACK_TOOL_SPAN_TYPE = "$agent:tool:pi:other";
11
+ /** The name and description of a tool pi has when the session starts. */
12
+ export interface SessionTool {
13
+ name: string;
14
+ description?: string;
15
+ }
16
+ /**
17
+ * Span type details for one tool, replacing the defaults of its `$agent:tool:<name>` span type.
18
+ * The span type keeps its name, so Prefactor still shows the execution as a tool call.
19
+ */
20
+ export interface ToolSchemaOptions {
21
+ title?: string;
22
+ description?: string;
23
+ /** Liquid template summarising the call. `params` holds the arguments; `result` or `error` the outcome. */
24
+ template?: string;
25
+ /** JSON Schema of the tool's arguments, recorded as `params`. */
26
+ params_schema?: JsonSchema;
27
+ /** JSON Schema of the structured value the tool returns as `details`, recorded as `result.details`. */
28
+ result_schema?: JsonSchema;
29
+ data_risk?: DataRisk;
30
+ }
31
+ /** What developers add to the agent schema version the extension registers. */
32
+ export interface SchemaExtensions {
33
+ spanTypeSchemas?: SpanTypeSchema[];
34
+ qualitySchemas?: QualitySchema[];
35
+ alertSchemas?: AlertSchema[];
36
+ /** Span type details by tool name. */
37
+ toolSchemas?: Record<string, ToolSchemaOptions>;
38
+ }
39
+ /** Whether a span type name belongs to the span types the extension defines itself. */
40
+ export declare function isReservedSpanType(name: string): boolean;
41
+ /**
42
+ * Names of the tools that get their own span type: the tools pi has at session start and the
43
+ * tools given span type details, in that order, without repeats.
44
+ */
45
+ export declare function registeredToolNames(tools: SessionTool[], toolSchemas?: Record<string, ToolSchemaOptions>): string[];
46
+ /**
47
+ * Builds the agent schema version registered for each pi session. pi's own work is recorded with
48
+ * the canonical `$agent:*` span types, so Prefactor shows the session as a conversation, inside
49
+ * a `pi:session` root span. Each tool pi has at session start, and each tool in
50
+ * `extensions.toolSchemas`, gets its own span type. The developer's span types, quality schemas
51
+ * and alert schemas follow.
52
+ */
53
+ export declare function buildAgentSchemaVersion(tools: SessionTool[], extensions?: SchemaExtensions): AgentSchemaVersion;
54
+ //# sourceMappingURL=schema.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,kBAAkB,EAClB,WAAW,EACX,QAAQ,EACR,UAAU,EACV,aAAa,EACb,cAAc,EACf,MAAM,iBAAiB,CAAC;AAKzB,+FAA+F;AAC/F,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,4CAA4C;AAC5C,eAAO,MAAM,gBAAgB,iBAAiB,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,uBAAuB,yBAAgC,CAAC;AAErE,yEAAyE;AACzE,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,2GAA2G;IAC3G,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,iEAAiE;IACjE,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B,uGAAuG;IACvG,aAAa,CAAC,EAAE,UAAU,CAAC;IAC3B,SAAS,CAAC,EAAE,QAAQ,CAAC;CACtB;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B,eAAe,CAAC,EAAE,cAAc,EAAE,CAAC;IACnC,cAAc,CAAC,EAAE,aAAa,EAAE,CAAC;IACjC,YAAY,CAAC,EAAE,WAAW,EAAE,CAAC;IAC7B,sCAAsC;IACtC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,CAAC;CACjD;AAED,uFAAuF;AACvF,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAExD;AA2ED;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAAE,EACpB,WAAW,GAAE,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAM,GAClD,MAAM,EAAE,CAEV;AAED;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,WAAW,EAAE,EACpB,UAAU,GAAE,gBAAqB,GAChC,kBAAkB,CAgJpB"}