@ai-matrx/coding-sessions 0.1.83 → 0.1.86

package/dist/react/index.d.cts

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react';
+import { JsonValue } from '@ai-matrx/agents/portable';
 import { ChatThreadStore, ChatMessage } from '@ai-matrx/chat';
 
 /**
@@ -7,6 +8,7 @@ import { ChatThreadStore, ChatMessage } from '@ai-matrx/chat';
  * touches Node or the DOM, and every value is JSON-serializable because it
  * crosses a transport (WebSocket today, desktop IPC later).
  */
+
 /** The coding agents this package drives. "coding session" is the canonical
  *  platform term (chat.coding_session, the Coding Session Bridge). */
 type CodingProvider = "claude" | "codex";
@@ -192,6 +194,10 @@ interface CodingSession {
     lastRunStatus: RunStatus | null;
     /** Prompts waiting for the active run to finish, oldest first. */
     queued: string[];
+    /** The AI Matrx agent loaded into every run of this session, when one was picked. */
+    agent?: SessionAgent | null | undefined;
+    /** Codex must be told, in the next prompt, that an earlier agent no longer applies. */
+    agentRemovedDue?: boolean | undefined;
 }
 /**
  * One normalized transcript item — the same shape from Claude and Codex, from
@@ -272,12 +278,105 @@ interface StartInput {
     prompt: string;
     model?: string | null | undefined;
     effort?: string | null | undefined;
+    /** An AI Matrx agent to load into the CLI. Needs the host's `agents` credentials. */
+    agent?: AgentSelection | null | undefined;
+}
+/** Which AI Matrx agent a new session loads, and the person's variable values. */
+interface AgentSelection {
+    agentId: string;
+    /** Pin one saved version; omitted = the latest, pinned at start. */
+    versionId?: string | null | undefined;
+    variables?: Record<string, JsonValue> | undefined;
+}
+/** One part of an agent and whether this session's CLI carries it. */
+interface SessionAgentPart {
+    part: "instructions" | "skills" | "tools";
+    loaded: number;
+    total: number;
+}
+/**
+ * The agent a session runs with. Recorded at start and never drifts: every
+ * later turn reloads the SAME bundle (same version, same hash).
+ */
+interface SessionAgent {
+    agentId: string;
+    versionId: string | null;
+    versionNumber: number | null;
+    name: string;
+    definitionHash: string;
+    loaded: SessionAgentPart[];
+    /** What could not be carried, with the reason. */
+    unavailable: {
+        kind: string;
+        name: string;
+        reason: string;
+    }[];
+    /** The skills it carries (labels) and the tools it serves (names) — the agent's own set. */
+    skills?: string[] | undefined;
+    tools?: string[] | undefined;
+    /** The person's variable values, kept so "Update to vN" can reuse them. */
+    variables?: Record<string, JsonValue> | undefined;
+    /**
+     * The CLI must be TOLD in the next prompt (a delimited block): a Codex
+     * takeover or agent switch (Codex ignores developer_instructions on resume),
+     * or a Codex compaction that dropped the block. Cleared once delivered.
+     */
+    blockDue?: boolean | undefined;
+    /** When the block (or native instructions) last reached the CLI. */
+    deliveredAt?: string | null | undefined;
+}
+/** Whether this host can reach AI Matrx as a signed-in person. */
+interface AgentAccess {
+    signedIn: boolean;
+    userId: string | null;
+    organizationId: string | null;
+    /** True when the host was started with no AI Matrx connection at all. */
+    configured: boolean;
+}
+/** A catalogue read the picker asks the host to make (PostgREST RPC shape). */
+interface AgentCatalogRpcRequest {
+    fn: string;
+    args?: Record<string, unknown> | undefined;
+    count?: "exact" | "planned" | "estimated" | undefined;
+    range?: [number, number] | undefined;
+    order?: {
+        column: string;
+        ascending?: boolean | undefined;
+    } | undefined;
+}
+interface AgentCatalogRpcResult {
+    data: unknown;
+    error: {
+        message: string;
+        code?: string | undefined;
+        details?: string | null | undefined;
+        hint?: string | null | undefined;
+    } | null;
+    count?: number | null;
+}
+/** What a picker needs about one agent — the LIGHT read (no skills, no tools). */
+interface AgentDetails {
+    agentId: string;
+    name: string;
+    /** Variable declarations as authored (camelCase). */
+    variables: Record<string, JsonValue>[];
+    /** Newest first. */
+    versions: {
+        id: string;
+        versionNumber: number;
+        changedAt: string | null;
+    }[];
+    /** The version "Latest" resolves to right now. */
+    latestVersionNumber: number | null;
+    latestVersionId: string | null;
 }
 interface TakeoverInput {
     provider: CodingProvider;
     providerSessionId: string;
     cwd: string;
     title?: string | undefined;
+    /** Continue the chat WITH an AI Matrx agent ("Continue with agent"). */
+    agent?: AgentSelection | null | undefined;
 }
 interface SendResult {
     session: CodingSession;
@@ -348,6 +447,18 @@ interface CodingSessionsApi {
         model?: string | null;
         effort?: string | null;
     }): Promise<CodingSession>;
