@datalayer/agent-runtimes 1.5.44 → 1.5.46

package/lib/portable/hosts/quotas.d.ts

@@ -0,0 +1,81 @@
+/**
+ * Quotas before costly work (SLACK §9, S-404; DISCORD DC-402): questions an
+ * hour per person, installation (a Slack workspace, a Discord server),
+ * organization and application, taken atomically before a turn starts at
+ * Datalayer. A refusal says which limit and when it resets. Moved from the
+ * Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/quotas
+ */
+import { type ConnectionPool } from './queue';
+export type QuotaScope = 'user' | 'installation' | 'organization' | 'application';
+export type QuotaLimits = Readonly<Record<QuotaScope, number>>;
+export declare const DEFAULT_QUOTAS: QuotaLimits;
+export type QuotaEntry = Readonly<{
+    scope: QuotaScope;
+    key: string;
+    limit: number;
+}>;
+export type QuotaTaken = Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    scope: QuotaScope;
+    limit: number;
+    resetsAt: Date;
+}>;
+/** The hour a moment falls in: the period counts are kept by. */
+export declare function windowOf(now: Date): string;
+export declare function resetOf(now: Date): Date;
+/** A person's quota key in an installation: what their usage line reads. */
+export declare function userQuotaKey(installation: string, externalUserId: string): string;
+/**
+ * What each quota counts, for one turn. `keyPrefix` names the installation's
+ * key (`installation:<id>` by default; Slack keeps `workspace:<id>`, the keys
+ * its counts were kept under).
+ */
+export declare function quotaEntries(limits: QuotaLimits, turn: {
+    installation: string;
+    externalUserId: string;
+    applicationId: string;
+    organizationId?: string;
+}, keyPrefix?: string): QuotaEntry[];
+/**
+ * Words for a refusal, said privately. `installation` names the host's
+ * installation as its people say it: "this workspace", "this server".
+ */
+export declare function quotaWords(taken: Extract<QuotaTaken, {
+    ok: false;
+}>, installation: string): string;
+export type QuotaTake = Readonly<{
+    ok: true;
+}> | Readonly<{
+    ok: false;
+    entry: QuotaEntry;
+}>;
+/** Where quota counts are kept. */
+export interface QuotaStore {
+    /**
+     * Take one of each quota for a period, all or none (S-404): refused when
+     * any is spent, naming it.
+     */
+    takeQuota(entries: readonly QuotaEntry[], period: string): Promise<QuotaTake>;
+    /** How much of a quota is used in a period. */
+    quotaUsed(key: string, period: string): Promise<number>;
+}
+/** Counts in memory: development and tests. */
+export declare class MemoryQuotaStore implements QuotaStore {
+    #private;
+    takeQuota(entries: readonly QuotaEntry[], period: string): Promise<QuotaTake>;
+    quotaUsed(key: string, period: string): Promise<number>;
+}
+/** Counts in `<prefix>_usage`, taken in one transaction, rows locked in a stable order. */
+export declare class PostgresQuotaStore implements QuotaStore {
+    #private;
+    readonly database: ConnectionPool;
+    constructor(database: ConnectionPool, options: {
+        tablePrefix: string;
+    });
+    takeQuota(entries: readonly QuotaEntry[], period: string): Promise<QuotaTake>;
+    quotaUsed(key: string, period: string): Promise<number>;
+}

package/lib/portable/hosts/quotas.js

