@bastani/atomic-agent-core 0.0.0-stage → 0.9.88

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 ADDED
@@ -0,0 +1,22 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2025 Mario Zechner
4
+ Copyright (c) 2026 Bastani, Inc.
5
+
6
+ Permission is hereby granted, free of charge, to any person obtaining a copy
7
+ of this software and associated documentation files (the "Software"), to deal
8
+ in the Software without restriction, including without limitation the rights
9
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
10
+ copies of the Software, and to permit persons to whom the Software is
11
+ furnished to do so, subject to the following conditions:
12
+
13
+ The above copyright notice and this permission notice shall be included in all
14
+ copies or substantial portions of the Software.
15
+
16
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
21
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
22
+ SOFTWARE.
package/NOTICE.md ADDED
@@ -0,0 +1,13 @@
1
+ # Notice
2
+
3
+ `@bastani/atomic-agent-core` is a hard fork of the `packages/agent` package from
4
+ [earendil-works/pi](https://github.com/earendil-works/pi). It lives in this
5
+ monorepo at `packages/agent` and publishes at the same version as `@bastani/atomic`.
6
+
7
+ - Upstream package: [`@earendil-works/pi-agent-core`](https://www.npmjs.com/package/@earendil-works/pi-agent-core)
8
+ - Fork point: `v1.5.2` (`earendil-works/pi@b4afdddf44e059c67ccf5097e5317d913521b470`). Atomic does not sync further upstream changes.
9
+
10
+ Original work is Copyright (c) 2025 Mario Zechner and is licensed under the MIT License.
11
+ Bastani modifications are Copyright (c) 2026 Bastani, Inc. and are also licensed under the MIT License.
12
+
13
+ Import from `@bastani/atomic-agent-core` instead of `@earendil-works/pi-agent-core`.
package/README.md CHANGED
@@ -1,3 +1,70 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <a href="https://github.com/bastani-inc/atomic">
3
+ <img alt="Atomic" src="https://raw.githubusercontent.com/bastani-inc/atomic/main/packages/coding-agent/docs/logo.svg" width="324">
4
+ </a>
5
+ </p>
2
6
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
7
+ <p align="center">
8
+ <b>@bastani/atomic-agent-core</b><br>
9
+ A stateful agent loop with tool execution and event streaming.
10
+ </p>
11
+
12
+ <p align="center">
13
+ <a href="https://docs.bastani.ai/libraries/agent-core"><img alt="Docs" src="https://img.shields.io/badge/docs-atomic-blue?style=flat-square" /></a>
14
+ <a href="https://www.npmjs.com/package/@bastani/atomic-agent-core"><img alt="npm" src="https://img.shields.io/npm/v/@bastani/atomic-agent-core?style=flat-square" /></a>
15
+ <a href="https://github.com/bastani-inc/atomic"><img alt="GitHub" src="https://img.shields.io/badge/github-bastani--inc%2Fatomic-181717?style=flat-square&logo=github" /></a>
16
+ </p>
17
+
18
+ ---
19
+
20
+ The agent loop Atomic's sessions run on, built on `@bastani/atomic-ai`: tool execution with before and after hooks, event streaming, steering and follow-up messages, and custom message types.
21
+
22
+ [Atomic](https://github.com/bastani-inc/atomic), the verifiable coding agent runtime, is built on it, and it is published with every Atomic release at Atomic's version.
23
+
24
+ ## Install
25
+
26
+ ```bash
27
+ npm install @bastani/atomic-agent-core
28
+ ```
29
+
30
+ Inside an Atomic extension, import it without installing it: the running Atomic provides it. See [Libraries](https://docs.bastani.ai/libraries).
31
+
32
+ ## Quick start
33
+
34
+ ```typescript
35
+ import { Agent } from "@bastani/atomic-agent-core";
36
+ import { createModels } from "@bastani/atomic-ai";
37
+ import { anthropicProvider } from "@bastani/atomic-ai/providers/anthropic";
38
+
39
+ const models = createModels();
40
+ models.setProvider(anthropicProvider());
41
+ const model = models.getModel("anthropic", "claude-sonnet-4-6");
42
+ if (!model) throw new Error("Model not found");
43
+
44
+ const agent = new Agent({
45
+ initialState: {
46
+ systemPrompt: "You are a helpful assistant.",
47
+ model,
48
+ },
49
+ streamFn: models.streamSimple.bind(models),
50
+ });
51
+
52
+ agent.subscribe((event) => {
53
+ if (event.type === "message_update" && event.assistantMessageEvent.type === "text_delta") {
54
+ // Stream just the new text chunk
55
+ process.stdout.write(event.assistantMessageEvent.delta);
56
+ }
57
+ });
58
+
59
+ await agent.prompt("Hello!");
60
+ ```
61
+
62
+ ## Documentation
63
+
64
+ The full guide and API reference are in Atomic's docs: **[@bastani/atomic-agent-core](https://docs.bastani.ai/libraries/agent-core)**.
65
+
66
+ ## License
67
+
68
+ MIT. See [LICENSE](LICENSE).
69
+
70
+ Derived from pi by Mario Zechner and Earendil Works; see [NOTICE.md](NOTICE.md).
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Agent loop that works with AgentMessage throughout.
3
+ * Transforms to Message[] only at the LLM call boundary.
4
+ */
5
+ import { type AssistantMessage, type ClientIdentity, EventStream } from "@bastani/atomic-ai";
6
+ import type { AgentContext, AgentEvent, AgentLoopConfig, AgentMessage, AgentTool, AgentToolCall, AgentToolCallOutcome, AgentToolResult, StreamFn } from "./types.ts";
7
+ export type AgentEventSink = (event: AgentEvent) => Promise<void> | void;
8
+ /**
9
+ * Request identity of agent loops: `@bastani/atomic-ai`'s defaults with provider attribution to Atomic. `AgentLoopConfig.identity`
10
+ * overrides it field by field.
11
+ */
12
+ export declare const DEFAULT_AGENT_IDENTITY: ClientIdentity;
13
+ /**
14
+ * Start an agent loop with a new prompt message.
15
+ * The prompt is added to the context and events are emitted for it.
16
+ */
17
+ export declare function agentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, signal: AbortSignal | undefined, streamFn: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
18
+ /**
19
+ * Continue an agent loop from the current context without adding a new message.
20
+ * Used for retries - context already has user message or tool results.
21
+ *
22
+ * **Important:** The last message in context must convert to a `user` or `toolResult` message
23
+ * via `convertToLlm`. If it doesn't, the LLM provider will reject the request.
24
+ * This cannot be validated here since `convertToLlm` is only called once per turn.
25
+ */
26
+ export declare function agentLoopContinue(context: AgentContext, config: AgentLoopConfig, signal: AbortSignal | undefined, streamFn: StreamFn): EventStream<AgentEvent, AgentMessage[]>;
27
+ export declare function runAgentLoop(prompts: AgentMessage[], context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal: AbortSignal | undefined, streamFn: StreamFn): Promise<AgentMessage[]>;
28
+ export declare function runAgentLoopContinue(context: AgentContext, config: AgentLoopConfig, emit: AgentEventSink, signal: AbortSignal | undefined, streamFn: StreamFn): Promise<AgentMessage[]>;
29
+ /** The `beforeToolCall` and `afterToolCall` hooks of {@link AgentLoopConfig}. */
30
+ export type ToolCallHooks = Pick<AgentLoopConfig, "beforeToolCall" | "afterToolCall">;
31
+ type ToolUpdateSink = (partialResult: AgentToolResult<any>) => Promise<void> | void;
32
+ /** Options for {@link runToolCall}. */
33
+ export interface RunToolCallOptions extends ToolCallHooks {
34
+ /** Tools the call resolves against. */
35
+ tools: readonly AgentTool<any>[];
36
+ /** Passed to the hooks as the message that issued the call. */
37
+ assistantMessage: AssistantMessage;
38
+ /** Passed to the hooks as the current agent context. */
39
+ context: AgentContext;
40
+ signal?: AbortSignal;
41
+ onUpdate?: ToolUpdateSink;
42
+ }
43
+ /**
44
+ * Run one tool call through the same steps as a model-issued call: argument preparation, schema
45
+ * validation, `beforeToolCall`, execution, and `afterToolCall`. Emits no events and adds no
46
+ * messages. Tools that call other tools use this so the hooks (for example permission checks)
47
+ * apply to those calls too.
48
+ *
49
+ * Never rejects for tool failures: unknown tools, validation errors, blocked calls, and thrown
50
+ * errors come back as `isError: true`.
51
+ */
52
+ export declare function runToolCall(toolCall: AgentToolCall, options: RunToolCallOptions): Promise<AgentToolCallOutcome>;
53
+ export {};
54
+ //# sourceMappingURL=agent-loop.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"agent-loop.d.ts","sourceRoot":"","sources":["../src/agent-loop.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EACN,KAAK,gBAAgB,EAErB,KAAK,cAAc,EACnB,WAAW,EAUX,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EACX,YAAY,EACZ,UAAU,EACV,eAAe,EACf,YAAY,EACZ,SAAS,EACT,aAAa,EACb,oBAAoB,EACpB,eAAe,EAEf,QAAQ,EACR,MAAM,YAAY,CAAC;AAEpB,MAAM,MAAM,cAAc,GAAG,CAAC,KAAK,EAAE,UAAU,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAEzE;;;GAGG;AACH,eAAO,MAAM,sBAAsB,EAAE,cAAoD,CAAC;AAE1F;;;GAGG;AACH,wBAAgB,SAAS,CACxB,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,EAAE,QAAQ,GAChB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAiBzC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAChC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,EAAE,QAAQ,GAChB,WAAW,CAAC,UAAU,EAAE,YAAY,EAAE,CAAC,CAwBzC;AAED,wBAAsB,YAAY,CACjC,OAAO,EAAE,YAAY,EAAE,EACvB,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,YAAY,EAAE,CAAC,CAiBzB;AAED,wBAAsB,oBAAoB,CACzC,OAAO,EAAE,YAAY,EACrB,MAAM,EAAE,eAAe,EACvB,IAAI,EAAE,cAAc,EACpB,MAAM,EAAE,WAAW,GAAG,SAAS,EAC/B,QAAQ,EAAE,QAAQ,GAChB,OAAO,CAAC,YAAY,EAAE,CAAC,CAiBzB;AAqhBD,iFAAiF;AACjF,MAAM,MAAM,aAAa,GAAG,IAAI,CAAC,eAAe,EAAE,gBAAgB,GAAG,eAAe,CAAC,CAAC;AAEtF,KAAK,cAAc,GAAG,CAAC,aAAa,EAAE,eAAe,CAAC,GAAG,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;AAwGpF,uCAAuC;AACvC,MAAM,WAAW,kBAAmB,SAAQ,aAAa;IACxD,uCAAuC;IACvC,KAAK,EAAE,SAAS,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC;IACjC,+DAA+D;IAC/D,gBAAgB,EAAE,gBAAgB,CAAC;IACnC,wDAAwD;IACxD,OAAO,EAAE,YAAY,CAAC;IACtB,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,QAAQ,CAAC,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;;;GAQG;AACH,wBAAsB,WAAW,CAAC,QAAQ,EAAE,aAAa,EAAE,OAAO,EAAE,kBAAkB,GAAG,OAAO,CAAC,oBAAoB,CAAC,CAQrH"}