@haikeilabs/agentware 0.1.1 → 0.2.1

package/README.md

@@ -43,3 +43,22 @@ Register only the wrapped handler with an agent framework or tool registry.
 Keep channel ingress, identity verification, delegated credentials, and
 domain-specific authorization in the host application. Agentware is not a
 policy engine; a policy gate can wrap this same boundary later.
+
+## Maintainer releases
+
+Releases are deliberately manual and use npm staged publishing. Do not run
+`npm publish` from a workstation or add a registry token to CI.
+
+1. Update `typescript/package.json` and `typescript/package-lock.json` to the
+   intended semantic version in a pull request, then merge it to `main`.
+2. In GitHub Actions, run **Stage Agentware npm package** from `main`, entering
+   that exact version (for example, `0.1.1`). The workflow verifies the version,
+   creates the immutable `agentware-v<version>` tag, runs checks, and submits
+   the package with `npm stage publish`.
+3. Approve the GitHub `release` environment when prompted.
+4. Review the staged package in npm and approve it. The approving maintainer
+   needs npm publish access and 2FA enabled for write actions; a WebAuthn
+   security key is supported.
+
+The final npm approval is intentional: it is the human gate that makes the
+staged version publicly available.

package/dist/executor/agent_loop.d.ts

@@ -3,6 +3,7 @@ import type { ToolRegistry } from "../tools/index.js";
 import type { ResponseValidator } from "../middleware/guardrails/response_validator.js";
 import { ErrorTracker, ErrorCategory } from "../middleware/guardrails/error_tracker.js";
 import { StepEnforcer } from "../middleware/guardrails/step_enforcer.js";
