@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
package/dist/schema.js ADDED
@@ -0,0 +1,220 @@
1
+ import { DEFAULT_SPAN_TYPE_RISK, UNKNOWN_TOOL_RISK } from './data-risk.js';
2
+ import { SUPPORTED_TOOL_DEFINITIONS } from './tool-definitions.js';
3
+ import { PACKAGE_VERSION } from './version.js';
4
+ /** Version stamped as `_version` on every `$agent:*` payload and result, as Prefactor does. */
5
+ export const AGENT_SPAN_VERSION = 1;
6
+ /** Span type prefix for tool executions. */
7
+ export const TOOL_SPAN_PREFIX = '$agent:tool:';
8
+ /**
9
+ * Span type for tools added after the session started, which have no span type of their own.
10
+ * pi tool names cannot contain `:`, so this name never collides with a tool's own span type.
11
+ */
12
+ export const FALLBACK_TOOL_SPAN_TYPE = `${TOOL_SPAN_PREFIX}pi:other`;
13
+ /** Whether a span type name belongs to the span types the extension defines itself. */
14
+ export function isReservedSpanType(name) {
15
+ return name === 'pi:session' || name.startsWith('$agent:');
16
+ }
17
+ function versioned(properties, required = Object.keys(properties)) {
18
+ return {
19
+ type: 'object',
20
+ properties: { _version: { const: AGENT_SPAN_VERSION }, ...properties },
21
+ required: ['_version', ...required],
22
+ };
23
+ }
24
+ const EMPTY_RESULT = versioned({});
25
+ const TEXT_PARAMS = versioned({ text: { type: 'string' } });
26
+ const USAGE_SCHEMA = versioned({
27
+ input_tokens: { type: 'integer', minimum: 0 },
28
+ output_tokens: { type: 'integer', minimum: 0 },
29
+ cache_read_input_tokens: { type: 'integer', minimum: 0 },
30
+ cache_creation_input_tokens: { type: 'integer', minimum: 0 },
31
+ reasoning_tokens: { type: 'integer', minimum: 0 },
32
+ total_tokens: { type: 'integer', minimum: 0 },
33
+ }, []);
34
+ const COST_SCHEMA = {
35
+ type: 'object',
36
+ description: 'Cost reported by pi, in US dollars',
37
+ properties: {
38
+ input: { type: 'number' },
39
+ output: { type: 'number' },
40
+ cache_read: { type: 'number' },
41
+ cache_write: { type: 'number' },
42
+ total: { type: 'number' },
43
+ },
44
+ };
45
+ function toolSchema(tool, options = {}) {
46
+ const spanType = `${TOOL_SPAN_PREFIX}${tool.name}`;
47
+ const definition = Object.hasOwn(SUPPORTED_TOOL_DEFINITIONS, tool.name)
48
+ ? SUPPORTED_TOOL_DEFINITIONS[tool.name]
49
+ : undefined;
50
+ return {
51
+ name: spanType,
52
+ title: options.title ?? tool.name,
53
+ description: options.description ?? definition?.description ?? tool.description ?? `The ${tool.name} tool`,
54
+ template: options.template ?? definition?.template ?? `${tool.name}{% if error %} (error){% endif %}`,
55
+ params_schema: versioned({
56
+ tool_use_id: { type: 'string', description: 'Tool call id assigned by the model' },
57
+ params: options.params_schema ?? definition?.inputSchema ?? { type: 'object' },
58
+ }),
59
+ result_schema: versioned({
60
+ result: {
61
+ type: 'object',
62
+ properties: {
63
+ content: { type: 'array', description: 'Content returned to the model' },
64
+ details: options.result_schema ?? {
65
+ description: 'Structured details returned by the tool',
66
+ },
67
+ },
68
+ },
69
+ error: { type: 'string' },
70
+ }, []),
71
+ data_risk: options.data_risk ?? DEFAULT_SPAN_TYPE_RISK[spanType] ?? UNKNOWN_TOOL_RISK,
72
+ };
73
+ }
74
+ /**
75
+ * Names of the tools that get their own span type: the tools pi has at session start and the
76
+ * tools given span type details, in that order, without repeats.
77
+ */
78
+ export function registeredToolNames(tools, toolSchemas = {}) {
79
+ return [...new Set([...tools.map((tool) => tool.name), ...Object.keys(toolSchemas)])];
80
+ }
81
+ /**
82
+ * Builds the agent schema version registered for each pi session. pi's own work is recorded with
83
+ * the canonical `$agent:*` span types, so Prefactor shows the session as a conversation, inside
84
+ * a `pi:session` root span. Each tool pi has at session start, and each tool in
85
+ * `extensions.toolSchemas`, gets its own span type. The developer's span types, quality schemas
86
+ * and alert schemas follow.
87
+ */
88
+ export function buildAgentSchemaVersion(tools, extensions = {}) {
89
+ const toolSchemas = registeredToolNames(tools, extensions.toolSchemas).map((name) => toolSchema(tools.find((tool) => tool.name === name) ?? { name }, extensions.toolSchemas?.[name]));
90
+ return {
91
+ external_identifier: `prefactor-pi-${PACKAGE_VERSION}`,
92
+ span_type_schemas: [
93
+ {
94
+ name: 'pi:session',
95
+ title: 'pi session',
96
+ description: 'One pi session, from session start to shutdown',
97
+ template: 'pi session in {{ cwd | default: "(unknown directory)" }}',
98
+ params_schema: {
99
+ type: 'object',
100
+ properties: {
101
+ session_id: { type: 'string' },
102
+ cwd: { type: 'string', description: 'Working directory of the session' },
103
+ mode: { type: 'string', description: 'pi run mode: tui, rpc, json or print' },
104
+ reason: { type: 'string', description: 'Why the session started' },
105
+ provider: { type: 'string' },
106
+ model: { type: 'string' },
107
+ },
108
+ required: ['session_id', 'cwd'],
109
+ },
110
+ result_schema: {
111
+ type: 'object',
112
+ properties: { reason: { type: 'string', description: 'Why the session shut down' } },
113
+ },
114
+ data_risk: DEFAULT_SPAN_TYPE_RISK['pi:session'],
115
+ },
116
+ {
117
+ name: '$agent:system_message',
118
+ title: 'System message',
119
+ description: 'The system prompt, recorded when a run starts with a changed prompt',
120
+ template: 'System message: {{ text }}',
121
+ params_schema: TEXT_PARAMS,
122
+ result_schema: EMPTY_RESULT,
123
+ data_risk: DEFAULT_SPAN_TYPE_RISK['$agent:system_message'],
124
+ },
125
+ {
126
+ name: '$agent:user_turn',
127
+ title: 'User turn',
128
+ description: 'One user turn',
129
+ template: 'User turn {{ turn }}',
130
+ params_schema: versioned({
131
+ turn: { type: 'integer', description: 'Number of the user turn in this session' },
132
+ }),
133
+ result_schema: EMPTY_RESULT,
134
+ data_risk: DEFAULT_SPAN_TYPE_RISK['$agent:user_turn'],
135
+ },
136
+ {
137
+ name: '$agent:user_message',
138
+ title: 'User message',
139
+ description: 'A user message: a prompt, steering message or follow-up message',
140
+ template: 'User message: {{ text }}',
141
+ params_schema: TEXT_PARAMS,
142
+ result_schema: EMPTY_RESULT,
143
+ data_risk: DEFAULT_SPAN_TYPE_RISK['$agent:user_message'],
144
+ },
145
+ {
146
+ name: '$agent:assistant_turn',
147
+ title: 'Assistant turn',
148
+ description: 'The assistant responses and tool calls that follow a user turn',
149
+ template: 'Assistant turn{% if stop_reason %} -> {{ stop_reason }}{% endif %}',
150
+ params_schema: versioned({}),
151
+ result_schema: versioned({ stop_reason: { type: 'string' }, usage: USAGE_SCHEMA }, []),
152
+ data_risk: DEFAULT_SPAN_TYPE_RISK['$agent:assistant_turn'],
153
+ },
154
+ {
155
+ name: '$agent:llm_call',
156
+ title: 'LLM call',
157
+ description: 'One LLM response',
158
+ template: '{{ request.provider_name }}/{{ request.model }}{% if response.stop_reason %} -> {{ response.stop_reason }}{% endif %}{% if response.usage.total_tokens %} ({{ response.usage.total_tokens }} tokens){% endif %}',
159
+ params_schema: versioned({
160
+ request: versioned({
161
+ model: { type: 'string' },
162
+ provider_name: { type: 'string' },
163
+ api: { type: 'string', description: 'pi API used to call the provider' },
164
+ }, ['model', 'provider_name']),
165
+ }),
166
+ result_schema: versioned({
167
+ response: versioned({
168
+ id: { type: 'string' },
169
+ model: { type: 'string', description: 'Model that answered' },
170
+ provider_name: { type: 'string' },
171
+ stop_reason: { type: 'string' },
172
+ usage: USAGE_SCHEMA,
173
+ cost: COST_SCHEMA,
174
+ timestamp_started: { type: 'string', format: 'date-time' },
175
+ timestamp_completed: { type: 'string', format: 'date-time' },
176
+ }, ['model', 'provider_name']),
177
+ error: { type: 'string' },
178
+ }, []),
179
+ data_risk: DEFAULT_SPAN_TYPE_RISK['$agent:llm_call'],
180
+ },
181
+ {
182
+ name: '$agent:assistant_message',
183
+ title: 'Assistant message',
184
+ description: 'Assistant text produced by the model',
185
+ template: 'Assistant message: {{ text }}',
186
+ params_schema: TEXT_PARAMS,
187
+ result_schema: EMPTY_RESULT,
188
+ data_risk: DEFAULT_SPAN_TYPE_RISK['$agent:assistant_message'],
189
+ },
190
+ {
191
+ name: '$agent:assistant_thinking',
192
+ title: 'Assistant thinking',
193
+ description: 'Model reasoning',
194
+ template: 'Thinking: {{ text }}',
195
+ params_schema: versioned({
196
+ text: { type: 'string' },
197
+ type: { type: 'string', enum: ['opaque', 'transparent'] },
198
+ }),
199
+ result_schema: EMPTY_RESULT,
200
+ data_risk: DEFAULT_SPAN_TYPE_RISK['$agent:assistant_thinking'],
201
+ },
202
+ ...toolSchemas,
203
+ {
204
+ ...toolSchema({ name: 'pi:other' }),
205
+ title: 'Other tool',
206
+ description: 'Execution of a pi tool added after the session started',
207
+ template: '{{ tool_name | default: "(unknown tool)" }}{% if error %} (error){% endif %}',
208
+ params_schema: versioned({
209
+ tool_use_id: { type: 'string', description: 'Tool call id assigned by the model' },
210
+ tool_name: { type: 'string', description: 'Name of the pi tool' },
211
+ params: { type: 'object' },
212
+ }),
213
+ },
214
+ ...(extensions.spanTypeSchemas ?? []),
215
+ ],
216
+ ...(extensions.qualitySchemas?.length ? { quality_schemas: extensions.qualitySchemas } : {}),
217
+ ...(extensions.alertSchemas?.length ? { alert_schemas: extensions.alertSchemas } : {}),
218
+ };
219
+ }
220
+ //# sourceMappingURL=schema.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"schema.js","sourceRoot":"","sources":["../src/schema.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,144 @@
1
+ import type { PrefactorSession, SpanHandle, SpanStatus } from './prefactor-session.js';
2
+ /** The fields of pi's assistant message that the tracer records. */
3
+ export interface AssistantMessageLike {
4
+ role: 'assistant';
5
+ content: unknown[];
6
+ api?: string;
7
+ provider: string;
8
+ model: string;
9
+ responseModel?: string;
10
+ responseId?: string;
11
+ usage?: {
12
+ input: number;
13
+ output: number;
14
+ cacheRead: number;
15
+ cacheWrite: number;
16
+ reasoning?: number;
17
+ totalTokens: number;
18
+ cost?: {
19
+ input: number;
20
+ output: number;
21
+ cacheRead: number;
22
+ cacheWrite: number;
23
+ total: number;
24
+ };
25
+ };
26
+ stopReason?: string;
27
+ errorMessage?: string;
28
+ timestamp: number;
29
+ durationMs?: number;
30
+ }
31
+ /** The fields of pi's user message that the tracer records. */
32
+ export interface UserMessageLike {
33
+ role: 'user';
34
+ content: unknown;
35
+ }
36
+ export interface SessionStartInfo {
37
+ sessionId: string;
38
+ cwd: string;
39
+ mode: string;
40
+ reason: string;
41
+ provider?: string;
42
+ model?: string;
43
+ /** Names of the tools pi has at session start. Other tools use the fallback span type. */
44
+ toolNames: string[];
45
+ }
46
+ export interface ToolExecutionStart {
47
+ toolCallId: string;
48
+ toolName: string;
49
+ args: unknown;
50
+ parentToolCallId?: string;
51
+ }
52
+ export interface ToolExecutionEnd {
53
+ toolCallId: string;
54
+ result: unknown;
55
+ isError: boolean;
56
+ }
57
+ export interface TracerLimits {
58
+ maxInputLength: number;
59
+ maxOutputLength: number;
60
+ }
61
+ /**
62
+ * Maps one pi session's events onto Prefactor's canonical agent spans, inside a `pi:session` root
63
+ * span:
64
+ *
65
+ * - `$agent:system_message` when a run starts with a system prompt that differs from the last one
66
+ * recorded.
67
+ * - `$agent:user_turn` with its `$agent:user_message` for each user message, including steering
68
+ * and follow-up messages.
69
+ * - `$agent:assistant_turn` for the assistant's work after a user turn, holding each response's
70
+ * `$agent:llm_call`, its `$agent:assistant_thinking` and `$agent:assistant_message` blocks, and
71
+ * `$agent:tool:<name>` tool executions. A tool called by another tool is a child of that tool.
72
+ *
73
+ * The assistant turn finishes at the end of the run, or when a steering message starts the next
74
+ * user turn. Start and finish times come from one clock that never repeats or goes back, so
75
+ * Prefactor orders spans as they happened, no span finishes before it starts, and no parent
76
+ * finishes before its children.
77
+ */
78
+ export declare class SessionTracer {
79
+ private readonly session;
80
+ private readonly limits;
81
+ private sessionSpan;
82
+ private assistantTurn;
83
+ private userTurns;
84
+ private recordedSystemPrompt;
85
+ private toolNames;
86
+ private lastTimestamp;
87
+ private readonly toolSpans;
88
+ private readonly customSpans;
89
+ constructor(session: PrefactorSession, limits: TracerLimits);
90
+ sessionStart(info: SessionStartInfo): void;
91
+ /**
92
+ * Starts a run. An assistant turn left open by a run that never ended is cancelled, and the
93
+ * system prompt is recorded when it differs from the last one recorded.
94
+ */
95
+ agentStart(systemPrompt: string): void;
96
+ /** Finishes the run's assistant turn. */
97
+ agentEnd(): void;
98
+ /** Records a user message, which ends any open assistant turn and starts a user turn. */
99
+ userMessage(message: UserMessageLike): void;
100
+ /**
101
+ * Records a finished assistant message as an `$agent:llm_call` with its thinking and text
102
+ * blocks, in the open assistant turn, which it opens when there is none.
103
+ */
104
+ assistantMessage(message: AssistantMessageLike): void;
105
+ toolStart(event: ToolExecutionStart): void;
106
+ toolEnd(event: ToolExecutionEnd): void;
107
+ /**
108
+ * Starts a span of one of the developer's span types. Its parent is `parent`, else the span of
109
+ * the tool call `toolCallId` while that call runs, else the open assistant turn, else the
110
+ * session span.
111
+ */
112
+ startCustomSpan(options: {
113
+ schemaName: string;
114
+ payload: Record<string, unknown>;
115
+ parent?: SpanHandle;
116
+ toolCallId?: string;
117
+ }): SpanHandle;
118
+ /**
119
+ * Finishes a span from {@link startCustomSpan}. A span already finished is left as it is. When
120
+ * the result cannot be serialized, this throws and the span stays open, so a later call or
121
+ * shutdown can still finish it.
122
+ */
123
+ finishCustomSpan(span: SpanHandle, status: SpanStatus, result: Record<string, unknown>): void;
124
+ /**
125
+ * Finishes every open span, then the session span. Open custom spans, tools and the open
126
+ * assistant turn are cancelled.
127
+ */
128
+ sessionShutdown(reason: string): void;
129
+ private openAssistantTurn;
130
+ /**
131
+ * Finishes the open assistant turn with the stop reason of its last response and the usage
132
+ * summed over its responses. The status follows the last response unless one is given.
133
+ */
134
+ private endAssistantTurn;
135
+ private recordContentBlock;
136
+ /**
137
+ * Returns `at` (default now), moved later when needed so that it is after every timestamp
138
+ * returned before.
139
+ */
140
+ private timestamp;
141
+ private input;
142
+ private output;
143
+ }
144
+ //# sourceMappingURL=session-tracer.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-tracer.d.ts","sourceRoot":"","sources":["../src/session-tracer.ts"],"names":[],"mappings":"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"}