@nylorun/core 0.0.0-bootstrap → 0.1.1-beta

package/dist/types/tool.d.ts

@@ -0,0 +1,187 @@
+import type { ZodType } from "zod";
+import type { DeferredOutcome, JsonObject, JsonValue } from "./shared.js";
+import type { ModelAdapter } from "./model.js";
+export interface SchemaIssue {
+    readonly path: readonly (string | number)[];
+    readonly code: string;
+    readonly message: string;
+}
+export type SchemaValidation<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly ok: false;
+    readonly issues: readonly SchemaIssue[];
+};
+/** The portable, locally-enforced schema contract accepted by a Harness tool. */
+export interface ToolSchema<T> {
+    readonly jsonSchema: JsonObject;
+    validate(value: unknown): SchemaValidation<T>;
+}
+/** The synchronous Standard Schema subset required to project and validate a tool contract. */
+export interface StandardToolSchema<Input = unknown, Output = unknown> {
+    readonly "~standard": {
+        readonly validate: (value: Input) => {
+            readonly value: Output;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: readonly StandardSchemaIssue[];
+            readonly value?: undefined;
+        } | Promise<unknown>;
+        readonly jsonSchema: {
+            readonly input: () => unknown;
+            readonly output: () => unknown;
+        };
+    };
+}
+export interface StandardSchemaIssue {
+    readonly message?: string;
+    readonly path?: readonly (string | number | symbol)[];
+    readonly code?: string;
+}
+export type ToolSchemaSource<T = unknown> = ZodType<T> | StandardToolSchema<any, T> | ToolSchema<T>;
+export type SchemaOutput<Schema> = Schema extends ZodType<infer Value> ? Value : Schema extends StandardToolSchema<any, infer Value> ? Value : Schema extends ToolSchema<infer Value> ? Value : never;
+export type ToolInputSchema = ToolSchemaSource;
+export type ToolOutputSchema = ToolSchemaSource;
+type OutputFor<Schema> = Schema extends ToolSchemaSource ? SchemaOutput<Schema> : ToolContent;
+/** Side-effect class for crash / redelivery semantics (code-only; never in the manifest). */
+export type ToolEffects = "read" | "idempotent" | "write";
+/**
+ * Declarative approval gate. Return a prompt string (or `true`) to pause;
+ * return `false` / `undefined` / empty string to proceed.
+ */
+export type ToolApproval<InputSchema extends ToolInputSchema> = (args: SchemaOutput<InputSchema>) => string | boolean | undefined | Promise<string | boolean | undefined>;
+export interface SessionStateBag {
+    get(key: string): JsonValue | undefined;
+    set(key: string, value: JsonValue): void;
+    entries(): Readonly<Record<string, JsonValue>>;
+}
+export interface ToolDefinition<InputSchema extends ToolInputSchema = ToolInputSchema, Info = unknown, OutputSchema extends ToolOutputSchema | undefined = undefined> {
+    readonly name: string;
+    readonly description?: string;
+    /** Preferred alias for `inputSchema`. */
+    readonly input?: InputSchema;
+    readonly inputSchema?: InputSchema;
+    /** Preferred alias for `outputSchema`. */
+    readonly output?: OutputSchema;
+    readonly outputSchema?: OutputSchema;
+    /** Preferred alias for `execute`. */
+    run?(args: SchemaOutput<InputSchema>, context: ToolExecutionContext<Info>): Promise<ToolRunResult<OutputFor<OutputSchema>>>;
+    execute?(args: SchemaOutput<InputSchema>, context: ToolExecutionContext<Info>): Promise<ToolRunResult<OutputFor<OutputSchema>>>;
+    /** Code-only metadata — never serialized into the manifest. */
+    readonly approval?: ToolApproval<InputSchema>;
+    /** Code-only metadata — never serialized into the manifest. */
+    readonly effects?: ToolEffects;
+}
+/** A plain return value is treated as `{ kind: "completed", output }`. Legacy tagged outcomes remain valid. */
+export type ToolRunResult<Output = ToolContent> = Output | ToolOutcome<Output>;
+export interface ToolOwner {
+    readonly middlewareId: string;
+    readonly slot: string;
+}
+export interface Interaction {
+    readonly id?: string;
+    readonly kind: "approval" | "response";
+    readonly prompt: string;
+    readonly metadata?: JsonObject;
+}
+export interface RequiredInteraction extends Interaction {
+    readonly id: string;
+}
+export interface ToolExecutionResume {
+    readonly interactionId: string;
+    readonly kind: "approval" | "response";
+    readonly approved?: boolean;
+    readonly value?: JsonValue;
+    readonly token?: JsonValue;
+}
+interface ToolExecutionContextBase {
+    readonly executionId: string;
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly callId: string;
+    readonly invocationId: string;
+    readonly signal: AbortSignal;
+    /** The invocation's model callable, for tools that explicitly run a child agent. */
+    readonly onModelCall?: ModelAdapter;
+    readonly resume?: ToolExecutionResume;
+    /** Stable per invocation across crash and replay. */
+    readonly idempotencyKey: string;
+    /** True when this invocation is being offered again after an interrupted active call. */
+    readonly redelivery?: boolean;
+    /** Durable session memory (tools write; beforeModelCall reads). */
+    readonly state: SessionStateBag;
+    /** Session identity stub — Runtime fills this later. */
+    readonly session: {
+        readonly id: string;
+    };
+    /** Live progress stub — emits an observation when a listener is present. */
+    progress(message: string, data?: JsonObject): void;
+    /** Durable wait: park for a human/app response. */
+    ask(prompt: string, opts?: JsonObject): Promise<JsonValue>;
+    /** Durable wait: park for approval. */
+    approve(prompt: string): Promise<boolean>;
+    /** Durable wait: park until a timer fires (host settles). */
+    sleep(duration: string | number): Promise<void>;
+    /** Durable wait: park until a named event arrives. */
+    waitFor(event: string, opts?: {
+        readonly match?: JsonValue;
+        readonly timeout?: string | number;
+    }): Promise<JsonValue>;
+    /** Memoized sub-step so effects before a wait are not re-run on resume. */
+    step<T>(name: string, fn: () => Promise<T> | T): Promise<T>;
+}
+export type ToolExecutionContext<Info = unknown> = ToolExecutionContextBase & {
+    readonly info?: Info;
+};
+export type ToolContent = JsonValue;
+export type ToolOutcome<Output = ToolContent> = {
+    readonly kind: "completed";
+    readonly output: Output;
+} | {
+    readonly kind: "denied";
+    readonly reason: string;
+} | {
+    readonly kind: "failed";
+    readonly code: string;
+    readonly message: string;
+} | {
+    readonly kind: "interaction-required";
+    readonly interaction: Interaction;
+    readonly token?: JsonValue;
+} | DeferredOutcome;
+export interface ToolValidationFailureDetails {
+    readonly phase: "input" | "output";
+    readonly issues: readonly SchemaIssue[];
+}
+export type ToolResult = {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly kind: "completed";
+    readonly output: ToolContent;
+} | {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly kind: "denied";
+    readonly reason: string;
+} | {
+    readonly callId: string;
+    readonly toolName: string;
+    readonly kind: "failed";
+    readonly code: string;
+    readonly message: string;
+    readonly details?: ToolValidationFailureDetails;
+};
+/** Immutable tool metadata supplied to model adapters and observers. */
+export interface ToolDescriptor {
+    readonly name: string;
+    readonly description?: string;
+    readonly owner: ToolOwner;
+    readonly inputSchema: {
+        readonly jsonSchema: JsonObject;
+    };
+    readonly outputSchema?: {
+        readonly jsonSchema: JsonObject;
+    };
+}
+export {};

