@kindgi/agents 0.1.2 → 0.1.4-rc.0

package/src/provenance-emit.ts

@@ -6,6 +6,7 @@ import type {
   Provenance,
   ProvenanceBuilder,
   ProvenanceEmitBinding,
+  ProvenanceEmitContext,
 } from '@kindgi/provenance';
 import { signProvenance } from '@kindgi/provenance';
 import type { Result } from '@kindgi/types';
@@ -55,6 +56,8 @@ export interface ProvenanceBindings {
 export async function persistProvenance(
   builder: ProvenanceBuilder,
   bindings: ProvenanceBindings,
+  /** Stored beside the record (the turn's project); see `ProvenanceEmitContext`. */
+  context?: ProvenanceEmitContext,
 ): Promise<Result<Provenance, PersistenceError>> {
   let provenance: Provenance = builder.snapshot();
   if (bindings.keyProvider !== undefined) {
@@ -84,7 +87,7 @@ export async function persistProvenance(
         },
       };
     }
-    const emitted = await bindings.emitBinding.emit(provenance);
+    const emitted = await bindings.emitBinding.emit(provenance, context);
     if (emitted.kind === 'err') {
       return {
         kind: 'err',

package/src/run-snapshot-binding.ts

@@ -3,6 +3,8 @@
 
 import type { ProjectId, Result, RunId, Semver, TenantId, Timestamp } from '@kindgi/types';
 
+import type { RunReplayRef } from '@kindgi/runtime';
+
 import type { PersistenceError } from './errors.js';
 import type { AgentId, ConversationId } from './types.js';
 
@@ -37,6 +39,8 @@ export interface RunSnapshotWriteInput {
    * as `principal`.
    */
   readonly authz?: unknown;
+  /** The turn's replay marker (`InvokeAgentInput.replay`): a resumed replay stays one. */
+  readonly replay?: RunReplayRef;
 }
 
 /**
@@ -59,6 +63,8 @@ export interface RunSnapshotRecord {
   readonly dryRun: boolean;
   readonly principal?: unknown;
   readonly authz?: unknown;
+  /** The turn's replay marker (`InvokeAgentInput.replay`): a resumed replay stays one. */
+  readonly replay?: RunReplayRef;
   readonly createdAt: Timestamp;
 }
 

package/src/schema.ts

@@ -43,6 +43,13 @@ export const agentConversations = pgTable(
      * SSO subject). Kept as text so the caller decides the shape.
      */
     participantId: text('participant_id'),
+    /**
+     * The project the conversation is in, set when it is opened (a run
+     * opens it in the run's project). Null when opened without one, and
+     * on conversations from before the column (nothing is backfilled).
+     * No foreign key: `projects` belongs to the runtime's schema.
+     */
+    projectId: uuid('project_id'),
     /**
      * Structural scope — project id, matter id, etc. Persisted through
      * the versioning envelope so shape evolution is migrate-on-read.
@@ -74,6 +81,10 @@ export const agentConversations = pgTable(
       t.tenantId,
       t.participantId,
     ),
+    /** One project's conversations, newest first (`listConversationsPage({ scope })`). */
+    tenantProjectOpenedIdx: index('agent_conversations_tenant_project_opened_idx')
+      .on(t.tenantId, t.projectId, t.openedAt.desc())
+      .where(sql`${t.projectId} IS NOT NULL`),
     /** Partial index: open conversations sorted by recency. Used by the UI list. */
     openRecentIdx: index('agent_conversations_open_recent_idx')
       .on(t.tenantId, t.lastMessageAt.desc())
@@ -137,6 +148,11 @@ export const agentRunSnapshots = pgTable(
      * Threaded back into the resumed TurnContext.
      */
     authz: jsonb('authz'),
+    /**
+     * The replay marker (`{of, evalRunId}`) of a replay turn, so a resumed
+     * replay stays one: its tool calls are still decided by the replay rules.
+     */
+    replay: jsonb('replay'),
     createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
   },
   (t) => ({

package/src/streaming.ts

@@ -86,6 +86,11 @@ export interface ToolCompletedEvent {
   readonly invocationId: string;
   readonly output: unknown;
   readonly durationMs: number;
+  /**
+   * In a replay turn: whether the tool ran (`live`), the past run's result
+   * was used (`recorded`), or the call was refused (`refused`).
+   */
+  readonly replay?: 'live' | 'recorded' | 'refused';
 }
 
 export interface ToolFailedEvent {

package/src/types.ts

@@ -4,7 +4,9 @@
 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';
+import type { Brand, ConversationId, ProjectId, Semver, TenantId, Timestamp } from '@kindgi/types';
+
+import type { AgentDerivation, AgentPins } from './pins.js';
 
 /**
  * Branded agent id. Convention: dotted namespace under the tenant's
@@ -121,6 +123,22 @@ export interface ToolRef {
   readonly version: string;
 }
 
+/**
+ * A prompt block an agent's instructions come from: its id and a semver
+ * range, resolved like a tool's (`pickVersion`) and pinned when the
+ * agent version is published.
+ */
+export interface PromptRef {
+  readonly prompt: string;
+  readonly version: string;
+}
+
+/** A settings block an agent reads: its id and a semver range, pinned at publish. */
+export interface BlockRef {
+  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).
@@ -204,6 +222,14 @@ export interface ConversationHitlPolicy {
    * (see `resolveEffectiveHitlPolicy`).
    */
   readonly timeoutMs?: number;
+  /**
+   * What happens when an approval's time runs out: it escalates one
+   * reviewer tier, and at `admin` it expires (the turn fails with
+   * `hitl-cancelled`). `'escalate'` is the only behavior today, and the
+   * default; `'auto-approve'` and `'auto-reject'` are refused rather than
+   * accepted and ignored.
+   */
+  readonly onTimeout?: 'escalate';
 }
 
 /**
@@ -284,8 +310,13 @@ export interface Agent {
    * unresolved reference fails the turn at invoke time
    * (`model-invocation-failed` whose `cause` is the `missing-parameter`
    * render error), never a silent empty string.
+   *
+   * Or a prompt block, by range (`{ prompt: 'acme.intake-prompt',
+   * version: '^1.0.0' }`): its template renders here instead, with the
+   * parameters it declares, and the version that runs is pinned when the
+   * agent version is published (`pins.prompts`).
    */
-  readonly instructions: string;
+  readonly instructions: string | PromptRef;
   /**
    * Typed parameters the caller supplies at invoke time. The UI reads
    * this to build a "configure agent" form; the runtime validates each
@@ -397,6 +428,35 @@ export interface Agent {
    * A tenant's `tool-errors` policy can lower it. See `ToolErrorsSpec`.
    */
   readonly toolErrors?: ToolErrorsSpec;
+  /**
+   * The exact block versions this agent version runs, resolved by the
+   * runtime when the version was published (see `AgentPins`). Never
+   * authored: `defineAgent` doesn't take it. Absent on an agent defined
+   * in code and on a version published before pins existed; its tool
+   * ranges then resolve per run.
+   */
+  readonly pins?: AgentPins;
+  /**
+   * Settings blocks the agent reads, by range. Each block's values reach
+   * its tools as `ToolContext.settings[<block id>]` and its templates as
+   * `settings.<block id>.<key>`; the versions are pinned at publish
+   * (`pins.settings`).
+   */
+  readonly settings?: readonly BlockRef[];
+  /**
+   * A settings block of model settings (`MODEL_SETTINGS_SCHEMA`:
+   * `temperature`, `maxOutputTokens`) the turn's model calls use. Pinned
+   * at publish with the other settings.
+   */
+  readonly modelSettings?: BlockRef;
+  /** `pinsDigest(pins)`, recorded when the version was published. */
+  readonly pinsDigest?: string;
+  /**
+   * Set by the runtime on a version it registered under another number
+   * than the definition's, when a deploy couldn't register that number
+   * as it was (see `AgentDerivation`). Never authored.
+   */
+  readonly derivedFrom?: AgentDerivation;
 }
 
 /**
@@ -416,6 +476,12 @@ export interface Conversation {
   readonly title: string;
   /** UUID or free-form identifier for the human participant. */
   readonly participantId?: string;
+  /**
+   * The project the conversation is in, set when it is opened (by a run,
+   * from the run's project). Absent on conversations opened without one,
+   * and on those from before it was stored.
+   */
+  readonly projectId?: ProjectId;
   /** Additional attributes (project id, matter id, etc.). */
   readonly scope: MemoryScope;
   readonly openedAt: Timestamp;