@vertesia/common 1.5.0-dev.20260806.125520Z → 1.5.0-dev.20260826.064249Z

package/src/api-schemas/agent-communication.contract.test.ts

@@ -0,0 +1,90 @@
+import { describe, expect, expectTypeOf, it } from 'vitest';
+import type {
+    ComputeRunFacetsResponse,
+    ContentQueryPayload,
+    ContentQueryResult,
+    ListUserGroupsQuery,
+    RegisterPendingAskRequest,
+    SendEmailRequest,
+    UpdateEmailRouteRequest,
+} from '../index.js';
+import type {
+    RegisterPendingAskRequestSchema,
+    SendEmailRequestSchema,
+    UpdateEmailRouteRequestSchema,
+} from './agent-communication.js';
+import type { ContentQueryPayloadSchema, ContentQueryResultSchema } from './content-query.js';
+import type { ListUserGroupsQuerySchema } from './group.js';
+import type { ComputeRunFacetsResponseSchema } from './interaction.js';
+import { validateApiRequest, validateApiResponse } from './registry.js';
+
+describe('agent communication API contracts', () => {
+    it('derives public types from the runtime schemas', () => {
+        expectTypeOf<SendEmailRequest>().toEqualTypeOf<import('zod').z.infer<typeof SendEmailRequestSchema>>();
+        expectTypeOf<UpdateEmailRouteRequest>().toEqualTypeOf<
+            import('zod').z.infer<typeof UpdateEmailRouteRequestSchema>
+        >();
+        expectTypeOf<RegisterPendingAskRequest>().toEqualTypeOf<
+            import('zod').z.infer<typeof RegisterPendingAskRequestSchema>
+        >();
+        expectTypeOf<ContentQueryPayload>().toEqualTypeOf<import('zod').z.infer<typeof ContentQueryPayloadSchema>>();
+        expectTypeOf<ContentQueryResult>().toEqualTypeOf<import('zod').z.infer<typeof ContentQueryResultSchema>>();
+        expectTypeOf<ComputeRunFacetsResponse>().toEqualTypeOf<
+            import('zod').z.infer<typeof ComputeRunFacetsResponseSchema>
+        >();
+        expectTypeOf<ListUserGroupsQuery>().toEqualTypeOf<import('zod').z.infer<typeof ListUserGroupsQuerySchema>>();
+    });
+
+    it('allows only the email route fields the server updates', () => {
+        expect(validateApiRequest('UpdateEmailRouteRequest', { threadSubject: 'Subject' }).valid).toBe(true);
+        expect(validateApiRequest('UpdateEmailRouteRequest', { projectId: 'project-1' }).valid).toBe(false);
+    });
+
+    it('preserves the established user-group filter contract', () => {
+        expect(
+            validateApiRequest('ListUserGroupsQuery', {
+                search: 'admins',
+                tags: ['internal'],
+                limit: 20,
+                offset: 0,
+                project: 'project-1',
+            }).valid,
+        ).toBe(true);
+        expect(validateApiRequest('ListUserGroupsQuery', { unsupported: true }).valid).toBe(false);
+    });
+
+    it('validates content query requests and results', () => {
+        expect(validateApiRequest('ContentQueryPayload', { sql: 'SELECT * FROM content' }).valid).toBe(true);
+        expect(validateApiRequest('ContentQueryPayload', { explain: true }).valid).toBe(false);
+        expect(
+            validateApiResponse('ContentQueryResult', {
+                type: 'dsl',
+                hits: [{ id: 'object-1', score: 1, source: { name: 'Example' } }],
+                total: 1,
+            }).valid,
+        ).toBe(true);
+    });
+
+    it('validates the flat run-facet response returned by the endpoint', () => {
+        expect(
+            validateApiResponse('ComputeRunFacetsResponse', {
+                total: 3,
+                statuses: [
+                    { _id: 'completed', count: 2 },
+                    { _id: null, count: 1 },
+                ],
+            }).valid,
+        ).toBe(true);
+        expect(
+            validateApiResponse('ComputeRunFacetsResponse', {
+                status: [{ _id: 'completed', count: 2 }],
+            }).valid,
+        ).toBe(false);
+        expect(
+            validateApiResponse('ComputeRunFacetsResponse', {
+                count: { total: 3 },
+                facet: { statuses: { buckets: [] } },
+            }).valid,
+        ).toBe(false);
+    });
+});