+import { ReasoningAdapter, type ContextTree } from "../reasoning/index.js";
 export declare enum AgentTerminationReason {
     COMPLETE = "complete",
     MAX_ITERATIONS = "max_iterations",
@@ -18,6 +19,9 @@ export interface AgentLoopConfig {
     max_iterations?: number;
     max_nudges?: number;
     require_tool_call?: boolean;
+    /** Optional reasoning adapter override for limits and registered model
+     * fields. */
+    reasoning?: ReasoningAdapter;
 }
 export interface AgentResult {
     final_response: string;
@@ -26,6 +30,11 @@ export interface AgentResult {
     nudges: number;
     termination_reason: AgentTerminationReason;
     conversation: Message[];
+    /** Normalized context tree for the last turn that carried reasoning
+     * (native reasoning_content and/or thinking tags). Null when no turn
+     * carried reasoning. Holds bounded summaries only; raw reasoning is never
+     * attached. */
+    reasoning_tree: ContextTree | null;
 }
 export declare function registryToolDefinitions(registry: ToolRegistry): ToolDefinition[];
 export declare function categorizeError(message: string): ErrorCategory;

package/dist/executor/agent_loop.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent_loop.d.ts","sourceRoot":"","sources":["../../src/executor/agent_loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,YAAY,EACZ,aAAa,EACd,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAQzE,oBAAY,sBAAsB;IAChC,QAAQ,aAAa;IACrB,cAAc,mBAAmB;IACjC,gBAAgB,qBAAqB;IACrC,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,sBAAsB,CAAC;IAC3C,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,YAAY,GACrB,cAAc,EAAE,CASlB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CA0B9D;AAiBD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,eAAe;IAU7B,GAAG,CACP,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,OAAO,EAAO,EACvB,UAAU,GAAE,MAAW,GACtB,OAAO,CAAC,WAAW,CAAC;IAsLvB,OAAO,CAAC,QAAQ;IAiBhB,OAAO,CAAC,MAAM;CAiBf"}
+{"version":3,"file":"agent_loop.d.ts","sourceRoot":"","sources":["../../src/executor/agent_loop.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AAG7E,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEtD,OAAO,KAAK,EACV,iBAAiB,EAElB,MAAM,gDAAgD,CAAC;AACxD,OAAO,EACL,YAAY,EACZ,aAAa,EACd,MAAM,2CAA2C,CAAC;AACnD,OAAO,EAAE,YAAY,EAAE,MAAM,2CAA2C,CAAC;AAOzE,OAAO,EACL,gBAAgB,EAGhB,KAAK,WAAW,EACjB,MAAM,uBAAuB,CAAC;AAE/B,oBAAY,sBAAsB;IAChC,QAAQ,aAAa;IACrB,cAAc,mBAAmB;IACjC,gBAAgB,qBAAqB;IACrC,KAAK,UAAU;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,CAAC;IACtB,QAAQ,EAAE,YAAY,CAAC;IACvB,SAAS,EAAE,iBAAiB,CAAC;IAC7B,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,aAAa,CAAC,EAAE,YAAY,CAAC;IAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;iBACa;IACb,SAAS,CAAC,EAAE,gBAAgB,CAAC;CAC9B;AAED,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,kBAAkB,EAAE,sBAAsB,CAAC;IAC3C,YAAY,EAAE,OAAO,EAAE,CAAC;IACxB;;;mBAGe;IACf,cAAc,EAAE,WAAW,GAAG,IAAI,CAAC;CACpC;AAKD,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,YAAY,GACrB,cAAc,EAAE,CASlB;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,aAAa,CA0B9D;AAiBD,qBAAa,SAAS;IACpB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAkB;IACzC,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;gBAEvB,MAAM,EAAE,eAAe;IAU7B,GAAG,CACP,aAAa,EAAE,MAAM,EACrB,YAAY,EAAE,MAAM,EACpB,OAAO,GAAE,OAAO,EAAO,EACvB,UAAU,GAAE,MAAW,GACtB,OAAO,CAAC,WAAW,CAAC;IA2OvB,OAAO,CAAC,QAAQ;IAiBhB,OAAO,CAAC,MAAM;CAmBf"}

package/dist/executor/agent_loop.js

@@ -3,6 +3,7 @@ import { executeTool, Result } from "../tools/index.js";
 import { ErrorCategory, } from "../middleware/guardrails/error_tracker.js";
 import { NudgeKind, stepNudge, } from "../middleware/guardrails/nudge.js";
 import { MessageType } from "../middleware/types.js";
+import { ReasoningAdapter, ReasoningError, isContextTreeEmpty, } from "../reasoning/index.js";
 export var AgentTerminationReason;
 (function (AgentTerminationReason) {
     AgentTerminationReason["COMPLETE"] = "complete";
@@ -10,6 +11,8 @@ export var AgentTerminationReason;
     AgentTerminationReason["NUDGES_EXHAUSTED"] = "nudges_exhausted";
     AgentTerminationReason["ERROR"] = "error";
 })(AgentTerminationReason || (AgentTerminationReason = {}));
+// Default adapter strips and normalizes reasoning in the agent loop.
+const defaultAdapter = new ReasoningAdapter();
 export function registryToolDefinitions(registry) {
     return registry.all().map((tool) => ({
         name: tool.name,
@@ -69,14 +72,19 @@ export class AgentLoop {
             config.max_nudges && config.max_nudges > 0 ? config.max_nudges : 3;
     }
     async run(system_prompt, user_message, history = [], session_id = "") {
-        const conversation = [...history];
-        conversation.push({ role: Role.SYSTEM, content: system_prompt });
+        // Cross-language contract: the system prompt leads the conversation,
+        // ahead of any caller-supplied history (mirrors Go buildConversation).
+        const conversation = [
+            { role: Role.SYSTEM, content: system_prompt },
+            ...history,
+        ];
         conversation.push({ role: Role.USER, content: user_message });
         const toolDefs = registryToolDefinitions(this.config.registry);
         let iterations = 0;
         let toolCallsMade = 0;
         let nudges = 0;
         let finalResponse = "";
+        let reasoningTree = null;
         while (iterations < this.maxIterations) {
             iterations++;
             let resp;
@@ -85,17 +93,57 @@ export class AgentLoop {
             }
             catch (err) {
                 this.config.error_tracker?.recordError(session_id, "", {}, toError(err), ErrorCategory.UNKNOWN);
-                return this.finish(finalResponse, iterations, toolCallsMade, nudges, AgentTerminationReason.ERROR, conversation);
+                return this.finish(finalResponse, iterations, toolCallsMade, nudges, AgentTerminationReason.ERROR, conversation, reasoningTree);
             }
-            const validation = this.validate(resp);
+            // AR-1 parity: normalize reasoning and strip it before validation.
+            // Reasoning can arrive as a native reasoning_content field or as
+            // embedded thinking tags in content; both are combined into a synthetic
+            // structured input so the adapter sees the full picture. Malformed or
+            // unbounded reasoning fails closed: this turn is treated as invalid and
+            // retried rather than parsed partially.
+            let turnTree = null;
+            let cleanContent = resp.content;
+            let reasoningFailed = false;
+            if (resp.content || resp.reasoning) {
+                const reasoningInput = {
+                    content: resp.content,
+                };
+                if (resp.reasoning) {
+                    reasoningInput["reasoning_content"] = resp.reasoning;
+                }
+                const adapter = this.config.reasoning ?? defaultAdapter;
+                try {
+                    turnTree = adapter.extract(reasoningInput, this.config.backend.modelName(), "agent-loop");
+                    cleanContent = adapter.strip(reasoningInput);
+                }
+                catch (e) {
+                    if (e instanceof ReasoningError) {
+                        reasoningFailed = true;
+                        // Fail closed: never echo content that may carry reasoning we
+                        // could not parse.
+                        cleanContent = "";
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+            }
+            // Keep the last turn that actually carried reasoning; a later plain
+            // turn must not blank out the tree the consumer is after.
+            if (!isContextTreeEmpty(turnTree)) {
+                reasoningTree = turnTree;
+            }
+            const validation = reasoningFailed
+                ? { toolCalls: [], nudge: null, needsRetry: true }
+                : this.validate(resp, cleanContent);
             if (validation.needsRetry) {
                 if (nudges >= this.maxNudges) {
-                    return this.finish(resp.content, iterations, toolCallsMade, nudges, AgentTerminationReason.NUDGES_EXHAUSTED, conversation);
+                    return this.finish(cleanContent, iterations, toolCallsMade, nudges, AgentTerminationReason.NUDGES_EXHAUSTED, conversation, reasoningTree);
                 }
                 nudges++;
                 conversation.push({
                     role: Role.ASSISTANT,
-                    content: resp.content,
+                    content: cleanContent,
                     meta: { type: MessageType.TEXT_RESPONSE },
                 });
                 if (validation.nudge) {
@@ -108,8 +156,8 @@ export class AgentLoop {
                 continue;
             }
             if (validation.toolCalls.length === 0) {
-                finalResponse = resp.content;
-                return this.finish(finalResponse, iterations, toolCallsMade, nudges, AgentTerminationReason.COMPLETE, conversation);
+                finalResponse = cleanContent;
+                return this.finish(finalResponse, iterations, toolCallsMade, nudges, AgentTerminationReason.COMPLETE, conversation, reasoningTree);
             }
             let stepNudged = false;
             for (const call of validation.toolCalls) {
@@ -117,7 +165,7 @@ export class AgentLoop {
                     const [allowed, missing] = this.config.step_enforcer.canExecute(session_id, call.tool);
                     if (!allowed) {
                         if (nudges >= this.maxNudges) {
-                            return this.finish(resp.content, iterations, toolCallsMade, nudges, AgentTerminationReason.NUDGES_EXHAUSTED, conversation);
+                            return this.finish(cleanContent, iterations, toolCallsMade, nudges, AgentTerminationReason.NUDGES_EXHAUSTED, conversation, reasoningTree);
                         }
                         nudges++;
                         stepNudged = true;
@@ -178,13 +226,13 @@ export class AgentLoop {
                 continue;
             }
         }
-        return this.finish(finalResponse, iterations, toolCallsMade, nudges, AgentTerminationReason.MAX_ITERATIONS, conversation);
+        return this.finish(finalResponse, iterations, toolCallsMade, nudges, AgentTerminationReason.MAX_ITERATIONS, conversation, reasoningTree);
     }
-    validate(resp) {
+    validate(resp, cleanContent) {
         if (resp.tool_calls.length > 0) {
             return this.config.validator.validateToolCalls(resp.tool_calls.map((tc) => ({ tool: tc.name, args: tc.arguments })));
         }
-        const textValidation = this.config.validator.validateTextResponse(resp.content);
+        const textValidation = this.config.validator.validateTextResponse(cleanContent);
         if (textValidation.toolCalls.length > 0) {
             return textValidation;
         }
@@ -193,7 +241,7 @@ export class AgentLoop {
         }
         return { toolCalls: [], nudge: null, needsRetry: false };
     }
-    finish(finalResponse, iterations, toolCallsMade, nudges, termination, conversation) {
+    finish(finalResponse, iterations, toolCallsMade, nudges, termination, conversation, reasoningTree) {
         return {
             final_response: finalResponse,
             iterations,
@@ -201,6 +249,7 @@ export class AgentLoop {
             nudges,
             termination_reason: termination,
             conversation,
+            reasoning_tree: reasoningTree,
         };
     }
 }

package/dist/executor/executor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/executor/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAIxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,oBAAY,iBAAiB;IAC3B,QAAQ,aAAa;IACrB,cAAc,mBAAmB;IACjC,KAAK,UAAU;IACf,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,iBAAiB,CAAC;IACtC,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,aAAa,CAAC;CAC7C;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,aAAa,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAA0B;gBAE5B,MAAM,EAAE,uBAAuB;IAQ3C,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,aAAa;CA2D5C"}
+{"version":3,"file":"executor.d.ts","sourceRoot":"","sources":["../../src/executor/executor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAIxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAC5D,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACtD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAE5D,oBAAY,iBAAiB;IAC3B,QAAQ,aAAa;IACrB,cAAc,mBAAmB;IACjC,KAAK,UAAU;IACf,QAAQ,aAAa;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,OAAO,EAAE,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,UAAU,EAAE,aAAa,CAAC;IAC1B,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,CAAC;IACxB,kBAAkB,EAAE,iBAAiB,CAAC;IACtC,YAAY,EAAE,OAAO,EAAE,CAAC;CACzB;AAED,MAAM,WAAW,QAAQ;IACvB,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,aAAa,CAAC;CAC7C;AAED,MAAM,WAAW,uBAAuB;IACtC,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,aAAa,EAAE,OAAO,CAAC;IACvB,SAAS,EAAE,aAAa,CAAC;IACzB,cAAc,EAAE,MAAM,CAAC;IACvB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,qBAAa,iBAAkB,YAAW,QAAQ;IAChD,OAAO,CAAC,MAAM,CAA0B;gBAE5B,MAAM,EAAE,uBAAuB;IAQ3C,OAAO,CAAC,GAAG,EAAE,cAAc,GAAG,aAAa;CA+D5C"}

package/dist/executor/executor.js

@@ -16,8 +16,12 @@ export class InferenceExecutor {
         };
     }
     execute(req) {
-        const conversation = [...req.history];
-        conversation.push({ role: Role.SYSTEM, content: req.system_prompt });
+        // Cross-language contract: the system prompt leads the conversation,
+        // ahead of any caller-supplied history (mirrors Go buildConversation).
+        const conversation = [
+            { role: Role.SYSTEM, content: req.system_prompt },
+            ...req.history,
+        ];
         conversation.push({ role: Role.USER, content: req.user_message });
         let iterations = 0;
         let tool_calls_made = 0;

package/dist/index.d.ts

@@ -8,4 +8,5 @@ export * from "./prompts/index.js";
 export * from "./toolformat/index.js";
 export * from "./memory/index.js";
 export * from "./reasoning/index.js";
+export * from "./kei/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,qBAAqB,CAAC;AACpC,cAAc,iBAAiB,CAAC;AAChC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,uBAAuB,CAAC;AACtC,cAAc,mBAAmB,CAAC;AAClC,cAAc,sBAAsB,CAAC;AACrC,cAAc,gBAAgB,CAAC"}

package/dist/index.js

@@ -8,3 +8,4 @@ export * from "./prompts/index.js";
 export * from "./toolformat/index.js";
 export * from "./memory/index.js";
 export * from "./reasoning/index.js";
+export * from "./kei/index.js";

package/dist/kei/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./runtimeLink.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/kei/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/kei/index.ts"],"names":[],"mappings":"AAAA,cAAc,kBAAkB,CAAC"}

package/dist/kei/index.js

@@ -0,0 +1 @@
+export * from "./runtimeLink.js";

package/dist/kei/runtimeLink.d.ts

@@ -0,0 +1,281 @@
+/**
+ * RuntimeLink contract: the harness → Agentware → kei-connector-runtime heartbeat.
+ *
+ * TypeScript mirror of the Go reference `go/kei/runtimelink` for
+ * `docs/specs/runtime-heartbeat-liveness.md` (HAI-141). Contract types only:
+ * configuration, status, identity, failure classes, the child's JSONL wire
+ * events, and redacted lifecycle events. It never spawns a process, opens a
+ * network connection, or reads a credential value. The only heartbeat path is
+ * harness → RuntimeLink → kei-connector-runtime; nothing here talks to the
+ * catalog.
+ *
+ * All three SDK languages share `testing/contracts/runtime-link`. Durations
+ * are milliseconds here (`intervalMs`), seconds in Python, and
+ * `time.Duration` in Go.
+ */
+/** The child stdout event version ("v") this SDK accepts. */
+export declare const RUNTIME_LINK_CONTRACT_VERSION = 1;
+/** Bound on one child stdout line, excluding the newline. */
+export declare const MAX_CHILD_LINE_BYTES = 4096;
+/** Capacity of the RuntimeLink event ring. */
+export declare const RUNTIME_LINK_EVENT_BUFFER_SIZE = 64;
+export declare const RUNTIME_LINK_SDK_LANG = "typescript";
+export declare const HARNESS_KINDS: readonly ["assistant", "pde", "chat-discord", "chat-slack", "chat-teams", "cli"];
+export type HarnessKind = (typeof HARNESS_KINDS)[number];
+export declare const LINK_STATES: readonly ["disabled", "starting", "connected", "degraded", "reconnecting", "terminal", "stopped"];
+export type LinkState = (typeof LINK_STATES)[number];
+/**
+ * Closed failure taxonomy (spec §6.3). Separates harness↔runtime failures
+ * from runtime↔catalog failures so alerts route to the right owner.
+ */
+export declare const FAILURE_CLASSES: readonly ["config_invalid", "runtime_unavailable", "runtime_crashloop", "runtime_unresponsive", "contract_mismatch", "catalog_unreachable", "catalog_timeout", "catalog_error", "catalog_backpressure", "installation_unauthorized", "installation_stale", "installation_offline", "audit_backlog", "legacy_runtime_unverified"];
+export type FailureClass = (typeof FAILURE_CLASSES)[number];
+export declare const BEAT_OUTCOMES: readonly ["ok", "catalog_unreachable", "catalog_timeout", "catalog_error", "catalog_backpressure", "catalog_rejected", "unauthorized"];
+export type BeatOutcome = (typeof BEAT_OUTCOMES)[number];
+export declare const LIFECYCLE_EVENT_NAMES: readonly ["runtime.link.started", "runtime.link.connected", "runtime.link.degraded", "runtime.link.reconnecting", "runtime.link.terminal", "runtime.link.stopped"];
+export type LifecycleEventName = (typeof LIFECYCLE_EVENT_NAMES)[number];
+export declare const SDK_LANGS: readonly ["go", "python", "typescript"];
+export type SdkLang = (typeof SDK_LANGS)[number];
+/** The exact environment a runtime child may receive; never `process.env`. */
+export declare const CHILD_ENV_ALLOWLIST: readonly ["KEI_RUNTIME_TOKEN", "KEI_RUNTIME_CONTROL_PLANE_URL", "KEI_HARNESS_KIND", "KEI_HARNESS_VERSION", "KEI_DEPLOYMENT_ENV", "KEI_AGENTWARE_SDK_LANG", "KEI_AGENTWARE_SDK_VERSION", "KEI_HEARTBEAT_RUN_ID", "PATH", "HOME", "TZ"];
+/** Environment variables. KEI_PROXY_* keep their legacy names (runtime contract). */
+export declare const RUNTIME_LINK_ENV: {
+    readonly enabled: "KEI_RUNTIME_ENABLED";
+    readonly token: "KEI_RUNTIME_TOKEN";
+    readonly legacyToken: "KEI_HARNESS_TOKEN";
+    readonly controlPlaneUrl: "KEI_RUNTIME_CONTROL_PLANE_URL";
+    readonly proxyPath: "KEI_PROXY_PATH";
+    readonly proxySha: "KEI_PROXY_SHA";
+    readonly interval: "KEI_HEARTBEAT_INTERVAL";
+    readonly timeout: "KEI_HEARTBEAT_TIMEOUT";
+    readonly restartMin: "KEI_HEARTBEAT_RESTART_MIN";
+    readonly restartMax: "KEI_HEARTBEAT_RESTART_MAX";
+    readonly stableSeconds: "KEI_HEARTBEAT_STABLE_SECONDS";
+    readonly logCount: "KEI_HEARTBEAT_LOG_COUNT";
+    readonly harnessKind: "KEI_HARNESS_KIND";
+    readonly harnessVersion: "KEI_HARNESS_VERSION";
+    readonly deploymentEnv: "KEI_DEPLOYMENT_ENV";
+};
+/** The distribution keeps the kei-proxy name; the repo is kei-connector-runtime. */
+export declare const DEFAULT_RUNTIME_BINARY_PATH = "kei-proxy";
+/**
+ * Bounds. Interval is clamped; everything else is rejected when out of range
+ * so a typo fails closed instead of silently changing behavior.
+ */
+export declare const RUNTIME_LINK_BOUNDS: {
+    readonly minIntervalMs: 15000;
+    readonly maxIntervalMs: 300000;
+    readonly maxGraceMs: 300000;
+    readonly minRestartMs: 1000;
+    readonly maxRestartMs: 3600000;
+    readonly minStableResetMs: 1000;
+    readonly maxStableResetMs: 3600000;
+    readonly minStopTimeoutMs: 1000;
+    readonly maxStopTimeoutMs: 60000;
+    readonly maxLogCount: 100;
+};
+export declare const RUNTIME_LINK_CONFIG_ERROR_CODES: readonly ["invalid_value", "out_of_range", "beat_timeout", "harness_kind", "envelope", "legacy_token", "token_missing", "control_plane_url", "binary"];
+export type RuntimeLinkConfigErrorCode = (typeof RUNTIME_LINK_CONFIG_ERROR_CODES)[number];
+/**
+ * Invalid RuntimeLink configuration. Carries the offending field and a stable
+ * code, never the offending value, so a misplaced secret cannot leak.
+ */
+export declare class RuntimeLinkConfigError extends Error {
+    readonly code: RuntimeLinkConfigErrorCode;
+    readonly field: string;
+    constructor(code: RuntimeLinkConfigErrorCode, field: string);
+}
+/** The runtime binary and its expected SHA-256 (lowercase hex). */
+export interface BinaryRef {
+    path: string;
+    sha256: string;
+}
+/** Where the runtime token lives: the env var name only, never the value. */
+export interface SecretSource {
+    env: string;
+}
+/** Child restart backoff with full jitter. */
+export interface Backoff {
+    minMs: number;
+    maxMs: number;
+    stableResetMs: number;
+}
+/** Declared, non-authoritative harness metadata. Never used for authorization. */
+export interface HarnessEnvelope {
+    kind: string;
+    version: string;
+    deploymentEnv: string;
+}
+export interface RuntimeLinkConfig {
+    enabled: boolean;
+    binary: BinaryRef;
+    controlPlaneUrl: string;
+    token: SecretSource;
+    intervalMs: number;
+    beatTimeoutMs: number;
+    graceMs: number;
+    restart: Backoff;
+    stopTimeoutMs: number;
+    logCount: number;
+    harness: HarnessEnvelope;
+}
+/** The spec defaults with the link disabled. */
+export declare function defaultRuntimeLinkConfig(): RuntimeLinkConfig;
+/**
+ * Clamp `intervalMs` to [15s, 300s] and validate every other field, throwing
+ * RuntimeLinkConfigError on the first violation. A disabled link (local-only
+ * mode) is valid, but its declared envelope and timings are still checked so
+ * typos fail loudly.
+ */
+export declare function normalizeRuntimeLinkConfig(cfg: RuntimeLinkConfig): RuntimeLinkConfig;
+export type EnvSource = Readonly<Record<string, string | undefined>>;
+/**
+ * Build a normalized config from the spec §3.2 variables. Non-empty fields of
+ * `harness` override the KEI_HARNESS_* variables. The runtime token is only
+ * checked for presence; its value is never retained.
+ */
+export declare function runtimeLinkConfigFromEnv(env?: EnvSource, harness?: Partial<HarnessEnvelope>): RuntimeLinkConfig;
+/**
+ * Full-jitter restart delay for attempt n (0-based):
+ * `floor(r × min(maxMs, minMs × 2^n))`. `r` is clamped to [0, 1); negative
+ * attempts count as 0.
+ */
+export declare function backoffDelayMs(backoff: Pick<Backoff, "minMs" | "maxMs">, attempt: number, r: number): number;
+export interface WaitBackoffOptions {
+    signal?: AbortSignal;
+    random?: () => number;
+}
+/**
+ * Sleep for the jittered delay, or reject with the signal's abort reason as
+ * soon as `signal` aborts, so a stop during backoff never waits out the delay.
+ */
+export declare function waitBackoff(backoff: Pick<Backoff, "minMs" | "maxMs">, attempt: number, options?: WaitBackoffOptions): Promise<void>;
+/** Point-in-time snapshot. Diagnostic only: readiness must never depend on it. */
+export interface LinkStatus {
+    state: LinkState;
+    /** Absent when connected. */
+    reason?: FailureClass;
+    lastBeatAt?: Date;
+    lastCatalogOkAt?: Date;
+    consecutiveFails: number;
+    runId: string;
+    restarts: number;
+}
+/** Authoritative installation identity from catalog whoami, via the runtime. */
+export interface RuntimeIdentity {
+    runId: string;
+    installationId: string;
+    orgId: string;
+    workspaceId: string;
+    platform: string;
+    status: string;
+    bindingStatus: string;
+    runtimeVersion: string;
+}
+export type ChildLineErrorKind = "line_too_long" | "malformed" | "contract_mismatch";
+/** A child line the SDK must drop and count. */
+export declare class ChildLineError extends Error {
+    readonly kind: ChildLineErrorKind;
+    constructor(kind: ChildLineErrorKind, detail: string);
+}
+export interface BeatEvent {
+    runId: string;
+    /** 0 when absent: the runtime omits seq on beats sent before identity. */
+    seq: number;
+    at: string;
+    outcome: BeatOutcome;
+    httpStatus: number;
+    latencyMs: number;
+    nextInMs: number;
+}
+export interface TerminalEvent {
+    runId: string;
+    reason: string;
+}
+export type ChildEvent = {
+    kind: "identity";
+    identity: RuntimeIdentity;
+} | {
+    kind: "beat";
+    beat: BeatEvent;
+} | {
+    kind: "terminal";
+    terminal: TerminalEvent;
+} | {
+    kind: "ignored";
+};
+/**
+ * Parse one line of child stdout (a trailing "\n" / "\r\n" is ignored). Only
+ * allowlisted fields survive; payloads, results, reasoning, tokens, or any
+ * other key the runtime might emit are dropped. Throws ChildLineError for
+ * lines the SDK must drop and count.
+ */
+export declare function parseChildLine(line: string | Uint8Array): ChildEvent;
+/** A lifecycle event has a value outside its closed set or bounds. */
+export declare class InvalidLinkEventError extends Error {
+    constructor(detail: string);
+}
+export interface EventHarness {
+    kind: HarnessKind;
+    version: string;
+    deploymentEnv: string;
+    sdkLang: SdkLang;
+    sdkVersion: string;
+}
+/**
+ * A redacted lifecycle record. Redacted by construction: the type has no
+ * field that could carry a token, argv, env, child stderr, provider payload
+ * or result, reasoning, customer content, or a subject.
+ */
+export interface LinkEvent {
+    name: LifecycleEventName;
+    at: Date;
+    state: LinkState;
+    /** Empty when there is no failure. */
+    reason: FailureClass | "";
+    runId: string;
+    seq: number;
+    sdkInstanceId: string;
+    harness: EventHarness;
+    restarts: number;
+    consecutiveFails: number;
+}
+/** The serialized form: exactly these keys, in this order. */
+export interface LinkEventWire {
+    name: LifecycleEventName;
+    at: string;
+    state: LinkState;
+    reason: FailureClass | "";
+    run_id: string;
+    seq: number;
+    sdk_instance_id: string;
+    harness: {
+        kind: HarnessKind;
+        version: string;
+        deployment_env: string;
+        sdk_lang: SdkLang;
+        sdk_version: string;
+    };
+    restarts: number;
+    consecutive_fails: number;
+}
+/** Throws InvalidLinkEventError unless every closed set and bound holds. */
+export declare function validateLinkEvent(ev: LinkEvent): LinkEvent;
+/** Build an event from allowlisted wire keys only; everything else is dropped. */
+export declare function linkEventFromWire(raw: unknown): LinkEvent;
+/** Validate and emit exactly the allowlisted keys; `at` is UTC with millisecond precision. */
+export declare function linkEventToWire(ev: LinkEvent): LinkEventWire;
+/**
+ * Supervises the harness→runtime heartbeat. `start` returns promptly and
+ * rejects only for invalid config, never for network or runtime state.
+ * Aborting the signal passed to `start`, or calling `stop`, ends the link;
+ * `stop` is idempotent and bounded by `stopTimeoutMs`.
+ */
+export interface RuntimeLink {
+    start(signal?: AbortSignal): Promise<void>;
+    stop(): Promise<void>;
+    status(): LinkStatus;
+    identity(): RuntimeIdentity | undefined;
+    events(): AsyncIterable<LinkEvent>;
+}
+//# sourceMappingURL=runtimeLink.d.ts.map

package/dist/kei/runtimeLink.d.ts.map

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

package/dist/kei/runtimeLink.js

@@ -0,0 +1,591 @@
+/**
+ * RuntimeLink contract: the harness → Agentware → kei-connector-runtime heartbeat.
+ *
+ * TypeScript mirror of the Go reference `go/kei/runtimelink` for
+ * `docs/specs/runtime-heartbeat-liveness.md` (HAI-141). Contract types only:
+ * configuration, status, identity, failure classes, the child's JSONL wire
+ * events, and redacted lifecycle events. It never spawns a process, opens a
+ * network connection, or reads a credential value. The only heartbeat path is
+ * harness → RuntimeLink → kei-connector-runtime; nothing here talks to the
+ * catalog.
+ *
+ * All three SDK languages share `testing/contracts/runtime-link`. Durations
+ * are milliseconds here (`intervalMs`), seconds in Python, and
+ * `time.Duration` in Go.
+ */
+/** The child stdout event version ("v") this SDK accepts. */
+export const RUNTIME_LINK_CONTRACT_VERSION = 1;
+/** Bound on one child stdout line, excluding the newline. */
+export const MAX_CHILD_LINE_BYTES = 4096;
+/** Capacity of the RuntimeLink event ring. */
+export const RUNTIME_LINK_EVENT_BUFFER_SIZE = 64;
+export const RUNTIME_LINK_SDK_LANG = "typescript";
+export const HARNESS_KINDS = [
+    "assistant",
+    "pde",
+    "chat-discord",
+    "chat-slack",
+    "chat-teams",
+    "cli",
+];
+export const LINK_STATES = [
+    "disabled",
+    "starting",
+    "connected",
+    "degraded",
+    "reconnecting",
+    "terminal",
+    "stopped",
+];
+/**
+ * Closed failure taxonomy (spec §6.3). Separates harness↔runtime failures
+ * from runtime↔catalog failures so alerts route to the right owner.
+ */
+export const FAILURE_CLASSES = [
+    "config_invalid",
+    "runtime_unavailable",
+    "runtime_crashloop",
+    "runtime_unresponsive",
+    "contract_mismatch",
+    "catalog_unreachable",
+    "catalog_timeout",
+    "catalog_error",
+    "catalog_backpressure",
+    "installation_unauthorized",
+    "installation_stale",
+    "installation_offline",
+    "audit_backlog",
+    "legacy_runtime_unverified",
+];
+export const BEAT_OUTCOMES = [
+    "ok",
+    "catalog_unreachable",
+    "catalog_timeout",
+    "catalog_error",
+    "catalog_backpressure",
+    "catalog_rejected",
+    "unauthorized",
+];
+export const LIFECYCLE_EVENT_NAMES = [
+    "runtime.link.started",
+    "runtime.link.connected",
+    "runtime.link.degraded",
+    "runtime.link.reconnecting",
+    "runtime.link.terminal",
+    "runtime.link.stopped",
+];
+export const SDK_LANGS = ["go", "python", "typescript"];
+/** The exact environment a runtime child may receive; never `process.env`. */
+export const CHILD_ENV_ALLOWLIST = [
+    "KEI_RUNTIME_TOKEN",
+    "KEI_RUNTIME_CONTROL_PLANE_URL",
+    "KEI_HARNESS_KIND",
+    "KEI_HARNESS_VERSION",
+    "KEI_DEPLOYMENT_ENV",
+    "KEI_AGENTWARE_SDK_LANG",
+    "KEI_AGENTWARE_SDK_VERSION",
+    "KEI_HEARTBEAT_RUN_ID",
+    "PATH",
+    "HOME",
+    "TZ",
+];
+function isOneOf(set, value) {
+    return (typeof value === "string" && set.includes(value));
+}
+// ---------------------------------------------------------------------------
+// Configuration (spec §3.1, §3.2)
+// ---------------------------------------------------------------------------
+/** Environment variables. KEI_PROXY_* keep their legacy names (runtime contract). */
+export const RUNTIME_LINK_ENV = {
+    enabled: "KEI_RUNTIME_ENABLED",
+    token: "KEI_RUNTIME_TOKEN",
+    legacyToken: "KEI_HARNESS_TOKEN",
+    controlPlaneUrl: "KEI_RUNTIME_CONTROL_PLANE_URL",
+    proxyPath: "KEI_PROXY_PATH",
+    proxySha: "KEI_PROXY_SHA",
+    interval: "KEI_HEARTBEAT_INTERVAL",
+    timeout: "KEI_HEARTBEAT_TIMEOUT",
+    restartMin: "KEI_HEARTBEAT_RESTART_MIN",
+    restartMax: "KEI_HEARTBEAT_RESTART_MAX",
+    stableSeconds: "KEI_HEARTBEAT_STABLE_SECONDS",
+    logCount: "KEI_HEARTBEAT_LOG_COUNT",
+    harnessKind: "KEI_HARNESS_KIND",
+    harnessVersion: "KEI_HARNESS_VERSION",
+    deploymentEnv: "KEI_DEPLOYMENT_ENV",
+};
+/** The distribution keeps the kei-proxy name; the repo is kei-connector-runtime. */
+export const DEFAULT_RUNTIME_BINARY_PATH = "kei-proxy";
+/**
+ * Bounds. Interval is clamped; everything else is rejected when out of range
+ * so a typo fails closed instead of silently changing behavior.
+ */
+export const RUNTIME_LINK_BOUNDS = {
+    minIntervalMs: 15_000,
+    maxIntervalMs: 300_000,
+    maxGraceMs: 300_000,
+    minRestartMs: 1_000,
+    maxRestartMs: 3_600_000,
+    minStableResetMs: 1_000,
+    maxStableResetMs: 3_600_000,
+    minStopTimeoutMs: 1_000,
+    maxStopTimeoutMs: 60_000,
+    maxLogCount: 100,
+};
+export const RUNTIME_LINK_CONFIG_ERROR_CODES = [
+    "invalid_value",
+    "out_of_range",
+    "beat_timeout",
+    "harness_kind",
+    "envelope",
+    "legacy_token",
+    "token_missing",
+    "control_plane_url",
+    "binary",
+];
+/**
+ * Invalid RuntimeLink configuration. Carries the offending field and a stable
+ * code, never the offending value, so a misplaced secret cannot leak.
+ */
+export class RuntimeLinkConfigError extends Error {
+    code;
+    field;
+    constructor(code, field) {
+        super(`runtimeLink: invalid config: ${field}: ${code}`);
+        this.code = code;
+        this.field = field;
+        this.name = "RuntimeLinkConfigError";
+    }
+}
+/** The spec defaults with the link disabled. */
+export function defaultRuntimeLinkConfig() {
+    return {
+        enabled: false,
+        binary: { path: DEFAULT_RUNTIME_BINARY_PATH, sha256: "" },
+        controlPlaneUrl: "",
+        token: { env: RUNTIME_LINK_ENV.token },
+        intervalMs: 60_000,
+        beatTimeoutMs: 10_000,
+        graceMs: 15_000,
+        restart: { minMs: 1_000, maxMs: 300_000, stableResetMs: 300_000 },
+        stopTimeoutMs: 10_000,
+        logCount: 3,
+        harness: { kind: "", version: "", deploymentEnv: "" },
+    };
+}
+const VERSION_RE = /^[A-Za-z0-9._+-]{1,64}$/;
+const ENV_NAME_RE = /^[A-Za-z0-9._-]{1,32}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+const REASON_RE = /^[a-z0-9_]{1,64}$/;
+const TIMESTAMP_RE = /^(\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2})(\.\d{1,9})?(Z|[+-]\d{2}:\d{2})$/;
+const ENV_INT_RE = /^[0-9]{1,9}$/;
+/**
+ * Clamp `intervalMs` to [15s, 300s] and validate every other field, throwing
+ * RuntimeLinkConfigError on the first violation. A disabled link (local-only
+ * mode) is valid, but its declared envelope and timings are still checked so
+ * typos fail loudly.
+ */
+export function normalizeRuntimeLinkConfig(cfg) {
+    const b = RUNTIME_LINK_BOUNDS;
+    const h = cfg.harness;
+    if ((h.kind && !isOneOf(HARNESS_KINDS, h.kind)) || (cfg.enabled && !h.kind)) {
+        throw new RuntimeLinkConfigError("harness_kind", "harness.kind");
+    }
+    if (h.version && !VERSION_RE.test(h.version)) {
+        throw new RuntimeLinkConfigError("envelope", "harness.version");
+    }
+    if (h.deploymentEnv && !ENV_NAME_RE.test(h.deploymentEnv)) {
+        throw new RuntimeLinkConfigError("envelope", "harness.deploymentEnv");
+    }
+    if (cfg.enabled) {
+        if (cfg.token.env === RUNTIME_LINK_ENV.legacyToken) {
+            throw new RuntimeLinkConfigError("legacy_token", "token");
+        }
+        if (cfg.token.env !== RUNTIME_LINK_ENV.token) {
+            throw new RuntimeLinkConfigError("invalid_value", "token");
+        }
+        validateControlPlaneUrl(cfg.controlPlaneUrl);
+        if (!cfg.binary.path || cfg.binary.path.includes("\0")) {
+            throw new RuntimeLinkConfigError("binary", "binary.path");
+        }
+        if (!cfg.binary.sha256 && h.deploymentEnv === "prod") {
+            throw new RuntimeLinkConfigError("binary", "binary.sha256");
+        }
+    }
+    if (cfg.binary.sha256 && !SHA256_RE.test(cfg.binary.sha256)) {
+        throw new RuntimeLinkConfigError("binary", "binary.sha256");
+    }
+    const intervalMs = Math.min(Math.max(cfg.intervalMs, b.minIntervalMs), b.maxIntervalMs);
+    if (!(cfg.beatTimeoutMs > 0) || 2 * cfg.beatTimeoutMs >= intervalMs) {
+        throw new RuntimeLinkConfigError("beat_timeout", "beatTimeoutMs");
+    }
+    if (!inRange(cfg.graceMs, 0, b.maxGraceMs)) {
+        throw new RuntimeLinkConfigError("out_of_range", "graceMs");
+    }
+    const r = cfg.restart;
+    if (!(r.minMs >= b.minRestartMs) ||
+        !(r.maxMs <= b.maxRestartMs) ||
+        r.minMs > r.maxMs) {
+        throw new RuntimeLinkConfigError("out_of_range", "restart");
+    }
+    if (!inRange(r.stableResetMs, b.minStableResetMs, b.maxStableResetMs)) {
+        throw new RuntimeLinkConfigError("out_of_range", "restart.stableResetMs");
+    }
+    if (!inRange(cfg.stopTimeoutMs, b.minStopTimeoutMs, b.maxStopTimeoutMs)) {
+        throw new RuntimeLinkConfigError("out_of_range", "stopTimeoutMs");
+    }
+    if (!Number.isInteger(cfg.logCount) ||
+        !inRange(cfg.logCount, 0, b.maxLogCount)) {
+        throw new RuntimeLinkConfigError("out_of_range", "logCount");
+    }
+    return { ...cfg, intervalMs };
+}
+function inRange(v, lo, hi) {
+    return v >= lo && v <= hi;
+}
+function validateControlPlaneUrl(raw) {
+    let ok = false;
+    try {
+        const u = new URL(raw);
+        ok =
+            (u.protocol === "http:" || u.protocol === "https:") &&
+                u.hostname !== "" &&
+                u.username === "" &&
+                u.password === "";
+    }
+    catch {
+        ok = false;
+    }
+    if (!ok)
+        throw new RuntimeLinkConfigError("control_plane_url", "controlPlaneUrl");
+}
+/**
+ * Build a normalized config from the spec §3.2 variables. Non-empty fields of
+ * `harness` override the KEI_HARNESS_* variables. The runtime token is only
+ * checked for presence; its value is never retained.
+ */
+export function runtimeLinkConfigFromEnv(env = process.env, harness = {}) {
+    const E = RUNTIME_LINK_ENV;
+    const get = (key) => (env[key] ?? "").trim();
+    const seconds = (key) => {
+        const raw = get(key);
+        if (raw === "")
+            return undefined;
+        if (!ENV_INT_RE.test(raw))
+            throw new RuntimeLinkConfigError("invalid_value", key);
+        return Number(raw) * 1000;
+    };
+    const cfg = defaultRuntimeLinkConfig();
+    cfg.intervalMs = seconds(E.interval) ?? cfg.intervalMs;
+    cfg.beatTimeoutMs = seconds(E.timeout) ?? cfg.beatTimeoutMs;
+    cfg.restart.minMs = seconds(E.restartMin) ?? cfg.restart.minMs;
+    cfg.restart.maxMs = seconds(E.restartMax) ?? cfg.restart.maxMs;
+    cfg.restart.stableResetMs =
+        seconds(E.stableSeconds) ?? cfg.restart.stableResetMs;
+    const logCount = get(E.logCount);
+    if (logCount !== "") {
+        if (!ENV_INT_RE.test(logCount))
+            throw new RuntimeLinkConfigError("invalid_value", E.logCount);
+        cfg.logCount = Number(logCount);
+    }
+    const hasToken = get(E.token) !== "";
+    if (!hasToken && get(E.legacyToken) !== "") {
+        throw new RuntimeLinkConfigError("legacy_token", E.legacyToken);
+    }
+    cfg.enabled = hasToken;
+    const enabled = get(E.enabled).toLowerCase();
+    if (enabled !== "") {
+        if (enabled === "true" || enabled === "1") {
+            if (!hasToken)
+                throw new RuntimeLinkConfigError("token_missing", E.token);
+            cfg.enabled = true;
+        }
+        else if (enabled === "false" || enabled === "0") {
+            cfg.enabled = false;
+        }
+        else {
+            throw new RuntimeLinkConfigError("invalid_value", E.enabled);
+        }
+    }
+    cfg.controlPlaneUrl = get(E.controlPlaneUrl);
+    cfg.binary = {
+        path: get(E.proxyPath) || DEFAULT_RUNTIME_BINARY_PATH,
+        sha256: get(E.proxySha),
+    };
+    cfg.harness = {
+        kind: harness.kind || get(E.harnessKind),
+        version: harness.version || get(E.harnessVersion),
+        deploymentEnv: harness.deploymentEnv || get(E.deploymentEnv),
+    };
+    return normalizeRuntimeLinkConfig(cfg);
+}
+// ---------------------------------------------------------------------------
+// Backoff and cancellation
+// ---------------------------------------------------------------------------
+const MAX_JITTER_SAMPLE = 1 - Number.EPSILON / 2;
+/**
+ * Full-jitter restart delay for attempt n (0-based):
+ * `floor(r × min(maxMs, minMs × 2^n))`. `r` is clamped to [0, 1); negative
+ * attempts count as 0.
+ */
+export function backoffDelayMs(backoff, attempt, r) {
+    const n = Math.min(Math.max(Math.trunc(attempt), 0), 30);
+    const capMs = Math.min(backoff.maxMs, backoff.minMs * 2 ** n);
+    const sample = Math.min(Math.max(r, 0), MAX_JITTER_SAMPLE);
+    return Math.floor(sample * capMs);
+}
+/**
+ * Sleep for the jittered delay, or reject with the signal's abort reason as
+ * soon as `signal` aborts, so a stop during backoff never waits out the delay.
+ */
+export function waitBackoff(backoff, attempt, options = {}) {
+    const { signal, random = Math.random } = options;
+    return new Promise((resolve, reject) => {
+        const abortReason = () => signal?.reason ?? new Error("aborted");
+        if (signal?.aborted) {
+            reject(abortReason());
+            return;
+        }
+        const onAbort = () => {
+            clearTimeout(timer);
+            reject(abortReason());
+        };
+        const timer = setTimeout(() => {
+            signal?.removeEventListener("abort", onAbort);
+            resolve();
+        }, backoffDelayMs(backoff, attempt, random()));
+        signal?.addEventListener("abort", onAbort, { once: true });
+    });
+}
+/** A child line the SDK must drop and count. */
+export class ChildLineError extends Error {
+    kind;
+    constructor(kind, detail) {
+        super(`runtimeLink: child line ${kind}: ${detail}`);
+        this.kind = kind;
+        this.name = "ChildLineError";
+    }
+}
+const MAX_SEQ = Number.MAX_SAFE_INTEGER;
+const MAX_LATENCY_MS = 3_600_000;
+const MAX_NEXT_IN_MS = 3_600_000;
+class FieldReader {
+    raw;
+    constructor(raw) {
+        this.raw = raw;
+    }
+    text(key, required) {
+        if (!Object.hasOwn(this.raw, key)) {
+            if (required)
+                throw new ChildLineError("malformed", key);
+            return "";
+        }
+        const v = this.raw[key];
+        if (typeof v !== "string")
+            throw new ChildLineError("malformed", key);
+        return v;
+    }
+    id(key, required) {
+        const v = this.text(key, required);
+        if ((v !== "" || required) && !ID_RE.test(v))
+            throw new ChildLineError("malformed", key);
+        return v;
+    }
+    timestamp(key) {
+        const v = this.text(key, true);
+        if (!TIMESTAMP_RE.test(v))
+            throw new ChildLineError("malformed", key);
+        return v;
+    }
+    integer(key, required, lo, hi) {
+        if (!Object.hasOwn(this.raw, key)) {
+            if (required)
+                throw new ChildLineError("malformed", key);
+            return 0;
+        }
+        const v = this.raw[key];
+        if (typeof v !== "number" || !Number.isSafeInteger(v) || v < lo || v > hi) {
+            throw new ChildLineError("malformed", key);
+        }
+        return v;
+    }
+}
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+/**
+ * Parse one line of child stdout (a trailing "\n" / "\r\n" is ignored). Only
+ * allowlisted fields survive; payloads, results, reasoning, tokens, or any
+ * other key the runtime might emit are dropped. Throws ChildLineError for
+ * lines the SDK must drop and count.
+ */
+export function parseChildLine(line) {
+    let text = typeof line === "string" ? line : decoder.decode(line);
+    if (text.endsWith("\n"))
+        text = text.slice(0, -1);
+    if (text.endsWith("\r"))
+        text = text.slice(0, -1);
+    if (encoder.encode(text).length > MAX_CHILD_LINE_BYTES) {
+        throw new ChildLineError("line_too_long", "line");
+    }
+    let raw;
+    try {
+        raw = JSON.parse(text);
+    }
+    catch {
+        throw new ChildLineError("malformed", "not json");
+    }
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new ChildLineError("malformed", "not an object");
+    }
+    const obj = raw;
+    if (obj.v !== RUNTIME_LINK_CONTRACT_VERSION) {
+        throw new ChildLineError("contract_mismatch", "v");
+    }
+    if (typeof obj.event !== "string")
+        throw new ChildLineError("malformed", "event");
+    const f = new FieldReader(obj);
+    switch (obj.event) {
+        case "identity":
+            return {
+                kind: "identity",
+                identity: {
+                    runId: f.id("run_id", true),
+                    installationId: f.id("installation_id", true),
+                    orgId: f.id("org_id", true),
+                    workspaceId: f.id("workspace_id", false),
+                    platform: f.id("platform", false),
+                    status: f.id("status", false),
+                    bindingStatus: f.id("binding_status", false),
+                    runtimeVersion: f.id("runtime_version", false),
+                },
+            };
+        case "beat": {
+            const runId = f.id("run_id", true);
+            const seq = f.integer("seq", false, 0, MAX_SEQ);
+            const at = f.timestamp("at");
+            const outcome = f.text("outcome", true);
+            const latencyMs = f.integer("latency_ms", false, 0, MAX_LATENCY_MS);
+            const nextInMs = f.integer("next_in_ms", false, 0, MAX_NEXT_IN_MS);
+            const httpStatus = f.integer("http_status", false, 0, 599);
+            if (httpStatus > 0 && httpStatus < 100)
+                throw new ChildLineError("malformed", "http_status");
+            if (!isOneOf(BEAT_OUTCOMES, outcome))
+                throw new ChildLineError("contract_mismatch", "outcome");
+            return {
+                kind: "beat",
+                beat: { runId, seq, at, outcome, httpStatus, latencyMs, nextInMs },
+            };
+        }
+        case "terminal": {
+            const runId = f.id("run_id", true);
+            const reason = f.text("reason", true);
+            if (!REASON_RE.test(reason))
+                throw new ChildLineError("malformed", "reason");
+            return { kind: "terminal", terminal: { runId, reason } };
+        }
+        default:
+            return { kind: "ignored" };
+    }
+}
+// ---------------------------------------------------------------------------
+// Redacted lifecycle events (spec §5.3)
+// ---------------------------------------------------------------------------
+/** A lifecycle event has a value outside its closed set or bounds. */
+export class InvalidLinkEventError extends Error {
+    constructor(detail) {
+        super(`runtimeLink: invalid lifecycle event: ${detail}`);
+        this.name = "InvalidLinkEventError";
+    }
+}
+function isCount(v) {
+    return typeof v === "number" && Number.isSafeInteger(v) && v >= 0;
+}
+/** Throws InvalidLinkEventError unless every closed set and bound holds. */
+export function validateLinkEvent(ev) {
+    const h = ev.harness;
+    const ok = isOneOf(LIFECYCLE_EVENT_NAMES, ev.name) &&
+        isOneOf(LINK_STATES, ev.state) &&
+        (ev.reason === "" || isOneOf(FAILURE_CLASSES, ev.reason)) &&
+        ev.at instanceof Date &&
+        !Number.isNaN(ev.at.getTime()) &&
+        (ev.runId === "" || ID_RE.test(ev.runId)) &&
+        ID_RE.test(ev.sdkInstanceId) &&
+        isOneOf(HARNESS_KINDS, h.kind) &&
+        isOneOf(SDK_LANGS, h.sdkLang) &&
+        (h.version === "" || VERSION_RE.test(h.version)) &&
+        (h.deploymentEnv === "" || ENV_NAME_RE.test(h.deploymentEnv)) &&
+        (h.sdkVersion === "" || VERSION_RE.test(h.sdkVersion)) &&
+        isCount(ev.seq) &&
+        isCount(ev.restarts) &&
+        isCount(ev.consecutiveFails);
+    if (!ok)
+        throw new InvalidLinkEventError("value outside contract");
+    return ev;
+}
+function str(v, fallback = "") {
+    if (v === undefined)
+        return fallback;
+    if (typeof v !== "string")
+        throw new InvalidLinkEventError("expected string");
+    return v;
+}
+function parseEventTimestamp(v) {
+    const m = typeof v === "string" ? TIMESTAMP_RE.exec(v) : null;
+    if (!m)
+        throw new InvalidLinkEventError("at");
+    const fraction = (m[2] ?? ".000").slice(0, 4);
+    return new Date(`${m[1]}${fraction}${m[3]}`);
+}
+/** Build an event from allowlisted wire keys only; everything else is dropped. */
+export function linkEventFromWire(raw) {
+    if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+        throw new InvalidLinkEventError("not an object");
+    }
+    const o = raw;
+    const hRaw = o.harness ?? {};
+    if (hRaw === null || typeof hRaw !== "object" || Array.isArray(hRaw)) {
+        throw new InvalidLinkEventError("harness");
+    }
+    const h = hRaw;
+    return validateLinkEvent({
+        name: str(o.name),
+        at: parseEventTimestamp(o.at),
+        state: str(o.state),
+        reason: str(o.reason),
+        runId: str(o.run_id),
+        seq: (o.seq ?? 0),
+        sdkInstanceId: str(o.sdk_instance_id),
+        harness: {
+            kind: str(h.kind),
+            version: str(h.version),
+            deploymentEnv: str(h.deployment_env),
+            sdkLang: str(h.sdk_lang),
+            sdkVersion: str(h.sdk_version),
+        },
+        restarts: (o.restarts ?? 0),
+        consecutiveFails: (o.consecutive_fails ?? 0),
+    });
+}
+/** Validate and emit exactly the allowlisted keys; `at` is UTC with millisecond precision. */
+export function linkEventToWire(ev) {
+    validateLinkEvent(ev);
+    const h = ev.harness;
+    return {
+        name: ev.name,
+        at: ev.at.toISOString(),
+        state: ev.state,
+        reason: ev.reason,
+        run_id: ev.runId,
+        seq: ev.seq,
+        sdk_instance_id: ev.sdkInstanceId,
+        harness: {
+            kind: h.kind,
+            version: h.version,
+            deployment_env: h.deploymentEnv,
+            sdk_lang: h.sdkLang,
+            sdk_version: h.sdkVersion,
+        },
+        restarts: ev.restarts,
+        consecutive_fails: ev.consecutiveFails,
+    };
+}

package/package.json

@@ -1,18 +1,24 @@
 {
   "name": "@haikeilabs/agentware",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Agent middleware and tooling for LLM tool calling",
   "repository": {
     "type": "git",
-    "url": "https://github.com/HaikeiLabs/Agentware.git",
+    "url": "git+https://github.com/HaikeiLabs/agentware.git",
     "directory": "typescript"
   },
-  "homepage": "https://github.com/HaikeiLabs/Agentware#readme",
+  "homepage": "https://github.com/HaikeiLabs/agentware#readme",
   "bugs": {
-    "url": "https://github.com/HaikeiLabs/Agentware/issues"
+    "url": "https://github.com/HaikeiLabs/agentware/issues"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
   "type": "module",
   "files": [
     "dist",
@@ -21,6 +27,7 @@
   "scripts": {
     "prepack": "npm run build",
     "build": "tsc",
+    "check:package": "node scripts/check-package.mjs",
     "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
     "lint": "eslint src --ext .ts",
     "format": "prettier --write \"src/**/*.ts\""