@nylorun/harness 0.7.0-beta.1 → 0.8.0-beta.1

package/CHANGELOG.md

@@ -4,6 +4,23 @@ All notable changes to `@nylorun/harness` are documented in this file.
 
 The project follows [Semantic Versioning](https://semver.org/). Before 1.0, the public API is experimental: breaking changes may occur in minor releases, while patch releases are reserved for compatible fixes.
 
+## [0.8.0-beta.1] - 2026-08-31
+
+### Breaking changes
+
+- `Agent()` now takes identity options instead of a model adapter. Migrate
+  `Agent(adapter).use(...).build()` to
+  `Agent({ id, name, instructions }).use(...).with(adapter).build()`.
+- `.build()` exists only on `BoundAgentBuilder`, the type returned by a single `.with(onModelCall)`.
+  `AgentBuilder` has `.use()` and `.with()` only.
+- `AgentManifest` now includes `id` and `name`. Built agents expose the same fields as `agent.id`
+  and `agent.name`.
+
+### Added
+
+- Optional constructor `instructions` compile as reserved `agent` middleware. A string is
+  normalized to one instruction. Capability-specific instructions still go through `.use()`.
+
 ## [0.7.0-beta.1] - 2026-08-30
 
 ### Breaking changes
@@ -75,3 +92,4 @@ The project follows [Semantic Versioning](https://semver.org/). Before 1.0, the
 [0.5.0-beta.1]: https://github.com/nylorun/harness/tree/main/harness
 [0.6.0-beta.1]: https://github.com/nylorun/harness/tree/main/harness
 [0.7.0-beta.1]: https://github.com/nylorun/harness/tree/main/harness
+[0.8.0-beta.1]: https://github.com/nylorun/harness/tree/main/harness

package/README.md

@@ -18,8 +18,13 @@ const echo = tool({
   execute: async ({ text }) => ({ kind: "completed", output: text }),
 });
 
-const agent = Agent(adapter)
-  .use({ id: "echo", instructions: ["Use echo when asked."], tools: [echo] })
+const agent = Agent({
+  id: "echo",
+  name: "Echo",
+  instructions: "Use echo when asked.",
+})
+  .use({ id: "echo", tools: [echo] })
+  .with(adapter)
   .build();
 
 const result = await agent.run().input("Echo hello").completed;

package/dist/build/agent.d.ts

@@ -10,6 +10,8 @@ export declare class BuiltAgent {
     #private;
     readonly middleware: readonly BoundMiddleware[];
     readonly manifest: AgentManifest;
+    readonly id: string;
+    readonly name: string;
     private constructor();
     run(options?: SessionRunOptions): Session;
 }

package/dist/build/agent.js

@@ -5,10 +5,14 @@ let createBoundAgent;
 export class BuiltAgent {
     middleware;
     manifest;
+    id;
+    name;
     #loopAgent;
     constructor(middleware, invoke, manifest) {
         this.middleware = middleware;
         this.manifest = manifest;
+        this.id = manifest.id;
+        this.name = manifest.name;
         this.#loopAgent = Object.freeze({
             middleware,
             invoke,

package/dist/build/assemble.d.ts

@@ -2,4 +2,7 @@ import type { BuildResult } from "../types/manifest.js";
 import type { BoundMiddleware } from "../types/middleware.js";
 import type { ModelAdapter } from "../types/model.js";
 import { type BuiltAgent } from "./agent.js";
-export declare function assembleAgent(middleware: readonly BoundMiddleware[], invoke: ModelAdapter): BuildResult<BuiltAgent>;
+export declare function assembleAgent(middleware: readonly BoundMiddleware[], invoke: ModelAdapter, identity: Readonly<{
+    id: string;
+    name: string;
+}>): BuildResult<BuiltAgent>;

package/dist/build/assemble.js

@@ -1,8 +1,14 @@
 import { bindAgent } from "./agent.js";
 import { createManifest } from "./manifest.js";
 const diagnostic = (code, message, extra = {}) => Object.freeze({ code, message, ...extra });
-export function assembleAgent(middleware, invoke) {
+export function assembleAgent(middleware, invoke, identity) {
     const diagnostics = [];
+    if (typeof identity.id !== "string" || identity.id.length === 0) {
+        diagnostics.push(diagnostic("agent.invalid-id", "Agent id must be a non-empty string"));
+    }
+    if (typeof identity.name !== "string" || identity.name.length === 0) {
+        diagnostics.push(diagnostic("agent.invalid-name", "Agent name must be a non-empty string"));
+    }
     if (typeof invoke !== "function") {
         diagnostics.push(diagnostic("harness.invalid-model", "A model invoke function is required"));
     }
@@ -27,7 +33,11 @@ export function assembleAgent(middleware, invoke) {
     if (diagnostics.length)
         return Object.freeze({ ok: false, diagnostics: Object.freeze(diagnostics) });
     const frozenMiddleware = Object.freeze(frozen);
-    const manifest = createManifest({ middleware: frozenMiddleware });
+    const manifest = createManifest({
+        id: identity.id,
+        name: identity.name,
+        middleware: frozenMiddleware,
+    });
     const agent = bindAgent(frozenMiddleware, invoke, manifest);
     return Object.freeze({ ok: true, agent, manifest });
 }

package/dist/build/builder.d.ts

@@ -1,8 +1,24 @@
-import type { CapabilityDeclaration, StepMiddleware } from "../types/middleware.js";
+import type { BoundMiddleware, CapabilityDeclaration, StepMiddleware } from "../types/middleware.js";
 import type { ModelAdapter } from "../types/model.js";
 import type { BuildDiagnostic } from "../types/shared.js";
 import { HarnessError } from "../errors.js";
 import type { BuiltAgent } from "./agent.js";
+export interface AgentOptions {
+    readonly id: string;
+    readonly name: string;
+    readonly instructions?: string | readonly string[];
+}
+interface BuilderState {
+    readonly id: string;
+    readonly name: string;
+    readonly middleware: BoundMiddleware[];
+    invoke?: ModelAdapter;
+    bound: boolean;
+    sealed: boolean;
+    agent?: BuiltAgent;
+    error?: AgentBuildError;
+    middlewareSeq: number;
+}
 export declare class AgentBuildError extends HarnessError {
     readonly diagnostics: readonly BuildDiagnostic[];
     constructor(diagnostics: readonly BuildDiagnostic[]);
@@ -10,19 +26,21 @@ export declare class AgentBuildError extends HarnessError {
 export declare class AgentLifecycleError extends HarnessError {
     constructor(message: string);
 }
-export declare function Agent(model: ModelAdapter): AgentBuilder;
+export declare function Agent(options: AgentOptions): AgentBuilder;
 export declare class AgentBuilder {
-    private readonly invoke;
-    private readonly middleware;
-    private sealed;
-    private agent?;
-    private error?;
-    private middlewareSeq;
-    constructor(invoke: ModelAdapter);
+    private readonly state;
+    constructor(state: BuilderState);
     use(middleware: StepMiddleware): this;
     use(id: string, middleware: StepMiddleware): this;
     use<State>(declaration: CapabilityDeclaration<State>): this;
-    build(): BuiltAgent;
+    with(onModelCall: ModelAdapter): BoundAgentBuilder;
     private nextMiddlewareId;
     private push;
+    private assertOpen;
+}
+export declare class BoundAgentBuilder {
+    private readonly state;
+    constructor(state: BuilderState);
+    build(): BuiltAgent;
 }
+export {};

package/dist/build/builder.js

@@ -14,18 +14,13 @@ export class AgentLifecycleError extends HarnessError {
         this.name = "AgentLifecycleError";
     }
 }
-export function Agent(model) {
-    return new AgentBuilder(model);
+export function Agent(options) {
+    return new AgentBuilder(createState(options));
 }
 export class AgentBuilder {
-    invoke;
-    middleware = [];
-    sealed = false;
-    agent;
-    error;
-    middlewareSeq = 0;
-    constructor(invoke) {
-        this.invoke = invoke;
+    state;
+    constructor(state) {
+        this.state = state;
     }
     use(idOrMiddleware, middleware) {
         if (typeof idOrMiddleware === "function") {
@@ -35,35 +30,70 @@ export class AgentBuilder {
             return this.push(compileDeclaration(idOrMiddleware));
         return this.push({ id: idOrMiddleware, handle: middleware });
     }
-    build() {
-        if (this.agent)
-            return this.agent;
-        if (this.error)
-            throw this.error;
-        this.sealed = true;
-        const result = assembleAgent(this.middleware, this.invoke);
-        if (!result.ok) {
-            this.error = new AgentBuildError(result.diagnostics);
-            throw this.error;
-        }
-        this.agent = result.agent;
-        return this.agent;
+    with(onModelCall) {
+        this.assertOpen("with()");
+        this.state.bound = true;
+        this.state.invoke = onModelCall;
+        return new BoundAgentBuilder(this.state);
     }
     nextMiddlewareId() {
-        const taken = new Set(this.middleware.map((item) => item.id));
+        const taken = new Set(this.state.middleware.map((item) => item.id));
         let id;
         do {
-            this.middlewareSeq += 1;
-            id = `middleware-${this.middlewareSeq}`;
+            this.state.middlewareSeq += 1;
+            id = `middleware-${this.state.middlewareSeq}`;
         } while (taken.has(id));
         return id;
     }
     push(entry) {
-        if (this.sealed)
-            throw new AgentLifecycleError("AgentBuilder cannot be changed after build()");
-        this.middleware.push(entry);
+        this.assertOpen("build()");
+        this.state.middleware.push(entry);
         return this;
     }
+    assertOpen(after) {
+        if (this.state.bound)
+            throw new AgentLifecycleError("AgentBuilder cannot be changed after with()");
+        if (this.state.sealed)
+            throw new AgentLifecycleError(`AgentBuilder cannot be changed after ${after}`);
+    }
+}
+export class BoundAgentBuilder {
+    state;
+    constructor(state) {
+        this.state = state;
+    }
+    build() {
+        if (this.state.agent)
+            return this.state.agent;
+        if (this.state.error)
+            throw this.state.error;
+        this.state.sealed = true;
+        const result = assembleAgent(this.state.middleware, this.state.invoke, {
+            id: this.state.id,
+            name: this.state.name,
+        });
+        if (!result.ok) {
+            this.state.error = new AgentBuildError(result.diagnostics);
+            throw this.state.error;
+        }
+        this.state.agent = result.agent;
+        return this.state.agent;
+    }
+}
+function createState(options) {
+    const middleware = [];
+    if (options.instructions !== undefined) {
+        const instructions = typeof options.instructions === "string" ? [options.instructions] : options.instructions;
+        middleware.push(compileDeclaration({ id: "agent", instructions }));
+    }
+    return {
+        id: options.id,
+        name: options.name,
+        middleware,
+        bound: false,
+        sealed: false,
+        middlewareSeq: 0,
+    };
 }
 function compileDeclaration(declaration) {
     const tools = copyItems(declaration.tools, declaration.id);

package/dist/build/manifest.d.ts

@@ -1,5 +1,7 @@
 import type { AgentManifest } from "../types/manifest.js";
 import type { BoundMiddleware } from "../types/middleware.js";
 export declare function createManifest(input: {
+    id: string;
+    name: string;
     middleware: readonly BoundMiddleware[];
 }): AgentManifest;

package/dist/build/manifest.js

@@ -2,6 +2,8 @@ import { deepFreeze } from "../utils/immutable.js";
 export function createManifest(input) {
     const middleware = input.middleware.map(({ id }) => ({ id }));
     return deepFreeze({
+        id: input.id,
+        name: input.name,
         middleware,
     });
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError } from "./build/builder.js";
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, BoundAgentBuilder, } from "./build/builder.js";
+export type { AgentOptions } from "./build/builder.js";
 export { HarnessError, isHarnessError } from "./errors.js";
 export type { HarnessErrorCode, HarnessErrorDetails, HarnessErrorOptions } from "./errors.js";
 export { BuiltAgent } from "./build/agent.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError } from "./build/builder.js";
+export { Agent, AgentBuilder, AgentBuildError, AgentLifecycleError, BoundAgentBuilder, } from "./build/builder.js";
 export { HarnessError, isHarnessError } from "./errors.js";
 export { BuiltAgent } from "./build/agent.js";
 export { middleware, model, tool } from "./build/helpers.js";

package/dist/types/manifest.d.ts

@@ -1,6 +1,8 @@
 import type { BoundMiddleware } from "./middleware.js";
 import type { BuildDiagnostic } from "./shared.js";
 export interface AgentManifest {
+    readonly id: string;
+    readonly name: string;
     readonly middleware: readonly {
         readonly id: string;
     }[];

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nylorun/harness",
-  "version": "0.7.0-beta.1",
+  "version": "0.8.0-beta.1",
   "description": "A provider-neutral, in-memory agent loop for TypeScript.",
   "type": "module",
   "license": "Apache-2.0",