@lloyal-labs/lloyal-agents 1.0.0 → 1.2.0

package/dist/trace-types.d.ts

@@ -0,0 +1,178 @@
+/**
+ * Monotonically increasing trace ID
+ *
+ * Allocated by {@link TraceWriter.nextId}. Cheap — just an incrementing
+ * counter. Used to build parent-child relationships across scopes, agent
+ * pools, and tool dispatches in the trace tree.
+ *
+ * @category Agents
+ */
+export type TraceId = number;
+/** Base shape for all trace events */
+interface TraceEventBase {
+    traceId: TraceId;
+    parentTraceId: TraceId | null;
+    ts: number;
+}
+/**
+ * Discriminated union of all trace event types
+ *
+ * Every variant extends {@link TraceEventBase} with a `type` discriminant.
+ * Events cover the full lifecycle of agent execution: scope open/close,
+ * prompt formatting, branch creation/prefill/prune, generation start/end,
+ * agent pool ticks, tool dispatch/result, diverge attempts, reranker
+ * passes, and source bindings.
+ *
+ * Written to a {@link TraceWriter} throughout the runtime. Consumers
+ * (e.g. {@link JsonlTraceWriter}) serialize events to JSONL for
+ * post-hoc analysis.
+ *
+ * @category Agents
+ */
+export type TraceEvent = TraceEventBase & {
+    type: 'scope:open';
+    name: string;
+    meta?: Record<string, unknown>;
+} | TraceEventBase & {
+    type: 'scope:close';
+    name: string;
+    durationMs: number;
+} | TraceEventBase & {
+    type: 'prompt:format';
+    promptText: string;
+    taskContent?: string;
+    tokenCount: number;
+    messages: string;
+    tools?: string;
+    grammar?: string;
+    role: 'sharedRoot' | 'agentSuffix' | 'generate' | 'diverge' | 'toolResultDelta';
+} | TraceEventBase & {
+    type: 'branch:create';
+    branchHandle: number;
+    parentHandle: number | null;
+    position: number;
+    role: 'root' | 'sharedRoot' | 'agentFork' | 'scratchpad' | 'divergeAttempt';
+} | TraceEventBase & {
+    type: 'branch:prefill';
+    branchHandle: number;
+    tokenCount: number;
+    role: 'sharedPrefix' | 'agentSuffix' | 'toolResult' | 'warmDelta' | 'scratchpad';
+} | TraceEventBase & {
+    type: 'branch:prune';
+    branchHandle: number;
+    position: number;
+} | TraceEventBase & {
+    type: 'generate:start';
+    branchHandle: number;
+    hasGrammar: boolean;
+    hasParent: boolean;
+    role: string;
+} | TraceEventBase & {
+    type: 'generate:end';
+    branchHandle: number;
+    tokenCount: number;
+    output: string;
+    parsed?: unknown;
+} | TraceEventBase & {
+    type: 'pool:open';
+    agentCount: number;
+    taskSuffixTokens: number[];
+    pressure: {
+        remaining: number;
+        softLimit: number;
+        headroom: number;
+    };
+} | TraceEventBase & {
+    type: 'pool:close';
+    agents: Array<{
+        agentId: number;
+        tokenCount: number;
+        toolCallCount: number;
+        findings: string | null;
+        ppl: number;
+    }>;
+    totalTokens: number;
+    steps: number;
+    durationMs: number;
+} | TraceEventBase & {
+    type: 'pool:tick';
+    phase: 'PRODUCE' | 'COMMIT' | 'SETTLE' | 'DISPATCH';
+    activeAgents: number;
+    pressure: {
+        remaining: number;
+        cellsUsed: number;
+        nCtx: number;
+        headroom: number;
+    };
+} | TraceEventBase & {
+    type: 'pool:agentDrop';
+    agentId: number;
+    reason: 'pressure_init' | 'pressure_critical' | 'pressure_softcut' | 'pressure_settle_reject' | 'maxTurns' | 'stop_token';
+} | TraceEventBase & {
+    type: 'agent:turn';
+    agentId: number;
+    turn: number;
+    rawOutput: string;
+    parsedContent: string | null;
+    parsedToolCalls: Array<{
+        name: string;
+        arguments: string;
+    }>;
+} | TraceEventBase & {
+    type: 'tool:dispatch';
+    agentId: number;
+    tool: string;
+    toolIndex: number;
+    toolkitSize: number;
+    args: Record<string, unknown>;
+    callId: string;
+} | TraceEventBase & {
+    type: 'tool:result';
+    agentId: number;
+    tool: string;
+    result: unknown;
+    prefillTokenCount: number;
+    durationMs: number;
+} | TraceEventBase & {
+    type: 'tool:error';
+    agentId: number;
+    tool: string;
+    error: string;
+} | TraceEventBase & {
+    type: 'diverge:start';
+    attempts: number;
+    prefixLength: number;
+} | TraceEventBase & {
+    type: 'diverge:end';
+    bestIdx: number;
+    ppls: number[];
+    outputs: string[];
+    totalTokens: number;
+} | TraceEventBase & {
+    type: 'rerank:start';
+    query: string;
+    chunkCount: number;
+} | TraceEventBase & {
+    type: 'rerank:end';
+    topResults: Array<{
+        file: string;
+        heading: string;
+        score: number;
+    }>;
+    selectedPassageCount: number;
+    totalChars: number;
+    durationMs: number;
+} | TraceEventBase & {
+    type: 'source:bind';
+    sourceName: string;
+} | TraceEventBase & {
+    type: 'source:research';
+    sourceName: string;
+    questions: string[];
+} | TraceEventBase & {
+    type: 'source:chunks';
+    sourceName: string;
+    chunkCount: number;
+};
+export {};
+//# sourceMappingURL=trace-types.d.ts.map

