@hypen-space/gloop-effect 0.1.0

package/README.md

@@ -0,0 +1,422 @@
+# @hypen-space/gloop-effect
+
+Effect-TS native agent loop. Pairs with [`@hypen-space/gloop-loop`](../gloop-loop) — the Form ADT, slash-command parser, skill helpers, and builtin tool bodies are shared; the actor shell, provider interface, error model, and event bus are rebuilt on Effect primitives (`Stream`, `Fiber`, `PubSub`, `Ref`, `Queue`).
+
+## Why use this over `gloop-loop`?
+
+- **Typed errors** — every failure is a `Schema.TaggedError`, so `catchTag`/`catchTags` narrows precisely.
+- **Stream events** — `agent.events: Stream<AgentEvent>` fans out via `PubSub`; subscribers get backpressure + filter/map/merge for free.
+- **Fiber interrupts** — `agent.interrupt` uses structured concurrency, not an `AbortController`.
+- **Layer-based DI** — providers, memory, and IO drop in as `Layer`s at the app root.
+- **Spans everywhere** — public methods wrap themselves in `Effect.fn(...)` / `Effect.withSpan(...)` with useful attributes. Plug in `@effect/opentelemetry` and get a full trace per turn.
+- **Schema-unified** — events, IDs, messages, tool calls are all `Schema.TaggedStruct` — JSON-codec-ready for RPC transport.
+
+## Install
+
+```bash
+bun add @hypen-space/gloop-effect effect
+# or: npm install / pnpm add
+```
+
+You need an `OPENROUTER_API_KEY` in the environment for the default provider.
+
+## Quick start — a deploy bot with 3 tools
+
+```ts
+import { Effect, Option, Stream } from "effect"
+import { NodeRuntime } from "@effect/platform-node"
+import {
+  Agent,
+  OpenRouterProviderLive,
+  type Tool,
+} from "@hypen-space/gloop-effect"
+
+const listEnvs: Tool<never> = {
+  name: "ListEnvironments",
+  description: "List all deployment environments.",
+  arguments: [],
+  execute: () => Effect.succeed("staging, prod, canary"),
+}
+
+const getStatus: Tool<never> = {
+  name: "GetStatus",
+  description: "Get the current deployment status of an environment.",
+  arguments: [{ name: "env", description: "Environment name" }],
+  execute: (args) => Effect.succeed(`${args.env}: healthy, 3 instances`),
+}
+
+const deploy: Tool<never> = {
+  name: "Deploy",
+  description: "Deploy the current build to an environment.",
+  arguments: [
+    { name: "env", description: "Target environment" },
+    { name: "version", description: "Version tag" },
+  ],
+  // Returning Some(reason) pauses the turn for ConfirmRequest.
+  askPermission: (args) =>
+    args.env === "prod"
+      ? Option.some(`Deploy ${args.version} to prod?`)
+      : Option.none(),
+  execute: (args) => Effect.succeed(`Deployed ${args.version} to ${args.env}`),
+}
+
+const program = Effect.gen(function* () {
+  const agent = yield* Agent.make({
+    model: "anthropic/claude-sonnet-4.5",
+    system: "You are a deploy bot. Use the tools to help the user.",
+    tools: [listEnvs, getStatus, deploy],
+    // Auto-approve every confirm. For a TUI, omit this and listen for
+    // ConfirmRequest events instead.
+    confirm: () => Effect.succeed(true),
+  })
+
+  // Render streaming chunks to stdout.
+  yield* Effect.forkScoped(
+    agent.events.pipe(
+      Stream.runForEach((e) =>
+        e._tag === "StreamChunk"
+          ? Effect.sync(() => process.stdout.write(e.text))
+          : Effect.void,
+      ),
+    ),
+  )
+
+  yield* agent.sendSync("deploy v2.1.0 to staging and report status")
+})
+
+NodeRuntime.runMain(
+  Effect.scoped(program).pipe(
+    Effect.provide(
+      OpenRouterProviderLive({ apiKey: process.env.OPENROUTER_API_KEY! }),
+    ),
+  ),
+)
+```
+
+## The shape of `Agent`
+
+```ts
+interface Agent {
+  send:       (msg: AgentMessage | string) => Effect<MessageId>
+  sendSync:   (msg: AgentMessage | string) => Effect<void, AgentError>
+  events:     Stream<AgentEvent>
+  eventsOf:   <T extends AgentEvent["_tag"]>(tag: T) => Stream<AgentEventOf<T>>
+  interrupt:  Effect<void>
+  stop:       Effect<void>
+  awaitIdle:  Effect<void>
+  pending:    Effect<number>
+
+  addTool:    <E extends AgentError>(tool: Tool<E>) => Effect<void>
+  removeTool: (name: string) => Effect<void>
+  setTools:   (tools: ReadonlyArray<AnyTool>) => Effect<void>
+  setSystem:  (prompt: string) => Effect<void>
+  clear:      Effect<void>
+
+  respondToConfirm: (id: RequestId, ok: boolean) => Effect<void>
+  respondToAsk:     (id: RequestId, answer: string) => Effect<void>
+
+  registry:     ToolRegistry
+  conversation: ConversationHandle
+}
+```
+
+`Agent.make` is **scoped** — run inside `Effect.scoped` (or provide a `Scope` layer) so resources tear down cleanly.
+
+## Subscribing to events
+
+```ts
+// Full firehose
+agent.events.pipe(Stream.runForEach(handleEvent))
+
+// Single tag — type-narrowed
+agent.eventsOf("ToolDone").pipe(
+  Stream.runForEach((e) => Effect.log(`tool ${e.name} → ${e.ok}`)),
+)
+
+// Merged or filtered
+Stream.merge(
+  agent.eventsOf("StreamChunk"),
+  agent.eventsOf("TaskComplete"),
+).pipe(Stream.runForEach(...))
+```
+
+Every call creates a fresh subscription via `PubSub.subscribe` — late subscribers miss past events. Subscribe *before* sending if you need a specific event (or use `sendSync`, which subscribes internally and awaits the matching `TurnEnd`).
+
+### Event variants
+
+`AgentEvent` is a `Schema.Union` of 17 `TaggedStruct` variants, discriminated on `_tag`:
+
+| Tag | Payload | When |
+|---|---|---|
+| `TurnStart` | `message` | A message is about to be processed |
+| `TurnEnd` | — | The current turn finished |
+| `Busy` / `Idle` | — | The loop picked up / drained work |
+| `QueueChanged` | `pending` | Inbox size changed |
+| `StreamChunk` | `text` | Streamed assistant text delta |
+| `StreamDone` | — | Stream finished (tool calls may follow) |
+| `ToolStart` / `ToolDone` | `id`, `name`, …​ | Tool invocation lifecycle |
+| `Memory` | `op`, `content` | Agent called Remember / Forget |
+| `SystemRefreshed` | — | System prompt was rebuilt |
+| `TaskComplete` | `summary` | CompleteTask was called |
+| `Interrupted` | — | Current turn was aborted |
+| `Error` / `Fatal` | `error: AgentError` | Non-fatal / fatal turn error |
+| `ConfirmRequest` / `AskRequest` | `id`, …​ | Blocking user prompt |
+
+## Custom tools
+
+Tools are plain objects whose `execute` returns an `Effect`. The error channel is constrained to `AgentError` so failures fit the interpreter's union:
+
+```ts
+import { Effect, Option } from "effect"
+import { ToolExecutionError, type Tool } from "@hypen-space/gloop-effect"
+
+const fetchUrl: Tool<ToolExecutionError> = {
+  name: "FetchUrl",
+  description: "HTTP GET a URL and return the body",
+  arguments: [{ name: "url", description: "Full URL" }],
+  askPermission: (args) => Option.none(),          // None → run immediately
+  execute: (args) =>
+    Effect.tryPromise({
+      try: () => fetch(args.url!).then((r) => r.text()),
+      catch: (e) =>
+        new ToolExecutionError({
+          name: "FetchUrl",
+          message: e instanceof Error ? e.message : String(e),
+          cause: e,
+        }),
+    }),
+}
+```
+
+Tool failures fold into a `ToolResult { success: false }` — the model sees the error and decides whether to retry. If you want a tool error to be **turn-fatal**, return `Effect.die(...)` instead of `Effect.fail(...)`.
+
+### Builtins
+
+```ts
+import { primitiveTools } from "@hypen-space/gloop-effect"
+
+const agent = yield* Agent.make({
+  model: "...",
+  system: "...",
+  tools: primitiveTools(),       // ReadFile, WriteFile, Patch_file, Bash, CompleteTask, AskUser, Remember, Forget, ManageContext
+})
+```
+
+Wraps `gloop-loop`'s builtins as `Tool<ToolExecutionError>`. Pass a custom `BuiltinIO` to override filesystem / shell semantics.
+
+## Skills (Agent Skills / `SKILL.md`)
+
+Pass discovered skills via `AgentMakeOptions.skills` — the agent:
+
+1. **Merges names + descriptions into the system prompt** so the model knows what exists.
+2. **Auto-registers `InvokeSkill`** as a tool so the model can call `InvokeSkill(name, arguments)` and receive the fully-substituted skill body as the next turn's input. (If you pass your own tool named `InvokeSkill`, it takes precedence.)
+3. **Resolves slash commands** in user messages: `/skills` lists, `/skill <name> [args]` runs, `/<name> [args]` runs if `<name>` matches a skill.
+
+```ts
+import {
+  Agent,
+  parseSkillMarkdown,
+  type Skill,
+} from "@hypen-space/gloop-effect"
+import { readdir, readFile } from "node:fs/promises"
+
+// Your host discovers SKILL.md files wherever — .claude/skills, .agent/skills, etc.
+const skills: Skill[] = await Promise.all(
+  (await readdir(".claude/skills")).map(async (dir) => {
+    const body = await readFile(`.claude/skills/${dir}/SKILL.md`, "utf8")
+    return parseSkillMarkdown(body, dir)
+  }),
+)
+
+const agent = yield* Agent.make({
+  model: "...",
+  system: "You are a designer.",
+  skills,
+})
+
+yield* agent.sendSync("/skill web-design-guidelines review the homepage")
+```
+
+Skill discovery lives in **your host code** — the library doesn't read the filesystem for them. Use `parseSkillMarkdown` / `findSkill` / `mergeSkillsIntoSystem` / `formatSkillsListing` / `applySkillSubstitutions` / `splitSkillArguments` / `matchSkillSlash` / `skillInvocationToThinkInput` / `thinkInputFromSkillSubcommand` — all re-exported from this package.
+
+## Hosts, memory, and defaults
+
+Three shipped defaults — each a single import away:
+
+### `OpenRouterProviderLive`
+
+```ts
+import { OpenRouterProviderLive } from "@hypen-space/gloop-effect"
+
+const ProviderLive = OpenRouterProviderLive({
+  apiKey: process.env.OPENROUTER_API_KEY!,
+  httpReferer: "https://myapp.example",   // optional
+  xTitle: "my-app",                       // optional
+})
+```
+
+Provides the `AIProvider` service. Spans on `OpenRouterProvider.complete` and `.stream.*` with `model` attributes.
+
+### `fileMemory`
+
+```ts
+import { fileMemory } from "@hypen-space/gloop-effect"
+
+const memory = fileMemory({
+  path: "./.gloop/memory.md",            // default
+  maxEntryLength: 500,                    // default
+})
+
+const agent = yield* Agent.make({
+  model: "...",
+  system: "...",
+  remember: memory.remember,              // plug into hooks
+  forget:   memory.forget,
+})
+```
+
+### `createNodeIO`
+
+```ts
+import { createNodeIO, primitiveTools } from "@hypen-space/gloop-effect"
+
+const io = createNodeIO()
+const tools = primitiveTools(io)          // ReadFile/WriteFile/Bash use these
+```
+
+## Tracing
+
+Every public method is a named span:
+
+| Span | Attributes |
+|---|---|
+| `Agent.send` / `sendSync` / `interrupt` / `stop` / `awaitIdle` / `respondTo*` | `messageId`, `requestId` |
+| `Agent.runTurn` | `messageId`, `role`, `contentLength` |
+| `Conversation.send` / `.stream` | `model`, `historyLength`, `toolCount` |
+| `OpenRouterProvider.complete` / `.stream.*` | `model` |
+| `Interpreter.evalForm` | `form` (tag) |
+| `Interpreter.evalThink` | — |
+| `Interpreter.evalInvoke` | `toolCount` |
+| `Interpreter.dispatchCall` | `tool`, `kind`, `success`, `denied` |
+| `ToolRegistry.register` / `.unregister` | `toolName` |
+
+Wire an exporter with `@effect/opentelemetry`:
+
+```ts
+import { NodeSdk } from "@effect/opentelemetry"
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http"
+import { BatchSpanProcessor } from "@opentelemetry/sdk-trace-base"
+
+const TracingLive = NodeSdk.layer(() => ({
+  resource: { serviceName: "my-agent" },
+  spanProcessor: new BatchSpanProcessor(
+    new OTLPTraceExporter({ url: "http://localhost:4318/v1/traces" }),
+  ),
+}))
+
+NodeRuntime.runMain(
+  Effect.scoped(program).pipe(
+    Effect.provide(Layer.mergeAll(ProviderLive, TracingLive)),
+  ),
+)
+```
+
+No code change in your app — the spans already exist.
+
+## Logging
+
+Two channels:
+
+**Effect-native** — `Effect.log` / `Effect.logInfo` / `Effect.logDebug`. Provide any `Logger` layer at the root:
+
+```ts
+import { Logger, LogLevel } from "effect"
+
+Effect.provide(Logger.pretty),                         // human-readable
+Effect.provide(Logger.json),                           // one JSON line per log
+Effect.provide(Logger.withMinimumLogLevel(LogLevel.Debug))
+```
+
+Internally, `LLM_INPUT` / `LLM_OUTPUT` / `TOOL_CALLS` are emitted at `Debug` level.
+
+**Host debug hook** — `AgentMakeOptions.log: (label, content) => Effect<void>`. Fires alongside the Effect logger. Useful for piping transcripts to a file or a TUI panel:
+
+```ts
+const agent = yield* Agent.make({
+  model: "...",
+  system: "...",
+  log: (label, content) =>
+    Effect.sync(() => fs.appendFileSync("debug.log", `[${label}] ${content}\n`)),
+})
+```
+
+## Errors
+
+All failures are `Schema.TaggedError` with a `message` field:
+
+| Error | When |
+|---|---|
+| `AIProviderError` | Provider call failed — carries `op`, `model`, `provider`, `cause` |
+| `ToolNotFoundError` | Model called a tool that isn't registered |
+| `ToolExecutionError` | A tool's `execute` failed |
+| `ToolPermissionDeniedError` | A gated tool was denied by the host |
+| `AgentInterruptedError` | The current turn was interrupted |
+| `FatalAgentError` | Turn-level error classified as fatal via `isFatal` |
+| `FileIOError` | `BuiltinIO` read/write/delete failed — carries `op`, `path` |
+| `ShellExecError` | `BuiltinIO.exec` non-zero exit |
+| `MemoryError` | `fileMemory` read/write failed |
+
+`AgentError` is the union. Use `catchTag`/`catchTags` — never `catchAll`:
+
+```ts
+yield* agent.sendSync(userInput).pipe(
+  Effect.catchTags({
+    AIProviderError:         (e) => showBanner(`Provider down: ${e.provider ?? "?"}`),
+    AgentInterruptedError:   () => showBanner("Interrupted"),
+    ToolExecutionError:      (e) => showBanner(`Tool ${e.name} failed`),
+  }),
+)
+```
+
+## Testing
+
+The bundled `test/helpers.ts` exposes a scriptable stub provider:
+
+```ts
+import { Effect, Layer, Stream } from "effect"
+import { AIProvider, type AIProviderImpl } from "@hypen-space/gloop-effect"
+
+const stub: AIProviderImpl = {
+  name: "stub",
+  complete: () => Effect.succeed({ id: "x", model: "stub", content: "ok", finishReason: "stop" }),
+  stream:   () => ({
+    chunks: Stream.fromIterable(["o", "k"]),
+    result: Effect.succeed({ id: "x", model: "stub", content: "ok", finishReason: "stop" }),
+    cancel: Effect.void,
+  }),
+}
+
+Effect.runPromise(
+  Effect.scoped(program).pipe(
+    Effect.provide(Layer.succeed(AIProvider, stub)),
+  ),
+)
+```
+
+See `test/` for 21 tests covering: actor lifecycle (`interrupt`, `stop`, `awaitIdle`), error escalation (`Error` vs `Fatal`), tool execution + `ToolStart`/`ToolDone` pairing, confirm approve / deny, skill auto-registration, and conversation history.
+
+## What's shared with `gloop-loop`
+
+Pure / data / helpers are imported directly — no duplicate source of truth:
+
+- `Form` ADT (`Think`, `Invoke`, `Confirm`, `Ask`, `Remember`, `Forget`, `Emit`, `Refresh`, `Done`, `Seq`, `Nil`, `Install`, `ListTools`, `Spawn`) and the interpreter dispatch (`toolCallsToForm`, `formatResults`, `parseInput`)
+- Skill parsing/formatting (`parseSkillMarkdown`, `findSkill`, `mergeSkillsIntoSystem`, `formatSkillsListing`, `applySkillSubstitutions`, `splitSkillArguments`, `matchSkillSlash`, `skillInvocationToThinkInput`, `thinkInputFromSkillSubcommand`, `createInvokeSkillTool`)
+- Builtin tool bodies (wrapped by `toEffectTool` into Effect tools)
+- `createNodeIO`, `createFileMemory` (wrapped with Effect adapters)
+- OpenRouter HTTP logic (wrapped into the `AIProvider` layer)
+
+Rebuilt on Effect primitives: the actor shell, provider interface, conversation state, tool registry, error types, and every public method signature.
+
+## License
+
+MIT

