@celljs/ai-agent 0.0.0-stage → 4.0.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 (126) hide show
  1. package/README.md +68 -2
  2. package/cell.yml +5 -0
  3. package/esm/node/agent/agent-factory.d.ts +10 -0
  4. package/esm/node/agent/agent-factory.js +76 -0
  5. package/esm/node/agent/agent-factory.js.map +1 -0
  6. package/esm/node/agent/index.d.ts +1 -0
  7. package/esm/node/agent/index.js +2 -0
  8. package/esm/node/agent/index.js.map +1 -0
  9. package/esm/node/agent-protocol.d.ts +32 -0
  10. package/esm/node/agent-protocol.js +5 -0
  11. package/esm/node/agent-protocol.js.map +1 -0
  12. package/esm/node/error/errors.d.ts +11 -0
  13. package/esm/node/error/errors.js +16 -0
  14. package/esm/node/error/errors.js.map +1 -0
  15. package/esm/node/error/index.d.ts +1 -0
  16. package/esm/node/error/index.js +2 -0
  17. package/esm/node/error/index.js.map +1 -0
  18. package/esm/node/event/agent-event-util.d.ts +37 -0
  19. package/esm/node/event/agent-event-util.js +60 -0
  20. package/esm/node/event/agent-event-util.js.map +1 -0
  21. package/esm/node/event/index.d.ts +1 -0
  22. package/esm/node/event/index.js +2 -0
  23. package/esm/node/event/index.js.map +1 -0
  24. package/esm/node/index.d.ts +5 -0
  25. package/esm/node/index.js +6 -0
  26. package/esm/node/index.js.map +1 -0
  27. package/esm/node/module.d.ts +3 -0
  28. package/esm/node/module.js +4 -0
  29. package/esm/node/module.js.map +1 -0
  30. package/esm/node/pi/index.d.ts +2 -0
  31. package/esm/node/pi/index.js +3 -0
  32. package/esm/node/pi/index.js.map +1 -0
  33. package/esm/node/pi/pi-agent-core-util.d.ts +6 -0
  34. package/esm/node/pi/pi-agent-core-util.js +17 -0
  35. package/esm/node/pi/pi-agent-core-util.js.map +1 -0
  36. package/esm/node/pi/pi-types.d.ts +6 -0
  37. package/esm/node/pi/pi-types.js +2 -0
  38. package/esm/node/pi/pi-types.js.map +1 -0
  39. package/esm/node/test/index.d.ts +2 -0
  40. package/esm/node/test/index.js +3 -0
  41. package/esm/node/test/index.js.map +1 -0
  42. package/esm/node/test/test-container.d.ts +7 -0
  43. package/esm/node/test/test-container.js +11 -0
  44. package/esm/node/test/test-container.js.map +1 -0
  45. package/esm/package.json +3 -0
  46. package/lib/node/agent/agent-factory.d.ts +11 -0
  47. package/lib/node/agent/agent-factory.d.ts.map +1 -0
  48. package/lib/node/agent/agent-factory.js +79 -0
  49. package/lib/node/agent/agent-factory.js.map +1 -0
  50. package/lib/node/agent/agent-factory.spec.d.ts +47 -0
  51. package/lib/node/agent/agent-factory.spec.d.ts.map +1 -0
  52. package/lib/node/agent/agent-factory.spec.js +109 -0
  53. package/lib/node/agent/agent-factory.spec.js.map +1 -0
  54. package/lib/node/agent/index.d.ts +2 -0
  55. package/lib/node/agent/index.d.ts.map +1 -0
  56. package/lib/node/agent/index.js +18 -0
  57. package/lib/node/agent/index.js.map +1 -0
  58. package/lib/node/agent-protocol.d.ts +33 -0
  59. package/lib/node/agent-protocol.d.ts.map +1 -0
  60. package/lib/node/agent-protocol.js +8 -0
  61. package/lib/node/agent-protocol.js.map +1 -0
  62. package/lib/node/error/errors.d.ts +12 -0
  63. package/lib/node/error/errors.d.ts.map +1 -0
  64. package/lib/node/error/errors.js +22 -0
  65. package/lib/node/error/errors.js.map +1 -0
  66. package/lib/node/error/index.d.ts +2 -0
  67. package/lib/node/error/index.d.ts.map +1 -0
  68. package/lib/node/error/index.js +18 -0
  69. package/lib/node/error/index.js.map +1 -0
  70. package/lib/node/event/agent-event-util.d.ts +38 -0
  71. package/lib/node/event/agent-event-util.d.ts.map +1 -0
  72. package/lib/node/event/agent-event-util.js +63 -0
  73. package/lib/node/event/agent-event-util.js.map +1 -0
  74. package/lib/node/event/agent-event-util.spec.d.ts +2 -0
  75. package/lib/node/event/agent-event-util.spec.d.ts.map +1 -0
  76. package/lib/node/event/agent-event-util.spec.js +81 -0
  77. package/lib/node/event/agent-event-util.spec.js.map +1 -0
  78. package/lib/node/event/index.d.ts +2 -0
  79. package/lib/node/event/index.d.ts.map +1 -0
  80. package/lib/node/event/index.js +18 -0
  81. package/lib/node/event/index.js.map +1 -0
  82. package/lib/node/index.d.ts +6 -0
  83. package/lib/node/index.d.ts.map +1 -0
  84. package/lib/node/index.js +22 -0
  85. package/lib/node/index.js.map +1 -0
  86. package/lib/node/module.d.ts +4 -0
  87. package/lib/node/module.d.ts.map +1 -0
  88. package/lib/node/module.js +6 -0
  89. package/lib/node/module.js.map +1 -0
  90. package/lib/node/pi/index.d.ts +3 -0
  91. package/lib/node/pi/index.d.ts.map +1 -0
  92. package/lib/node/pi/index.js +19 -0
  93. package/lib/node/pi/index.js.map +1 -0
  94. package/lib/node/pi/pi-agent-core-util.d.ts +7 -0
  95. package/lib/node/pi/pi-agent-core-util.d.ts.map +1 -0
  96. package/lib/node/pi/pi-agent-core-util.js +20 -0
  97. package/lib/node/pi/pi-agent-core-util.js.map +1 -0
  98. package/lib/node/pi/pi-types.d.ts +7 -0
  99. package/lib/node/pi/pi-types.d.ts.map +1 -0
  100. package/lib/node/pi/pi-types.js +3 -0
  101. package/lib/node/pi/pi-types.js.map +1 -0
  102. package/lib/node/test/index.d.ts +3 -0
  103. package/lib/node/test/index.d.ts.map +1 -0
  104. package/lib/node/test/index.js +21 -0
  105. package/lib/node/test/index.js.map +1 -0
  106. package/lib/node/test/test-container.d.ts +8 -0
  107. package/lib/node/test/test-container.d.ts.map +1 -0
  108. package/lib/node/test/test-container.js +14 -0
  109. package/lib/node/test/test-container.js.map +1 -0
  110. package/package.json +94 -4
  111. package/src/node/agent/agent-factory.spec.ts +97 -0
  112. package/src/node/agent/agent-factory.ts +60 -0
  113. package/src/node/agent/index.ts +1 -0
  114. package/src/node/agent-protocol.ts +39 -0
  115. package/src/node/error/errors.ts +20 -0
  116. package/src/node/error/index.ts +1 -0
  117. package/src/node/event/agent-event-util.spec.ts +87 -0
  118. package/src/node/event/agent-event-util.ts +79 -0
  119. package/src/node/event/index.ts +1 -0
  120. package/src/node/index.ts +5 -0
  121. package/src/node/module.ts +4 -0
  122. package/src/node/pi/index.ts +2 -0
  123. package/src/node/pi/pi-agent-core-util.ts +19 -0
  124. package/src/node/pi/pi-types.ts +8 -0
  125. package/src/node/test/index.ts +2 -0
  126. package/src/node/test/test-container.ts +15 -0