+    /** Is this host signed in to AI Matrx (so agents can load)? */
+    agentAccess(): Promise<AgentAccess>;
+    /** One allowlisted agent-catalogue read, made by the host as the signed-in person. */
+    agentCatalogRpc(request: AgentCatalogRpcRequest): Promise<AgentCatalogRpcResult>;
+    /** An agent's variables and saved versions, for the New session form. */
+    agentDetails(agentId: string): Promise<AgentDetails>;
+    /**
+     * Load a different agent into a session from its next message on (or
+     * remove it, with `null`). Claude reads it every turn; Codex is told in the
+     * next prompt.
+     */
+    setAgent(sessionId: string, agent: AgentSelection | null): Promise<CodingSession>;
 }
 type RawTranscript = {
     available: true;
@@ -501,14 +612,8 @@ declare class CodingSessionsClient {
     refreshAll: () => Promise<void>;
     transcript(sessionId: string): SessionTranscript;
     readPreview(provider: CodingProvider, providerSessionId: string, maxBytes?: number): Promise<PreviewState>;
-    start(input: {
-        provider: CodingProvider;
-        cwd: string;
-        prompt: string;
-        model?: string | null;
-        effort?: string | null;
-    }): Promise<SendResult>;
-    takeover(session: DiscoveredSession): Promise<CodingSession>;
+    start(input: StartInput): Promise<SendResult>;
+    takeover(session: DiscoveredSession, agent?: AgentSelection | null): Promise<CodingSession>;
     send(sessionId: string, prompt: string): Promise<SendResult>;
     stop(runId: string): Promise<RunRecord | null>;
 }

package/dist/react/index.d.ts

@@ -1,4 +1,5 @@
 import { ReactNode } from 'react';
+import { JsonValue } from '@ai-matrx/agents/portable';
 import { ChatThreadStore, ChatMessage } from '@ai-matrx/chat';
 
 /**
@@ -7,6 +8,7 @@ import { ChatThreadStore, ChatMessage } from '@ai-matrx/chat';
  * touches Node or the DOM, and every value is JSON-serializable because it
  * crosses a transport (WebSocket today, desktop IPC later).
  */
+
 /** The coding agents this package drives. "coding session" is the canonical
  *  platform term (chat.coding_session, the Coding Session Bridge). */
 type CodingProvider = "claude" | "codex";
@@ -192,6 +194,10 @@ interface CodingSession {
     lastRunStatus: RunStatus | null;
     /** Prompts waiting for the active run to finish, oldest first. */
     queued: string[];
+    /** The AI Matrx agent loaded into every run of this session, when one was picked. */
+    agent?: SessionAgent | null | undefined;
+    /** Codex must be told, in the next prompt, that an earlier agent no longer applies. */
+    agentRemovedDue?: boolean | undefined;
 }
 /**
  * One normalized transcript item — the same shape from Claude and Codex, from
@@ -272,12 +278,105 @@ interface StartInput {
     prompt: string;
     model?: string | null | undefined;
     effort?: string | null | undefined;
+    /** An AI Matrx agent to load into the CLI. Needs the host's `agents` credentials. */
+    agent?: AgentSelection | null | undefined;
+}
+/** Which AI Matrx agent a new session loads, and the person's variable values. */
+interface AgentSelection {
+    agentId: string;
+    /** Pin one saved version; omitted = the latest, pinned at start. */
+    versionId?: string | null | undefined;
+    variables?: Record<string, JsonValue> | undefined;
+}
+/** One part of an agent and whether this session's CLI carries it. */
+interface SessionAgentPart {
+    part: "instructions" | "skills" | "tools";
+    loaded: number;
+    total: number;
+}
+/**
+ * The agent a session runs with. Recorded at start and never drifts: every
+ * later turn reloads the SAME bundle (same version, same hash).
+ */
+interface SessionAgent {
+    agentId: string;
+    versionId: string | null;
+    versionNumber: number | null;
+    name: string;
+    definitionHash: string;
+    loaded: SessionAgentPart[];
+    /** What could not be carried, with the reason. */
+    unavailable: {
+        kind: string;
+        name: string;
+        reason: string;
+    }[];
+    /** The skills it carries (labels) and the tools it serves (names) — the agent's own set. */
+    skills?: string[] | undefined;
+    tools?: string[] | undefined;
+    /** The person's variable values, kept so "Update to vN" can reuse them. */
+    variables?: Record<string, JsonValue> | undefined;
+    /**
+     * The CLI must be TOLD in the next prompt (a delimited block): a Codex
+     * takeover or agent switch (Codex ignores developer_instructions on resume),
+     * or a Codex compaction that dropped the block. Cleared once delivered.
+     */
+    blockDue?: boolean | undefined;
+    /** When the block (or native instructions) last reached the CLI. */
+    deliveredAt?: string | null | undefined;
+}
+/** Whether this host can reach AI Matrx as a signed-in person. */
+interface AgentAccess {
+    signedIn: boolean;
+    userId: string | null;
+    organizationId: string | null;
+    /** True when the host was started with no AI Matrx connection at all. */
+    configured: boolean;
+}
+/** A catalogue read the picker asks the host to make (PostgREST RPC shape). */
+interface AgentCatalogRpcRequest {
+    fn: string;
+    args?: Record<string, unknown> | undefined;
+    count?: "exact" | "planned" | "estimated" | undefined;
+    range?: [number, number] | undefined;
+    order?: {
+        column: string;
+        ascending?: boolean | undefined;
+    } | undefined;
+}
+interface AgentCatalogRpcResult {
+    data: unknown;
+    error: {
+        message: string;
+        code?: string | undefined;
+        details?: string | null | undefined;
+        hint?: string | null | undefined;
+    } | null;
+    count?: number | null;
+}
+/** What a picker needs about one agent — the LIGHT read (no skills, no tools). */
+interface AgentDetails {
+    agentId: string;
+    name: string;
+    /** Variable declarations as authored (camelCase). */
+    variables: Record<string, JsonValue>[];
+    /** Newest first. */
+    versions: {
+        id: string;
+        versionNumber: number;
+        changedAt: string | null;
+    }[];
+    /** The version "Latest" resolves to right now. */
+    latestVersionNumber: number | null;
+    latestVersionId: string | null;
 }
 interface TakeoverInput {
     provider: CodingProvider;
     providerSessionId: string;
     cwd: string;
     title?: string | undefined;
+    /** Continue the chat WITH an AI Matrx agent ("Continue with agent"). */
+    agent?: AgentSelection | null | undefined;
 }
 interface SendResult {
     session: CodingSession;
@@ -348,6 +447,18 @@ interface CodingSessionsApi {
         model?: string | null;
         effort?: string | null;
     }): Promise<CodingSession>;
