@vertesia/common 1.4.0-dev.20260615.051508Z → 1.4.0-dev.20260629.130134Z

package/src/store/conversation-state.ts

@@ -1,6 +1,7 @@
 import type { CompletionResult, ExecutionTokenUsage, StatelessExecutionOptions, ToolUse } from '@llumiverse/common';
 import type { ConversationStripOptions, ResolvedInteractionExecutionInfo, UserChannel } from '../interaction.js';
 import type { ExecutionRunDocRef } from '../runs.js';
+import type { AgentToolApprovalMode, PendingToolApprovalResults, ToolApprovalGrant } from './agent-approval.js';
 import type { Plan, WorkflowAncestor } from './workflow.js';
 
 /**
@@ -13,34 +14,6 @@ export interface ToolReference {
     stored_at: string;
 }
 
-/** Reference to text content externalized to agent artifact storage. */
-export interface TextArtifactReference {
-    storage_id: string;
-    artifact_path: string;
-    display_ref: string;
-    sha256: string;
-    size_bytes: number;
-    content_type: string;
-}
-
-/**
- * Sidecar metadata for generated tool input fields that were stored outside
- * model-visible tool_input. Keyed by tool_use.id on ConversationState.
- */
-export interface ExternalizedToolInputRef {
-    tool_name: string;
-    input_path: ['content'];
-    ref: TextArtifactReference;
-}
-
-export interface ExternalizedToolInputRefs {
-    [toolUseId: string]: ExternalizedToolInputRef[];
-}
-
-export function toolInputRefsArtifactPath(storageId: string): string {
-    return `agents/${storageId}/tool-input-refs.json`;
-}
-
 /**
  * Conversation state passed between workflow activities.
  * Contains all context needed to continue a multi-turn agent conversation.
@@ -66,14 +39,17 @@ export interface ConversationState {
      */
     tool_use?: ToolUse[];
 
-    /**
-     * Transport sidecar for large generated tool input fields.
-     *
-     * These refs are intentionally kept out of tool_use.tool_input so they are
-     * not shown to the model. Tool execution hydrates them from artifact storage
-     * immediately before activity validation.
-     */
-    tool_input_refs?: ExternalizedToolInputRefs;
+    /** Effective side-effecting tool approval mode for this interactive conversation. */
+    tool_approval_mode?: AgentToolApprovalMode;
+
+    /** Run-scoped, exact-target grants created by "allow this action for this run". */
+    tool_approval_grants?: Record<string, ToolApprovalGrant>;
+
+    /** Buffered tool results held while approval denial pauses until the next user message. */
+    pending_tool_approval_results?: PendingToolApprovalResults;
+
+    /** Compact, redacted latest user intent for reviewer-style system interactions. */
+    latest_user_message?: string;
 
     /**
      * The output of the this conversation step
@@ -168,12 +144,44 @@ export interface ConversationState {
      */
     latest_activity_id?: string;
 
+    /**
+     * Stable streaming ID from the latest LLM call.
+     * Unlike Temporal activity IDs, this is scoped to the concrete workflow run
+     * that produced the stream, so it remains safe across continue-as-new.
+     */
+    latest_streaming_id?: string;
+
     /**
      * Mapping of skill names to their related tools.
      * When a skill is called, its related tools are added to unlocked_tools.
      */
     skill_tool_map?: Record<string, string[]>;
 