@@ -0,0 +1,79 @@
1
+ /** The part of a Node.js `ServerResponse` that {@link AgentEventUtil.stream} writes to. */
2
+ export interface EventStreamResponse {
3
+ setHeader(name: string, value: string): unknown;
4
+ write(chunk: string): unknown;
5
+ end(): unknown;
6
+ flushHeaders?(): void;
7
+ readonly writableEnded?: boolean;
8
+ }
9
+
10
+ /** What emits agent events: a pi-agent-core `Agent` or a pi coding agent `AgentSession`. */
11
+ export interface AgentEventSource {
12
+ subscribe(listener: (event: any) => unknown): () => void;
13
+ }
14
+
15
+ /** An agent event: pi-agent-core's `AgentEvent` or pi coding agent's `AgentSessionEvent`. */
16
+ export interface AgentWireEvent {
17
+ type: string;
18
+ [key: string]: any;
19
+ }
20
+
21
+ /** Sent by {@link AgentEventUtil.stream} when the run fails; pi's own events never use this type. */
22
+ export interface AgentErrorEvent {
23
+ type: 'error';
24
+ message: string;
25
+ }
26
+
27
+ export namespace AgentEventUtil {
28
+ /**
29
+ * The event as pi's JSON and RPC modes write it (see pi coding agent's docs/json.md):
30
+ * `message_update` keeps only the delta and the usage, so a stream grows linearly. Other events are unchanged.
31
+ */
32
+ export function toWire<T extends AgentWireEvent>(event: T): AgentWireEvent {
33
+ if (event.type !== 'message_update') {
34
+ return event;
35
+ }
36
+ const { partial, ...delta } = event.assistantMessageEvent as { type: string; contentIndex: number; partial?: { content: any[] } };
37
+ const wire: Record<string, unknown> = delta;
38
+ if (delta.type === 'toolcall_start' && partial) {
39
+ const toolCall = partial.content[delta.contentIndex];
40
+ wire.id = toolCall?.id;
41
+ wire.toolName = toolCall?.name;
42
+ }
43
+ return { type: 'message_update', usage: event.message?.usage, assistantMessageEvent: wire };
44
+ }
45
+
46
+ /** One Server-Sent Events frame: the event type as `event`, the wire event as JSON `data`. */
47
+ export function toSse(event: AgentWireEvent | AgentErrorEvent): string {
48
+ return `event: ${event.type}\ndata: ${JSON.stringify(event)}\n\n`;
49
+ }
50
+
51
+ /**
52
+ * Streams the events of `source` to `response` as Server-Sent Events while `run` (usually
53
+ * `() => agent.prompt(text)`) is pending, then ends the response. A failure of `run` becomes an
54
+ * `error` event. The agent keeps running if the client goes away; abort it explicitly.
55
+ */
56
+ export async function stream(source: AgentEventSource, response: EventStreamResponse, run: () => Promise<unknown>): Promise<void> {
57
+ response.setHeader('Content-Type', 'text/event-stream; charset=utf-8');
58
+ response.setHeader('Cache-Control', 'no-cache, no-transform');
59
+ response.setHeader('Connection', 'keep-alive');
60
+ response.setHeader('X-Accel-Buffering', 'no');
61
+ response.flushHeaders?.();
62
+ const write = (chunk: string) => {
63
+ if (!response.writableEnded) {
64
+ response.write(chunk);
65
+ }
66
+ };
67
+ const unsubscribe = source.subscribe(event => write(toSse(toWire(event))));
68
+ try {
69
+ await run();
70
+ } catch (error) {
71
+ write(toSse({ type: 'error', message: error instanceof Error ? error.message : String(error) }));
72
+ } finally {
73
+ unsubscribe();
74
+ if (!response.writableEnded) {
75
+ response.end();
76
+ }
77
+ }
78
+ }
79
+ }
@@ -0,0 +1 @@
1
+ export * from './agent-event-util';
@@ -0,0 +1,5 @@
1
+ export * from './agent';
2
+ export * from './agent-protocol';
3
+ export * from './error';
4
+ export * from './event';
5
+ export * from './pi';
@@ -0,0 +1,4 @@
1
+ import { autoBind } from '@celljs/core';
2
+ import './index';
3
+
4
+ export default autoBind();
@@ -0,0 +1,2 @@
1
+ export * from './pi-agent-core-util';
2
+ export * from './pi-types';
@@ -0,0 +1,19 @@
1
+ import { AgentError } from '../error';
2
+
3
+ /** The module namespace of `@earendil-works/pi-agent-core`. */
4
+ export type PiAgentCore = typeof import('@earendil-works/pi-agent-core', { with: { 'resolution-mode': 'import' }});
5
+
6
+ export namespace PiAgentCoreUtil {
7
+ let core: Promise<PiAgentCore> | undefined;
8
+
9
+ /** Loads pi-agent-core once, with a dynamic `import()`: it is an ES module package. */
10
+ export function load(): Promise<PiAgentCore> {
11
+ core ??= import('@earendil-works/pi-agent-core').catch(cause => {
12
+ core = undefined;
13
+ throw new AgentError('Cannot load @earendil-works/pi-agent-core. Install it next to @celljs/ai-agent; it needs Node.js >= 22.19.0 or Bun.', {
14
+ cause,
15
+ });
16
+ });
17
+ return core;
18
+ }
19
+ }
@@ -0,0 +1,8 @@
1
+ // pi-agent-core is an ES module package: the CommonJS build of this package can only name its types
2
+ // through import types with `resolution-mode`.
3
+ export type Agent = import('@earendil-works/pi-agent-core', { with: { 'resolution-mode': 'import' }}).Agent;
4
+ export type AgentEvent = import('@earendil-works/pi-agent-core', { with: { 'resolution-mode': 'import' }}).AgentEvent;
5
+ export type AgentMessage = import('@earendil-works/pi-agent-core', { with: { 'resolution-mode': 'import' }}).AgentMessage;
6
+ export type AgentToolResult<T = any> = import('@earendil-works/pi-agent-core', { with: { 'resolution-mode': 'import' }}).AgentToolResult<T>;
7
+ export type AgentToolUpdateCallback<T = any> = import('@earendil-works/pi-agent-core', { with: { 'resolution-mode': 'import' }}).AgentToolUpdateCallback<T>;
8
+ export type ThinkingLevel = import('@earendil-works/pi-agent-core', { with: { 'resolution-mode': 'import' }}).ThinkingLevel;
@@ -0,0 +1,2 @@
1
+ export { FauxPiModels, type FauxPiReply } from '@celljs/ai-pi/lib/node/test';
2
+ export * from './test-container';
@@ -0,0 +1,15 @@
1
+ import { createPiTestContainer, FauxPiModels, type PiTestContainer } from '@celljs/ai-pi/lib/node/test';
2
+ import { autoBind, currentThis } from '@celljs/core';
3
+ import type { AgentOptions } from '../agent-protocol';
4
+ import '../index';
5
+
6
+ const agentModule = autoBind();
7
+
8
+ type ContainerModule = Parameters<typeof createPiTestContainer>[1];
9
+
10
+ /** A container with ai-core, ai-pi, this package and the scripted `FauxPiModels` as the agents' model. */
11
+ export async function createAgentTestContainer(options: AgentOptions = {}, ...modules: ContainerModule[]): Promise<PiTestContainer> {
12
+ const test = await createPiTestContainer({}, agentModule, ...modules);
13
+ currentThis.cellProps.cell.ai.agent = { model: FauxPiModels.MODEL, ...options };
14
+ return test;
15
+ }