package/dist/types/tool.js

@@ -0,0 +1 @@
+export {};

package/dist/types/transcript.d.ts

@@ -0,0 +1,65 @@
+import type { ModelCandidate } from "./model.js";
+import type { JsonObject, JsonValue } from "./shared.js";
+import type { ToolResult } from "./tool.js";
+export type InputEvent = {
+    readonly kind: "user-message" | "interrupt";
+    readonly text: string;
+    readonly metadata?: JsonObject;
+} | {
+    readonly kind: "user-message" | "interrupt";
+    readonly content: readonly UserContentPart[];
+    /** Undefined for content-bearing events; retained for text-event narrowing compatibility. */
+    readonly text?: undefined;
+    readonly metadata?: JsonObject;
+} | {
+    readonly kind: "approve";
+    readonly interactionId: string;
+    readonly approved: boolean;
+} | {
+    readonly kind: "respond";
+    readonly interactionId: string;
+    readonly value: JsonValue;
+};
+/** Ordered, model-visible user content. Media references stay host-owned JSON values. */
+export type UserContentPart = {
+    readonly type: "text";
+    readonly text: string;
+} | {
+    readonly type: "media";
+    readonly mediaType: string;
+    readonly reference: JsonValue;
+};
+export type MessageInput = string | {
+    readonly text: string;
+    readonly metadata?: JsonObject;
+} | {
+    readonly content: readonly UserContentPart[];
+    readonly metadata?: JsonObject;
+};
+export type InteractionReply = Extract<InputEvent, {
+    kind: "approve" | "respond";
+}>;
+export interface TranscriptInputEntry {
+    readonly kind: "input";
+    readonly turnId: string;
+    readonly event: InputEvent;
+}
+export interface TranscriptCandidateEntry {
+    readonly kind: "candidate";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly candidate: ModelCandidate;
+}
+export interface TranscriptToolsEntry {
+    readonly kind: "tool-results";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly results: readonly ToolResult[];
+}
+export interface TranscriptFinalEntry {
+    readonly kind: "final";
+    readonly turnId: string;
+    readonly stepId: string;
+    readonly output: JsonValue;
+}
+export type TranscriptEntry = TranscriptInputEntry | TranscriptCandidateEntry | TranscriptToolsEntry | TranscriptFinalEntry;

