@vertesia/common 1.5.0-dev.20260722.120446Z → 1.5.0-dev.20260725.083715Z

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vertesia/common",
-  "version": "1.5.0-dev.20260722.120446Z",
+  "version": "1.5.0-dev.20260725.083715Z",
   "license": "Apache-2.0",
   "type": "module",
   "main": "./lib/index.js",
@@ -17,14 +17,14 @@
     }
   },
   "devDependencies": {
-    "rolldown": "1.1.5",
+    "rolldown": "1.2.0",
     "typescript": "^6.0.3",
     "vitest": "^4.1.10",
     "@vertesia/tsconfig": "0.1.0"
   },
   "dependencies": {
     "ajv": "^8.20.0",
-    "@llumiverse/common": "1.5.0-dev.20260722.112223Z"
+    "@llumiverse/common": "1.5.0-dev.20260725.065646Z"
   },
   "repository": {
     "type": "git",
@@ -39,7 +39,7 @@
     "ai",
     "typescript"
   ],
-  "gitHead": "203c30e5a8ddc583ac9f1acce0f5445eb38a9551",
+  "gitHead": "57bcc2f27dd17b3387f27c18e89329c4c37f98ac",
   "scripts": {
     "lint": "biome lint src",
     "test": "vitest run",

package/src/agent-resources.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, it } from 'vitest';
+import { type AgentResourceReference, getResourcesFromToolResult, normalizeAgentResources } from './interaction.js';
+import { AgentMessageType, getResourcesFromMessage } from './store/workflow.js';
+
+const validRef: AgentResourceReference = {
+    type: 'document',
+    id: 'doc-1',
+    label: 'My Document',
+    action: 'created',
+};
+
+describe('normalizeAgentResources', () => {
+    it('returns an empty array for non-array input', () => {
+        expect(normalizeAgentResources(undefined)).toEqual([]);
+        expect(normalizeAgentResources(null)).toEqual([]);
+        expect(normalizeAgentResources('nope')).toEqual([]);
+        expect(normalizeAgentResources({})).toEqual([]);
+    });
+
+    it('keeps a well-formed reference', () => {
+        expect(normalizeAgentResources([validRef])).toEqual([validRef]);
+    });
+
+    it('preserves revision_id when present and non-empty', () => {
+        const ref = { ...validRef, revision_id: 'rev-9' };
+        expect(normalizeAgentResources([ref])).toEqual([ref]);
+    });
+
+    it('drops an empty revision_id rather than keeping it', () => {
+        const result = normalizeAgentResources([{ ...validRef, revision_id: '' }]);
+        expect(result[0]).not.toHaveProperty('revision_id');
+    });
+
+    it('falls back to the id when the label is missing or empty', () => {
+        const result = normalizeAgentResources([{ type: 'collection', id: 'col-1', action: 'updated' }]);
+        expect(result).toEqual([{ type: 'collection', id: 'col-1', label: 'col-1', action: 'updated' }]);
+    });
+
+    it('drops entries with an unknown type or action', () => {
+        const result = normalizeAgentResources([
+            { type: 'artifact', id: 'a', label: 'a', action: 'created' },
+            { type: 'document', id: 'd', label: 'd', action: 'viewed' },
+            { type: 'document', id: '', label: 'd', action: 'created' },
+            validRef,
+        ]);
+        expect(result).toEqual([validRef]);
+    });
+
+    it('accepts every supported resource type', () => {
+        const types = [
+            'document',
+            'collection',
+            'content_type',
+            'interaction',
+            'prompt',
+            'agent',
+            'workflow',
+            'process',
+            'process_run',
+            'interaction_run',
+            'view',
+        ] as const;
+        const input = types.map((type, i) => ({ type, id: `id-${i}`, label: `L${i}`, action: 'created' }));
+        expect(normalizeAgentResources(input)).toHaveLength(types.length);
+    });
+});
+
+describe('getResourcesFromToolResult', () => {
+    it('reads resources from result meta', () => {
+        expect(getResourcesFromToolResult({ meta: { resources: [validRef] } })).toEqual([validRef]);
+    });
+
+    it('returns an empty array when meta or resources are absent', () => {
+        expect(getResourcesFromToolResult({})).toEqual([]);
+        expect(getResourcesFromToolResult({ meta: {} })).toEqual([]);
+    });
+});
+
+describe('getResourcesFromMessage', () => {
+    it('reads resources from message details', () => {
+        const msg = {
+            timestamp: 0,
+            workflow_run_id: 'run-1',
+            type: AgentMessageType.THOUGHT,
+            message: '',
+            details: { event_class: 'activity', resources: [validRef] },
+        };
+        expect(getResourcesFromMessage(msg)).toEqual([validRef]);
+    });
+
+    it('returns an empty array when details or resources are absent', () => {
+        const msg = {
+            timestamp: 0,
+            workflow_run_id: 'run-1',
+            type: AgentMessageType.COMPLETE,
+            message: '',
+        };
+        expect(getResourcesFromMessage(msg)).toEqual([]);
+    });
+});

