operon-agents 0.1.0-alpha.1 → 0.1.0-alpha.10

package/README.md

@@ -16,3 +16,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 `harness` 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({
+  model,
+  harness: () => ({ 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/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

@@ -63,7 +63,7 @@ async function main() {
     const harness = createHarness({
         model: args.model ?? "anthropic/claude-opus-4-8",
         resolveModel,
-        ...(args.home !== undefined ? { repository: new DiskSessionRepository(args.home) } : {}),
+        ...(args.home !== undefined ? { harness: () => ({ sessionRepository: new DiskSessionRepository(args.home) }) } : {}),
         ...(args.workdir !== undefined ? { workDir: args.workdir } : {}),
         permission: { mode: args.permission ?? "yolo" },
     });

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

@@ -0,0 +1,115 @@
+/**
+ * Runtime shape of every host → server request and server → host reverse request in
+ * `protocol.ts`. That module stays pure types so other languages can mirror it; this one is the
+ * TypeScript side's proof that a message read off the wire actually has that shape before a
+ * handler touches it. A miss is an `InvalidParams` error that names the field.
+ */
+import { z } from "zod";
+import type { Message, QuestionItem } from "operon-agents-core";
+import type { ClientCancelRequestParams, ClientRequestApprovalParams, ClientRequestQuestionParams, InitializeParams, SessionFollowUpParams, SessionForkParams, SessionInvokeParams, SessionNewParams, SessionPromptParams, SessionRef, SessionRespondParams, SessionResumeParams, SessionSnapshotParams, SessionSteerParams } from "./protocol.ts";
+export declare const SessionRefSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const InitializeParamsSchema: z.ZodObject<{
+    protocolVersion: z.ZodNumber;
+    clientInfo: z.ZodOptional<z.ZodObject<{
+        name: z.ZodString;
+        version: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    clientCapabilities: z.ZodOptional<z.ZodObject<{
+        approval: z.ZodOptional<z.ZodBoolean>;
+        question: z.ZodOptional<z.ZodBoolean>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const SessionNewParamsSchema: z.ZodObject<{
+    workDir: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+}, z.core.$strip>;
+export declare const SessionResumeParamsSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const SessionForkParamsSchema: z.ZodObject<{
+    title: z.ZodOptional<z.ZodString>;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const SessionCloseParamsSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const SessionCancelParamsSchema: z.ZodObject<{
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const SessionPromptParamsSchema: z.ZodObject<{
+    input: z.ZodUnion<readonly [z.ZodString, z.ZodCustom<Message[], Message[]>]>;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const SessionSnapshotParamsSchema: z.ZodObject<{
+    addresses: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodString>>>;
+    maxMessages: z.ZodOptional<z.ZodNumber>;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const SessionRespondParamsSchema: z.ZodObject<{
+    answers: z.ZodRecord<z.ZodString, z.ZodObject<{
+        decision: z.ZodEnum<{
+            approved: "approved";
+            rejected: "rejected";
+            cancelled: "cancelled";
+        }>;
+        scope: z.ZodOptional<z.ZodLiteral<"session">>;
+        feedback: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const SessionSteerParamsSchema: z.ZodObject<{
+    text: z.ZodString;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const SessionFollowUpParamsSchema: z.ZodObject<{
+    text: z.ZodString;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const SessionInvokeParamsSchema: z.ZodObject<{
+    method: z.ZodString;
+    args: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodUnknown>>>;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const ClientRequestApprovalParamsSchema: z.ZodObject<{
+    request: z.ZodObject<{
+        toolCallId: z.ZodString;
+        toolName: z.ZodString;
+        approvalRule: z.ZodString;
+    }, z.core.$loose>;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const ClientRequestQuestionParamsSchema: z.ZodObject<{
+    request: z.ZodObject<{
+        turnId: z.ZodString;
+        toolCallId: z.ZodString;
+        questions: z.ZodCustom<readonly QuestionItem[], readonly QuestionItem[]>;
+    }, z.core.$loose>;
+    sessionId: z.ZodString;
+}, z.core.$strip>;
+export declare const ClientCancelRequestParamsSchema: z.ZodObject<{
+    id: z.ZodUnion<readonly [z.ZodString, z.ZodNumber]>;
+}, z.core.$strip>;
+/** Parse `params` against a method's schema; a miss is `InvalidParams` naming the field. */
+export declare function parseParams<S extends z.ZodType>(schema: S, params: unknown): z.output<S>;
+export declare const INVOKABLE: Set<string>;
+type Assert<T extends true> = T;
+type Extends<A, B> = A extends B ? true : false;
+export type _Initialize = Assert<Extends<InitializeParams, z.input<typeof InitializeParamsSchema>>>;
+export type _SessionNew = Assert<Extends<SessionNewParams, z.input<typeof SessionNewParamsSchema>>>;
+export type _SessionResume = Assert<Extends<SessionResumeParams, z.input<typeof SessionResumeParamsSchema>>>;
+export type _SessionFork = Assert<Extends<SessionForkParams, z.input<typeof SessionForkParamsSchema>>>;
+export type _SessionRef = Assert<Extends<SessionRef, z.input<typeof SessionRefSchema>>>;
+export type _SessionPrompt = Assert<Extends<SessionPromptParams, z.input<typeof SessionPromptParamsSchema>>>;
+export type _SessionSnapshot = Assert<Extends<SessionSnapshotParams, z.input<typeof SessionSnapshotParamsSchema>>>;
+export type _SessionRespond = Assert<Extends<SessionRespondParams, z.input<typeof SessionRespondParamsSchema>>>;
+export type _SessionSteer = Assert<Extends<SessionSteerParams, z.input<typeof SessionSteerParamsSchema>>>;
+export type _SessionFollowUp = Assert<Extends<SessionFollowUpParams, z.input<typeof SessionFollowUpParamsSchema>>>;
+export type _SessionInvoke = Assert<Extends<SessionInvokeParams, z.input<typeof SessionInvokeParamsSchema>>>;
+export type _ClientRequestApproval = Assert<Extends<z.output<typeof ClientRequestApprovalParamsSchema>, ClientRequestApprovalParams>>;
+export type _ClientRequestQuestion = Assert<Extends<z.output<typeof ClientRequestQuestionParamsSchema>, ClientRequestQuestionParams>>;
+export type _ClientCancelRequest = Assert<Extends<ClientCancelRequestParams, z.input<typeof ClientCancelRequestParamsSchema>>>;
+export {};
+//# sourceMappingURL=params.d.ts.map

package/dist/app-server/params.js

@@ -0,0 +1,81 @@
+/**
+ * Runtime shape of every host → server request and server → host reverse request in
+ * `protocol.ts`. That module stays pure types so other languages can mirror it; this one is the
+ * TypeScript side's proof that a message read off the wire actually has that shape before a
+ * handler touches it. A miss is an `InvalidParams` error that names the field.
+ */
+import { z } from "zod";
+import { ErrorCode, INVOKABLE_METHODS } from "./protocol.js";
+import { RpcError } from "./codec.js";
+const sessionRef = { sessionId: z.string().min(1, "sessionId required") };
+export const SessionRefSchema = z.object(sessionRef);
+export const InitializeParamsSchema = z.object({
+    protocolVersion: z.number({ error: "protocolVersion (number) required" }),
+    clientInfo: z.object({ name: z.string(), version: z.string().optional() }).optional(),
+    clientCapabilities: z.object({ approval: z.boolean().optional(), question: z.boolean().optional() }).optional(),
+});
+export const SessionNewParamsSchema = z.object({
+    workDir: z.string().optional(),
+    title: z.string().optional(),
+    model: z.string().optional(),
+});
+export const SessionResumeParamsSchema = SessionRefSchema;
+export const SessionForkParamsSchema = z.object({ ...sessionRef, title: z.string().optional() });
+export const SessionCloseParamsSchema = SessionRefSchema;
+export const SessionCancelParamsSchema = SessionRefSchema;
+const isMessageLike = (value) => typeof value === "object" && value !== null && typeof value.role === "string";
+/** `AgentInput`: a prompt string, or a message array whose contents the core validates itself. */
+const AgentInputSchema = z.union([z.string(), z.custom((value) => Array.isArray(value) && value.every(isMessageLike))], { error: "input must be a string or an array of messages" });
+export const SessionPromptParamsSchema = z.object({ ...sessionRef, input: AgentInputSchema });
+export const SessionSnapshotParamsSchema = z.object({
+    ...sessionRef,
+    addresses: z.array(z.string()).readonly().optional(),
+    maxMessages: z.number().int().nonnegative().optional(),
+});
+const ApprovalResponseSchema = z.object({
+    decision: z.enum(["approved", "rejected", "cancelled"]),
+    scope: z.literal("session").optional(),
+    feedback: z.string().optional(),
+});
+export const SessionRespondParamsSchema = z.object({
+    ...sessionRef,
+    answers: z.record(z.string(), ApprovalResponseSchema),
+});
+export const SessionSteerParamsSchema = z.object({ ...sessionRef, text: z.string() });
+export const SessionFollowUpParamsSchema = z.object({ ...sessionRef, text: z.string() });
+export const SessionInvokeParamsSchema = z.object({
+    ...sessionRef,
+    method: z.string(),
+    args: z.array(z.unknown()).readonly().optional(),
+});
+// ── Reverse-RPC (server → host), validated by the reference client ───────────
+export const ClientRequestApprovalParamsSchema = z.object({
+    ...sessionRef,
+    request: z.looseObject({ toolCallId: z.string(), toolName: z.string(), approvalRule: z.string() }),
+});
+export const ClientRequestQuestionParamsSchema = z.object({
+    ...sessionRef,
+    request: z.looseObject({
+        turnId: z.string(),
+        toolCallId: z.string(),
+        questions: z.custom((value) => Array.isArray(value), "questions must be an array"),
+    }),
+});
+export const ClientCancelRequestParamsSchema = z.object({ id: z.union([z.string(), z.number()]) });
+/** Parse `params` against a method's schema; a miss is `InvalidParams` naming the field. */
+export function parseParams(schema, params) {
+    const result = schema.safeParse(params ?? {});
+    if (result.success)
+        return result.data;
+    throw new RpcError(ErrorCode.InvalidParams, describeIssues(result.error.issues));
+}
+function describeIssues(issues) {
+    return issues
+        .map((issue) => {
+        const path = issue.path.map(String).join(".");
+        return path.length > 0 ? `${path}: ${issue.message}` : issue.message;
+    })
+        .join("; ");
+}
+export const INVOKABLE = new Set(INVOKABLE_METHODS);
+//# sourceMappingURL=params.js.map

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

@@ -194,11 +194,17 @@ export interface SessionInvokeResult {
     readonly value: unknown;
 }
 /**
- * The whitelist of `HarnessSession` methods reachable through `session/invoke`.
- * Run-driving (prompt/steer/follow_up/cancel), lifecycle (close), and handler registration
- * are deliberately excluded — they are first-class methods or host-side concerns.
+ * The whitelist of operations reachable through `session/invoke`.
+ *
+ * `"<service>.<op>"` names an operation on one of the session's capability services
+ * (`session.goal.create`); a bare name is a method on the session itself. Run-driving
+ * (prompt/steer/follow_up/cancel), lifecycle (close) and handler registration are deliberately
+ * excluded — they are first-class methods or host-side concerns.
+ *
+ * This list stays explicit, one entry per reachable operation: it is a security boundary, so a
+ * new capability operation should have to be named here to become remotely callable.
  */
-export declare const INVOKABLE_METHODS: readonly ["setModel", "setThinking", "setPermissionMode", "createGoal", "getGoal", "pauseGoal", "resumeGoal", "cancelGoal", "setGoalBudget", "setPlanMode", "getPlan", "clearPlan", "compact", "pendingCompaction", "cancelCompaction", "listSkills", "activateSkill", "listPlugins", "getPluginInfo", "installPlugin", "setPluginEnabled", "setPluginMcpServerEnabled", "removePlugin", "reloadPlugins", "listBackgroundTasks", "readBackgroundTaskOutput", "readBackgroundTaskOutputDelta", "stopBackgroundTask", "detachTool", "runCommand", "getRecords", "listSubagents", "reconcileSubagents", "getContextBreakdown", "listMcpServers", "reconnectMcpServer"];
+export declare const INVOKABLE_METHODS: readonly ["setModel", "setThinking", "setPermissionMode", "goal.create", "goal.snapshot", "goal.pause", "goal.resume", "goal.cancel", "goal.changeBudget", "plan.setEnabled", "plan.data", "compaction.request", "compaction.pending", "compaction.cancel", "skills.listSkills", "skills.activateSkill", "plugins.summaries", "plugins.info", "plugins.installSummary", "plugins.setEnabled", "plugins.setMcpServerEnabled", "plugins.remove", "plugins.reload", "background.list", "background.readOutput", "background.readOutputDelta", "background.stop", "background.detach", "background.listSubagents", "background.reconcileSubagents", "background.listWorkflows", "background.getWorkflow", "runCommand", "getRecords", "getContextBreakdown", "mcp.list", "mcp.listTools", "mcp.reconnect"];
 export type InvokableMethod = (typeof INVOKABLE_METHODS)[number];
 /** `session/event` — an AgentEvent verbatim (already carries `sessionId` + `address`). */
 export type SessionEventParams = AgentEvent;

package/dist/app-server/protocol.js

@@ -42,59 +42,66 @@ export const ErrorCode = {
     RequestCancelled: -32011,
 };
 /**
- * The whitelist of `HarnessSession` methods reachable through `session/invoke`.
- * Run-driving (prompt/steer/follow_up/cancel), lifecycle (close), and handler registration
- * are deliberately excluded — they are first-class methods or host-side concerns.
+ * The whitelist of operations reachable through `session/invoke`.
+ *
+ * `"<service>.<op>"` names an operation on one of the session's capability services
+ * (`session.goal.create`); a bare name is a method on the session itself. Run-driving
+ * (prompt/steer/follow_up/cancel), lifecycle (close) and handler registration are deliberately
+ * excluded — they are first-class methods or host-side concerns.
+ *
+ * This list stays explicit, one entry per reachable operation: it is a security boundary, so a
+ * new capability operation should have to be named here to become remotely callable.
  */
 export const INVOKABLE_METHODS = [
-    // runtime settings
+    // runtime settings — on the session itself
     "setModel",
     "setThinking",
     "setPermissionMode",
     // goal
-    "createGoal",
-    "getGoal",
-    "pauseGoal",
-    "resumeGoal",
-    "cancelGoal",
-    "setGoalBudget",
+    "goal.create",
+    "goal.snapshot",
+    "goal.pause",
+    "goal.resume",
+    "goal.cancel",
+    "goal.changeBudget",
     // plan
-    "setPlanMode",
-    "getPlan",
-    "clearPlan",
+    "plan.setEnabled",
+    "plan.data",
     // compaction
-    "compact",
-    "pendingCompaction",
-    "cancelCompaction",
+    "compaction.request",
+    "compaction.pending",
+    "compaction.cancel",
     // skills
-    "listSkills",
-    "activateSkill",
+    "skills.listSkills",
+    "skills.activateSkill",
     // plugins
-    "listPlugins",
-    "getPluginInfo",
-    "installPlugin",
-    "setPluginEnabled",
-    "setPluginMcpServerEnabled",
-    "removePlugin",
-    "reloadPlugins",
-    // background tasks
-    "listBackgroundTasks",
-    "readBackgroundTaskOutput",
-    "readBackgroundTaskOutputDelta",
-    "stopBackgroundTask",
-    "detachTool",
+    "plugins.summaries",
+    "plugins.info",
+    "plugins.installSummary",
+    "plugins.setEnabled",
+    "plugins.setMcpServerEnabled",
+    "plugins.remove",
+    "plugins.reload",
+    // background tasks, subagents and workflow runs — one ledger, three views
+    "background.list",
+    "background.readOutput",
+    "background.readOutputDelta",
+    "background.stop",
+    "background.detach",
+    "background.listSubagents",
+    "background.reconcileSubagents",
+    "background.listWorkflows",
+    "background.getWorkflow",
     // slash commands — the serializable control surface for extensions (cron et al.):
     // per-feature cron RPCs are gone with the capability, /cron rides this instead.
     "runCommand",
     // conversation log
     "getRecords",
-    // subagents
-    "listSubagents",
-    "reconcileSubagents",
     // context introspection
     "getContextBreakdown",
     // mcp
-    "listMcpServers",
-    "reconnectMcpServer",
+    "mcp.list",
+    "mcp.listTools",
+    "mcp.reconnect",
 ];
 //# sourceMappingURL=protocol.js.map

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

@@ -45,7 +45,6 @@ export declare class AppServer {
     private callClient;
     private resolveReverse;
     private rejectReverseForSession;
-    private requireId;
     private requireSession;
 }
 //# sourceMappingURL=server.d.ts.map

package/dist/app-server/server.js

@@ -1,6 +1,6 @@
 import { errorToBody, failure, notification, request as makeRequest, RpcError, success, toWireSafe, } from "./codec.js";
 import { ErrorCode, INVOKABLE_METHODS, Method, PROTOCOL_VERSION, } from "./protocol.js";
-const INVOKABLE = new Set(INVOKABLE_METHODS);
+import { INVOKABLE, InitializeParamsSchema, parseParams, SessionCancelParamsSchema, SessionCloseParamsSchema, SessionFollowUpParamsSchema, SessionForkParamsSchema, SessionInvokeParamsSchema, SessionNewParamsSchema, SessionPromptParamsSchema, SessionRespondParamsSchema, SessionResumeParamsSchema, SessionSnapshotParamsSchema, SessionSteerParamsSchema, } from "./params.js";
 export class AppServer {
     harness;
     transport;
@@ -73,43 +73,41 @@ export class AppServer {
     }
     async route(method, params) {
         if (method === Method.Initialize)
-            return this.onInitialize(params);
+            return this.onInitialize(parseParams(InitializeParamsSchema, params));
         if (!this.initialized)
             throw new RpcError(ErrorCode.NotInitialized, "call initialize first");
+        // Method lookup before params: an unknown method is `MethodNotFound` whatever it carries.
         switch (method) {
             case Method.SessionNew:
-                return this.onSessionNew((params ?? {}));
+                return this.onSessionNew(parseParams(SessionNewParamsSchema, params));
             case Method.SessionResume:
-                return this.onSessionResume(params);
+                return this.onSessionResume(parseParams(SessionResumeParamsSchema, params));
             case Method.SessionFork:
-                return this.onSessionFork(params);
+                return this.onSessionFork(parseParams(SessionForkParamsSchema, params));
             case Method.SessionList:
                 return this.harness.listSessions();
             case Method.SessionClose:
-                return this.onSessionClose(params);
+                return this.onSessionClose(parseParams(SessionCloseParamsSchema, params));
             case Method.SessionPrompt:
-                return this.onSessionPrompt(params);
+                return this.onSessionPrompt(parseParams(SessionPromptParamsSchema, params));
             case Method.SessionSnapshot:
-                return this.onSessionSnapshot(params);
+                return this.onSessionSnapshot(parseParams(SessionSnapshotParamsSchema, params));
             case Method.SessionRespond:
-                return this.onSessionRespond(params);
+                return this.onSessionRespond(parseParams(SessionRespondParamsSchema, params));
             case Method.SessionSteer:
-                return this.onSessionSteer(params);
+                return this.onSessionSteer(parseParams(SessionSteerParamsSchema, params));
             case Method.SessionFollowUp:
-                return this.onSessionFollowUp(params);
+                return this.onSessionFollowUp(parseParams(SessionFollowUpParamsSchema, params));
             case Method.SessionCancel:
-                return this.onSessionCancel(params);
+                return this.onSessionCancel(parseParams(SessionCancelParamsSchema, params));
             case Method.SessionInvoke:
-                return this.onSessionInvoke(params);
+                return this.onSessionInvoke(parseParams(SessionInvokeParamsSchema, params));
             default:
                 throw new RpcError(ErrorCode.MethodNotFound, `unknown method: ${method}`);
         }
     }
     // ── Handshake ─────────────────────────────────────────────────────────────
     onInitialize(params) {
-        if (typeof params?.protocolVersion !== "number") {
-            throw new RpcError(ErrorCode.InvalidParams, "protocolVersion (number) required");
-        }
         this.clientApproval = params.clientCapabilities?.approval ?? false;
         this.clientQuestion = params.clientCapabilities?.question ?? false;
         this.initialized = true;
@@ -132,19 +130,19 @@ export class AppServer {
         return { sessionId: session.id, workDir: session.workDir };
     }
     async onSessionResume(params) {
-        const session = await this.harness.resumeSession(this.requireId(params));
+        const session = await this.harness.resumeSession(params.sessionId);
         this.wireSession(session);
         return { sessionId: session.id, workDir: session.workDir };
     }
     async onSessionFork(params) {
-        const session = await this.harness.forkSession(this.requireId(params), {
+        const session = await this.harness.forkSession(params.sessionId, {
             ...(params.title !== undefined ? { title: params.title } : {}),
         });
         this.wireSession(session);
         return { sessionId: session.id, workDir: session.workDir };
     }
     async onSessionClose(params) {
-        const id = this.requireId(params);
+        const id = params.sessionId;
         this.wired.get(id)?.unsubscribe();
         this.wired.delete(id);
         this.rejectReverseForSession(id, "session closed");
@@ -176,12 +174,12 @@ export class AppServer {
     }
     onSessionSteer(params) {
         const session = this.requireSession(params);
-        return { accepted: true, steerId: session.steer(params.text) };
+        return { accepted: true, steerId: session.steer(params.text).steerId };
     }
     onSessionFollowUp(params) {
         const session = this.requireSession(params);
-        const steerId = session.followUp(params.text);
-        return steerId === null ? { accepted: false } : { accepted: true, steerId };
+        const receipt = session.followUp(params.text);
+        return receipt === null ? { accepted: false } : { accepted: true, steerId: receipt.steerId };
     }
     onSessionCancel(params) {
         const session = this.requireSession(params);
@@ -192,15 +190,34 @@ export class AppServer {
     }
     async onSessionInvoke(params) {
         const session = this.requireSession(params);
-        if (typeof params.method !== "string" || !INVOKABLE.has(params.method)) {
-            throw new RpcError(ErrorCode.MethodNotFound, `not invokable: ${String(params.method)}`);
+        if (!INVOKABLE.has(params.method)) {
+            throw new RpcError(ErrorCode.MethodNotFound, `not invokable: ${params.method}`);
+        }
+        // `"<service>.<op>"` resolves through the session's capability accessor; a bare name is a
+        // method on the session. Reading a REQUIRE accessor throws when that capability is not open,
+        // which is a legitimate answer for a remote caller — reported as "unavailable", not a crash.
+        const dot = params.method.indexOf(".");
+        let target = session;
+        let name = params.method;
+        if (dot > 0) {
+            const service = params.method.slice(0, dot);
+            name = params.method.slice(dot + 1);
+            try {
+                target = session[service];
+            }
+            catch (error) {
+                throw new RpcError(ErrorCode.MethodNotFound, `capability unavailable: ${service} (${error instanceof Error ? error.message : String(error)})`);
+            }
+            if (target === undefined || target === null) {
+                throw new RpcError(ErrorCode.MethodNotFound, `capability unavailable: ${service}`);
+            }
         }
-        const fn = session[params.method];
+        const fn = target[name];
         if (typeof fn !== "function") {
             throw new RpcError(ErrorCode.MethodNotFound, `not a method: ${params.method}`);
         }
-        const args = Array.isArray(params.args) ? params.args : [];
-        const value = await fn.apply(session, args);
+        const args = [...(params.args ?? [])];
+        const value = await fn.apply(target, args);
         return { value: toWireSafe(value) };
     }
     // ── Per-session wiring: events out, reverse-RPC for approvals/questions ──────
@@ -258,16 +275,10 @@ export class AppServer {
         }
     }
     // ── Helpers ──────────────────────────────────────────────────────────────────
-    requireId(ref) {
-        if (!ref || typeof ref.sessionId !== "string")
-            throw new RpcError(ErrorCode.InvalidParams, "sessionId required");
-        return ref.sessionId;
-    }
     requireSession(ref) {
-        const id = this.requireId(ref);
-        const session = this.harness.getSession(id);
+        const session = this.harness.getSession(ref.sessionId);
         if (!session)
-            throw new RpcError(ErrorCode.SessionNotFound, `session not found: ${id}`);
+            throw new RpcError(ErrorCode.SessionNotFound, `session not found: ${ref.sessionId}`);
         return session;
     }
 }

package/dist/core.d.ts

@@ -4,8 +4,8 @@
  * `import { Runner, defineAgent, defineModel } from 'operon-agents/core'`
  *
  * Everything the core engine exposes: Runner / Session / Agent / capabilities /
- * machines / tools. Pass no machine and omit file tools to run a stateless,
- * no-filesystem agent (a `NullMachine` refuses any stray I/O). For the
+ * environments / tools. Pass no environment and omit file tools to run a stateless,
+ * no-filesystem agent (a `NullEnvironment` refuses any stray I/O). For the
  * batteries-included facade, import from `operon-agents` instead.
  */
 export * from "operon-agents-core";

package/dist/core.js

@@ -4,8 +4,8 @@
  * `import { Runner, defineAgent, defineModel } from 'operon-agents/core'`
  *
  * Everything the core engine exposes: Runner / Session / Agent / capabilities /
- * machines / tools. Pass no machine and omit file tools to run a stateless,
- * no-filesystem agent (a `NullMachine` refuses any stray I/O). For the
+ * environments / tools. Pass no environment and omit file tools to run a stateless,
+ * no-filesystem agent (a `NullEnvironment` refuses any stray I/O). For the
  * batteries-included facade, import from `operon-agents` instead.
  */
 export * from "operon-agents-core";

package/dist/cron/cron-expr.js

@@ -52,7 +52,7 @@ function parseField(field, min, max, name) {
     return out;
 }
 // Cron numeric fields are digit-only; `Number(...)` would otherwise accept '', '1e1',
-// '0x10', '+5', '  3  ' — none valid cron. Gate before conversion to machine typos.
+// '0x10', '+5', '  3  ' — none valid cron. Gate before conversion to surface typos.
 const DIGIT_ONLY = /^\d+$/;
 function parseCronInt(raw, name, role) {
     if (!DIGIT_ONLY.test(raw)) {

package/dist/cron/extension.js

@@ -29,8 +29,8 @@ export function normalizeCronTaskInput(manager, input) {
 export function cronExtension(options = {}) {
     return {
         id: "cron",
-        async setup(api) {
-            // One manager per session: setup runs per session open, so scheduling state is
+        async session(api) {
+            // One manager per session: session() runs per session open, so scheduling state is
             // session-scoped exactly as the capability's openSession was.
             const manager = new CronManager(options);
             manager.attach({