package/dist/trace-types.d.ts.map

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

package/dist/trace-types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=trace-types.js.map

package/dist/trace-types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-types.js","sourceRoot":"","sources":["../src/trace-types.ts"],"names":[],"mappings":""}

package/dist/trace-writer.d.ts

@@ -0,0 +1,58 @@
+import type { TraceEvent, TraceId } from './trace-types';
+/**
+ * Sink for structured trace events emitted by the agent runtime
+ *
+ * Implementations receive every {@link TraceEvent} produced during agent
+ * execution. The runtime reads the active writer from the {@link Trace}
+ * Effection context (set by {@link initAgents}).
+ *
+ * All methods must be synchronous and must not throw — tracing is
+ * best-effort and must never disrupt agent execution.
+ *
+ * @category Agents
+ */
+export interface TraceWriter {
+    /** Write a trace event. Must not throw. */
+    write(event: TraceEvent): void;
+    /** Allocate a new trace ID. Monotonically increasing. */
+    nextId(): TraceId;
+    /** Flush pending writes. Called at scope boundaries. */
+    flush(): void;
+}
+/**
+ * No-op trace writer — zero cost when tracing is disabled
+ *
+ * Default writer set by {@link initAgents} when no trace file is
+ * configured. Every method is a no-op; {@link nextId} always returns 0.
+ *
+ * @category Agents
+ */
+export declare class NullTraceWriter implements TraceWriter {
+    nextId(): TraceId;
+    write(_event: TraceEvent): void;
+    flush(): void;
+}
+/**
+ * JSONL file writer — one JSON object per line, buffered sync writes
+ *
+ * Buffers up to 64 events in memory before flushing to the underlying
+ * file descriptor with `fs.writeSync`. Flush also occurs at every
+ * {@link traceScope} close boundary to guarantee scope pairs are
+ * persisted promptly.
+ *
+ * Construct with an open file descriptor (e.g. from `fs.openSync`).
+ * Write failures are silently swallowed — tracing must never crash
+ * the runtime.
+ *
+ * @category Agents
+ */
+export declare class JsonlTraceWriter implements TraceWriter {
+    private _fd;
+    private _nextId;
+    private _buffer;
+    constructor(fd: number);
+    nextId(): TraceId;
+    write(event: TraceEvent): void;
+    flush(): void;
+}
+//# sourceMappingURL=trace-writer.d.ts.map

package/dist/trace-writer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-writer.d.ts","sourceRoot":"","sources":["../src/trace-writer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,eAAe,CAAC;AAEzD;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,2CAA2C;IAC3C,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC/B,yDAAyD;IACzD,MAAM,IAAI,OAAO,CAAC;IAClB,wDAAwD;IACxD,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;;;GAOG;AACH,qBAAa,eAAgB,YAAW,WAAW;IACjD,MAAM,IAAI,OAAO;IACjB,KAAK,CAAC,MAAM,EAAE,UAAU,GAAG,IAAI;IAC/B,KAAK,IAAI,IAAI;CACd;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,gBAAiB,YAAW,WAAW;IAClD,OAAO,CAAC,GAAG,CAAS;IACpB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,OAAO,CAAgB;gBAEnB,EAAE,EAAE,MAAM;IAEtB,MAAM,IAAI,OAAO;IAEjB,KAAK,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAK9B,KAAK,IAAI,IAAI;CASd"}

package/dist/trace-writer.js