package/dist/types/transcript.js

@@ -0,0 +1 @@
+export {};

package/dist/utils/canonical.d.ts

@@ -0,0 +1 @@
+export declare function canonical(value: unknown): string;

package/dist/utils/canonical.js

@@ -0,0 +1,10 @@
+export function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => a.localeCompare(b))
+            .map(([key, item]) => `${JSON.stringify(key)}:${canonical(item)}`)
+            .join(",")}}`;
+    return JSON.stringify(value);
+}

package/dist/utils/hash.d.ts

@@ -0,0 +1,3 @@
+import type { AgentManifest } from "../types/manifest.js";
+/** Canonical SHA-256 hex digest of a manifest (agent identity). */
+export declare function hashManifest(manifest: AgentManifest): string;

package/dist/utils/hash.js

@@ -0,0 +1,7 @@
+import { sha256 } from "@noble/hashes/sha256";
+import { bytesToHex } from "@noble/hashes/utils";
+import { canonical } from "./canonical.js";
+/** Canonical SHA-256 hex digest of a manifest (agent identity). */
+export function hashManifest(manifest) {
+    return bytesToHex(sha256(canonical(manifest)));
+}

package/dist/utils/immutable.d.ts

@@ -0,0 +1,6 @@
+import type { JsonObject, JsonValue } from "../types/shared.js";
+export declare function assertJson(value: unknown, path?: string): asserts value is JsonValue;
+export declare function copyJson<T>(value: T): T;
+export declare function copyJsonObject(value: unknown, path: string): JsonObject;
+export declare function deepFreeze<T>(value: T): T;
+export declare function freezeGraph<T>(value: T, seen?: WeakSet<object>): T;

package/dist/utils/immutable.js

@@ -0,0 +1,76 @@
+import { HarnessError } from "../errors.js";
+export function assertJson(value, path = "value") {
+    assertJsonValue(value, path, new WeakSet());
+}
+function assertJsonValue(value, path, ancestors) {
+    if (value === null || typeof value === "string" || typeof value === "boolean")
+        return;
+    if (typeof value === "number" && Number.isFinite(value))
+        return;
+    if (Array.isArray(value)) {
+        enterJsonContainer(value, path, ancestors);
+        value.forEach((item, index) => assertJsonValue(item, `${path}[${index}]`, ancestors));
+        ancestors.delete(value);
+        return;
+    }
+    if (typeof value === "object") {
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null)
+            throw new HarnessError("json.invalid-data", `${path} must be plain JSON data`, {
+                details: { path },
+            });
+        enterJsonContainer(value, path, ancestors);
+        for (const [key, item] of Object.entries(value)) {
+            if (item === undefined)
+                throw new HarnessError("json.invalid-data", `${path}.${key} cannot be undefined`, {
+                    details: { path: `${path}.${key}` },
+                });
+            assertJsonValue(item, `${path}.${key}`, ancestors);
+        }
+        ancestors.delete(value);
+        return;
+    }
+    throw new HarnessError("json.invalid-data", `${path} must be JSON-serializable`, {
+        details: { path },
+    });
+}
+function enterJsonContainer(value, path, ancestors) {
+    if (ancestors.has(value))
+        throw new HarnessError("json.invalid-data", `${path} cannot contain a cycle`, {
+            details: { path },
+        });
+    ancestors.add(value);
+}
+export function copyJson(value) {
+    assertJson(value);
+    if (Array.isArray(value))
+        return Object.freeze(value.map((item) => copyJson(item)));
+    if (value !== null && typeof value === "object") {
+        return Object.freeze(Object.fromEntries(Object.entries(value).map(([key, item]) => [key, copyJson(item)])));
+    }
+    return value;
+}
+export function copyJsonObject(value, path) {
+    assertJson(value, path);
+    if (value === null || Array.isArray(value) || typeof value !== "object")
+        throw new HarnessError("json.invalid-object", `${path} must be a JSON object`, {
+            details: { path },
+        });
+    return copyJson(value);
+}
+export function deepFreeze(value) {
+    if (value && typeof value === "object" && !Object.isFrozen(value)) {
+        Object.freeze(value);
+        for (const item of Object.values(value))
+            deepFreeze(item);
+    }
+    return value;
+}
+export function freezeGraph(value, seen = new WeakSet()) {
+    if (!value || typeof value !== "object" || seen.has(value))
+        return value;
+    seen.add(value);
+    for (const item of Object.values(value))
+        freezeGraph(item, seen);
+    return Object.freeze(value);
+}

package/package.json

@@ -1,12 +1,62 @@
 {
   "name": "@nylorun/core",
-  "version": "0.0.0-bootstrap",
-  "description": "Bootstrap placeholder for @nylorun/core",
-  "main": "index.js",
+  "version": "0.1.1-beta",
+  "type": "module",
+  "license": "Apache-2.0",
+  "description": "Shared agent definitions and wire contracts",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nylorun/harness.git",
+    "directory": "core"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "engines": {
+    "node": "^22.14.0 || ^24.0.0 || >=26.0.0"
+  },
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "npm run clean && node ../scripts/check-typescript-version.mjs && tsc -p tsconfig.json",
+    "clean": "node -e \"import('node:fs').then(({rmSync})=>rmSync('dist',{recursive:true,force:true}))\"",
+    "check": "npm run build && npm test && node scripts/check-package.mjs",
+    "test": "vitest run --passWithNoTests",
+    "prepack": "npm run build"
+  },
+  "dependencies": {
+    "@noble/hashes": "^1.8.0"
+  },
+  "devDependencies": {
+    "typescript": "npm:@typescript/typescript6@^6.0.2",
+    "@types/node": "^26.5.0",
+    "vitest": "^5.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./define": {
+      "types": "./dist/define.d.ts",
+      "import": "./dist/define.js"
+    },
+    "./contracts": {
+      "types": "./dist/contracts.d.ts",
+      "import": "./dist/contracts.js"
+    },
+    "./compatibility": {
+      "types": "./dist/compatibility.d.ts",
+      "import": "./dist/compatibility.js"
+    }
+  },
+  "peerDependencies": {
+    "zod": "^4.5.4"
   },
-  "keywords": [],
-  "author": "",
-  "license": "MIT"
+  "sideEffects": false
 }

package/index.js

@@ -1 +0,0 @@
-export {}