package/dist/AIProvider.d.ts

@@ -0,0 +1,43 @@
+/**
+ * gloop-effect/AIProvider — Effect-native provider interface.
+ *
+ * Wraps the callable surface of an LLM provider as an Effect service.
+ * `complete` returns a plain Effect; `stream` returns a Stream of chunks
+ * plus an Effect for the finalized response (including tool calls).
+ *
+ * Concrete providers (OpenRouter, Anthropic, local) are registered by
+ * providing a layer at the application root.
+ */
+import { Context, Effect, Stream } from "effect";
+import type { AIRequestConfig, AIResponse, JsonToolCall } from "@hypen-space/gloop-loop";
+import type { AIProviderError } from "./Errors.js";
+/**
+ * A streaming response. `chunks` yields text deltas as they arrive; `result`
+ * resolves once the stream is complete with tool calls and finish reason.
+ *
+ * Consumers typically drain `chunks` (to emit `stream_chunk` events) and
+ * then await `result` to pick up any tool calls.
+ */
+export interface StreamResponse {
+    readonly chunks: Stream.Stream<string, AIProviderError>;
+    readonly result: Effect.Effect<AIResponse, AIProviderError>;
+    /** Cancel an in-flight stream. Safe to call after the stream completes. */
+    readonly cancel: Effect.Effect<void>;
+}
+export interface AIProviderImpl {
+    readonly name: string;
+    readonly complete: (config: AIRequestConfig) => Effect.Effect<AIResponse, AIProviderError>;
+    readonly stream: (config: AIRequestConfig) => StreamResponse;
+}
+declare const AIProvider_base: Context.TagClass<AIProvider, "gloop/AIProvider", AIProviderImpl>;
+export declare class AIProvider extends AIProvider_base {
+}
+/**
+ * Drain a `StreamResponse`: emit each chunk through `onChunk`, then resolve
+ * with the final `AIResponse`. Interruption cancels the underlying stream.
+ */
+export declare const consumeStream: (response: StreamResponse, onChunk: (text: string) => Effect.Effect<void>) => Effect.Effect<AIResponse, AIProviderError>;
+/** Extract just the tool calls from a completed AIResponse. */
+export declare const toolCallsOf: (response: AIResponse) => ReadonlyArray<JsonToolCall>;
+export {};
+//# sourceMappingURL=AIProvider.d.ts.map