package/src/api-schemas/agent-communication.ts

@@ -0,0 +1,169 @@
+import { z } from 'zod';
+import { UserChannelSchema } from './interaction.js';
+import { TaskFieldSchema } from './task.js';
+
+export const EmailRouteDataSchema = z
+    .strictObject({
+        runId: z.string(),
+        accountId: z.string(),
+        projectId: z.string(),
+        threadSubject: z.string().optional(),
+        inReplyTo: z.string().optional(),
+        references: z.array(z.string()).optional(),
+        userEmail: z.string(),
+        inboundDomain: z.string(),
+    })
+    .meta({ id: 'EmailRouteData' });
+
+export const SendEmailRequestSchema = z
+    .strictObject({
+        to_email: z.string(),
+        subject: z.string(),
+        body: z.string(),
+        agent_name: z.string(),
+        from_name: z.string().optional(),
+        run_id: z.string(),
+        route_key: z.string().optional(),
+        in_reply_to: z.string().optional(),
+        references: z.array(z.string()).optional(),
+    })
+    .meta({ id: 'SendEmailRequest' });
+
+export const SendEmailResponseSchema = z
+    .strictObject({
+        success: z.boolean(),
+        email_id: z.string().optional(),
+        message_id: z.string().optional(),
+        route_key: z.string().optional(),
+        error: z.string().optional(),
+    })
+    .meta({ id: 'SendEmailResponse' });
+
+export const ResolveEmailRouteRequestSchema = z
+    .strictObject({ route_key: z.string() })
+    .meta({ id: 'ResolveEmailRouteRequest' });
+
+export const CreateEmailRouteRequestSchema = z
+    .strictObject({
+        run_id: z.string(),
+        user_email: z.string(),
+        thread_subject: z.string().optional(),
+    })
+    .meta({ id: 'CreateEmailRouteRequest' });
+
+export const CreateEmailRouteResponseSchema = z
+    .strictObject({
+        route_key: z.string(),
+        reply_to: z.string(),
+        email_domain: z.string(),
+    })
+    .meta({ id: 'CreateEmailRouteResponse' });
+
+export const EmailRouteResponseSchema = EmailRouteDataSchema.extend({ route_key: z.string() }).meta({
+    id: 'EmailRouteResponse',
+});
+
+export const UpdateEmailRouteRequestSchema = EmailRouteDataSchema.pick({
+    threadSubject: true,
+    inReplyTo: true,
+    references: true,
+    userEmail: true,
+})
+    .partial()
+    .meta({ id: 'UpdateEmailRouteRequest' });
+
+export const UpdateEmailRouteResponseSchema = z
+    .strictObject({ success: z.boolean(), route_key: z.string() })
+    .meta({ id: 'UpdateEmailRouteResponse' });
+
+export const ForwardEmailRequestSchema = z
+    .strictObject({
+        email: z.strictObject({
+            from: z.string(),
+            subject: z.string().optional(),
+            text: z.string(),
+            html: z.string().optional(),
+            message_id: z.string().optional(),
+        }),
+        context: z.record(z.string(), z.unknown()).optional(),
+        attachments: z
+            .array(
+                z.strictObject({
+                    filename: z.string(),
+                    content_type: z.string(),
+                    size: z.number(),
+                    download_url: z.string(),
+                }),
+            )
+            .optional(),
+    })
+    .meta({ id: 'ForwardEmailRequest' });
+
+export const ForwardEmailResponseSchema = z
+    .strictObject({
+        success: z.boolean(),
+        run_id: z.string(),
+        workflow_id: z.string(),
+        route_key: z.string(),
+    })
+    .meta({ id: 'ForwardEmailResponse' });
+
+export const PendingAskStatusSchema = z.enum(['pending', 'resolved', 'expired']).meta({ id: 'PendingAskStatus' });
+
+export const PendingAskDataSchema = z
+    .strictObject({
+        askId: z.string(),
+        runId: z.string(),
+        workflowId: z.string(),
+        projectId: z.string(),
+        accountId: z.string(),
+        agentName: z.string(),
+        questions: z.array(z.string()),
+        timeoutHours: z.number(),
+        userChannels: z.array(UserChannelSchema),
+        createdAt: z.number(),
+        expiresAt: z.number(),
+        status: PendingAskStatusSchema,
+        taskId: z.string().optional(),
+        resolvedAt: z.number().optional(),
+        response: z.string().optional(),
+    })
+    .meta({ id: 'PendingAskData' });
+
+export const RegisterPendingAskRequestSchema = z
+    .strictObject({
+        runId: z.string(),
+        workflowId: z.string(),
+        agentName: z.string(),
+        questions: z.array(z.string()),
+        timeoutHours: z.number().optional(),
+        userChannels: z.array(UserChannelSchema),
+        taskFields: z.array(TaskFieldSchema).optional(),
+    })
+    .meta({ id: 'RegisterPendingAskRequest' });
+
+export const RegisterPendingAskResponseSchema = z
+    .strictObject({
+        success: z.boolean(),
+        askId: z.string().optional(),
+        webhookSent: z.boolean().optional(),
+        error: z.string().optional(),
+    })
+    .meta({ id: 'RegisterPendingAskResponse' });
+
+export const ResolvePendingAskRequestSchema = z
+    .strictObject({ response: z.string() })
+    .meta({ id: 'ResolvePendingAskRequest' });
+
+export const ResolvePendingAskResponseSchema = z
+    .strictObject({
+        success: z.boolean(),
+        webhookSent: z.boolean().optional(),
+        waitDurationMs: z.number().optional(),
+        error: z.string().optional(),
+    })
+    .meta({ id: 'ResolvePendingAskResponse' });
+
+export const ListPendingAsksResponseSchema = z
+    .strictObject({ asks: z.array(PendingAskDataSchema) })
+    .meta({ id: 'ListPendingAsksResponse' });

