@datalayer/agent-runtimes 1.5.65 → 1.5.70

package/lib/specs/sessionFiles.js

@@ -0,0 +1,578 @@
+/*
+ * Copyright (c) 2025-2026 Datalayer, Inc.
+ * Distributed under the terms of the Modified BSD License.
+ */
+/**
+ * Session file format (MH-12).
+ *
+ * The datalayer-session/1 JSONL file: its caps, the states, the entry kinds,
+ * the redaction rules and the refusal sentences, as agentspecs says them.
+ *
+ * This file is AUTO-GENERATED from YAML specifications.
+ * DO NOT EDIT MANUALLY - run 'make specs' to regenerate.
+ */
+/** The format: what a file's first line says. */
+export const SESSION_FILE_FORMAT = 'datalayer-session/1';
+export const SESSION_FILE_MEDIA_TYPE = 'application/x-ndjson';
+export const SESSION_FILE_EXTENSION = '.session.jsonl';
+/** A file over either is refused with its counts. */
+export const SESSION_FILE_MAX_BYTES = 67108864;
+export const SESSION_FILE_MAX_ENTRIES = 20000;
+/** A session's state, as the record says it. */
+export const SESSION_STATES = ['open', 'paused', 'ended'];
+/** The kinds an entry line may carry: the record's, and the session's audit rows. */
+export const SESSION_ENTRY_KINDS = [
+    'session',
+    'run',
+    'tool_call',
+    'decision',
+    'check',
+    'approval',
+    'output',
+    'feedback',
+    'turn',
+    'notification',
+    'step',
+    'thread',
+    'asked',
+    'audio',
+    'diff',
+    'terminal',
+    'file',
+    'rule',
+    'paused',
+    'ended',
+    'swapped',
+    'cloned',
+    'imported',
+    'exported',
+    'titled',
+];
+/** The redaction rules applied at export, by id, each with what it does. */
+export const SESSION_REDACTION_RULES = {
+    authorization_header: 'A header or key named Authorization, Proxy-Authorization or Cookie, whatever its value.',
+    bearer_token: 'A value that reads `Bearer …`, `Basic …` or `token …`, or a key, secret or password field.',
+    declared_secret: "The value of a secret the application or its harness declares (`requires.secrets`, the Appspec's env), by name.",
+    url_userinfo: 'A URL with userinfo (`https://user:pass@host`): the userinfo is dropped.',
+    signed_user: "The user an embed's host signed for the session (`signed`): dropped, with the entry's `user`.",
+    runtime_address: "The runtime's uid and addresses (`runs_on`, the sandbox's host): dropped from every entry.",
+};
+/** Said, word for word, by whoever refuses a file; `{…}` are filled in. */
+export const SESSION_FILE_REFUSALS = {
+    unversioned: "A session file's first line is a session line that says its format, datalayer-session/1; this file's first line does not.",
+    other_version: 'The file is {format}; this runtime reads datalayer-session/1.',
+    not_a_line: 'Line {line} of the file is not a session, team_session or entry line: it says record_type {record_type!r}.',
+    unknown_kind: 'Line {line} is an entry of kind {kind!r}, which the record does not have: one of {kinds}.',
+    entry_without_at: 'Line {line} is an entry that does not say when it was recorded (`at`).',
+    team_without_seats: 'A team session line names its seats, in order, each with its session uid; this one names none.',
+    too_large: 'The file has {entries} entries over {megabytes} MB; a session file holds at most 20 000 entries in 64 MB.',
+    not_json: 'Line {line} of the file is not JSON.',
+};
+/** The spec's sentence for a refusal, its facts filled in. */
+export function sessionFileRefusal(name, facts = {}) {
+    return SESSION_FILE_REFUSALS[name].replace(/\{(\w+)(?:!r)?\}/g, (whole, key) => key in facts
+        ? whole.endsWith('!r}')
+            ? JSON.stringify(String(facts[key])).replace(/^"|"$/g, "'")
+            : String(facts[key])
+        : whole);
+}
+/** The JSON Schema of one line of the file. */
+export const SESSION_FILE_SCHEMA = {
+    $defs: {
+        EntryLine: {
+            additionalProperties: false,
+            description: 'One entry of the record, as the record holds it, redacted.',
+            properties: {
+                at: {
+                    description: 'When it was recorded, ISO 8601',
+                    minLength: 1,
+                    title: 'At',
+                    type: 'string',
+                },
+                kind: {
+                    enum: [
+                        'session',
+                        'run',
+                        'tool_call',
+                        'decision',
+                        'check',
+                        'approval',
+                        'output',
+                        'feedback',
+                        'turn',
+                        'notification',
+                        'step',
+                        'thread',
+                        'asked',
+                        'audio',
+                        'diff',
+                        'terminal',
+                        'file',
+                        'rule',
+                        'paused',
+                        'ended',
+                        'swapped',
+                        'cloned',
+                        'imported',
+                        'exported',
+                        'titled',
+                    ],
+                    title: 'Kind',
+                    type: 'string',
+                },
+                payload: {
+                    additionalProperties: true,
+                    title: 'Payload',
+                    type: 'object',
+                },
+                record_type: {
+                    pattern: '^entry$',
+                    title: 'Record Type',
+                    type: 'string',
+                },
+                summary: {
+                    default: '',
+                    title: 'Summary',
+                    type: 'string',
+                },
+            },
+            required: ['record_type', 'kind', 'at'],
+            title: 'EntryLine',
+            type: 'object',
+        },
+        ForkedFrom: {
+            additionalProperties: false,
+            description: "A clone's source: the session, and the turn it was cut at.",
+            properties: {
+                at_turn: {
+                    minimum: 0,
+                    title: 'At Turn',
+                    type: 'integer',
+                },
+                uid: {
+                    minLength: 1,
+                    title: 'Uid',
+                    type: 'string',
+                },
+            },
+            required: ['uid', 'at_turn'],
+            title: 'ForkedFrom',
+            type: 'object',
+        },
+        ImportedFrom: {
+            additionalProperties: false,
+            description: "An import's source: the file's digest, when and by whom it was exported.\n\n``exported_by`` is the exporter's uid, a string — the shape the record's\n``imported`` entry and the services' listing say it in (one shape, no\nsecond one for older readers).",
+            properties: {
+                digest: {
+                    pattern: '^sha256:[0-9a-f]{64}$',
+                    title: 'Digest',
+                    type: 'string',
+                },
+                exported_at: {
+                    minLength: 1,
+                    title: 'Exported At',
+                    type: 'string',
+                },
+                exported_by: {
+                    description: "The exporter's uid",
+                    minLength: 1,
+                    title: 'Exported By',
+                    type: 'string',
+                },
+            },
+            required: ['digest', 'exported_at', 'exported_by'],
+            title: 'ImportedFrom',
+            type: 'object',
+        },
+        Lineage: {
+            additionalProperties: false,
+            description: 'Where a session came from: both keys said, each ``null`` when it did not.',
+            properties: {
+                forked_from: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/ForkedFrom',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                },
+                imported_from: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/ImportedFrom',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                },
+            },
+            required: ['forked_from', 'imported_from'],
+            title: 'Lineage',
+            type: 'object',
+        },
+        Owner: {
+            additionalProperties: false,
+            description: "Who a session is: a uid, never a handle (a handle is the target's to resolve).",
+            properties: {
+                uid: {
+                    minLength: 1,
+                    title: 'Uid',
+                    type: 'string',
+                },
+            },
+            required: ['uid'],
+            title: 'Owner',
+            type: 'object',
+        },
+        SessionApp: {
+            additionalProperties: false,
+            description: 'The application a session is of, and the version it was had on.',
+            properties: {
+                id: {
+                    minLength: 1,
+                    title: 'Id',
+                    type: 'string',
+                },
+                version: {
+                    minimum: 0,
+                    title: 'Version',
+                    type: 'integer',
+                },
+            },
+            required: ['id', 'version'],
+            title: 'SessionApp',
+            type: 'object',
+        },
+        SessionLine: {
+            additionalProperties: false,
+            description: 'The first line: the session.',
+            properties: {
+                agent: {
+                    description: 'The agentspec bound to it when exported',
+                    minLength: 1,
+                    title: 'Agent',
+                    type: 'string',
+                },
+                app: {
+                    $ref: '#/$defs/SessionApp',
+                },
+                archived: {
+                    title: 'Archived',
+                    type: 'boolean',
+                },
+                entries: {
+                    description: 'How many entry lines follow',
+                    minimum: 0,
+                    title: 'Entries',
+                    type: 'integer',
+                },
+                exported_at: {
+                    minLength: 1,
+                    title: 'Exported At',
+                    type: 'string',
+                },
+                exported_by: {
+                    $ref: '#/$defs/Owner',
+                },
+                format: {
+                    pattern: '^datalayer-session/1$',
+                    title: 'Format',
+                    type: 'string',
+                },
+                harness: {
+                    anyOf: [
+                        {
+                            type: 'string',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    description: 'Its harness when the agent is one; null otherwise',
+                    title: 'Harness',
+                },
+                kinds: {
+                    description: "The kinds the application's record keeps: what is in the file",
+                    items: {
+                        enum: [
+                            'session',
+                            'run',
+                            'tool_call',
+                            'decision',
+                            'check',
+                            'approval',
+                            'output',
+                            'feedback',
+                            'turn',
+                            'notification',
+                            'step',
+                            'thread',
+                            'asked',
+                            'audio',
+                            'diff',
+                            'terminal',
+                            'file',
+                            'rule',
+                            'paused',
+                            'ended',
+                            'swapped',
+                            'cloned',
+                            'imported',
+                            'exported',
+                            'titled',
+                        ],
+                        type: 'string',
+                    },
+                    title: 'Kinds',
+                    type: 'array',
+                },
+                lineage: {
+                    $ref: '#/$defs/Lineage',
+                },
+                owner: {
+                    $ref: '#/$defs/Owner',
+                },
+                record_type: {
+                    pattern: '^session$',
+                    title: 'Record Type',
+                    type: 'string',
+                },
+                redactions: {
+                    description: 'How many values redaction replaced or dropped',
+                    minimum: 0,
+                    title: 'Redactions',
+                    type: 'integer',
+                },
+                state: {
+                    $ref: '#/$defs/SessionState',
+                },
+                title: {
+                    maxLength: 200,
+                    title: 'Title',
+                    type: 'string',
+                },
+                turns: {
+                    description: "The person's turns in the file: up to the last complete one",
+                    minimum: 0,
+                    title: 'Turns',
+                    type: 'integer',
+                },
+                uid: {
+                    title: 'Uid',
+                    type: 'string',
+                },
+            },
+            required: [
+                'record_type',
+                'format',
+                'uid',
+                'app',
+                'agent',
+                'harness',
+                'owner',
+                'state',
+                'turns',
+                'title',
+                'archived',
+                'lineage',
+                'kinds',
+                'entries',
+                'exported_at',
+                'exported_by',
+                'redactions',
+            ],
+            title: 'SessionLine',
+            type: 'object',
+        },
+        SessionState: {
+            description: "A session's state.",
+            enum: ['open', 'paused', 'ended'],
+            title: 'SessionState',
+            type: 'string',
+        },
+        TeamForkedFrom: {
+            additionalProperties: false,
+            description: "A team session clone's source: the run.",
+            properties: {
+                execution_id: {
+                    minLength: 1,
+                    title: 'Execution Id',
+                    type: 'string',
+                },
+            },
+            required: ['execution_id'],
+            title: 'TeamForkedFrom',
+            type: 'object',
+        },
+        TeamLine: {
+            additionalProperties: false,
+            description: "The first line of a team session's file: the run, then each seat's session follows.",
+            properties: {
+                execution_id: {
+                    minLength: 1,
+                    title: 'Execution Id',
+                    type: 'string',
+                },
+                exported_at: {
+                    minLength: 1,
+                    title: 'Exported At',
+                    type: 'string',
+                },
+                exported_by: {
+                    $ref: '#/$defs/Owner',
+                },
+                format: {
+                    pattern: '^datalayer-session/1$',
+                    title: 'Format',
+                    type: 'string',
+                },
+                lineage: {
+                    $ref: '#/$defs/TeamLineage',
+                },
+                owner: {
+                    $ref: '#/$defs/Owner',
+                },
+                record_type: {
+                    pattern: '^team_session$',
+                    title: 'Record Type',
+                    type: 'string',
+                },
+                redactions: {
+                    minimum: 0,
+                    title: 'Redactions',
+                    type: 'integer',
+                },
+                seats: {
+                    description: 'In order, each with its session uid; never empty',
+                    items: {
+                        $ref: '#/$defs/TeamSeat',
+                    },
+                    title: 'Seats',
+                    type: 'array',
+                },
+                state: {
+                    $ref: '#/$defs/SessionState',
+                },
+                team: {
+                    $ref: '#/$defs/TeamSpecRef',
+                },
+            },
+            required: [
+                'record_type',
+                'format',
+                'execution_id',
+                'team',
+                'owner',
+                'state',
+                'seats',
+                'lineage',
+                'exported_at',
+                'exported_by',
+                'redactions',
+            ],
+            title: 'TeamLine',
+            type: 'object',
+        },
+        TeamLineage: {
+            additionalProperties: false,
+            description: 'Where a team session came from.',
+            properties: {
+                forked_from: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/TeamForkedFrom',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                },
+                imported_from: {
+                    anyOf: [
+                        {
+                            $ref: '#/$defs/ImportedFrom',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                },
+            },
+            required: ['forked_from', 'imported_from'],
+            title: 'TeamLineage',
+            type: 'object',
+        },
+        TeamSeat: {
+            additionalProperties: false,
+            description: 'One seat of a team session, with its session.',
+            properties: {
+                agent: {
+                    minLength: 1,
+                    title: 'Agent',
+                    type: 'string',
+                },
+                harness: {
+                    anyOf: [
+                        {
+                            type: 'string',
+                        },
+                        {
+                            type: 'null',
+                        },
+                    ],
+                    title: 'Harness',
+                },
+                id: {
+                    minLength: 1,
+                    title: 'Id',
+                    type: 'string',
+                },
+                session_uid: {
+                    minLength: 1,
+                    title: 'Session Uid',
+                    type: 'string',
+                },
+            },
+            required: ['id', 'session_uid', 'agent', 'harness'],
+            title: 'TeamSeat',
+            type: 'object',
+        },
+        TeamSpecRef: {
+            additionalProperties: false,
+            description: 'The team spec a run was of.',
+            properties: {
+                id: {
+                    minLength: 1,
+                    title: 'Id',
+                    type: 'string',
+                },
+                version: {
+                    minLength: 1,
+                    title: 'Version',
+                    type: 'string',
+                },
+            },
+            required: ['id', 'version'],
+            title: 'TeamSpecRef',
+            type: 'object',
+        },
+    },
+    $id: 'https://agentspecs.datalayer.tech/schemas/session-file.json',
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    description: 'One line of a datalayer-session/1 file: the session, the team session, or an entry.',
+    oneOf: [
+        {
+            $ref: '#/$defs/SessionLine',
+        },
+        {
+            $ref: '#/$defs/EntryLine',
+        },
+        {
+            $ref: '#/$defs/TeamLine',
+        },
+    ],
+    title: 'SessionFileLine',
+};

package/lib/types/agentspecs.d.ts

@@ -219,6 +219,8 @@ export interface HarnessAcpSpec {
     modes: string[];
     /** Plain variables the launch needs, never a secret. */
     env: Record<string, string>;
+    /** Whether the adapter exposes the vendor's own session id (`meta`) or not (`none`). */
+    nativeSession: 'meta' | 'none';
 }
 /**
  * An agent program driven over the Agent Client Protocol
@@ -380,6 +382,25 @@ export interface ListedHarness {
     servedToThirdParties: 'api_key_only' | 'permitted' | 'refused' | 'unknown';
     note: string;
 }
+/** The capabilities table of a harness (`capabilities:` in `agentspecs/harnesses`). */
+export interface HarnessCapabilitiesSpec {
+    /** How its own session comes back after its process ended. */
+    resume: 'none' | 'load' | 'native';
+    /** What a clone carries of its history. */
+    forkHistory: 'none' | 'replay' | 'rebuild';
+    /** Whether a running turn can be cancelled. */
+    interrupt: boolean;
+    /** Whether it takes input mid-turn (false for every ACP harness). */
+    steering: boolean;
+    /** Whether a prompt may carry an image. */
+    images: boolean;
+    /** Who compacts the context window. */
+    compaction: 'own' | 'none';
+    /** The session modes a swap or a clone may set, as `acp.modes` names them. */
+    modes: string[];
+    /** The commands it runs without asking its client, one anchored regular expression per family; empty when it asks about every command. */
+    autoRun: string[];
+}
 export interface HarnessSpec {
     /** What `harness:` names (e.g. 'claude-code'). */
     id: string;
@@ -414,6 +435,11 @@ export interface HarnessSpec {
         model: boolean;
         subagents: boolean;
     };
+    /**
+     * What a session may rely on of it (MH-20): read by swap, clone and
+     * resume instead of branching on the harness's id.
+     */
+    capabilities: HarnessCapabilitiesSpec;
     /** The workspace file it reads its instructions from. */
     instructionsFile: string;
     /** The register's line: what was checked, and where. */

package/lib/types/chat.d.ts

@@ -62,6 +62,22 @@ export interface ToolCallCompleteContext {
     /** Error message, if the tool call failed */
     error?: string;
 }
+/**
+ * A tool call said again while it runs (VSCODE VS-24): a coding agent's
+ * terminal output so far, a diff as it grows — the display its update
+ * carries (`datalayer.harness.tool_call`, SH-13), handed to the host as
+ * the stream brings it, before `onToolCallComplete`.
+ */
+export interface ToolCallUpdateContext {
+    /** The tool name as declared by the agent */
+    toolName: string;
+    /** Unique identifier for this tool invocation */
+    toolCallId: string;
+    /** Arguments passed to the tool, as far as they are known */
+    args: Record<string, unknown>;
+    /** The display the update carries, read strictly (`portable/displays`) */
+    display: import('../portable/displays').ProtocolDisplay;
+}
 /**
  * View mode for the chat component.
  * - 'floating': Full-height floating panel (pinned to the right edge with offset)
@@ -528,6 +544,12 @@ export interface ChatCommonProps {
     onToolCallStart?: (context: ToolCallStartContext) => void;
     /** Post-hook: fires when a tool result is received */
     onToolCallComplete?: (context: ToolCallCompleteContext) => void;
+    /**
+     * Fires each time a running tool call's display is updated by the
+     * stream (a terminal's output as it streams, VS-24): a host drawing the
+     * display elsewhere — an editor's terminal — follows it as it comes.
+     */
+    onToolCallUpdate?: (context: ToolCallUpdateContext) => void;
     /** Suggestions to show in empty state */
     suggestions?: Suggestion[];
     /**
@@ -997,6 +1019,16 @@ export interface ChatBaseProps {
      * over. False for a host that wants the transcript bare.
      */
     showTurnFooter?: boolean;
+    /**
+     * The host's row under a message, beside the chat's own (*interrupted*,
+     * read aloud): nothing when it draws nothing. `at.turn` is the person's
+     * turn the message belongs to — the count of their messages up to and
+     * including it — so that an action on a turn's row names the turn
+     * (*Clone from here*).
+     */
+    renderMessageFooter?: (message: ChatMessage, at: {
+        turn: number;
+    }) => ReactNode;
     /**
      * Show notebook tool results as read-only surfaces in the transcript,
      * addressed to this notebook document id.
@@ -1308,6 +1340,12 @@ export interface ChatBaseProps {
      * ```
      */
     onToolCallComplete?: (context: ToolCallCompleteContext) => void;
+    /**
+     * Fires each time a running tool call's display is updated by the
+     * stream (a terminal's output as it streams, VS-24): a host drawing the
+     * display elsewhere — an editor's terminal — follows it as it comes.
+     */
+    onToolCallUpdate?: (context: ToolCallUpdateContext) => void;
     /**
      * The Agent Inspector's tracer: the agent's turns (`invoke_agent` spans:
      * its model, its tokens) and its tool calls (`execute_tool` spans), from

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@datalayer/agent-runtimes",
-    "version": "1.5.65",
+    "version": "1.5.70",
     "type": "module",
     "workspaces": [
         ".",