package/dist/AIProvider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIProvider.d.ts","sourceRoot":"","sources":["../src/AIProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAChD,OAAO,KAAK,EACV,eAAe,EACf,UAAU,EACV,YAAY,EACb,MAAM,yBAAyB,CAAA;AAChC,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,aAAa,CAAA;AAMlD;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE,eAAe,CAAC,CAAA;IACvD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAA;IAC3D,2EAA2E;IAC3E,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAA;CACrC;AAMD,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,QAAQ,EAAE,CACjB,MAAM,EAAE,eAAe,KACpB,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAAC,CAAA;IAC/C,QAAQ,CAAC,MAAM,EAAE,CAAC,MAAM,EAAE,eAAe,KAAK,cAAc,CAAA;CAC7D;;AAED,qBAAa,UAAW,SAAQ,eAG7B;CAAG;AAMN;;;GAGG;AACH,eAAO,MAAM,aAAa,GACxB,UAAU,cAAc,EACxB,SAAS,CAAC,IAAI,EAAE,MAAM,KAAK,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,KAC7C,MAAM,CAAC,MAAM,CAAC,UAAU,EAAE,eAAe,CAMzC,CAAA;AAEH,+DAA+D;AAC/D,eAAO,MAAM,WAAW,GAAI,UAAU,UAAU,KAAG,aAAa,CAAC,YAAY,CACnD,CAAA"}