package/src/apps.ts

@@ -1,7 +1,12 @@
 import type { JSONObject, JSONSchema, ToolDefinition } from '@llumiverse/common';
 import type { AppDashboardDefinition } from './data-platform.js';
 import type { CatalogInteractionRef } from './interaction.js';
-import type { DSLActivityOptions, InCodeProcessDefinition, InCodeTypeDefinition } from './store/index.js';
+import type {
+    AgentRunSearchHit,
+    DSLActivityOptions,
+    InCodeProcessDefinition,
+    InCodeTypeDefinition,
+} from './store/index.js';
 import type { InCodeViewDefinition } from './views.js';
 
 /** Allowed values for AppUINavItem.preferredSection */
@@ -552,6 +557,8 @@ export interface AppVersionRecord {
     promoted?: boolean;
     target?: AppVersionTarget;
     agent_run_id?: string;
+    /** Development task that produced this version, when built by the app assistant. */
+    development_task_id?: string;
     /** Temporal workflow that produced this version. */
     build_workflow_id?: string;
     /** Temporal run that produced this version. */
@@ -597,6 +604,8 @@ export interface UpsertAppVersionRequest {
     state?: AppVersionState;
     target?: AppVersionTarget;
     agent_run_id?: string;
+    /** Development task that produced this version, when built by the app assistant. */
+    development_task_id?: string;
     build_workflow_id?: string;
     build_workflow_run_id?: string;
     sandbox_id?: string;
@@ -721,6 +730,7 @@ export interface AppScaffoldWorkflowInput extends StartAppScaffoldRequest {}
 export interface AppScaffoldWorkflowResult {
     app_id: string;
     app_record_id?: string;
+    installation_id?: string;
     git_url?: string;
     source_git?: AppVersionGitSource;
     files?: number;
@@ -741,6 +751,7 @@ export interface AppScaffoldProgress {
     step: string;
     app_id?: string;
     app_record_id?: string;
+    installation_id?: string;
     git_url?: string;
     files?: number;
     initial_version_build?: StartAppBuildResponse;
@@ -1063,6 +1074,44 @@ export interface AppRepoRefs {
     tags: AppRepoRef[];
 }
 
+/** A mutable app development task represented by an `agent/*` Git branch. */
+export interface AppDevelopmentTask {
+    /** Task slug derived from the branch name. */
+    id: string;
+    /** Complete Git branch name. */
+    branch: string;
+    /** Commit currently at the branch head. */
+    source_commit: string;
+    /** Branch-head commit date, when available. */
+    commit_date?: string;
+}
+
+/** Git-backed development tasks and the branch used for new tasks by default. */
+export interface AppDevelopmentTaskList {
+    /** Repository default branch, when resolvable. */
+    default_branch?: string;
+    tasks: AppDevelopmentTask[];
+}
+
+/** Development task details, including the latest parent assistant run when one exists. */
+export interface AppDevelopmentTaskDetails extends AppDevelopmentTask {
+    /** Latest Studio Assistant run started for this task branch. */
+    agent_run?: AgentRunSearchHit;
+}
+
+/** Request to create a branch from an existing branch, tag, or commit. */
+export interface CreateAppRepoBranchRequest {
+    name: string;
+    source_ref: string;
+}
+
+/** A newly created app repository branch. */
+export interface AppRepoBranch {
+    name: string;
+    commit: string;
+    source_ref: string;
+}
+
 /**
  * Canonical package scopes, including the catch-all `all`. The public type is derived
  * from this list so request parsing and TypeScript cannot drift.

package/src/environment.ts

@@ -91,6 +91,8 @@ export interface TextFallbackOptions {
 export interface ExecutionEnvironmentSettings {
     [key: string]: unknown;
     bucket_access_principal?: string;
+    /** Custom HTTP headers sent by OpenAI-compatible environments. */
+    default_headers?: Record<string, string>;
 }
 
 /**

package/src/interaction.ts

@@ -717,6 +717,21 @@ export {
 } from './email.js';
 // ================= end user communication channels ====================
 
+/**
+ * A tool invocation executed before the first model turn of a conversation.
+ * Results are injected into the initial context so the agent starts with them in hand.
+ */
+export interface InitialToolCall {
+    /** Stable identifier used to make initialization replay-safe. */
+    id: string;
+    /** Read-only builtin activity tool name. Skills are configured separately through initial_skills. */
+    tool: string;
+    /** Tool input parameters. */
+    input?: Record<string, unknown>;
+    /** Whether a failed initialization call aborts the conversation start. */
+    on_error?: 'fail' | 'continue';
+}
+
 export interface AsyncConversationExecutionPayload extends AsyncExecutionPayloadBase {
     type: 'conversation';
 
@@ -735,6 +750,28 @@ export interface AsyncConversationExecutionPayload extends AsyncExecutionPayload
      */
     tool_names?: string[];
 
+    /**
+     * Builtin system skills to activate at conversation start. Their related tools are
+     * exposed from the first turn and their instructions are injected into the initial
+     * context, replacing the learn_<skill> round-trip.
+     */
+    initial_skills?: string[];
+
+    /**
+     * Tool calls executed before the first model turn. Results are injected into the
+     * initial context. These run sequentially with the caller's authority before the
+     * first model turn. Only a bounded set of read/hydration tools is accepted.
+     */
+    initial_tool_calls?: InitialToolCall[];
+
+    /**
+     * Hard denylist of tool names for this conversation. Excluded tools are never
+     * exposed to the model and are refused at execution time, even when a skill or
+     * tool refresh would otherwise unlock them. Takes precedence over tool_names,
+     * initial_skills, and skill-based tool activation.
+     */
+    excluded_tools?: string[];
+
     /**
      * The maximum number of iterations in case of a conversation. If <=0 the default of 20 will be used.
      */
@@ -973,6 +1010,52 @@ interface ResumeConversationPayload {
     asyncCompletion?: AsyncCompletionOptions;
 }
 
+/**
+ * The kinds of Vertesia resource an agent tool can report having created, updated, or deleted.
+ * Restricted to resources that have a real detail route to navigate to — do not emit a reference
+ * for a mutation with no meaningful navigation target. Add new kinds only once their route exists.
+ */
+export type AgentResourceType =
+    | 'document'
+    | 'collection'
+    | 'content_type'
+    | 'interaction'
+    | 'prompt'
+    | 'agent'
+    | 'workflow'
+    | 'process'
+    | 'process_run'
+    | 'interaction_run'
+    | 'view';
+
+export type AgentResourceAction = 'created' | 'updated' | 'deleted';
+
+/**
+ * A navigable reference to a resource an agent tool mutated. Tools return these as tool-result
+ * metadata (see {@link ToolResultMeta.resources}); the conversation runtime promotes them onto the
+ * tool's completed lifecycle message so the UI can render deterministic deep links and an
+ * end-of-turn "resources changed" summary — independent of any link the model writes in prose.
+ */
+export interface AgentResourceReference {
+    type: AgentResourceType;
+    /** The resource id used to build its detail route. */
+    id: string;
+    /** Human-readable label captured at mutation time (e.g. the document name). */
+    label: string;
+    action: AgentResourceAction;
+    /** Set when the mutation produced a new revision, enabling a "view changes" affordance. */
+    revision_id?: string;
+}
+
+/**
+ * Metadata a tool executor may attach to its result. Kept as an open record for forward
+ * compatibility while typing the fields the runtime interprets.
+ */
+export interface ToolResultMeta extends Record<string, unknown> {
+    /** Resources this tool created/updated/deleted, surfaced as deep links in the UI. */
+    resources?: AgentResourceReference[];
+}
+
 export interface ToolResultContent {
     content: string;
     /**
@@ -992,7 +1075,54 @@ export interface ToolResultContent {
     /**
      * Can contain metadata returned by the tool executor.
      */
-    meta?: Record<string, unknown>;
+    meta?: ToolResultMeta;
+}
+
+const AGENT_RESOURCE_TYPES: readonly AgentResourceType[] = [
+    'document',
+    'collection',
+    'content_type',
+    'interaction',
+    'prompt',
+    'agent',
+    'workflow',
+    'process',
+    'process_run',
+    'interaction_run',
+    'view',
+];
+
+const AGENT_RESOURCE_ACTIONS: readonly AgentResourceAction[] = ['created', 'updated', 'deleted'];
+
+/**
+ * Validate and normalize an untrusted value into a clean list of resource references. References
+ * cross the wire and may originate from external/MCP tools, so malformed entries are dropped
+ * rather than throwing, and an empty/absent label falls back to the id.
+ */
+export function normalizeAgentResources(value: unknown): AgentResourceReference[] {
+    if (!Array.isArray(value)) return [];
+    const result: AgentResourceReference[] = [];
+    for (const entry of value) {
+        if (!entry || typeof entry !== 'object') continue;
+        const ref = entry as Record<string, unknown>;
+        const { type, id, label, action, revision_id } = ref;
+        if (typeof type !== 'string' || !AGENT_RESOURCE_TYPES.includes(type as AgentResourceType)) continue;
+        if (typeof id !== 'string' || id.length === 0) continue;
+        if (typeof action !== 'string' || !AGENT_RESOURCE_ACTIONS.includes(action as AgentResourceAction)) continue;
+        result.push({
+            type: type as AgentResourceType,
+            id,
+            label: typeof label === 'string' && label.length > 0 ? label : id,
+            action: action as AgentResourceAction,
+            ...(typeof revision_id === 'string' && revision_id.length > 0 ? { revision_id } : {}),
+        });
+    }
+    return result;
+}
+
+/** Extract the normalized resource references a tool declared in its result metadata. */
+export function getResourcesFromToolResult(result: Pick<ToolResultContent, 'meta'>): AgentResourceReference[] {
+    return normalizeAgentResources(result.meta?.resources);
 }
 
 export interface ToolResult extends ToolResultContent {

package/src/store/agent-run.ts

@@ -16,6 +16,7 @@ import type { UserChannel } from '../email.js';
 import type {
     AgentSearchScope,
     ConversationVisibility,
+    InitialToolCall,
     InteractionExecutionConfiguration,
     InteractionRef,
     RunSource,
@@ -173,6 +174,15 @@ export interface AgentRunBase<TData = Record<string, unknown>, TProperties = Rec
     /** Tools configured for this run (+/- syntax supported) */
     tool_names?: string[];
 
+    /** Builtin system skills activated before the first model turn. */
+    initial_skills?: string[];
+
+    /** Ordered, bounded hydration/read calls executed before the first model turn. */
+    initial_tool_calls?: InitialToolCall[];
+
+    /** Hard denylist of tool names: never exposed to the model, refused at execution time. */
+    excluded_tools?: string[];
+
     /** Scoped collection (if any) */
     collection_id?: string;
 
@@ -547,6 +557,25 @@ export interface AgentArtifactUrlResponse {
     path: string;
 }
 
+/** Text content and concurrency token for an agent artifact. */
+export interface AgentArtifactContentResponse {
+    path: string;
+    content: string;
+    generation: string;
+}
+
+/** Conditional text update for an agent artifact. */
+export interface UpdateAgentArtifactContentPayload {
+    content: string;
+    generation: string;
+}
+
+/** Result of a conditional agent artifact update. */
+export interface UpdateAgentArtifactContentResponse {
+    path: string;
+    generation: string;
+}
+
 /**
  * Telemetry ingestion payload for an agent run.
  */

package/src/store/content-type-editing.test.ts

@@ -0,0 +1,17 @@
+import Ajv from 'ajv';
+import { describe, expect, it } from 'vitest';
+import { ContentTypeEditingPolicySchema } from './store.js';
+
+const validate = new Ajv.default({ allErrors: true, strict: false }).compile(ContentTypeEditingPolicySchema);
+
+describe('ContentTypeEditingPolicySchema', () => {
+    it('accepts an omitted or configured interaction', () => {
+        expect(validate({})).toBe(true);
+        expect(validate({ interaction: 'sys:GeneralAgent' })).toBe(true);
+    });
+
+    it('rejects unknown fields and non-string interactions', () => {
+        expect(validate({ interaction: 42 })).toBe(false);
+        expect(validate({ interaction: 'sys:GeneralAgent', tools: [] })).toBe(false);
+    });
+});

package/src/store/conversation-state.ts

@@ -206,6 +206,9 @@ export interface ConversationState {
      */
     skill_instructions_delivered?: string[];
 
+    /** Stable ids of initialization tool calls completed before the first model turn. */
+    initialization_call_ids?: string[];
+
     /**
      * Denylist of MCP tool-collection ids deactivated for this conversation.
      * `undefined`/empty means all installed/connected MCP collections are active.

package/src/store/store.ts

@@ -1034,6 +1034,26 @@ export interface ContentTypeIntakePolicy {
     default_view?: 'auto' | 'text' | 'pdf' | 'image' | 'properties';
 }
 
+/** Per-content-type policy for collaborative document editing. */
+export interface ContentTypeEditingPolicy {
+    /** Agent interaction used for new document-editing sessions. Defaults to sys:GeneralAgent. */
+    interaction?: string;
+}
+
+export const ContentTypeEditingPolicySchema: JSONSchemaType<ContentTypeEditingPolicy> = {
+    type: 'object',
+    description: 'Per-content-type policy for collaborative document editing.',
+    required: [],
+    additionalProperties: false,
+    properties: {
+        interaction: {
+            type: 'string',
+            description: 'Agent interaction used for new document-editing sessions. Omit to use sys:GeneralAgent.',
+            nullable: true,
+        },
+    },
+};
+
 /** Reusable sub-schema for IntakePageScope ('all' | 'located'). */
 const IntakePageScopeSchema = {
     type: 'string',
@@ -1494,6 +1514,7 @@ export interface ContentObjectTypeItem extends BaseObject {
     status?: ContentObjectTypeStatus;
     is_chunkable?: boolean;
     intake?: ContentTypeIntakePolicy;
+    editing?: ContentTypeEditingPolicy;
     /**
      * This is only included in ContentObjectTypeItem if explicitly requested
      * It is always included in ContentObjectType
@@ -1522,6 +1543,7 @@ export type InCodeTypeDefinition = Pick<
     | 'strict_mode'
     | 'status'
     | 'intake'
+    | 'editing'
 >;
 export interface ContentObjectTypeCatalogEntry extends InCodeTypeDefinition {
     updated_by?: string;

package/src/store/workflow.ts

@@ -1,10 +1,12 @@
 import type { ExecutionTokenUsage, HttpTimeoutOptions, ModelOptions } from '@llumiverse/common';
 import type {
+    AgentResourceReference,
     ConversationVisibility,
     InteractionExecutionConfiguration,
     InteractionRef,
     UserChannel,
 } from '../interaction.js';
+import { normalizeAgentResources } from '../interaction.js';
 import type { JSONObject, JSONValue } from '../json.js';
 import type { JSONSchema } from '../json-schema.js';
 import type { SupportedEmbeddingTypes } from '../project.js';
@@ -770,6 +772,8 @@ export interface AgentMessageDetails extends Record<string, unknown> {
     outputFiles?: string[];
     files?: ConversationFile[] | string[];
     plan?: PlanTask[];
+    /** Deep-linkable references to resources a tool created/updated/deleted (see AgentResourceReference). */
+    resources?: AgentResourceReference[];
     streaming_id?: string;
     streaming_id_scope?: 'workflow_run' | 'workstream';
     chunk_index?: number;
@@ -846,6 +850,11 @@ export function isToolCallMessage(msg: AgentMessage): msg is AgentMessage & { de
     );
 }
 
+/** Extract the normalized resource references carried on a message's details, if any. */
+export function getResourcesFromMessage(msg: AgentMessage): AgentResourceReference[] {
+    return normalizeAgentResources((msg.details as AgentMessageDetails | undefined)?.resources);
+}
+
 export function isDocumentEventMessage(msg: AgentMessage): msg is AgentMessage & { details: DocumentEventDetails } {
     const details = msg.details as Record<string, unknown> | undefined;
     return (