+    /**
+     * Names of skills whose full instructions are already present in the live conversation
+     * history (i.e. were delivered by a prior `learn_<skill>` call). Used to make skill
+     * re-activation idempotent: a repeat call returns a short "already active" acknowledgement
+     * instead of re-dumping the instructions.
+     *
+     * Unlike `unlocked_tools`/`skill_tool_map` (which must survive a checkpoint so tools stay
+     * unlocked), this list is reset when a checkpoint compacts the conversation, because the
+     * summary no longer carries the skill instructions and the next call must re-deliver them.
+     */
+    skill_instructions_delivered?: string[];
+
+    /**
+     * Denylist of MCP tool-collection ids deactivated for this conversation.
+     * `undefined`/empty means all installed/connected MCP collections are active.
+     * Updated mid-conversation via the MCP config signal; consumed when tools are re-discovered.
+     */
+    disabled_mcp_collections?: string[];
+
+    /**
+     * MCP servers that are active (not disabled) and accessible to the user but not yet
+     * OAuth-connected. Surfaced to the agent (via discover_tools) so it can offer to connect.
+     */
+    pending_mcp_connections?: PendingMcpConnection[];
+
     /**
      * Current activity group ID for internal tool-execution progress messages.
      * All updates emitted during one tool-execution cycle should share this ID.
@@ -198,6 +206,24 @@ export interface ConversationState {
     launch_id?: string;
 }
 
+/**
+ * An MCP server the user can connect to but hasn't yet (active + accessible, no OAuth token).
+ * Built at tool-discovery time and stored on the conversation state so the agent can
+ * discover it (by description) and ask the user to connect.
+ */
+export interface PendingMcpConnection {
+    /** The app installation id owning the collection (used for OAuth operations). */
+    app_install_id: string;
+    /** The MCP tool-collection id. */
+    collection_id: string;
+    /** Human-readable label for the server/collection. */
+    name: string;
+    /** Manifest description of what the server provides (used for discovery). */
+    description?: string;
+    /** Tool-name prefix for this collection. */
+    namespace?: string;
+}
+
 /** Skill metadata collected at workflow start for upfront sandbox hydration */
 export interface AvailableSkill {
     /** Skill name (e.g., "analyze_data") - without the "learn_" prefix */

package/src/store/index.ts

@@ -1,4 +1,5 @@
 export * from './activity-catalog.js';
+export * from './agent-approval.js';
 export * from './agent-run.js';
 export * from './collections.js';
 export * from './common.js';

package/src/store/signals.ts

@@ -1,5 +1,10 @@
 export interface UserInputSignal {
     message: string;
+    /**
+     * Client-generated id used to correlate a UserInput signal with the
+     * persisted QUESTION message emitted by the workflow.
+     */
+    client_message_id?: string;
     metadata?: Record<string, unknown>;
     auth_token?: string;
     /**
@@ -10,6 +15,17 @@ export interface UserInputSignal {
     attachments?: Attachment[];
 }
 
+export interface StopSignal {
+    message?: string;
+    /**
+     * Client-generated id used to correlate a Stop signal with the persisted
+     * IDLE marker emitted by the workflow.
+     */
+    client_message_id?: string;
+    metadata?: Record<string, unknown>;
+    auth_token?: string;
+}
+
 /**
  * Attachment metadata for processing in conversation workflows.
  */

package/src/store/workflow.test.ts

@@ -160,6 +160,28 @@ describe('CompactMessage converters', () => {
             expect(compact.d).toEqual({ plan: [{ id: 1, goal: 'Step 1' }] });
         });
 
+        it('preserves user message acknowledgement details', () => {
+            const legacy: AgentMessage = {
+                type: AgentMessageType.QUESTION,
+                timestamp: 1234567890,
+                workflow_run_id: 'run-123',
+                message: 'Follow up',
+                details: {
+                    event_class: 'user_content',
+                    ack: 'message-1',
+                    _deliveryStatus: 'consumed',
+                },
+            };
+
+            const compact = toCompactMessage(legacy);
+
+            expect(compact.d).toEqual({
+                event_class: 'user_content',
+                ack: 'message-1',
+                _deliveryStatus: 'consumed',
+            });
+        });
+
         it('handles streaming chunk with is_final flag', () => {
             const legacy: AgentMessage = {
                 type: AgentMessageType.STREAMING_CHUNK,
@@ -199,6 +221,24 @@ describe('CompactMessage converters', () => {
             expect(compact.f).toBeUndefined();
         });
 
+        it('restores run-scoped streaming id from compact streaming chunk details', () => {
+            const compact: CompactMessage = {
+                t: AgentMessageType.STREAMING_CHUNK,
+                m: 'chunk content',
+                i: 'activity-7',
+                d: {
+                    streaming_id: 'run-2-activity-7',
+                    streaming_id_scope: 'workflow_run',
+                },
+            };
+
+            const restored = toAgentMessage(compact, 'workflow-id');
+
+            expect(restored.details?.streaming_id).toBe('run-2-activity-7');
+            expect(restored.details?.streaming_id_scope).toBe('workflow_run');
+            expect(restored.details?.activity_id).toBe('activity-7');
+        });
+
         it('normalizes legacy string type values', () => {
             // Simulate a message from Redis with old string type
             const legacy = {
@@ -282,6 +322,26 @@ describe('CompactMessage converters', () => {
             expect(legacy.details).toEqual({ batch_id: 'batch-1', completed: 5, total: 10 });
         });
 
+        it('restores user message acknowledgement details', () => {
+            const compact: CompactMessage = {
+                t: AgentMessageType.QUESTION,
+                m: 'Follow up',
+                d: {
+                    event_class: 'user_content',
+                    ack: 'message-1',
+                    _deliveryStatus: 'consumed',
+                },
+            };
+
+            const legacy = toAgentMessage(compact, 'run-1');
+
+            expect(legacy.details).toEqual({
+                event_class: 'user_content',
+                ack: 'message-1',
+                _deliveryStatus: 'consumed',
+            });
+        });
+
         it('restores streaming chunk details with is_final', () => {
             const compact: CompactMessage = {
                 t: AgentMessageType.STREAMING_CHUNK,

package/src/store/workflow.ts

@@ -1,4 +1,4 @@
-import type { HttpTimeoutOptions, ModelOptions } from '@llumiverse/common';
+import type { ExecutionTokenUsage, HttpTimeoutOptions, ModelOptions } from '@llumiverse/common';
 import type {
     ConversationVisibility,
     InteractionExecutionConfiguration,
@@ -7,6 +7,7 @@ import type {
 } from '../interaction.js';
 import type { JSONObject, JSONValue } from '../json.js';
 import type { JSONSchema } from '../json-schema.js';
+import type { AgentToolApprovalMode } from './agent-approval.js';
 import type { WorkflowInput } from './dsl-workflow.js';
 
 export enum ContentEventName {
@@ -638,6 +639,7 @@ export interface WorkflowInteractionVars {
     type: string;
     interaction: string;
     interactive: boolean;
+    tool_approval_mode?: AgentToolApprovalMode;
     debug_mode?: boolean;
     non_blocking_subagents?: boolean;
     /**
@@ -654,6 +656,11 @@ export interface WorkflowInteractionVars {
     };
     interactionParamsSchema?: JSONSchema;
     collection_id?: string;
+    /**
+     * Denylist of MCP tool-collection ids deactivated for this conversation.
+     * `undefined`/empty ⇒ all installed/connected MCP collections are active.
+     */
+    disabled_mcp_collections?: string[];
     /**
      * The token threshold in thousands (K) for creating checkpoints.
      * If total tokens exceed this value, a checkpoint will be created.
@@ -736,6 +743,7 @@ export enum AgentMessageType {
 }
 
 export interface AgentMessageDetails extends Record<string, unknown> {
+    ack?: string;
     event_class?: string;
     tool?: string;
     tools?: string[];
@@ -752,15 +760,20 @@ export interface AgentMessageDetails extends Record<string, unknown> {
     message_to_human?: string;
     duration_ms?: number;
     observation?: unknown;
+    token_usage?: ExecutionTokenUsage;
+    checkpoint_at?: number;
+    checkpoint_threshold?: number;
     workflow_run_id?: string;
     outputFiles?: string[];
     files?: ConversationFile[] | string[];
     plan?: PlanTask[];
     streaming_id?: string;
+    streaming_id_scope?: 'workflow_run' | 'workstream';
     chunk_index?: number;
     is_final?: boolean;
     _optimistic?: boolean;
     _messageId?: string;
+    _deliveryStatus?: 'sending' | 'received' | 'consumed' | 'failed';
 }
 
 // ============================================
@@ -871,7 +884,7 @@ export interface StreamingChunkDetails {
     /** Unique identifier grouping chunks from the same stream */
     streaming_id: string;
     /** Order of this chunk within the stream (0-indexed) */
-    chunk_index: number;
+    chunk_index?: number;
     /** True if this is the final chunk of the stream */
     is_final: boolean;
     /** Activity ID for deduplication with final THOUGHT/ANSWER message */
@@ -1063,14 +1076,18 @@ export function toAgentMessage(compact: CompactMessage, workflowRunId: string =
 
     if (compact.d !== undefined && compact.d !== null) message.details = compact.d;
 
-    // For streaming chunks, restore is_final and streaming_id in details
-    // (streaming_id removed from wire format, use workstream_id as grouping key)
+    // For streaming chunks, restore is_final and preserve an explicit streaming_id
+    // when present. Older chunks fall back to workstream_id as their grouping key.
     if (compact.t === AgentMessageType.STREAMING_CHUNK) {
+        const details: AgentMessageDetails = typeof compact.d === 'object' && compact.d !== null ? compact.d : {};
+        const streamingId = typeof details.streaming_id === 'string' ? details.streaming_id : compact.w || 'main';
+        const activityId = compact.i ?? (typeof details.activity_id === 'string' ? details.activity_id : undefined);
+
         message.details = {
-            ...(typeof compact.d === 'object' ? compact.d : {}),
-            streaming_id: compact.w || 'main', // Use workstream_id as streaming_id
+            ...details,
+            streaming_id: streamingId,
             is_final: compact.f === 1,
-            activity_id: compact.i, // For deduplication with final THOUGHT/ANSWER
+            ...(activityId ? { activity_id: activityId } : {}),
         };
     }
 
@@ -1393,6 +1410,7 @@ export interface WorkstreamProgressInfo {
 export interface ActiveWorkstreamEntry {
     launch_id: string;
     workstream_id: string;
+    kind?: 'agent' | 'process';
     interaction: string;
     started_at: number;
     elapsed_ms: number;
@@ -1403,9 +1421,35 @@ export interface ActiveWorkstreamEntry {
     child_workflow_id: string;
     /** Child workflow run ID — use with retrieveMessages / streamMessages */
     child_workflow_run_id?: string;
+    process_run_id?: string;
+    process_workflow_id?: string;
+    process_name?: string;
+    process_run_type?: 'programmatic' | 'supervised';
+}
+
+/** Recently completed workstream entry returned by the ActiveWorkstreams query */
+export interface CompletedWorkstreamEntry {
+    launch_id: string;
+    workstream_id: string;
+    kind?: 'agent' | 'process';
+    status: 'completed' | 'failed' | 'canceled' | 'timeout';
+    summary?: string;
+    error?: string;
+    duration_ms?: number;
+    started_at?: number;
+    interaction?: string;
+    last_progress?: WorkstreamProgressInfo;
+    child_workflow_id?: string;
+    child_workflow_run_id?: string;
+    process_run_id?: string;
+    process_workflow_id?: string;
+    process_name?: string;
 }
 
 /** Result of the ActiveWorkstreams Temporal query */
 export interface ActiveWorkstreamsQueryResult {
     running: ActiveWorkstreamEntry[];
+    completed?: CompletedWorkstreamEntry[];
+    /** True when the workflow could not answer this optional query. */
+    unavailable?: boolean;
 }

package/src/sts-token-types.ts

@@ -2,7 +2,7 @@
  * STS Token Request Types
  * These types define the structure for token requests to the Security Token Service
  */
-import type { ProjectRoles } from './project.js';
+import type { SystemRoles } from './project.js';
 
 export type TokenType = 'apikey' | 'user' | 'project' | 'environment' | 'agent' | 'service_account';
 export type SigningAlgorithm = 'ES256' | 'RS256';
@@ -81,7 +81,7 @@ export interface ServiceAccountTokenRequest extends BaseTokenRequest {
     type: 'service_account';
     account_id: string;
     project_id: string; // Will verify it belongs to account
-    roles?: ProjectRoles[]; // Optional - roles for the service account token
+    roles?: SystemRoles[]; // Optional - roles for the service account token
     name?: string;
 }
 

package/src/transient-tokens.ts

@@ -1,4 +1,4 @@
-import type { ProjectRef, ProjectRoles } from './project.js';
+import type { ProjectRef, SystemRoles } from './project.js';
 import type { AccountRef, UserRef } from './user.js';
 
 export enum TransientTokenType {
@@ -20,7 +20,7 @@ export interface CreateOrUpdateTransientTokenPayload<T> extends Partial<Transien
 
 export interface UserInviteTokenData {
     email: string;
-    role: ProjectRoles;
+    role: SystemRoles;
     account: AccountRef;
     project?: ProjectRef;
     invited_by: UserRef;

package/src/user.ts

@@ -1,5 +1,5 @@
 import type { ApiKey } from './apikey.js';
-import type { ProjectRef, ProjectRoles } from './project.js';
+import type { ProjectRef, SystemRoles } from './project.js';
 
 export interface UserWithAccounts extends User {
     accounts: AccountRef[];
@@ -110,7 +110,7 @@ export const AccountRefPopulate = 'id name';
 
 export interface InviteUserRequestPayload {
     email: string;
-    role: ProjectRoles;
+    role: SystemRoles;
 }
 
 export interface InviteUserResponsePayload {

package/lib/roles.d.ts

@@ -1,19 +0,0 @@
-import { Permission } from './access-control.js';
-import { ProjectRoles } from './project.js';
-export declare class Role {
-    name: ProjectRoles;
-    permissions: Set<Permission>;
-    constructor(name: ProjectRoles, permissions: Permission[]);
-    hasPermission(permission: Permission): boolean;
-}
-export declare class RoleList {
-    readonly roles: Role[];
-    private constructor();
-    static fromRoleNames(roleNames: ProjectRoles[]): RoleList;
-    static fromRoleName(roleName: ProjectRoles): RoleList;
-    hasPermission(perm: Permission): boolean;
-}
-export declare function getRoleByName(name: ProjectRoles): Role;
-export declare function listRoles(): Role[];
-export declare function getPermissionsForRoles(roleNames: Iterable<ProjectRoles>): Permission[];
-//# sourceMappingURL=roles.d.ts.map

package/lib/roles.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"roles.d.ts","sourceRoot":"","sources":["../src/roles.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAE5C,qBAAa,IAAI;IAGF,IAAI,EAAE,YAAY;IAF7B,WAAW,EAAE,GAAG,CAAC,UAAU,CAAC,CAAC;gBAElB,IAAI,EAAE,YAAY,EACzB,WAAW,EAAE,UAAU,EAAE;IAK7B,aAAa,CAAC,UAAU,EAAE,UAAU;CAGvC;AAED,qBAAa,QAAQ;aACmB,KAAK,EAAE,IAAI,EAAE;IAAjD,OAAO;IAEP,MAAM,CAAC,aAAa,CAAC,SAAS,EAAE,YAAY,EAAE,GAAG,QAAQ;IAKzD,MAAM,CAAC,YAAY,CAAC,QAAQ,EAAE,YAAY,GAAG,QAAQ;IAKrD,aAAa,CAAC,IAAI,EAAE,UAAU,GAAG,OAAO;CAG3C;AAsMD,wBAAgB,aAAa,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAItD;AAED,wBAAgB,SAAS,IAAI,IAAI,EAAE,CAElC;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,QAAQ,CAAC,YAAY,CAAC,GAAG,UAAU,EAAE,CAStF"}