package/dist/AIProvider.js

@@ -0,0 +1,27 @@
+/**
+ * gloop-effect/AIProvider — Effect-native provider interface.
+ *
+ * Wraps the callable surface of an LLM provider as an Effect service.
+ * `complete` returns a plain Effect; `stream` returns a Stream of chunks
+ * plus an Effect for the finalized response (including tool calls).
+ *
+ * Concrete providers (OpenRouter, Anthropic, local) are registered by
+ * providing a layer at the application root.
+ */
+import { Context, Effect, Stream } from "effect";
+export class AIProvider extends Context.Tag("gloop/AIProvider")() {
+}
+// ============================================================================
+// Helpers for consumers
+// ============================================================================
+/**
+ * Drain a `StreamResponse`: emit each chunk through `onChunk`, then resolve
+ * with the final `AIResponse`. Interruption cancels the underlying stream.
+ */
+export const consumeStream = (response, onChunk) => Effect.gen(function* () {
+    yield* response.chunks.pipe(Stream.runForEach(onChunk));
+    return yield* response.result;
+}).pipe(Effect.onInterrupt(() => response.cancel));
+/** Extract just the tool calls from a completed AIResponse. */
+export const toolCallsOf = (response) => response.toolCalls ?? [];
+//# sourceMappingURL=AIProvider.js.map