+    /** Is this host signed in to AI Matrx (so agents can load)? */
+    agentAccess(): Promise<AgentAccess>;
+    /** One allowlisted agent-catalogue read, made by the host as the signed-in person. */
+    agentCatalogRpc(request: AgentCatalogRpcRequest): Promise<AgentCatalogRpcResult>;
+    /** An agent's variables and saved versions, for the New session form. */
+    agentDetails(agentId: string): Promise<AgentDetails>;
+    /**
+     * Load a different agent into a session from its next message on (or
+     * remove it, with `null`). Claude reads it every turn; Codex is told in the
+     * next prompt.
+     */
+    setAgent(sessionId: string, agent: AgentSelection | null): Promise<CodingSession>;
 }
 type RawTranscript = {
     available: true;
@@ -501,14 +612,8 @@ declare class CodingSessionsClient {
     refreshAll: () => Promise<void>;
     transcript(sessionId: string): SessionTranscript;
     readPreview(provider: CodingProvider, providerSessionId: string, maxBytes?: number): Promise<PreviewState>;
-    start(input: {
-        provider: CodingProvider;
-        cwd: string;
-        prompt: string;
-        model?: string | null;
-        effort?: string | null;
-    }): Promise<SendResult>;
-    takeover(session: DiscoveredSession): Promise<CodingSession>;
+    start(input: StartInput): Promise<SendResult>;
+    takeover(session: DiscoveredSession, agent?: AgentSelection | null): Promise<CodingSession>;
     send(sessionId: string, prompt: string): Promise<SendResult>;
     stop(runId: string): Promise<RunRecord | null>;
 }