@kindgi/agents 0.0.0-bootstrap.0 → 0.1.1

package/dist/types.d.ts

@@ -0,0 +1,435 @@
+import type { Capability } from '@kindgi/capabilities';
+import type { Fact, MemoryScope } from '@kindgi/memory';
+import type { ToolErrorsSpec, ToolHitlMode, ToolHitlRule } from '@kindgi/policy-contract';
+import type { Brand, ConversationId, Semver, TenantId, Timestamp } from '@kindgi/types';
+/**
+ * Branded agent id. Convention: dotted namespace under the tenant's
+ * pack — e.g. `acme.citation-verifier`, `acme.drafting`.
+ */
+export type AgentId = Brand<string, 'AgentId'>;
+/**
+ * `ConversationId` lives in `@kindgi/types` (the single source of
+ * truth for branded identifiers) and is re-exported here for
+ * convenience; `@kindgi/types` (or `@kindgi/sdk/types`) is the
+ * canonical import.
+ */
+export type { ConversationId };
+/**
+ * A single message inside a conversation. Persisted as a `Fact` in
+ * the memory subsystem scoped to the conversation, so it inherits
+ * retention + provenance + supersession from the fact substrate.
+ *
+ * The `role` discriminates who authored the message:
+ *   - `user`      — end-user input to the agent.
+ *   - `agent`     — the agent's assistant-role response.
+ *   - `tool`      — a tool-call result (the tool's own output).
+ *   - `system`    — a system-authored instruction (rare; e.g. HITL
+ *                   intervention, out-of-band context injection).
+ */
+export type MessageRole = 'user' | 'agent' | 'tool' | 'system';
+export interface ConversationMessage {
+    /**
+     * Monotonic index within the conversation. Assigned by the writer.
+     * Combined with `conversationId` this gives a stable ordering
+     * independent of clock skew.
+     */
+    readonly sequence: number;
+    readonly role: MessageRole;
+    /**
+     * Free-form text OR structured content. `string` is the common case
+     * (a chat message); `Record<string, unknown>` supports tool-result
+     * shapes and multi-modal payloads without a v2 bump.
+     */
+    readonly content: string | Readonly<Record<string, unknown>>;
+    /**
+     * For `role: 'tool'` messages: the tool id and the invocation id
+     * that produced this output. Enables provenance edges from the
+     * originating agent turn to the tool's result.
+     */
+    readonly toolCall?: {
+        readonly toolId: string;
+        readonly invocationId: string;
+    };
+    /**
+     * Attribution — user id, agent id, tool id, or system source. The
+     * literal role-vs-actor split lets the same agent produce many
+     * messages while the reviewer sees who was actually authoring.
+     */
+    readonly actor?: string;
+    readonly createdAt: Timestamp;
+}
+/**
+ * A named, typed input to an agent's instructions template. Every
+ * `{{ var }}` referenced in `instructions` must correspond to either a
+ * declared `PromptParameter` OR a framework-supplied auto-variable
+ * (see `AUTO_INJECTED_VARS`).
+ *
+ * Types are declared so a UI can build a proper form for the caller
+ * ("enter firm name", "pick jurisdiction").
+ */
+export interface PromptParameter {
+    readonly name: string;
+    readonly description?: string;
+    readonly type: 'string' | 'number' | 'boolean' | 'date';
+    /** Default true — omit to require the caller supply a value. */
+    readonly required?: boolean;
+    /** Default value used when the caller omits this parameter. */
+    readonly default?: string | number | boolean;
+}
+/**
+ * Declarative statement of what the agent retrieves before each turn.
+ * Distinct from tool invocation — retrieval is background reading the
+ * agent does silently to ground its response.
+ *
+ * Scope options:
+ *   - `same-conversation`: prior messages in this conversation only.
+ *   - `same-project`:      facts under the project (from Scope.projectId).
+ *   - `tenant`:            any tenant-scoped fact of the declared type.
+ */
+export interface RetrievalIntent {
+    readonly types: readonly string[];
+    readonly scope: 'same-conversation' | 'same-project' | 'tenant';
+    /** Cap on facts loaded per turn to keep the prompt small. Default 10. */
+    readonly limit?: number;
+    /** If `keyword` or `semantic`, biases which retrieval mode is used. */
+    readonly mode?: 'keyword' | 'semantic' | 'both';
+}
+/**
+ * Typed reference to a tool. Every agent tool binding is `{ id, version }`
+ * — no bare-id "latest" shortcut. `version` is a semver **range**
+ * (npm-style grammar), resolved at run start against the tenant's tool
+ * registry via `semver.maxSatisfying`.
+ *
+ * Range examples:
+ *   - `'1.2.3'`        — exact pin (matches only 1.2.3)
+ *   - `'^1.2.3'`       — compatible-updates (>=1.2.3 <2.0.0)
+ *   - `'~1.2.3'`       — patch-updates-only (>=1.2.3 <1.3.0)
+ *   - `'>=1.0.0 <2.0.0'` — explicit range
+ */
+export interface ToolRef {
+    readonly id: string;
+    readonly version: string;
+}
+/**
+ * Per-agent behavior for multi-turn conversations. The agent chooses:
+ *   - How many prior messages to load (`historyLimit`; unset = all).
+ *   - Whether to auto-close a conversation after a period of inactivity
+ *     (`autoCloseAfterInactiveSeconds` — checked at read time; unset =
+ *     never auto-close).
+ *   - A turn count after which each new turn waits for HITL approval
+ *     before it runs (`hitlAfterTurns`; `hitl.afterTurns` takes
+ *     precedence when both are set).
+ */
+export interface ConversationPolicy {
+    readonly historyLimit?: number;
+    readonly autoCloseAfterInactiveSeconds?: number;
+    readonly hitlAfterTurns?: number;
+    /**
+     * HITL policy: the session gate (`afterTurns`) and the tool-level
+     * gates that decide whether each tool call inside a turn waits for
+     * review before dispatch. Absent = no tool gates.
+     */
+    readonly hitl?: ConversationHitlPolicy;
+}
+/**
+ * Tool-level HITL mode.
+ *
+ * - `never_ask`   — dispatch straight through, no gate. Read-only tools
+ *   (`Tool.mutating: false`) get this default.
+ * - `ask_on_first_use` — on the first call to `(toolId, hashOfArgs)`
+ *   within a conversation, park + require approval. Approved decisions
+ *   cache on the conversation so subsequent identical calls dispatch
+ *   without re-parking. Mutating tools default to this.
+ * - `always_ask`  — park + require approval on EVERY invocation. No
+ *   caching. Highest friction; used for external-effect actions
+ *   (email/payment/deploy) where every occurrence is a real event.
+ */
+/**
+ * A tool's gate (`never_ask` | `ask_on_first_use` | `always_ask`), and a
+ * per-tool rule — a mode plus the reviewer role its approvals need
+ * (deployments that route "always-ask-financial-tools" through senior
+ * reviewers use the rule; a mode alone routes through the agent's
+ * `defaultReviewerRole`). Shared with the tenant `hitl` policy, so they
+ * live in `@kindgi/policy-contract`.
+ */
+export type { ToolHitlMode, ToolHitlRule } from '@kindgi/policy-contract';
+export interface ConversationHitlPolicy {
+    /**
+     * Session-turn count gate: once the conversation has this many
+     * completed turns, each new turn waits for HITL approval before it
+     * runs. Same meaning as `ConversationPolicy.hitlAfterTurns`; when both
+     * are set, `hitl.afterTurns` wins. Absent in both = no session gate.
+     */
+    readonly afterTurns?: number;
+    /**
+     * Tool-level policy. Applies to every tool call inside the turn
+     * unless the `tools.overrides` map has a specific rule.
+     */
+    readonly tools?: {
+        /**
+         * Mode for every tool without an entry in `overrides`. When absent,
+         * the framework falls back to a per-tool default: read-only tools
+         * (`mutating: false`) → `never_ask`, other tools →
+         * `ask_on_first_use`.
+         */
+        readonly default?: ToolHitlMode;
+        /**
+         * Explicit overrides keyed by ToolId. A string value is shorthand
+         * for `{ mode: <string> }` — the required-role stays the agent
+         * default.
+         */
+        readonly overrides?: Readonly<Record<string, ToolHitlMode | ToolHitlRule>>;
+    };
+    /**
+     * Reviewer role assigned to approvals materialized by tool + session
+     * gates. Absent = `'standard'`.
+     */
+    readonly defaultReviewerRole?: 'standard' | 'senior' | 'admin';
+    /**
+     * Timeout the approval carries at enqueue time. Absent = the
+     * framework default (24h). A tenant policy's `maxTimeoutMs` caps it
+     * (see `resolveEffectiveHitlPolicy`).
+     */
+    readonly timeoutMs?: number;
+}
+/**
+ * Budgets guard a single agent turn. Every field is optional; unset
+ * fields take the defaults below or have no cap. Steps and cost are
+ * enforced by the turn's `budget-check` step; wall-clock time by a
+ * timer in `invokeAgent`.
+ */
+export interface TurnBudget {
+    /** Maximum model→tool→model iterations per turn. Default 8. */
+    readonly maxSteps?: number;
+    /** Maximum USD spend per turn, summed over the turn's model calls. */
+    readonly maxCostUsd?: number;
+    /** Wall-clock cap in ms. Default 120_000 (2 min). */
+    readonly maxWallMs?: number;
+}
+/**
+ * A typed result for an agent turn: the agent's final answer must be
+ * JSON matching `schema`. When it doesn't parse or doesn't match, the
+ * turn tells the model what was wrong and asks again, up to
+ * `maxRepairs` times; after that the turn fails with
+ * `output-schema-violation`. The parsed value is
+ * `AgentTurnResult.output`.
+ */
+export interface AgentOutputSpec {
+    /** JSON Schema (draft 2020-12) the final answer must match. */
+    readonly schema: Readonly<Record<string, unknown>>;
+    /** A name for the output (shown to the model and in errors). Default `'output'`. */
+    readonly name?: string;
+    /** How many times the model is asked to repair an invalid answer. Default 1. */
+    readonly maxRepairs?: number;
+}
+/**
+ * An agent definition. Declarative: no runtime state, no closures. The
+ * same definition can be serialized, versioned, and reloaded — every
+ * field is either a primitive or a reference to a registered
+ * substrate object (tool id, guardrail id, capability declaration).
+ *
+ * The `version` field is authoritative for the agent's identity — an
+ * agent at a different version is a different agent for provenance
+ * and audit purposes. Callers pin agents by `{ id, version }` the way
+ * kernel runs pin flows.
+ */
+export interface Agent {
+    /**
+     * Globally-unique agent identifier. Convention:
+     * `<pack-id>.<agent-name>` (kebab-case, dot-namespaced). See the
+     * `AgentId` brand for the naming rule.
+     */
+    readonly id: AgentId;
+    /**
+     * Semver — REQUIRED. Distinct from tools' `version` in that agents
+     * are versioned per-tenant (rotate + rollout independently of tool
+     * versions). `agent_conversations.agentVersion` pins each thread to
+     * a specific version; resume-across-version bumps rejects with
+     * `agent-version-mismatch`.
+     */
+    readonly version: Semver;
+    /**
+     * Human-readable name shown in UI. Doesn't affect execution.
+     */
+    readonly name: string;
+    /**
+     * Optional prose describing what the agent does. Shows up in the
+     * agent catalog and in provenance metadata.
+     */
+    readonly description?: string;
+    /**
+     * System prompt rendered at the top of every turn. LiquidJS template
+     * syntax: `{{ variable }}` for substitution, `{% if %}` / `{% for %}`
+     * for control flow, filters via `{{ value | filter }}`. Every
+     * referenced variable must be either a declared `PromptParameter`
+     * or a framework-supplied auto-var (see `AUTO_INJECTED_VARS`).
+     *
+     * Templates are rendered with `strictVariables: true` — an
+     * unresolved reference fails the turn at invoke time
+     * (`model-invocation-failed` whose `cause` is the `missing-parameter`
+     * render error), never a silent empty string.
+     */
+    readonly instructions: string;
+    /**
+     * Typed parameters the caller supplies at invoke time. The UI reads
+     * this to build a "configure agent" form; the runtime validates each
+     * required parameter is provided before the model call.
+     *
+     * Framework auto-vars (`today`, `now`, `agent.*`, `conversation.*`)
+     * do not need to be declared here — they're supplied by the runtime.
+     */
+    readonly parameters?: readonly PromptParameter[];
+    /**
+     * Capability declarations the agent needs at runtime. Each entry is
+     * a separate resource-kind request (LLM inference, embedding, ...,
+     * distinguished by `Capability.kind`). The router picks providers at
+     * turn time; the agent definition doesn't hard-bind.
+     *
+     * The agent turn routes the first entry to pick its model; further
+     * entries are part of the definition but are not routed by the turn.
+     */
+    readonly capabilities: readonly Capability[];
+    /**
+     * Typed tool references. Each entry declares the tool id AND the
+     * semver range (or exact pin) the agent expects to invoke — the
+     * dispatch resolver uses `semver.maxSatisfying` to pick the highest
+     * active version matching the range at run start. Follows the
+     * "docker-tag pin vs latest" discipline npm/docker take: no implicit
+     * `:latest`, ever.
+     *
+     * `version` is a semver **range** in the wire shape:
+     * `'1.2.3'` = exact pin, `'^1.2.3'` = compatible-updates, `'~1.2.3'`
+     * = patch-updates-only, `'>=1.0.0 <2.0.0'` = explicit range. Full
+     * npm-compatible grammar (grammar handled by the `semver` library
+     * in the resolver — validation of the range shape lives there).
+     *
+     * An empty list means the agent is chat-only.
+     */
+    readonly tools: readonly ToolRef[];
+    /**
+     * Fact-retrieval intents. Zero or more; each triggers an independent
+     * retrieval pass before the model call.
+     */
+    readonly retrieval: readonly RetrievalIntent[];
+    /**
+     * Guardrail ids the agent is subject to. Resolved at turn start
+     * against the guardrail definitions bound for the run
+     * (`GuardrailsBindings.guardrails`, evaluated through its `checks`
+     * registry from `@kindgi/guardrails`); an unknown id fails the turn
+     * with `unresolved-guardrail`. Evaluated once per turn, on the final
+     * response before it is stored.
+     */
+    readonly guardrails: readonly string[];
+    /**
+     * Preferred model provider by id. Soft hint — the router prefers
+     * this provider when it satisfies the agent's `capabilities.needs`,
+     * falling back to normal capability-based selection when the
+     * preferred provider is unregistered or filtered out by tenant
+     * policy. Enables A/B'ing agents across providers without
+     * churning provider registrations: register several, pin the agent
+     * to the one you want to test.
+     *
+     * The value is a `ProviderMetadata.id` string (e.g. `'anthropic'`).
+     * Use in combination with `preferredModel` for `(provider, model)`
+     * tuple pinning. Unset = capability-match only.
+     */
+    readonly preferredProvider?: string;
+    /**
+     * Preferred model NAME within the selected provider. Soft hint —
+     * the router prefers `(provider, model)` tuples matching this
+     * name, falling back to capability-based ranking when no tuple
+     * matches. Combined semantics with `preferredProvider`:
+     *
+     *   - Both set → promote the exact `(provider, model)` tuple.
+     *   - Only `preferredModel` set → promote any provider exposing
+     *     that model.
+     *   - Only `preferredProvider` set → any model of that provider is
+     *     promoted.
+     *
+     * The value is a `ModelInfo.name` string (e.g. `'claude-sonnet-4-6'`).
+     * Enables model-level A/B'ing under one connection: register
+     * Anthropic once with `models: [sonnet, opus, haiku]`, then pin
+     * per-agent.
+     */
+    readonly preferredModel?: string;
+    /**
+     * Multi-turn behavior. Optional — when unset, each turn loads the
+     * full conversation history and no HITL gates apply.
+     */
+    readonly conversationPolicy?: ConversationPolicy;
+    /**
+     * Per-turn budget. Enforced by `invokeAgent`. Missing fields default
+     * (see `TurnBudget`).
+     */
+    readonly budget?: TurnBudget;
+    /**
+     * Free-form tags for filtering in the agent catalog (UI + admin).
+     * Not consumed by execution.
+     */
+    readonly tags?: readonly string[];
+    /**
+     * A typed result: the final answer is JSON matching this schema,
+     * validated (and repaired, see `AgentOutputSpec`) before the turn
+     * completes. Absent = the answer is free text.
+     */
+    readonly output?: AgentOutputSpec;
+    /**
+     * What the turn does when a tool call fails: the failure goes back to
+     * the model as the call's result, so it can correct the call, up to
+     * `maxRetries` times per turn, for the kinds in `retryOn`. Default:
+     * one retry, for `invalid-arguments` and `unknown-tool` (nothing ran).
+     * A tenant's `tool-errors` policy can lower it. See `ToolErrorsSpec`.
+     */
+    readonly toolErrors?: ToolErrorsSpec;
+}
+/**
+ * A conversation record (the `agent_conversations` table in this
+ * package's Postgres schema). Messages are stored separately, as memory
+ * facts scoped to this conversation's id.
+ */
+export interface Conversation {
+    readonly id: ConversationId;
+    readonly tenantId: TenantId;
+    readonly agentId: AgentId;
+    readonly agentVersion: Semver;
+    /**
+     * Auto-generated on first turn or explicitly set. Shown in the UI
+     * conversation list.
+     */
+    readonly title: string;
+    /** UUID or free-form identifier for the human participant. */
+    readonly participantId?: string;
+    /** Additional attributes (project id, matter id, etc.). */
+    readonly scope: MemoryScope;
+    readonly openedAt: Timestamp;
+    /** Set when the conversation is closed. Reopening is not supported. */
+    readonly closedAt?: Timestamp;
+    /**
+     * Denormalized turn counter — one +1 per completed agent turn.
+     * Incremented by the conversation binding when a turn's final
+     * (non-intermediate) agent message is appended.
+     */
+    readonly turnCount: number;
+    readonly lastMessageAt?: Timestamp;
+    /**
+     * Free-form metadata. Persisted via the versioning envelope, so a
+     * schema change can be migrated on read.
+     */
+    readonly metadata?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Optional bindings for agent operations. Not read by `invokeAgent`,
+ * which takes `InvokeAgentBindings`.
+ */
+export interface AgentBindings {
+    /** A retrieval-policy registry from the memory implementation (untyped here). */
+    readonly memoryPolicyRegistry?: unknown;
+}
+/** A retrieved fact + the retrieval intent that pulled it. */
+export interface RetrievedFact {
+    readonly fact: Fact<unknown>;
+    readonly intent: RetrievalIntent;
+    /** Similarity or keyword-rank score, if the retrieval mode produced one. */
+    readonly score?: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

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

package/dist/types.js

@@ -0,0 +1,4 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+export {};
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

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

package/dist/versioning.d.ts

@@ -0,0 +1,29 @@
+import type { Result } from '@kindgi/types';
+/**
+ * JSONB payload versioning for agents-owned tables. Nested
+ * `{ v: 1, doc: <content> }` envelope; `unwrap` accepts only
+ * `CURRENT_AGENTS_PAYLOAD_VERSION`.
+ */
+export declare const CURRENT_AGENTS_PAYLOAD_VERSION = 1;
+export interface UnsupportedPayloadVersionError {
+    readonly code: 'unsupported-payload-version';
+    readonly message: string;
+    readonly version: number;
+    readonly currentVersion: number;
+}
+export interface MalformedEnvelopeError {
+    readonly code: 'malformed-envelope';
+    readonly message: string;
+}
+export type EnvelopeError = UnsupportedPayloadVersionError | MalformedEnvelopeError;
+export declare class EnvelopeThrown extends Error {
+    readonly error: EnvelopeError;
+    constructor(error: EnvelopeError);
+}
+export declare function wrap<T>(value: T): {
+    readonly v: number;
+    readonly doc: T;
+};
+export declare function unwrap<T = unknown>(raw: unknown): Result<T | null | undefined, EnvelopeError>;
+export declare function unwrapOrThrow<T = unknown>(raw: unknown): T | null | undefined;
+//# sourceMappingURL=versioning.d.ts.map

package/dist/versioning.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.d.ts","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AAE5C;;;;GAIG;AAEH,eAAO,MAAM,8BAA8B,IAAI,CAAC;AAEhD,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,IAAI,EAAE,6BAA6B,CAAC;IAC7C,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;CACjC;AAED,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,MAAM,aAAa,GAAG,8BAA8B,GAAG,sBAAsB,CAAC;AAEpF,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;gBAClB,KAAK,EAAE,aAAa;CAKjC;AAED,wBAAgB,IAAI,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG;IAAE,QAAQ,CAAC,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,GAAG,EAAE,CAAC,CAAA;CAAE,CAEzE;AAED,wBAAgB,MAAM,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,MAAM,CAAC,CAAC,GAAG,IAAI,GAAG,SAAS,EAAE,aAAa,CAAC,CA8B7F;AAED,wBAAgB,aAAa,CAAC,CAAC,GAAG,OAAO,EAAE,GAAG,EAAE,OAAO,GAAG,CAAC,GAAG,IAAI,GAAG,SAAS,CAI7E"}

package/dist/versioning.js

@@ -0,0 +1,58 @@
+// SPDX-License-Identifier: Apache-2.0
+// Copyright (C) 2026 Kindgi Inc.
+/**
+ * JSONB payload versioning for agents-owned tables. Nested
+ * `{ v: 1, doc: <content> }` envelope; `unwrap` accepts only
+ * `CURRENT_AGENTS_PAYLOAD_VERSION`.
+ */
+export const CURRENT_AGENTS_PAYLOAD_VERSION = 1;
+export class EnvelopeThrown extends Error {
+    error;
+    constructor(error) {
+        super(error.message);
+        this.error = error;
+        this.name = 'EnvelopeThrown';
+    }
+}
+export function wrap(value) {
+    return { v: CURRENT_AGENTS_PAYLOAD_VERSION, doc: value };
+}
+export function unwrap(raw) {
+    if (raw === null || raw === undefined)
+        return { kind: 'ok', value: raw };
+    if (typeof raw !== 'object' || Array.isArray(raw)) {
+        return {
+            kind: 'err',
+            error: {
+                code: 'malformed-envelope',
+                message: `Expected { v, doc } envelope, got ${typeof raw === 'object' ? 'array' : typeof raw}`,
+            },
+        };
+    }
+    const envelope = raw;
+    if (typeof envelope.v !== 'number' || !('doc' in envelope)) {
+        return {
+            kind: 'err',
+            error: { code: 'malformed-envelope', message: 'Payload is missing v or doc field' },
+        };
+    }
+    if (envelope.v === CURRENT_AGENTS_PAYLOAD_VERSION) {
+        return { kind: 'ok', value: envelope.doc };
+    }
+    return {
+        kind: 'err',
+        error: {
+            code: 'unsupported-payload-version',
+            message: `Unsupported payload version ${envelope.v} (this reader handles version ${CURRENT_AGENTS_PAYLOAD_VERSION})`,
+            version: envelope.v,
+            currentVersion: CURRENT_AGENTS_PAYLOAD_VERSION,
+        },
+    };
+}
+export function unwrapOrThrow(raw) {
+    const r = unwrap(raw);
+    if (r.kind === 'err')
+        throw new EnvelopeThrown(r.error);
+    return r.value;
+}
+//# sourceMappingURL=versioning.js.map

package/dist/versioning.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"versioning.js","sourceRoot":"","sources":["../src/versioning.ts"],"names":[],"mappings":"AAAA,sCAAsC;AACtC,iCAAiC;AAIjC;;;;GAIG;AAEH,MAAM,CAAC,MAAM,8BAA8B,GAAG,CAAC,CAAC;AAgBhD,MAAM,OAAO,cAAe,SAAQ,KAAK;IAC9B,KAAK,CAAgB;IAC9B,YAAY,KAAoB;QAC9B,KAAK,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC;QACrB,IAAI,CAAC,KAAK,GAAG,KAAK,CAAC;QACnB,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;IAC/B,CAAC;CACF;AAED,MAAM,UAAU,IAAI,CAAI,KAAQ;IAC9B,OAAO,EAAE,CAAC,EAAE,8BAA8B,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC;AAC3D,CAAC;AAED,MAAM,UAAU,MAAM,CAAc,GAAY;IAC9C,IAAI,GAAG,KAAK,IAAI,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC;IACzE,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC;QAClD,OAAO;YACL,IAAI,EAAE,KAAK;YACX,KAAK,EAAE;gBACL,IAAI,EAAE,oBAAoB;gBAC1B,OAAO,EAAE,qCAAqC,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,OAAO,GAAG,EAAE;aAC/F;SACF,CAAC;IACJ,CAAC;IACD,MAAM,QAAQ,GAAG,GAAuD,CAAC;IACzE,IAAI,OAAO,QAAQ,CAAC,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,KAAK,IAAI,QAAQ,CAAC,EAAE,CAAC;QAC3D,OAAO;YACL,IAAI,EAAE,KAAK;YACX,KAAK,EAAE,EAAE,IAAI,EAAE,oBAAoB,EAAE,OAAO,EAAE,mCAAmC,EAAE;SACpF,CAAC;IACJ,CAAC;IACD,IAAI,QAAQ,CAAC,CAAC,KAAK,8BAA8B,EAAE,CAAC;QAClD,OAAO,EAAE,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC,GAAQ,EAAE,CAAC;IAClD,CAAC;IACD,OAAO;QACL,IAAI,EAAE,KAAK;QACX,KAAK,EAAE;YACL,IAAI,EAAE,6BAA6B;YACnC,OAAO,EAAE,+BAA+B,QAAQ,CAAC,CAAC,iCAAiC,8BAA8B,GAAG;YACpH,OAAO,EAAE,QAAQ,CAAC,CAAC;YACnB,cAAc,EAAE,8BAA8B;SAC/C;KACF,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,aAAa,CAAc,GAAY;IACrD,MAAM,CAAC,GAAG,MAAM,CAAI,GAAG,CAAC,CAAC;IACzB,IAAI,CAAC,CAAC,IAAI,KAAK,KAAK;QAAE,MAAM,IAAI,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC;IACxD,OAAO,CAAC,CAAC,KAAK,CAAC;AACjB,CAAC"}

package/migrations/0000_sparkling_talkback.sql

@@ -0,0 +1,18 @@
+CREATE TABLE "agent_conversations" (
+	"id" uuid PRIMARY KEY DEFAULT gen_random_uuid() NOT NULL,
+	"tenant_id" uuid NOT NULL,
+	"agent_id" text NOT NULL,
+	"agent_version" text NOT NULL,
+	"title" text NOT NULL,
+	"participant_id" text,
+	"scope" jsonb NOT NULL,
+	"opened_at" timestamp with time zone DEFAULT now() NOT NULL,
+	"closed_at" timestamp with time zone,
+	"turn_count" integer DEFAULT 0 NOT NULL,
+	"last_message_at" timestamp with time zone,
+	"metadata" jsonb
+);
+--> statement-breakpoint
+CREATE INDEX "agent_conversations_tenant_agent_idx" ON "agent_conversations" USING btree ("tenant_id","agent_id");--> statement-breakpoint
+CREATE INDEX "agent_conversations_tenant_participant_idx" ON "agent_conversations" USING btree ("tenant_id","participant_id");--> statement-breakpoint
+CREATE INDEX "agent_conversations_open_recent_idx" ON "agent_conversations" USING btree ("tenant_id","last_message_at" DESC NULLS LAST) WHERE "agent_conversations"."closed_at" IS NULL;

package/migrations/0001_tired_warhawk.sql

@@ -0,0 +1,16 @@
+CREATE TABLE "agent_run_snapshots" (
+	"id" uuid PRIMARY KEY NOT NULL,
+	"tenant_id" uuid NOT NULL,
+	"project_id" uuid NOT NULL,
+	"agent_id" text NOT NULL,
+	"agent_version" text NOT NULL,
+	"conversation_id" uuid NOT NULL,
+	"user_message" text NOT NULL,
+	"participant_id" text,
+	"dry_run" integer DEFAULT 0 NOT NULL,
+	"principal" jsonb,
+	"authz" jsonb,
+	"created_at" timestamp with time zone DEFAULT now() NOT NULL
+);
+--> statement-breakpoint
+CREATE INDEX "agent_run_snapshots_tenant_idx" ON "agent_run_snapshots" USING btree ("tenant_id");

package/migrations/0002_violet_ezekiel.sql

@@ -0,0 +1,2 @@
+ALTER TABLE "agent_run_snapshots" ADD COLUMN "parameters" jsonb;--> statement-breakpoint
+ALTER TABLE "agent_run_snapshots" ADD COLUMN "input" jsonb;