package/dist/AIProvider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"AIProvider.js","sourceRoot":"","sources":["../src/AIProvider.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAA;AAsChD,MAAM,OAAO,UAAW,SAAQ,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,EAG5D;CAAG;AAEN,+EAA+E;AAC/E,wBAAwB;AACxB,+EAA+E;AAE/E;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,QAAwB,EACxB,OAA8C,EACF,EAAE,CAC9C,MAAM,CAAC,GAAG,CAAC,QAAQ,CAAC;IAClB,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC,OAAO,CAAC,CAAC,CAAA;IACvD,OAAO,KAAK,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAA;AAC/B,CAAC,CAAC,CAAC,IAAI,CACL,MAAM,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC,QAAQ,CAAC,MAAM,CAAC,CAC1C,CAAA;AAEH,+DAA+D;AAC/D,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,QAAoB,EAA+B,EAAE,CAC/E,QAAQ,CAAC,SAAS,IAAI,EAAE,CAAA"}

package/dist/Agent.d.ts

@@ -0,0 +1,91 @@
+/**
+ * gloop-effect/Agent — Effect-native replacement for `AgentLoop`.
+ *
+ * Actor model:
+ *   - `Queue<AgentMessage>` is the inbox.
+ *   - `PubSub<AgentEvent>` is the event bus; `events` is a Stream over it.
+ *   - A single loop fiber drains the inbox, one turn at a time.
+ *   - Each turn forks a child fiber so `interrupt` can target just that turn.
+ *
+ * Lifecycle:
+ *   - `Agent.make(opts)` is scoped — call it inside an `Effect.scoped` or
+ *     `Layer.scoped` so the loop fiber is cleaned up when the scope closes.
+ *   - `interrupt` fires the current turn's fiber; the loop keeps running.
+ *   - `stop` interrupts the loop and drains the inbox.
+ */
+import { Effect, Scope, Stream } from "effect";
+import type { Skill, SpawnResult } from "@hypen-space/gloop-loop";
+import { AIProvider } from "./AIProvider.js";
+import { type ConversationHandle } from "./Conversation.js";
+import { type AnyTool, type Tool, type ToolRegistry } from "./Tool.js";
+import { type LoopConfig } from "./Interpreter.js";
+import { type AgentError } from "./Errors.js";
+import type { MessageId, ModelId, RequestId } from "./Schema.js";
+import type { AgentEvent, AgentEventOf, AgentMessage, AgentMessageRole, EnqueuedAgentMessage } from "./Schema.js";
+export type { AgentEvent, AgentEventOf, AgentMessage, AgentMessageRole, EnqueuedAgentMessage, };
+export interface AgentMakeOptions {
+    readonly model: ModelId | string;
+    readonly system?: string;
+    readonly skills?: ReadonlyArray<Skill>;
+    readonly tools?: ReadonlyArray<AnyTool>;
+    readonly maxTokens?: number;
+    readonly contextPruneInterval?: number;
+    readonly classifySpawn?: LoopConfig["classifySpawn"];
+    /** Override the default `confirm_request` + `respondToConfirm` handshake. */
+    readonly confirm?: (command: string) => Effect.Effect<boolean>;
+    /** Override the default `ask_request` + `respondToAsk` handshake. */
+    readonly ask?: (question: string) => Effect.Effect<string>;
+    readonly remember?: (content: string) => Effect.Effect<void>;
+    readonly forget?: (content: string) => Effect.Effect<void>;
+    /**
+     * Rebuild the base system prompt. The returned string is fed back through
+     * `mergeSkillsIntoSystem` before being applied. Return `void` to keep the
+     * existing prompt and just re-emit `system_refreshed`.
+     */
+    readonly refreshSystem?: () => Effect.Effect<string | void>;
+    readonly manageContext?: (instructions: string) => Effect.Effect<string>;
+    readonly installTool?: (source: string) => Effect.Effect<string>;
+    readonly listTools?: () => Effect.Effect<string>;
+    readonly spawn?: (task: string) => Effect.Effect<SpawnResult>;
+    /** Classify an error as fatal. Fatal errors stop the loop. */
+    readonly isFatal?: (error: AgentError) => boolean;
+    readonly log?: (label: string, content: string) => Effect.Effect<void>;
+}
+export interface Agent {
+    /** Enqueue a message. Returns its `MessageId` for correlation. */
+    readonly send: (msg: AgentMessage | string) => Effect.Effect<MessageId>;
+    /**
+     * Enqueue and await the turn's completion. Fails with the turn's
+     * `AgentError`, or `AgentInterruptedError` if the turn was interrupted.
+     */
+    readonly sendSync: (msg: AgentMessage | string) => Effect.Effect<void, AgentError>;
+    /** Full event firehose. Each call creates a fresh subscription. */
+    readonly events: Stream.Stream<AgentEvent>;
+    /** Filtered stream of a single event tag. */
+    readonly eventsOf: <T extends AgentEvent["_tag"]>(tag: T) => Stream.Stream<AgentEventOf<T>>;
+    /** Interrupt the current turn. The loop keeps running. */
+    readonly interrupt: Effect.Effect<void>;
+    /** Stop the loop, drain the inbox. */
+    readonly stop: Effect.Effect<void>;
+    /** Resolves when the inbox is empty *and* no turn is running. */
+    readonly awaitIdle: Effect.Effect<void>;
+    readonly pending: Effect.Effect<number>;
+    /** Register / update a tool; takes effect next turn. */
+    readonly addTool: <E extends import("./Errors.js").AgentError>(tool: Tool<E>) => Effect.Effect<void>;
+    readonly removeTool: (name: string) => Effect.Effect<void>;
+    readonly setTools: (tools: ReadonlyArray<AnyTool>) => Effect.Effect<void>;
+    readonly setSystem: (prompt: string) => Effect.Effect<void>;
+    readonly clear: Effect.Effect<void>;
+    /** Resolve a pending `ConfirmRequest`. */
+    readonly respondToConfirm: (id: RequestId, ok: boolean) => Effect.Effect<void>;
+    /** Resolve a pending `AskRequest`. */
+    readonly respondToAsk: (id: RequestId, answer: string) => Effect.Effect<void>;
+    /** Snapshot access for advanced callers. */
+    readonly registry: ToolRegistry;
+    readonly conversation: ConversationHandle;
+}
+export declare const make: (options: AgentMakeOptions) => Effect.Effect<Agent, never, AIProvider | Scope.Scope>;
+export declare const Agent: {
+    make: (options: AgentMakeOptions) => Effect.Effect<Agent, never, AIProvider | Scope.Scope>;
+};
+//# sourceMappingURL=Agent.d.ts.map

package/dist/Agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Agent.d.ts","sourceRoot":"","sources":["../src/Agent.ts"],"names":[],"mappings":"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"}