@@ -0,0 +1,56 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.JsonlTraceWriter = exports.NullTraceWriter = void 0;
+/**
+ * No-op trace writer — zero cost when tracing is disabled
+ *
+ * Default writer set by {@link initAgents} when no trace file is
+ * configured. Every method is a no-op; {@link nextId} always returns 0.
+ *
+ * @category Agents
+ */
+class NullTraceWriter {
+    nextId() { return 0; }
+    write(_event) { }
+    flush() { }
+}
+exports.NullTraceWriter = NullTraceWriter;
+/**
+ * JSONL file writer — one JSON object per line, buffered sync writes
+ *
+ * Buffers up to 64 events in memory before flushing to the underlying
+ * file descriptor with `fs.writeSync`. Flush also occurs at every
+ * {@link traceScope} close boundary to guarantee scope pairs are
+ * persisted promptly.
+ *
+ * Construct with an open file descriptor (e.g. from `fs.openSync`).
+ * Write failures are silently swallowed — tracing must never crash
+ * the runtime.
+ *
+ * @category Agents
+ */
+class JsonlTraceWriter {
+    _fd;
+    _nextId = 1;
+    _buffer = [];
+    constructor(fd) { this._fd = fd; }
+    nextId() { return this._nextId++; }
+    write(event) {
+        this._buffer.push(JSON.stringify(event));
+        if (this._buffer.length >= 64)
+            this.flush();
+    }
+    flush() {
+        if (this._buffer.length === 0)
+            return;
+        const data = this._buffer.join('\n') + '\n';
+        this._buffer.length = 0;
+        try {
+            // eslint-disable-next-line @typescript-eslint/no-require-imports
+            require('node:fs').writeSync(this._fd, data);
+        }
+        catch { /* non-fatal */ }
+    }
+}
+exports.JsonlTraceWriter = JsonlTraceWriter;
+//# sourceMappingURL=trace-writer.js.map

package/dist/trace-writer.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trace-writer.js","sourceRoot":"","sources":["../src/trace-writer.ts"],"names":[],"mappings":";;;AAuBA;;;;;;;GAOG;AACH,MAAa,eAAe;IAC1B,MAAM,KAAc,OAAO,CAAC,CAAC,CAAC,CAAC;IAC/B,KAAK,CAAC,MAAkB,IAAS,CAAC;IAClC,KAAK,KAAU,CAAC;CACjB;AAJD,0CAIC;AAED;;;;;;;;;;;;;GAaG;AACH,MAAa,gBAAgB;IACnB,GAAG,CAAS;IACZ,OAAO,GAAG,CAAC,CAAC;IACZ,OAAO,GAAa,EAAE,CAAC;IAE/B,YAAY,EAAU,IAAI,IAAI,CAAC,GAAG,GAAG,EAAE,CAAC,CAAC,CAAC;IAE1C,MAAM,KAAc,OAAO,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC;IAE5C,KAAK,CAAC,KAAiB;QACrB,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;QACzC,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,IAAI,EAAE;YAAE,IAAI,CAAC,KAAK,EAAE,CAAC;IAC9C,CAAC;IAED,KAAK;QACH,IAAI,IAAI,CAAC,OAAO,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO;QACtC,MAAM,IAAI,GAAG,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;QAC5C,IAAI,CAAC,OAAO,CAAC,MAAM,GAAG,CAAC,CAAC;QACxB,IAAI,CAAC;YACH,iEAAiE;YACjE,OAAO,CAAC,SAAS,CAAC,CAAC,SAAS,CAAC,IAAI,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC;QAC/C,CAAC;QAAC,MAAM,CAAC,CAAC,eAAe,CAAC,CAAC;IAC7B,CAAC;CACF;AAvBD,4CAuBC"}

package/dist/types.d.ts

@@ -48,6 +48,8 @@ export interface ToolSchema {
  * @category Agents
  */
 export interface ToolContext {
+    /** Stable agent identifier — branch handle at creation time */
+    agentId: number;
     /** Progress callback for long-running operations */
     onProgress?: (p: {
         filled: number;
@@ -241,12 +243,6 @@ export interface AgentPoolResult {
         warmPrefillCalls: number;
         /** Total branches across all warm prefill batches */
         warmPrefillBranches: number;
-        /** Ticks where no agent was generating (all awaiting tools) */
-        stalledTicks: number;
-        /** Peak concurrent tool executions */
-        maxConcurrentTools: number;
-        /** Ticks spent idle-waiting via action() */
-        idleTicks: number;
     };
 }
 /**
@@ -263,6 +259,8 @@ export interface GenerateOptions {
     params?: SamplingParams;
     /** Optional parser applied to the raw output string */
     parse?: (output: string) => unknown;
+    /** Fork from parent instead of creating a fresh root. Prompt is prefilled as a delta (with turn separator). */
+    parent?: Branch;
 }
 /**
  * Result from single-branch {@link generate}
@@ -376,5 +374,9 @@ export type AgentEvent = {
 } | {
     type: 'agent:done';
     agentId: number;
+} | {
+    type: 'agent:tick';
+    cellsUsed: number;
+    nCtx: number;
 };
 //# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lloyal-labs/lloyal-agents",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Multi-agent inference inside the decode loop — structured concurrency over shared KV state",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",