operon-agents 0.1.0-alpha.3 → 0.1.0-alpha.31

package/README.md

@@ -3,7 +3,8 @@
 Public SDK entrypoint for building agents.
 
 ```ts
-import { Agent, Runner, Session, ChatModel, tool } from "operon-agents";
+import { Agent, ChatModel, defineTool } from "operon-agents";
+import { Runner, Session } from "operon-agents/advanced";
 ```
 
 Use `operon-agents` from applications. `operon-agents-core` is the lower-level
@@ -16,3 +17,45 @@ import { TransportMCPServer } from "operon-agents/mcp";
 import { bashTool, readTool } from "operon-agents/tools";
 import { OTelTracingProcessor } from "operon-agents/tracing";
 ```
+
+## Tracing
+
+Every session drives the `TracingProcessor` the `infrastructure` hook returns as `tracing`: one
+trace per run (a prompt and everything it triggers), spans for agents, turns, model generations,
+tool calls and sub-agents, the session id on every span as `gen_ai.conversation.id`. By default
+spans are metadata only. Pass `content: "delta"` to also record the system prompt, the messages
+the model was asked to answer, its output, tool arguments and results — enough to replay a
+conversation in a trace viewer. Local Jaeger:
+
+```sh
+docker run --rm -p 16686:16686 -p 4318:4318 jaegertracing/jaeger:2.9.0
+```
+
+```ts
+import { NodeTracerProvider, BatchSpanProcessor } from "@opentelemetry/sdk-trace-node";
+import { OTLPTraceExporter } from "@opentelemetry/exporter-trace-otlp-http";
+import { resourceFromAttributes } from "@opentelemetry/resources";
+import { OTelTracingProcessor } from "operon-agents/tracing";
+
+const provider = new NodeTracerProvider({
+  resource: resourceFromAttributes({ "service.name": "my-agent" }),
+  spanProcessors: [new BatchSpanProcessor(new OTLPTraceExporter({ url: "http://localhost:4318/v1/traces" }))],
+});
+const tracing = new OTelTracingProcessor({ tracer: provider.getTracer("my-agent"), tracerProvider: provider, content: "delta", shutdownProvider: true });
+
+const harness = await createLocalHarness({
+  config: { defaults: { model } },
+  infrastructure: () => ({ tracing }),
+});
+```
+
+`content: "full"` repeats the entire context on every generation (trace size grows with steps ×
+context); `contentMaxChars` caps each attribute; `redact: true` masks tokens, emails and keys
+before export when the collector is not on the same machine.
+
+A run that pauses for an answer (`turn.paused`) ends its trace at the pause — the turn with
+reason `paused`, the suspended tool calls marked, not failed — and the run that continues it is
+the next trace of the same session. Spans are exported when they end, so a wait that may last
+days is never an open span. `examples/linear-github/server/langfuse.ts` shows the same
+processor exporting to Langfuse.
+

package/dist/advanced.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `operon-agents/advanced` — everything beyond the main entry point: extension and cron plumbing,
+ * custom capabilities, stores, providers, MCP wiring and the event and store contracts.
+ *
+ * Supported, but for hosts composing their own deployment. Most applications only need
+ * `operon-agents`. Engine internals with no stability guarantee live on `operon-agents/internal`.
+ */
+export * from "./harness.ts";
+export * from "./extensions/index.ts";
+export * from "./cron/index.ts";
+export * from "./providers.ts";
+export * from "./local.ts";
+export * from "./workspace-mcp.ts";
+export * from "operon-agents-core";
+//# sourceMappingURL=advanced.d.ts.map

package/dist/advanced.js

@@ -0,0 +1,15 @@
+/**
+ * `operon-agents/advanced` — everything beyond the main entry point: extension and cron plumbing,
+ * custom capabilities, stores, providers, MCP wiring and the event and store contracts.
+ *
+ * Supported, but for hosts composing their own deployment. Most applications only need
+ * `operon-agents`. Engine internals with no stability guarantee live on `operon-agents/internal`.
+ */
+export * from "./harness.js";
+export * from "./extensions/index.js";
+export * from "./cron/index.js";
+export * from "./providers.js";
+export * from "./local.js";
+export * from "./workspace-mcp.js";
+export * from "operon-agents-core";
+//# sourceMappingURL=advanced.js.map

package/dist/app-server/client.d.ts

@@ -7,7 +7,7 @@
  * in-process for tests.
  */
 import { type ChildProcess } from "node:child_process";
-import type { AgentEvent, ApprovalRequest, ApprovalResponse, QuestionRequest, QuestionResult, RunResult, SessionSummary } from "operon-agents-core";
+import type { AgentEvent, ApprovalRequest, ApprovalResponse, QuestionRequest, QuestionResult, RunResult, SessionConfig, SessionSummary } from "operon-agents-core";
 import { type JsonRpcTransport } from "./codec.ts";
 import { type ClientCapabilities, type InitializeResult, type SessionFollowUpResult, type SessionInfo, type SessionSnapshotResult, type SessionSteerResult } from "./protocol.ts";
 export type ApprovalHandler = (request: ApprovalRequest, sessionId: string) => Promise<ApprovalResponse> | ApprovalResponse;
@@ -49,10 +49,12 @@ export declare class AppServerClient {
         workDir?: string;
         title?: string;
         model?: string;
+        config?: SessionConfig;
     }): Promise<SessionInfo>;
     resumeSession(sessionId: string): Promise<SessionInfo>;
     forkSession(sessionId: string, opts?: {
         title?: string;
+        config?: SessionConfig;
     }): Promise<SessionInfo>;
     listSessions(): Promise<readonly SessionSummary[]>;
     closeSession(sessionId: string): Promise<unknown>;

package/dist/app-server/client.js

@@ -9,6 +9,7 @@
 import { spawn } from "node:child_process";
 import { classify, isFailure, nodeStreamTransport, request as makeRequest, RpcError, success, } from "./codec.js";
 import { Method, PROTOCOL_VERSION, } from "./protocol.js";
+import { ClientCancelRequestParamsSchema, ClientRequestApprovalParamsSchema, ClientRequestQuestionParamsSchema, parseParams, } from "./params.js";
 export class AppServerClient {
     transport;
     child;
@@ -66,9 +67,11 @@ export class AppServerClient {
             return;
         }
         if (method === Method.ClientCancelRequest) {
-            const { id } = (params ?? {});
-            this.inboundAbort.get(id)?.abort();
-            this.inboundAbort.delete(id);
+            const parsed = ClientCancelRequestParamsSchema.safeParse(params);
+            if (!parsed.success)
+                return;
+            this.inboundAbort.get(parsed.data.id)?.abort();
+            this.inboundAbort.delete(parsed.data.id);
         }
     }
     async onReverseRequest(id, method, params) {
@@ -88,13 +91,13 @@ export class AppServerClient {
     }
     async dispatchReverse(method, params, signal) {
         if (method === Method.ClientRequestApproval) {
-            const p = params;
+            const p = parseParams(ClientRequestApprovalParamsSchema, params);
             if (!this.approvalHandler)
                 return { decision: "rejected", feedback: "no approval handler" };
             return this.approvalHandler(p.request, p.sessionId);
         }
         if (method === Method.ClientRequestQuestion) {
-            const p = params;
+            const p = parseParams(ClientRequestQuestionParamsSchema, params);
             if (!this.questionHandler)
                 return null;
             return this.questionHandler(p.request, p.sessionId, { signal });

package/dist/app-server/main.js

@@ -5,14 +5,22 @@
  *
  *   operon-app-server --home ~/.agent --workdir /repo --model anthropic/claude-opus-4-...
  *
+ * Configuration comes from the same `config.toml` files any other host reads (`loadHarnessConfig`:
+ * `<home>/config.toml`, then the working directory's `.agents/config.toml` and
+ * `.agents/config.local.toml`), with the command-line flags laid over it. `--no-config` skips the
+ * files.
+ *
  * stdout carries the protocol (NDJSON JSON-RPC). stderr is logs. We defensively
  * redirect console.log/info/debug to stderr so a stray log can never corrupt the
  * protocol stream.
  */
-import { defineModel, DiskSessionRepository } from "operon-agents-core";
+import { DiskSessionRepository, loadHarnessConfig } from "operon-agents-core";
 import { createHarness } from "../harness.js";
 import { nodeStreamTransport } from "./codec.js";
 import { AppServer } from "./server.js";
+const PERMISSION_MODES = ["manual", "workspace", "yolo", "auto"];
+/** What this binary has always run on when nothing names a model. */
+const FALLBACK_MODEL = "anthropic/claude-opus-4-8";
 function parseArgs(argv) {
     const out = {};
     for (let i = 0; i < argv.length; i++) {
@@ -31,24 +39,19 @@ function parseArgs(argv) {
                 break;
             case "--permission": {
                 const mode = take();
-                if (mode === "manual" || mode === "workspace" || mode === "yolo")
+                if (PERMISSION_MODES.includes(mode))
                     out.permission = mode;
                 break;
             }
+            case "--no-config":
+                out.noConfig = true;
+                break;
             default:
                 break;
         }
     }
     return out;
 }
-/** Resolve a `provider/model` id into a ChatModel (API keys come from the env). */
-function resolveModel(id) {
-    const slash = id.indexOf("/");
-    if (slash <= 0 || slash === id.length - 1) {
-        throw new Error(`invalid --model "${id}": expected "provider/model" (e.g. anthropic/claude-opus-4-...)`);
-    }
-    return defineModel({ provider: id.slice(0, slash), model: id.slice(slash + 1) });
-}
 function redirectStdoutLogsToStderr() {
     const toStderr = (...parts) => {
         process.stderr.write(`${parts.map((p) => (typeof p === "string" ? p : JSON.stringify(p))).join(" ")}\n`);
@@ -60,12 +63,25 @@ function redirectStdoutLogsToStderr() {
 async function main() {
     redirectStdoutLogsToStderr();
     const args = parseArgs(process.argv.slice(2));
-    const harness = createHarness({
-        model: args.model ?? "anthropic/claude-opus-4-8",
-        resolveModel,
-        ...(args.home !== undefined ? { repository: new DiskSessionRepository(args.home) } : {}),
+    // The files first, the flags over them: one configuration, whichever way it was written.
+    const file = args.noConfig === true
+        ? { defaults: {} }
+        : await loadHarnessConfig({
+            ...(args.home !== undefined ? { homeDir: args.home } : {}),
+            ...(args.workdir !== undefined ? { cwd: args.workdir } : {}),
+        });
+    const config = {
+        ...file,
+        defaults: {
+            ...file.defaults,
+            model: args.model ?? file.defaults.model ?? FALLBACK_MODEL,
+            ...(args.permission !== undefined ? { permission: { ...file.defaults.permission, mode: args.permission } } : {}),
+        },
         ...(args.workdir !== undefined ? { workDir: args.workdir } : {}),
-        permission: { mode: args.permission ?? "yolo" },
+    };
+    const harness = createHarness({
+        config,
+        ...(args.home !== undefined ? { infrastructure: () => ({ sessionRepository: new DiskSessionRepository(args.home) }) } : {}),
     });
     const transport = nodeStreamTransport(process.stdin, process.stdout, {
         onParseError: (line, error) => process.stderr.write(`parse error: ${String(error)} on: ${line.slice(0, 200)}\n`),