package/src/api-schemas/agent-runs.ts

@@ -1,6 +1,6 @@
 // Runtime schemas for the agent runs API domain.
 
-import { ExecutionTokenUsageSchema } from '@llumiverse/common/schemas';
+import { ExecutionTokenUsageSchema, ReasoningEffortSchema } from '@llumiverse/common/schemas';
 import { z } from 'zod';
 import type { AgentMessageType, FileProcessingStatus } from '../store/workflow.js';
 import { type AgentEvent, AgentEventType, LlmCallType, TelemetryToolType } from '../workflow-analytics.js';
@@ -17,6 +17,7 @@ import {
     AgentResourceReferenceSchema,
     AgentSearchScopeSchema,
     AgentToolApprovalModeSchema,
+    ConversationEnrichmentFields,
     ConversationVisibilitySchema,
     InitialToolCallSchema,
     InteractionRefSchema,
@@ -354,6 +355,17 @@ export const AutonomousRunResponseSchema = z
         }).optional(),
         id: z.string().meta({ description: 'The stable identifier used by all client code' }),
         run_kind: z.literal('agent').meta({ description: 'Internal discriminator key' }),
+        parent_run_id: z
+            .string()
+            .meta({
+                description:
+                    'Process run this agent belongs to — set when a process agent node recorded this run. Its conversation lives on the parent run under `workstream_id`.',
+            })
+            .optional(),
+        workstream_id: z
+            .string()
+            .meta({ description: 'Workstream this run occupies inside its parent run (the process node id).' })
+            .optional(),
         run_type: z.literal('autonomous'),
         account: z.string().meta({ description: 'Account ID' }),
         project: z.string().meta({ description: 'Project ID' }),
@@ -396,6 +408,14 @@ export const AutonomousRunResponseSchema = z
             .string()
             .meta({ description: 'Conversation topic (longer description from topic analysis)' })
             .optional(),
+        generate_topic: z
+            .boolean()
+            .meta({ description: 'Whether automatic conversation title/topic generation is enabled for this run.' })
+            .optional(),
+        generate_lessons: z
+            .boolean()
+            .meta({ description: 'Whether automatic lessons generation is enabled for this run.' })
+            .optional(),
         lessons_learned: z
             .array(z.string())
             .meta({ description: 'Lessons learned from the conversation (extracted at completion)' })
@@ -483,6 +503,17 @@ export const AgentRunSchema = z
         }).optional(),
         id: z.string().meta({ description: 'The stable identifier used by all client code' }),
         run_kind: z.literal('agent').meta({ description: 'Internal discriminator key' }),
