@kindgi/agents 0.0.0-bootstrap.0 → 0.1.1

package/dist/streaming.d.ts

@@ -0,0 +1,118 @@
+import type { EvaluationResult } from '@kindgi/guardrails';
+import type { Semver } from '@kindgi/types';
+import type { AgentId, ConversationId, ConversationMessage, RetrievedFact } from './types.js';
+/**
+ * Discriminated union of every event a turn emits during execution.
+ * Callers wire `bindings.onEvent` to their transport (SSE, WebSocket,
+ * background job queue, or nothing at all).
+ *
+ * Order is deterministic per turn: `turn.started` first, `turn.completed`
+ * or `turn.failed` last. Intermediate events fire in the order the
+ * corresponding action happens.
+ */
+export type TurnEvent = TurnStartedEvent | RetrievalCompletedEvent | ModelCallStartedEvent | ModelCallCompletedEvent | ToolStartedEvent | ToolCompletedEvent | ToolFailedEvent | AgentMessageEvent | GuardrailViolatedEvent | TurnCompletedEvent | TurnFailedEvent;
+export interface TurnStartedEvent {
+    readonly kind: 'turn.started';
+    readonly conversationId: ConversationId;
+    readonly turnNumber: number;
+    readonly agentId: AgentId;
+    readonly agentVersion: Semver;
+    readonly userMessage: string;
+}
+export interface RetrievalCompletedEvent {
+    readonly kind: 'retrieval.completed';
+    readonly count: number;
+    /** Fact ids retrieved this turn. Empty when no intents declared. */
+    readonly factIds: readonly string[];
+}
+export interface ModelCallStartedEvent {
+    readonly kind: 'model.call.started';
+    readonly step: number;
+    readonly providerId: string;
+    readonly model: string;
+}
+export interface ModelCallCompletedEvent {
+    readonly kind: 'model.call.completed';
+    readonly step: number;
+    readonly finishReason: 'stop' | 'length' | 'tool-use' | 'content-filter' | 'error';
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly costUsd: number;
+    readonly durationMs: number;
+}
+export interface ToolStartedEvent {
+    readonly kind: 'tool.started';
+    readonly step: number;
+    readonly toolId: string;
+    /**
+     * The exact version dispatched (picked at run start by `resolve(id,
+     * range)` on the tenant's tool registry) so subscribers can
+     * distinguish `kb-search@1.2.3` from `kb-search@2.0.0`.
+     */
+    readonly toolVersion: string;
+    /** The semver range the agent binding declared for this tool. */
+    readonly toolVersionRange: string;
+    readonly invocationId: string;
+    readonly arguments: Readonly<Record<string, unknown>>;
+}
+export interface ToolCompletedEvent {
+    readonly kind: 'tool.completed';
+    readonly step: number;
+    readonly toolId: string;
+    readonly toolVersion: string;
+    readonly toolVersionRange: string;
+    readonly invocationId: string;
+    readonly output: unknown;
+    readonly durationMs: number;
+}
+export interface ToolFailedEvent {
+    readonly kind: 'tool.failed';
+    readonly step: number;
+    readonly toolId: string;
+    readonly invocationId: string;
+    readonly error: {
+        readonly code: string;
+        readonly message: string;
+    };
+}
+export interface AgentMessageEvent {
+    readonly kind: 'agent.message';
+    readonly step: number;
+    /** True when this is the final message that closes the turn. */
+    readonly isFinal: boolean;
+    readonly message: ConversationMessage;
+}
+export interface GuardrailViolatedEvent {
+    readonly kind: 'guardrail.violated';
+    readonly action: EvaluationResult['action'];
+    readonly severity: EvaluationResult['severity'];
+    readonly guardrailId: string;
+    readonly reason?: string;
+}
+export interface TurnCompletedEvent {
+    readonly kind: 'turn.completed';
+    readonly conversationId: ConversationId;
+    readonly turnNumber: number;
+    readonly response: ConversationMessage;
+    readonly retrieved: readonly RetrievedFact[];
+    readonly durationMs: number;
+    readonly totalCostUsd: number;
+}
+export interface TurnFailedEvent {
+    readonly kind: 'turn.failed';
+    readonly conversationId: ConversationId;
+    readonly errorCode: string;
+    readonly message: string;
+}
+/**
+ * Adapter shape callers plug into `bindings.onEvent`. Sync + async both
+ * supported. Errors thrown inside the handler are caught by the runtime
+ * — a broken telemetry sink never breaks the turn.
+ */
+export type OnTurnEvent = (event: TurnEvent) => void | Promise<void>;
+/**
+ * Safe emit wrapper. Called by the turn's handlers at each observation
+ * point; catches handler throws so a broken sink can't break the run.
+ */
+export declare function emitTurnEvent(onEvent: OnTurnEvent | undefined, event: TurnEvent): Promise<void>;
+//# sourceMappingURL=streaming.d.ts.map