@@ -0,0 +1,147 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Quotas before costly work (SLACK §9, S-404; DISCORD DC-402): questions an
+ * hour per person, installation (a Slack workspace, a Discord server),
+ * organization and application, taken atomically before a turn starts at
+ * Datalayer. A refusal says which limit and when it resets. Moved from the
+ * Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/quotas
+ */
+import { tablePrefixOf } from './queue';
+export const DEFAULT_QUOTAS = {
+    application: 600,
+    installation: 600,
+    organization: 2_000,
+    user: 60,
+};
+/** The hour a moment falls in: the period counts are kept by. */
+export function windowOf(now) {
+    return now.toISOString().slice(0, 13);
+}
+export function resetOf(now) {
+    const next = new Date(now);
+    next.setUTCMinutes(0, 0, 0);
+    next.setUTCHours(next.getUTCHours() + 1);
+    return next;
+}
+/** A person's quota key in an installation: what their usage line reads. */
+export function userQuotaKey(installation, externalUserId) {
+    return `user:${installation}:${externalUserId}`;
+}
+/**
+ * What each quota counts, for one turn. `keyPrefix` names the installation's
+ * key (`installation:<id>` by default; Slack keeps `workspace:<id>`, the keys
+ * its counts were kept under).
+ */
+export function quotaEntries(limits, turn, keyPrefix = 'installation') {
+    return [
+        {
+            key: userQuotaKey(turn.installation, turn.externalUserId),
+            limit: limits.user,
+            scope: 'user',
+        },
+        {
+            key: `${keyPrefix}:${turn.installation}`,
+            limit: limits.installation,
+            scope: 'installation',
+        },
+        ...(turn.organizationId
+            ? [
+                {
+                    key: `organization:${turn.organizationId}`,
+                    limit: limits.organization,
+                    scope: 'organization',
+                },
+            ]
+            : []),
+        {
+            key: `application:${turn.applicationId}`,
+            limit: limits.application,
+            scope: 'application',
+        },
+    ];
+}
+/**
+ * Words for a refusal, said privately. `installation` names the host's
+ * installation as its people say it: "this workspace", "this server".
+ */
+export function quotaWords(taken, installation) {
+    const whose = {
+        application: 'this application',
+        installation,
+        organization: 'your organization',
+        user: 'you',
+    };
+    const at = taken.resetsAt.toISOString().slice(11, 16);
+    return `@Datalayer has answered ${taken.limit} questions this hour for ${whose[taken.scope]}, its limit. Ask again after ${at} UTC.`;
+}
+/** Counts in memory: development and tests. */
+export class MemoryQuotaStore {
+    #usage = new Map();
+    async takeQuota(entries, period) {
+        const spent = entries.find(entry => (this.#usage.get(`${period}:${entry.key}`) ?? 0) >= entry.limit);
+        if (spent) {
+            return { entry: spent, ok: false };
+        }
+        for (const entry of entries) {
+            this.#usage.set(`${period}:${entry.key}`, (this.#usage.get(`${period}:${entry.key}`) ?? 0) + 1);
+        }
+        return { ok: true };
+    }
+    async quotaUsed(key, period) {
+        return this.#usage.get(`${period}:${key}`) ?? 0;
+    }
+}
+/** Counts in `<prefix>_usage`, taken in one transaction, rows locked in a stable order. */
+export class PostgresQuotaStore {
+    database;
+    #usage;
+    constructor(database, options) {
+        this.database = database;
+        this.#usage = `${tablePrefixOf(options.tablePrefix)}_usage`;
+    }
+    async takeQuota(entries, period) {
+        const client = await this.database.connect();
+        try {
+            await client.query('BEGIN');
+            const taken = await this.#take(client, entries, period);
+            await client.query(taken.ok ? 'COMMIT' : 'ROLLBACK');
+            return taken;
+        }
+        catch (error) {
+            await client.query('ROLLBACK');
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async #take(client, entries, period) {
+        // Rows locked in a stable order: two turns never deadlock on them.
+        const sorted = [...entries].sort((a, b) => a.key.localeCompare(b.key));
+        for (const entry of sorted) {
+            await client.query(`INSERT INTO ${this.#usage} (usage_key, usage_window, used) VALUES ($1, $2, 0)
+         ON CONFLICT (usage_key, usage_window) DO NOTHING`, [entry.key, period]);
+        }
+        const keys = sorted.map(entry => entry.key);
+        const used = await client.query(`SELECT usage_key, used FROM ${this.#usage}
+       WHERE usage_window = $1 AND usage_key = ANY($2::text[])
+       ORDER BY usage_key FOR UPDATE`, [period, keys]);
+        const counts = new Map(used.rows.map(row => [row.usage_key, row.used]));
+        const spent = entries.find(entry => (counts.get(entry.key) ?? 0) >= entry.limit);
+        if (spent) {
+            return { entry: spent, ok: false };
+        }
+        await client.query(`UPDATE ${this.#usage} SET used = used + 1
+       WHERE usage_window = $1 AND usage_key = ANY($2::text[])`, [period, keys]);
+        return { ok: true };
+    }
+    async quotaUsed(key, period) {
+        const result = await this.database.query(`SELECT used FROM ${this.#usage} WHERE usage_key = $1 AND usage_window = $2`, [key, period]);
+        return result.rows[0]?.used ?? 0;
+    }
+}

package/lib/portable/hosts/rateLimit.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The clock a host's rate limiter waits on: the system's, or a test's fake.
+ * Each host keeps its own limiter (Slack's method spacing, Discord's
+ * buckets), since what a 429 says differs by host. Moved from the Slack
+ * service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/rateLimit
+ */
+export interface Clock {
+    now(): number;
+    sleep(milliseconds: number): Promise<void>;
+}
+export declare const systemClock: Clock;

package/lib/portable/hosts/rateLimit.js

@@ -0,0 +1,8 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+export const systemClock = {
+    now: () => Date.now(),
+    sleep: milliseconds => new Promise(resolve => setTimeout(resolve, milliseconds)),
+};

package/lib/portable/hosts/resolution.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Which application a host's turn runs (SLACK §8, S-202; DISCORD §8): the
+ * thread's own, else an explicit choice, else the one chosen for the
+ * thread's next session, else the channel's, else the installation's
+ * default; then that application allowed here and in this kind of
+ * conversation. Datalayer's exchange checks the person may open it at every
+ * turn: nothing here authorizes alone. The host says each refusal in its own
+ * words. Moved from the Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/resolution
+ */
+/** An application the installation allows, as a host keeps it to show and choose from. */
+export type AllowanceView = Readonly<{
+    applicationId: string;
+    name: string;
+    enabled: boolean;
+    /** Whether it answers in channels, or in direct messages only. */
+    channelPolicy: 'channels' | 'direct-only';
+}>;
+/** A channel's own rule: denied, or its default application. */
+export type ChannelRule = Readonly<{
+    state: 'allow' | 'deny';
+    applicationId?: string;
+}>;
+export type ApplicationRefusal = 'channel-denied' | 'no-application' | 'not-allowed' | 'direct-only';
+export type ApplicationResolution<A extends AllowanceView> = Readonly<{
+    ok: true;
+    applicationId: string;
+    allowance?: A;
+}> | Readonly<{
+    ok: false;
+    refusal: ApplicationRefusal;
+    allowance?: A;
+}>;
+/**
+ * The application a turn runs, or why none does. The lookups are read only
+ * when the order reaches them. With no allowance kept, any application is
+ * taken (Datalayer's exchange still decides).
+ */
+export declare function resolveApplication<A extends AllowanceView>(input: {
+    visibility: 'channel' | 'direct';
+    /** The thread's application once it has a session: switching is explicit (S-208). */
+    threadApplication?: string;
+    /** The application chosen with this very prompt. */
+    explicit?: string;
+    /** The application chosen for the thread's next session. */
+    next: () => Promise<string | undefined>;
+    /** The channel's own rule; never read in a direct conversation. */
+    channel: () => Promise<ChannelRule | undefined>;
+    defaultApplication: () => Promise<string | undefined>;
+    allowances: readonly A[];
+}): Promise<ApplicationResolution<A>>;
+/** The applications a person may choose from here: enabled, and answering in this kind of conversation. */
+export declare function usableAllowances<A extends AllowanceView>(allowances: readonly A[], visibility: 'channel' | 'direct'): A[];

package/lib/portable/hosts/resolution.js

@@ -0,0 +1,46 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The application a turn runs, or why none does. The lookups are read only
+ * when the order reaches them. With no allowance kept, any application is
+ * taken (Datalayer's exchange still decides).
+ */
+export async function resolveApplication(input) {
+    let applicationId;
+    if (input.threadApplication) {
+        applicationId = input.threadApplication;
+    }
+    else if (input.explicit) {
+        applicationId = input.explicit;
+    }
+    else {
+        applicationId = await input.next();
+        if (!applicationId) {
+            const channel = input.visibility === 'channel' ? await input.channel() : undefined;
+            if (channel?.state === 'deny') {
+                return { ok: false, refusal: 'channel-denied' };
+            }
+            applicationId =
+                channel?.applicationId ?? (await input.defaultApplication());
+        }
+    }
+    if (!applicationId) {
+        return { ok: false, refusal: 'no-application' };
+    }
+    const allowance = input.allowances.find(one => one.applicationId === applicationId && one.enabled);
+    if (input.allowances.length > 0 && !allowance) {
+        return { ok: false, refusal: 'not-allowed' };
+    }
+    if (allowance?.channelPolicy === 'direct-only' &&
+        input.visibility === 'channel') {
+        return { ok: false, refusal: 'direct-only', allowance };
+    }
+    return { ok: true, applicationId, allowance };
+}
+/** The applications a person may choose from here: enabled, and answering in this kind of conversation. */
+export function usableAllowances(allowances, visibility) {
+    return allowances.filter(one => one.enabled &&
+        (one.channelPolicy === 'channels' || visibility === 'direct'));
+}

package/lib/portable/hosts/schema.d.ts

@@ -0,0 +1,19 @@
+/**
+ * The tables every host service keeps the same way, under its own prefix:
+ * ingress claims and the work queue (`<prefix>_event_claims`,
+ * `<prefix>_jobs`), quota counts (`<prefix>_usage`), privileged payload reads
+ * (`<prefix>_payload_access`) and dead-job replays (`<prefix>_job_replays`).
+ * Their final shapes, as idempotent statements: a service applies them
+ * before its own migrations, every time. TypeScript strings, since the npm
+ * tarball ships no `.sql`. Moved from the Slack service's migrations 001,
+ * 004 and 007 (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/schema
+ */
+import { type Queryable } from './queue';
+/** The shared tables of one host, as one idempotent script. */
+export declare function hostSchemaSql(tablePrefix: string): string;
+/** The tables `hostSchemaSql` makes, by name: what a test and an operator check. */
+export declare function hostTables(tablePrefix: string): string[];
+/** Apply the shared tables of one host: idempotent, before the service's own migrations. */
+export declare function applyHostSchema(database: Queryable, tablePrefix: string): Promise<void>;

package/lib/portable/hosts/schema.js

@@ -0,0 +1,81 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * The tables every host service keeps the same way, under its own prefix:
+ * ingress claims and the work queue (`<prefix>_event_claims`,
+ * `<prefix>_jobs`), quota counts (`<prefix>_usage`), privileged payload reads
+ * (`<prefix>_payload_access`) and dead-job replays (`<prefix>_job_replays`).
+ * Their final shapes, as idempotent statements: a service applies them
+ * before its own migrations, every time. TypeScript strings, since the npm
+ * tarball ships no `.sql`. Moved from the Slack service's migrations 001,
+ * 004 and 007 (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/schema
+ */
+import { tablePrefixOf } from './queue';
+/** The shared tables of one host, as one idempotent script. */
+export function hostSchemaSql(tablePrefix) {
+    const p = tablePrefixOf(tablePrefix);
+    return `BEGIN;
+
+CREATE TABLE IF NOT EXISTS ${p}_event_claims (
+  event_id text PRIMARY KEY,
+  claimed_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${p}_event_claims_claimed_at ON ${p}_event_claims (claimed_at);
+
+CREATE TABLE IF NOT EXISTS ${p}_jobs (
+  id bigserial PRIMARY KEY,
+  payload jsonb NOT NULL,
+  state text NOT NULL DEFAULT 'ready' CHECK (state IN ('ready', 'processing', 'dead')),
+  attempts integer NOT NULL DEFAULT 0,
+  available_at timestamptz NOT NULL DEFAULT now(),
+  locked_at timestamptz,
+  last_error text,
+  created_at timestamptz NOT NULL DEFAULT now()
+);
+CREATE INDEX IF NOT EXISTS ${p}_jobs_ready ON ${p}_jobs (state, available_at, id);
+
+CREATE TABLE IF NOT EXISTS ${p}_usage (
+  usage_key text NOT NULL,
+  usage_window text NOT NULL,
+  used integer NOT NULL DEFAULT 0,
+  PRIMARY KEY (usage_key, usage_window)
+);
+
+CREATE TABLE IF NOT EXISTS ${p}_payload_access (
+  id bigserial PRIMARY KEY,
+  job_id bigint NOT NULL,
+  operator text NOT NULL,
+  reason text NOT NULL,
+  read_at timestamptz NOT NULL DEFAULT now()
+);
+
+CREATE TABLE IF NOT EXISTS ${p}_job_replays (
+  id bigserial PRIMARY KEY,
+  job_id bigint NOT NULL,
+  operator text NOT NULL,
+  replayed boolean NOT NULL,
+  replayed_at timestamptz NOT NULL DEFAULT now()
+);
+
+COMMIT;
+`;
+}
+/** The tables `hostSchemaSql` makes, by name: what a test and an operator check. */
+export function hostTables(tablePrefix) {
+    const p = tablePrefixOf(tablePrefix);
+    return [
+        `${p}_event_claims`,
+        `${p}_jobs`,
+        `${p}_usage`,
+        `${p}_payload_access`,
+        `${p}_job_replays`,
+    ];
+}
+/** Apply the shared tables of one host: idempotent, before the service's own migrations. */
+export async function applyHostSchema(database, tablePrefix) {
+    await database.query(hostSchemaSql(tablePrefix));
+}

package/lib/portable/hosts/secretCipher.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Secrets at rest (SLACK §9, DISCORD §9): AES-256-GCM, each value bound to
+ * what it belongs to (its associated data, an installation's key), with the
+ * key's version kept beside it. Moved from the Slack service
+ * (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/secretCipher
+ */
+export type EncryptedSecret = Readonly<{
+    ciphertext: string;
+    iv: string;
+    keyVersion: number;
+    tag: string;
+}>;
+export declare class SecretCipher {
+    #private;
+    readonly keyVersion: number;
+    constructor(keyBase64: string, keyVersion: number, 
+    /** The setting the key is read from, named when it is refused. */
+    keyName?: string);
+    encrypt(value: string, associatedData: string): EncryptedSecret;
+    decrypt(secret: EncryptedSecret, associatedData: string): string;
+}

package/lib/portable/hosts/secretCipher.js

@@ -0,0 +1,45 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+import { createCipheriv, createDecipheriv, randomBytes } from 'node:crypto';
+export class SecretCipher {
+    keyVersion;
+    #key;
+    constructor(keyBase64, keyVersion, 
+    /** The setting the key is read from, named when it is refused. */
+    keyName = 'The encryption key') {
+        this.keyVersion = keyVersion;
+        this.#key = Buffer.from(keyBase64, 'base64');
+        if (this.#key.length !== 32) {
+            throw new Error(`${keyName} must be a base64-encoded 32-byte key.`);
+        }
+    }
+    encrypt(value, associatedData) {
+        const iv = randomBytes(12);
+        const cipher = createCipheriv('aes-256-gcm', this.#key, iv);
+        cipher.setAAD(Buffer.from(associatedData));
+        const ciphertext = Buffer.concat([
+            cipher.update(value, 'utf8'),
+            cipher.final(),
+        ]);
+        return {
+            ciphertext: ciphertext.toString('base64'),
+            iv: iv.toString('base64'),
+            keyVersion: this.keyVersion,
+            tag: cipher.getAuthTag().toString('base64'),
+        };
+    }
+    decrypt(secret, associatedData) {
+        if (secret.keyVersion !== this.keyVersion) {
+            throw new Error(`No decryption key is configured for version ${secret.keyVersion}.`);
+        }
+        const decipher = createDecipheriv('aes-256-gcm', this.#key, Buffer.from(secret.iv, 'base64'));
+        decipher.setAAD(Buffer.from(associatedData));
+        decipher.setAuthTag(Buffer.from(secret.tag, 'base64'));
+        return Buffer.concat([
+            decipher.update(Buffer.from(secret.ciphertext, 'base64')),
+            decipher.final(),
+        ]).toString('utf8');
+    }
+}

package/lib/portable/hosts/sessionUid.d.ts

@@ -0,0 +1,7 @@
+/**
+ * `<kind>-<40 hex>`: the SHA-256 of the thread's parts joined by `:`, and
+ * `:<generation>` once the thread started over or switched application. The
+ * same parts give the same uid (Slack: app, enterprise or `-`, team,
+ * channel, thread ts; Discord: application, guild, channel, thread).
+ */
+export declare function hostSessionUid(kind: string, parts: readonly string[], generation?: number): string;

package/lib/portable/hosts/sessionUid.js

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * One host thread is one Datalayer session: its uid, derived from where the
+ * thread is, so that a retry names it again (SLACK §2 rule 2, DISCORD §2
+ * rule 2). Moved from the Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/sessionUid
+ */
+import { createHash } from 'node:crypto';
+/**
+ * `<kind>-<40 hex>`: the SHA-256 of the thread's parts joined by `:`, and
+ * `:<generation>` once the thread started over or switched application. The
+ * same parts give the same uid (Slack: app, enterprise or `-`, team,
+ * channel, thread ts; Discord: application, guild, channel, thread).
+ */
+export function hostSessionUid(kind, parts, generation) {
+    if (!/^[a-z][a-z0-9-]{1,31}$/.test(kind)) {
+        throw new Error(`A host kind is lowercase letters and digits: ${kind}.`);
+    }
+    if (parts.length === 0 || parts.some(part => part === '')) {
+        throw new Error('A thread is named by its parts, none of them empty.');
+    }
+    const key = `${parts.join(':')}${generation ? `:${generation}` : ''}`;
+    return `${kind}-${createHash('sha256').update(key).digest('hex').slice(0, 40)}`;
+}

package/lib/portable/hosts/turnState.d.ts

@@ -0,0 +1,45 @@
+/**
+ * A turn's state as a chat host shows it, from its semantic events: the
+ * answer so far, the tools, the status line, the approvals waited on, the
+ * question it ends on, and how it ended. Each host renders it in its own
+ * blocks (Slack's Block Kit, Discord's components); nothing here is a
+ * host's. Moved from the Slack service (plans/DISCORD.md DC-004).
+ *
+ * @module portable/hosts/turnState
+ */
+import type { AskQuestion, SemanticEvent } from '../semantic';
+export type TurnEnding = 'completion' | 'stop' | 'error';
+export type TurnTool = Readonly<{
+    name: string;
+    status: string;
+}>;
+export type TurnFile = Readonly<{
+    mediaType?: string;
+    name: string;
+    url: string;
+}>;
+export declare class TurnState {
+    #private;
+    /** Whether the turn finished while it streamed: else a `turn.completed` delivery finishes it. */
+    get complete(): boolean;
+    /** Whether the turn ended (answered, stopped, failed) or waits on a question. */
+    get ended(): boolean;
+    /** Whether the turn still runs: not ended, and asking nothing. */
+    get running(): boolean;
+    /** The answer so far, its tables and citations as Markdown. */
+    get answer(): string;
+    /** The question the turn ends on, if any. */
+    get asking(): AskQuestion | undefined;
+    /** The tools whose approval the turn waited on, in order. */
+    get approvals(): readonly string[];
+    /** How the turn ended, if it did. */
+    get ending(): TurnEnding | undefined;
+    /** What the run said when it failed. */
+    get error(): string | undefined;
+    get files(): readonly TurnFile[];
+    /** The status line: what the turn is doing now. */
+    get status(): string;
+    /** Each tool the turn used, by its call, in the order first seen. */
+    get tools(): ReadonlyMap<string, TurnTool>;
+    apply(event: SemanticEvent): void;
+}