+        parent_run_id: z
+            .string()
+            .meta({
+                description:
+                    'Process run this agent belongs to — set when a process agent node recorded this run. Its conversation lives on the parent run under `workstream_id`.',
+            })
+            .optional(),
+        workstream_id: z
+            .string()
+            .meta({ description: 'Workstream this run occupies inside its parent run (the process node id).' })
+            .optional(),
         run_type: z.literal('autonomous').meta({ description: 'Public-facing runtime mode' }),
         account: z.string().meta({ description: 'Account ID' }),
         project: z.string().meta({ description: 'Project ID' }),
@@ -525,6 +556,14 @@ export const AgentRunSchema = z
             .string()
             .meta({ description: 'Conversation topic (longer description from topic analysis)' })
             .optional(),
+        generate_topic: z
+            .boolean()
+            .meta({ description: 'Whether automatic conversation title/topic generation is enabled for this run.' })
+            .optional(),
+        generate_lessons: z
+            .boolean()
+            .meta({ description: 'Whether automatic lessons generation is enabled for this run.' })
+            .optional(),
         lessons_learned: z
             .array(z.string())
             .meta({ description: 'Lessons learned from the conversation (extracted at completion)' })
@@ -555,6 +594,7 @@ export const AgentRunSchema = z
 export const CreateAgentRunPayloadSchema = z
     .strictObject({
         interaction: z.string().meta({ description: 'Interaction ID or code (e.g. "sys:generic_question").' }),
+        ...ConversationEnrichmentFields,
         data: z.looseObject({}).meta({ description: 'Input parameters, typed per interaction' }).optional(),
         config: InteractionExecutionConfigurationSchema.meta({
             description: 'Execution configuration (environment, model, model_options, etc.)',
@@ -1034,6 +1074,9 @@ export const RecordAgentRunPayloadSchema = z
         first_workflow_run_id: z.string(),
         run_kind: z.literal('agent').optional(),
         interaction: z.string(),
+        ...ConversationEnrichmentFields,
+        parent_run_id: z.string().optional(),
+        workstream_id: z.string().optional(),
         schedule_id: z.string().optional(),
         visibility: ConversationVisibilitySchema.optional(),
         data: z.looseObject({}).optional(),
@@ -1056,6 +1099,8 @@ export const UpdateAgentRunStatusPayloadSchema = z
         content: z.string().optional(),
         disabled_mcp_collections: z.array(z.string()).optional(),
         tool_approval_mode: AgentToolApprovalModeSchema.optional(),
+        model: z.string().min(1).optional(),
+        effort: ReasoningEffortSchema.nullable().optional(),
         archive_state: AgentRunArchiveStateSchema.optional(),
         archived_at: z.string().optional(),
         archive_version: z.number().optional(),

package/src/api-schemas/api-discriminators.test.ts

@@ -0,0 +1,185 @@
+import { describe, expect, it } from 'vitest';
+import { type ApiComponentName, ApiSchemaComponents, validateApiResponse } from './registry.js';
+
+/**
+ * The build-time half of `discriminator: true`.
+ *
+ * AJV applies its discriminator rules when it COMPILES a schema, not when it validates one, and it
+ * signals a union it cannot handle by throwing. Left unchecked that turns into a 500 on the first
+ * request to whichever endpoint publishes the offending component — a failure mode that depends on
+ * traffic and would reach a deployed environment before anyone saw it. Compiling every registered
+ * component here moves that to the build, and names the component when it happens.
+ *
+ * The rules a union has to satisfy, all of which `synthesizeDiscriminator` in the adapter already
+ * enforces before emitting a discriminator: `oneOf` members resolving to object schemas, a tag
+ * property present and REQUIRED in every branch, and a `const` or single-valued `enum` for the tag
+ * in each. A hand-written `.meta({ discriminator })` gets no such check when it is written, which
+ * is the case this test exists for.
+ *
+ * Generating a validator for each of the ~1000 components is real work: well under a second on a
+ * developer machine, ~8s on a loaded CI runner, past vitest's 5s default, hence the explicit budget
+ * below. It is generous on purpose — an unsupported discriminator makes AJV THROW during
+ * compilation, so a genuine regression is caught by the try/catch and never by the clock.
+ */
+const COMPILE_ALL_TIMEOUT_MS = 60_000;
+
+describe('published discriminators', () => {
+    it(
+        'compiles every registered component under AJV discriminator support',
+        () => {
+            const failures: string[] = [];
+            for (const name of Object.keys(ApiSchemaComponents)) {
+                try {
+                    // Compilation is the subject; the value only has to reach the validator. An
+                    // invalid result is expected and irrelevant.
+                    validateApiResponse(name as ApiComponentName, undefined);
+                } catch (err: unknown) {
+                    failures.push(`${name}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            expect(failures, `components AJV could not compile:\n${failures.join('\n')}`).toEqual([]);
+        },
+        COMPILE_ALL_TIMEOUT_MS,
+    );
+
+    it('keeps discriminator mapping in the published components for generated clients', () => {
+        // AJV's copy drops `mapping`; the OpenAPI document must not. A Java or Go client reads the
+        // mapping to pick a concrete subtype, so losing it here would be a silent codegen
+        // regression that no schema assertion elsewhere would catch.
+        const union = ApiSchemaComponents.ToolCollectionObject as {
+            discriminator?: { propertyName?: string; mapping?: Record<string, string> };
+        };
+        expect(union.discriminator?.propertyName).toBe('type');
+        expect(union.discriminator?.mapping).toMatchObject({
+            mcp: '#/components/schemas/MCPToolCollectionObject',
+        });
+    });
+
+    it('reports only the tagged branch when a legacy MCP collection is missing its id', () => {
+        // The `hubspot-mcp-dev` shape: created before the write path required `id`, still served by
+        // the five-level resolution chain in fetch-tools.ts. Without discriminator support AJV also
+        // reported `oauth_app` as an undeclared property and `type` as not matching a constant —
+        // both from the vertesia_sdk branch this value never claimed to be.
+        const legacy = {
+            type: 'mcp',
+            name: 'HubSpot',
+            namespace: 'hubspot',
+            description: 'HubSpot MCP',
+            auth: 'oauth',
+            url: 'https://mcp.hubspot.com',
+            oauth_app: 'hubspot',
+        };
+        const result = validateApiResponse('ToolCollectionObject', legacy);
+        expect(result.valid).toBe(false);
+        if (result.valid) return;
+        expect(result.errors).toEqual(["/ must have required property 'id'"]);
+    });
+
+    /** A one-branch `condition` node, the smallest thing that reaches the untagged `branches` union. */
+    function withBranch(branch: unknown): unknown {
+        return {
+            format_version: 1,
+            process: 'demo',
+            initial: 'a',
+            context: { schema: { type: 'object' }, initial: {} },
+            nodes: { a: { type: 'condition', branches: [branch] } },
+        };
+    }
+
+    it('attributes every claim under an untagged union to the candidate that made it', () => {
+        // The process-runs list, which `ProcessDefinitionBody` reaches through
+        // `ListAgentRunsResponse.items[].process_definition_snapshot`. `branches` is a `oneOf` with
+        // no tag, so AJV reports every candidate's failures flat and unattributed:
+        //
+        //     /nodes/a/branches/0 must NOT have additional properties: label, to, when
+        //
+        // `to` and `when` are declared on `BranchDefinition` — the shape this value plainly means —
+        // so read as a fact that line sends the reader after two valid fields.
+        const result = validateApiResponse(
+            'ProcessDefinitionBody',
+            withBranch({ label: 'Accepted', to: 'accepted', when: { '==': [{ var: 'ok' }, true] } }),
+        );
+        expect(result.valid).toBe(false);
+        if (result.valid) return;
+
+        // Against the candidate it means, `label` is the whole story.
+        expect(result.errors).toContain(
+            '/nodes/a/branches/0 as BranchDefinition: must NOT have additional properties: label',
+        );
+        // The other candidate is still reported — with no tag neither can be ruled out — but named,
+        // so it reads as a claim about that shape rather than about the value.
+        expect(result.errors).toContain(
+            '/nodes/a/branches/0 as BranchNodeBranchDefinition: must NOT have additional properties: label, to, when',
+        );
+        // Every attributed claim names a candidate of THIS union, never some nearer schema.
+        const named = result.issues.filter((i) => i.component !== undefined).map((i) => i.component);
+        expect(new Set(named)).toEqual(new Set(['BranchDefinition', 'BranchNodeBranchDefinition']));
+    });
+
+    it('attributes candidates that fail at different paths', () => {
+        // The case that defeats counting candidates per instance path: with a malformed `when`, the
+        // intended candidate fails at `/when` while the other fails at the branch root, so no path
+        // has two candidates and a per-path rule drops EVERY name — leaving
+        //
+        //     /nodes/a/branches/0 must NOT have additional properties: to, when
+        //
+        // stated as a bare fact again. Attribution has to follow the union, not the path.
+        const result = validateApiResponse('ProcessDefinitionBody', withBranch({ to: 'accepted', when: 'bad' }));
+        expect(result.valid).toBe(false);
+        if (result.valid) return;
+
+        expect(result.errors).toContain('/nodes/a/branches/0/when as BranchDefinition: must be object');
+        expect(result.errors).toContain(
+            '/nodes/a/branches/0 as BranchNodeBranchDefinition: must NOT have additional properties: to, when',
+        );
+        // The point of the fix: nothing under a failed union is left unattributed except the union's
+        // own line, so no candidate's complaint can be mistaken for a fact about the value.
+        const unattributed = result.issues.filter((i) => i.component === undefined);
+        expect(unattributed.map((i) => i.message)).toEqual(['must match exactly one schema in oneOf']);
+    });
+
+    it('leaves the component off outside a union', () => {
+        // A component name marks a claim as conditional. Attaching one where the issue holds
+        // outright would weaken a fact, besides spending characters against the response budget.
+        const result = validateApiResponse('ProcessDefinitionBody', {
+            format_version: 1,
+            process: 'demo',
+            initial: 'a',
+            title: 'Undeclared at the body level',
+            context: { schema: { type: 'object' }, initial: {} },
+            nodes: {},
+        });
+        expect(result.valid).toBe(false);
+        if (result.valid) return;
+        expect(result.issues).toEqual([
+            { path: '/', message: 'must NOT have additional properties', undeclared: ['title'], component: undefined },
+        ]);
+        expect(result.errors).toEqual(['/ must NOT have additional properties: title']);
+    });
+
+    it('still gathers every undeclared name one schema reports at a path', () => {
+        // The case gathering exists for, unaffected by the split above: one strict object, many
+        // foreign keys — an unmapped Mongoose subdocument — stays a single issue.
+        const result = validateApiResponse('ProcessDefinitionBody', {
+            format_version: 1,
+            process: 'demo',
+            initial: 'a',
+            context: { schema: { type: 'object' }, initial: {} },
+            nodes: {},
+            $__parent: {},
+            $isNew: false,
+            _doc: {},
+        });
+        expect(result.valid).toBe(false);
+        if (result.valid) return;
+        expect(result.issues).toHaveLength(1);
+        expect(result.issues[0].undeclared).toEqual(['$__parent', '$isNew', '_doc']);
+    });
+
+    it('rejects a value whose tag names no branch', () => {
+        const result = validateApiResponse('ToolCollectionObject', { type: 'nonesuch', url: 'https://example.com' });
+        expect(result.valid).toBe(false);
+        if (result.valid) return;
+        expect(result.errors.join('; ')).toContain('tag');
+    });
+});

package/src/api-schemas/app-lifecycle.ts

@@ -398,9 +398,9 @@ export const AppVersionGitSourceSchema = z
 
 export const StartAppScaffoldRequestSchema = z
     .strictObject({
-        app_id: z
-            .string()
-            .meta({ description: 'App id / package name to create. It is normalized to the same slug rules used by' }),
+        app_id: z.string().meta({
+            description: 'Package name for the new app to create and scaffold. This is not the id of an existing app.',
+        }),
         title: z.string().optional(),
         description: z.string().optional(),
         modules: z.array(AppScaffoldModuleSchema).optional(),
@@ -413,6 +413,18 @@ export const StartAppScaffoldRequestSchema = z
     })
     .meta({ id: 'StartAppScaffoldRequest' });
 
+export const StartAppDevelopmentTaskRequestSchema = z
+    .strictObject({
+        prompt: z.string().min(1).meta({ description: 'Development request passed to the App Builder parent.' }),
+        environment: z.string().min(1).meta({ description: 'Execution environment id for the App Builder run.' }),
+        model: z.string().min(1).meta({ description: 'Model id for the App Builder run.' }),
+        build_version: z
+            .boolean()
+            .meta({ description: 'Create one immutable app version after validation. Defaults to false.' })
+            .optional(),
+    })
+    .meta({ id: 'StartAppDevelopmentTaskRequest' });
+
 export const StartAppBuildRequestSchema = z
     .strictObject({
         source_ref: z
@@ -442,6 +454,12 @@ export const AgentToolDefinitionSchema = z
         // component publishes `true`. They accept identical values, but the name is still derived
         // through `AppPackage`, so this reproduces the published form exactly.
         input_schema: openObjectSchema,
+        output_schema: openObjectSchema
+            .meta({
+                description:
+                    'Optional MCP outputSchema advertised by the provider for its structuredContent payload. Execution adapters may expose results differently.',
+            })
+            .optional(),
         url: z
             .string()
             .meta({
@@ -844,7 +862,7 @@ export const AppDevelopmentTaskDetailsSchema = z
         source_commit: z.string().meta({ description: 'Commit currently at the branch head.' }),
         commit_date: z.string().meta({ description: 'Branch-head commit date, when available.' }).optional(),
         agent_run: AgentRunSearchHitSchema.meta({
-            description: 'Latest Studio Assistant run started for this task branch.',
+            description: 'Latest App Builder parent run started for this task branch.',
         }).optional(),
     })
     .meta({
@@ -863,6 +881,23 @@ export const AppInstallationKindSchema = z
     .enum(['ui', 'tools', 'all'])
     .meta({ id: 'AppInstallationKind', description: 'Which app contributions an installation listing is for.' });
 
+// `AppListScope` has a TypeScript name and therefore gets a reusable component of its own.
+export const AppListScopeSchema = z.enum(['account', 'project']).meta({
+    id: 'AppListScope',
+    description: 'Which apps an app listing covers.',
+});
+
+export const AppsQuerySchema = z
+    .strictObject({
+        scope: AppListScopeSchema.meta({
+            description:
+                'Restrict the listing to apps that belong to the current project — those installed ' +
+                'into it or that have built versions in it. Defaults to `account`, which lists every ' +
+                'app visible to the account, including the public catalog.',
+        }).optional(),
+    })
+    .meta({ id: 'AppsQuery' });
+
 export const AppInstallationsQuerySchema = z
     .strictObject({
         kind: AppInstallationKindSchema.meta({

package/src/api-schemas/app-runtime.ts

@@ -35,6 +35,7 @@ import { RemoteActivityDefinitionSchema } from './integrations.js';
 import { CatalogInteractionRefSchema } from './interaction.js';
 import { ProcessDefinitionBodySchema } from './process.js';
 import { RenderingTemplateDefinitionRefSchema } from './project.js';
+import { EditRevisionSchema, ExpectedEditRevisionSchema } from './schema-primitives.js';
 import { InCodeTypeDefinitionSchema } from './store.js';
 import { ViewExperienceConfigurationSchema } from './view-execution.js';
 
@@ -428,6 +429,10 @@ export const AppManifestDataSchema = z
     })
     .meta({ id: 'AppManifestData' });
 
+export const UpdateAppPayloadSchema = AppManifestDataSchema.extend({
+    expected_edit_revision: ExpectedEditRevisionSchema,
+}).meta({ id: 'UpdateAppPayload' });
+
 export const CompositeAppMenuNavItemSchema: z.ZodType<CompositeAppMenuNavItem> = z
     .strictObject({
         id: z.string().meta({ description: 'Stable unique identifier' }),
@@ -506,6 +511,7 @@ export const CompositeAppMessageOverridesSchema = z
 
 export const AppManifestSchema = z
     .strictObject({
+        edit_revision: EditRevisionSchema,
         name: z.string().meta({
             description: 'The name of the app, used as the id in the system. Must be in kebab case (e.g. my-app).',
         }),
@@ -737,6 +743,7 @@ export const AppInstallationListEntryArraySchema = z
 
 export const CompositeAppConfigSchema = z
     .strictObject({
+        edit_revision: EditRevisionSchema,
         id: z
             .string()
             .meta({
@@ -958,6 +965,7 @@ export const AppPackageSchema = z
 
 export const CompositeAppConfigPayloadSchema = z
     .strictObject({
+        expected_edit_revision: ExpectedEditRevisionSchema,
         card: CompositeAppCardOverridesSchema.meta({
             description: 'Card display overrides (includes visibility)',
         }).optional(),