package/dist/streaming.d.ts.map

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

package/dist/streaming.js

@@ -0,0 +1,17 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Safe emit wrapper. Called by the turn's handlers at each observation
+ * point; catches handler throws so a broken sink can't break the run.
+ */
+export async function emitTurnEvent(onEvent, event) {
+    if (onEvent === undefined)
+        return;
+    try {
+        await onEvent(event);
+    }
+    catch {
+        // Intentionally swallow — telemetry sinks must not affect run outcome.
+    }
+}
+//# sourceMappingURL=streaming.js.map

package/dist/streaming.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"streaming.js","sourceRoot":"","sources":["../src/streaming.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAyIjC;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAgC,EAChC,KAAgB;IAEhB,IAAI,OAAO,KAAK,SAAS;QAAE,OAAO;IAClC,IAAI,CAAC;QACH,MAAM,OAAO,CAAC,KAAK,CAAC,CAAC;IACvB,CAAC;IAAC,MAAM,CAAC;QACP,uEAAuE;IACzE,CAAC;AACH,CAAC"}

package/dist/tenant-policy.d.ts

@@ -0,0 +1,16 @@
+import type { TenantPolicy } from '@kindgi/capabilities';
+/**
+ * Combine two tenant policies (the statically bound one and one derived
+ * from the policy registry) so the result is at least as strict as each:
+ *
+ *   - allow lists (`providers.allow`, `models.allow`, `regionAllow`) →
+ *     INTERSECTION when both set one; a list set on one side only applies
+ *     as-is. An empty result allows nothing (the router fails closed).
+ *   - deny lists (`providers.deny`, `models.deny`) → UNION.
+ *   - `maxCostPerCallUsd` / `maxTokensPerCall` → the smaller value.
+ *
+ * Returns `undefined` when both are undefined (routing runs with no
+ * tenant policy).
+ */
+export declare function mergeTenantPolicies(a: TenantPolicy | undefined, b: TenantPolicy | undefined): TenantPolicy | undefined;
+//# sourceMappingURL=tenant-policy.d.ts.map

package/dist/tenant-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tenant-policy.d.ts","sourceRoot":"","sources":["../src/tenant-policy.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAIzD;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CACjC,CAAC,EAAE,YAAY,GAAG,SAAS,EAC3B,CAAC,EAAE,YAAY,GAAG,SAAS,GAC1B,YAAY,GAAG,SAAS,CAiB1B"}

package/dist/tenant-policy.js

@@ -0,0 +1,77 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * Combine two tenant policies (the statically bound one and one derived
+ * from the policy registry) so the result is at least as strict as each:
+ *
+ *   - allow lists (`providers.allow`, `models.allow`, `regionAllow`) →
+ *     INTERSECTION when both set one; a list set on one side only applies
+ *     as-is. An empty result allows nothing (the router fails closed).
+ *   - deny lists (`providers.deny`, `models.deny`) → UNION.
+ *   - `maxCostPerCallUsd` / `maxTokensPerCall` → the smaller value.
+ *
+ * Returns `undefined` when both are undefined (routing runs with no
+ * tenant policy).
+ */
+export function mergeTenantPolicies(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    const providers = mergeAllowDeny(a.providers, b.providers);
+    const models = mergeAllowDeny(a.models, b.models);
+    const regionAllow = intersectStrings(a.regionAllow, b.regionAllow);
+    const maxCost = minDefined(a.maxCostPerCallUsd, b.maxCostPerCallUsd);
+    const maxTokens = minDefined(a.maxTokensPerCall, b.maxTokensPerCall);
+    const merged = {
+        tenantId: a.tenantId,
+    };
+    if (providers !== undefined)
+        merged.providers = providers;
+    if (models !== undefined)
+        merged.models = models;
+    if (regionAllow !== undefined)
+        merged.regionAllow = regionAllow;
+    if (maxCost !== undefined)
+        merged.maxCostPerCallUsd = maxCost;
+    if (maxTokens !== undefined)
+        merged.maxTokensPerCall = maxTokens;
+    return merged;
+}
+function mergeAllowDeny(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    const allow = intersectStrings(a.allow, b.allow);
+    const deny = unionStrings(a.deny, b.deny);
+    if (allow === undefined && deny === undefined)
+        return undefined;
+    return {
+        ...(allow !== undefined && { allow }),
+        ...(deny !== undefined && { deny }),
+    };
+}
+function intersectStrings(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    const inB = new Set(b);
+    return Array.from(new Set(a)).filter((v) => inB.has(v));
+}
+function unionStrings(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return Array.from(new Set([...a, ...b]));
+}
+function minDefined(a, b) {
+    if (a === undefined)
+        return b;
+    if (b === undefined)
+        return a;
+    return Math.min(a, b);
+}
+//# sourceMappingURL=tenant-policy.js.map

package/dist/tenant-policy.js.map

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