@adea-ai/runtime-sdk 1.21.1 → 1.23.0

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './adapter.js';
 export * from './pi-durable-lead.js';
+export * from './pi-durable-questions.js';
 export * from './agent-plugins.js';
 export * from './channel-ownership.js';
 export * from './capabilities.js';

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './adapter.js';
 export * from './pi-durable-lead.js';
+export * from './pi-durable-questions.js';
 export * from './agent-plugins.js';
 export * from './channel-ownership.js';
 export * from './capabilities.js';

package/dist/pi-durable-lead.d.ts

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { PiDurableQuestionAnswersSchema, PiDurableQuestionRequestIdSchema } from './pi-durable-questions.js';
 import { IdentifierSchemas, ModelSelectionRefSchema } from '@adea-ai/contracts';
 import { RuntimeExecutionProgressSchema, RuntimeExecutionStatusSchema, RuntimeExecutionStateSchema, RuntimeObservedGenerationSchema } from './adapter.js';
 declare const IntentId: z.ZodUUID;
@@ -155,6 +156,55 @@ export declare const PiDurableLeadProgressRequestSchema: z.ZodObject<{
         afterSequence: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export declare const PI_DURABLE_LEAD_EVENTS_CONTRACT_VERSION = 1;
+export declare const PI_DURABLE_LEAD_EVENTS_MAX_PAGE = 256;
+export declare const PI_DURABLE_LEAD_EVENTS_MAX_WAIT_MS = 8000;
+export declare const PiDurableLeadEventsRequestSchema: z.ZodObject<{
+    contractVersion: z.ZodObject<{
+        major: z.ZodNumber;
+        minor: z.ZodNumber;
+    }, z.core.$strict>;
+    requestId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"request ID">, string>>;
+    workspaceId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"workspace ID">, string>>;
+    projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"project ID">, string>>>;
+    requestedAt: z.ZodISODateTime;
+    caller: typeof Caller;
+    correlation: typeof Correlation;
+    operation: z.ZodLiteral<"pi-durable.lead.events">;
+    parameters: z.ZodObject<{
+        dispatchId: typeof DispatchId;
+        messageId: z.ZodString;
+        afterSeq: z.ZodNumber;
+        waitMs: z.ZodNumber;
+        limit: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const PiDurableLeadTurnEventSchema: z.ZodObject<{
+    schemaVersion: z.ZodLiteral<1>;
+    eventId: z.ZodString;
+    runtimeSessionId: z.ZodString;
+    harnessRunId: z.ZodString;
+    generation: z.ZodLiteral<1>;
+    seq: z.ZodString;
+    occurredAt: z.ZodISODateTime;
+    receivedAt: z.ZodISODateTime;
+    source: z.ZodLiteral<"native">;
+    sourceEventId: z.ZodString;
+    confidence: z.ZodLiteral<"authoritative">;
+    classification: z.ZodEnum<{
+        restricted_local: "restricted_local";
+        workspace_private: "workspace_private";
+    }>;
+    kind: z.ZodString;
+    payload: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strict>;
+export declare const PiDurableLeadEventsDataSchema: z.ZodObject<{
+    contractVersion: z.ZodLiteral<1>;
+    dispatchId: typeof DispatchId;
+    events: z.ZodArray<typeof PiDurableLeadTurnEventSchema>;
+    nextSeq: z.ZodNumber;
+    complete: z.ZodBoolean;
+}, z.core.$strict>;
 export declare const PiDurableLeadChildrenCursorSchema: z.ZodReadonly<z.ZodObject<{
     acceptedAt: z.ZodISODateTime;
     delegationId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"delegation ID">, string>>;
@@ -215,6 +265,47 @@ export declare const PiDurableLeadCancelRequestSchema: z.ZodObject<{
         dispatchId: z.ZodString;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export declare const PiDurableLeadQuestionAnswerRequestSchema: z.ZodObject<{
+    contractVersion: z.ZodObject<{
+        major: z.ZodNumber;
+        minor: z.ZodNumber;
+    }, z.core.$strict>;
+    requestId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"request ID">, string>>;
+    workspaceId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"workspace ID">, string>>;
+    projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"project ID">, string>>>;
+    commandId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"command ID">, string>>;
+    idempotencyKey: z.ZodString;
+    payloadHash: z.ZodString;
+    issuedAt: z.ZodISODateTime;
+    caller: typeof Caller;
+    correlation: typeof Correlation;
+    operation: z.ZodLiteral<"pi-durable.lead.question-answer">;
+    payload: z.ZodObject<{
+        dispatchId: typeof DispatchId;
+        requestId: typeof PiDurableQuestionRequestIdSchema;
+        answers: typeof PiDurableQuestionAnswersSchema;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const PiDurableLeadChildCancelRequestSchema: z.ZodObject<{
+    contractVersion: z.ZodObject<{
+        major: z.ZodNumber;
+        minor: z.ZodNumber;
+    }, z.core.$strict>;
+    requestId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"request ID">, string>>;
+    workspaceId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"workspace ID">, string>>;
+    projectId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"project ID">, string>>>;
+    commandId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"command ID">, string>>;
+    idempotencyKey: z.ZodString;
+    payloadHash: z.ZodString;
+    issuedAt: z.ZodISODateTime;
+    caller: typeof Caller;
+    correlation: typeof Correlation;
+    operation: z.ZodLiteral<"pi-durable.lead.child-cancel">;
+    payload: z.ZodObject<{
+        dispatchId: typeof DispatchId;
+        delegationId: typeof IdentifierSchemas.delegationId;
+    }, z.core.$strict>;
+}, z.core.$strict>;
 export declare const PiDurableLeadReceiptResponseSchema: z.ZodObject<{
     schemaVersion: z.ZodLiteral<"pi-lead-dispatch/v1">;
     dispatchId: typeof DispatchId;
@@ -437,6 +528,51 @@ export declare const PiDurableLeadCancelResponseSchema: z.ZodObject<{
         status: typeof RuntimeExecutionStatusSchema;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export declare const PiDurableLeadQuestionAnswerResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodObject<{
+        major: z.ZodNumber;
+        minor: z.ZodNumber;
+    }, z.core.$strict>;
+    requestId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"request ID">, string>>;
+    correlation: z.ZodObject<{
+        traceId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"trace ID">, string>>;
+        causationCommandId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"command ID">, string>>>;
+        parentEventId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"event ID">, string>>>;
+    }, z.core.$strict>;
+    data: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<"pi-lead-dispatch/v1">;
+        dispatchId: typeof DispatchId;
+        intentId: typeof IntentId;
+        executionId: typeof IdentifierSchemas.executionId;
+        attemptId: typeof IdentifierSchemas.attemptId;
+        runtimeSessionId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"external-session ID">, string>>;
+        requestedTarget: z.ZodOptional<typeof PiDurableLeadRequestedTargetSchema>;
+        observedTarget: z.ZodOptional<typeof PiDurableLeadObservedTargetSchema>;
+        questionSchemaVersion: z.ZodLiteral<"pi-lead-question-answer/v1">;
+        requestId: typeof PiDurableQuestionRequestIdSchema;
+        requestEventId: z.ZodString;
+        outcome: z.ZodEnum<{
+            already_answered: "already_answered";
+            answered: "answered";
+            expired: "expired";
+        }>;
+        state: typeof RuntimeExecutionStateSchema;
+        status: typeof RuntimeExecutionStatusSchema;
+    }, z.core.$strict>;
+}, z.core.$strict>;
+export declare const PiDurableLeadEventsResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodObject<{
+        major: z.ZodNumber;
+        minor: z.ZodNumber;
+    }, z.core.$strict>;
+    requestId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"request ID">, string>>;
+    correlation: z.ZodObject<{
+        traceId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"trace ID">, string>>;
+        causationCommandId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"command ID">, string>>>;
+        parentEventId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"event ID">, string>>>;
+    }, z.core.$strict>;
+    data: typeof PiDurableLeadEventsDataSchema;
+}, z.core.$strict>;
 declare const ChildReference: z.ZodString;
 export declare const PiDurableLeadChildOutcomeSchema: z.ZodObject<{
     state: z.ZodEnum<{
@@ -506,6 +642,30 @@ export declare const PiDurableLeadChildrenResponseSchema: z.ZodObject<{
         next: z.ZodOptional<typeof PiDurableLeadChildrenCursorSchema>;
     }, z.core.$strict>;
 }, z.core.$strict>;
+export declare const PiDurableLeadChildCancelResponseSchema: z.ZodObject<{
+    contractVersion: z.ZodObject<{
+        major: z.ZodNumber;
+        minor: z.ZodNumber;
+    }, z.core.$strict>;
+    requestId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"request ID">, string>>;
+    correlation: z.ZodObject<{
+        traceId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"trace ID">, string>>;
+        causationCommandId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"command ID">, string>>>;
+        parentEventId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"event ID">, string>>>;
+    }, z.core.$strict>;
+    data: z.ZodObject<{
+        schemaVersion: z.ZodLiteral<"pi-lead-dispatch/v1">;
+        dispatchId: typeof DispatchId;
+        intentId: typeof IntentId;
+        executionId: typeof IdentifierSchemas.executionId;
+        attemptId: typeof IdentifierSchemas.attemptId;
+        runtimeSessionId: z.ZodPipe<z.ZodString, z.ZodTransform<import("@adea-ai/contracts").OpaqueIdentifier<"external-session ID">, string>>;
+        requestedTarget: z.ZodOptional<typeof PiDurableLeadRequestedTargetSchema>;
+        observedTarget: z.ZodOptional<typeof PiDurableLeadObservedTargetSchema>;
+        child: typeof PiDurableLeadChildSchema;
+        attributed: z.ZodBoolean;
+    }, z.core.$strict>;
+}, z.core.$strict>;
 export declare const PiDurableLeadChildTargetSchema: z.ZodObject<{
     source: z.ZodLiteral<"control_plane_reported">;
     runtimeConnectionId: typeof IdentifierSchemas.runtimeConnectionId;
@@ -629,6 +789,13 @@ export declare const PiDurableLeadHttpContract: Readonly<{
         requestSchema: typeof PiDurableLeadProgressRequestSchema;
         responseSchema: typeof PiDurableLeadProgressResponseSchema;
     }>;
+    events: Readonly<{
+        route: "events";
+        operation: "pi-durable.lead.events";
+        scope: "execution:read";
+        requestSchema: typeof PiDurableLeadEventsRequestSchema;
+        responseSchema: typeof PiDurableLeadEventsResponseSchema;
+    }>;
     children: Readonly<{
         route: "children";
         operation: "pi-durable.lead.children";
@@ -650,6 +817,20 @@ export declare const PiDurableLeadHttpContract: Readonly<{
         requestSchema: typeof PiDurableLeadCancelRequestSchema;
         responseSchema: typeof PiDurableLeadCancelResponseSchema;
     }>;
+    questionAnswer: Readonly<{
+        route: "questions/answer";
+        operation: "pi-durable.lead.question-answer";
+        scope: "execution:write";
+        requestSchema: typeof PiDurableLeadQuestionAnswerRequestSchema;
+        responseSchema: typeof PiDurableLeadQuestionAnswerResponseSchema;
+    }>;
+    childCancel: Readonly<{
+        route: "child-cancel";
+        operation: "pi-durable.lead.child-cancel";
+        scope: "execution:cancel";
+        requestSchema: typeof PiDurableLeadChildCancelRequestSchema;
+        responseSchema: typeof PiDurableLeadChildCancelResponseSchema;
+    }>;
 }>;
 export type PiDurableLeadPrepareRequest = z.output<typeof PiDurableLeadPrepareRequestSchema>;
 export type PiDurableLeadPrepareResponse = z.output<typeof PiDurableLeadPrepareResponseSchema>;
@@ -663,11 +844,18 @@ export type PiDurableLeadStatusRequest = z.output<typeof PiDurableLeadStatusRequ
 export type PiDurableLeadStatusResponse = z.output<typeof PiDurableLeadStatusResponseSchema>;
 export type PiDurableLeadProgressRequest = z.output<typeof PiDurableLeadProgressRequestSchema>;
 export type PiDurableLeadProgressResponse = z.output<typeof PiDurableLeadProgressResponseSchema>;
+export type PiDurableLeadEventsRequest = z.output<typeof PiDurableLeadEventsRequestSchema>;
+export type PiDurableLeadEventsResponse = z.output<typeof PiDurableLeadEventsResponseSchema>;
+export type PiDurableLeadTurnEvent = z.output<typeof PiDurableLeadTurnEventSchema>;
 export type PiDurableLeadChildrenRequest = z.output<typeof PiDurableLeadChildrenRequestSchema>;
 export type PiDurableLeadChildrenResponse = z.output<typeof PiDurableLeadChildrenResponseSchema>;
 export type PiDurableLeadChild = z.output<typeof PiDurableLeadChildSchema>;
 export type PiDurableLeadCancelRequest = z.output<typeof PiDurableLeadCancelRequestSchema>;
 export type PiDurableLeadCancelResponse = z.output<typeof PiDurableLeadCancelResponseSchema>;
+export type PiDurableLeadQuestionAnswerRequest = z.output<typeof PiDurableLeadQuestionAnswerRequestSchema>;
+export type PiDurableLeadQuestionAnswerResponse = z.output<typeof PiDurableLeadQuestionAnswerResponseSchema>;
+export type PiDurableLeadChildCancelRequest = z.output<typeof PiDurableLeadChildCancelRequestSchema>;
+export type PiDurableLeadChildCancelResponse = z.output<typeof PiDurableLeadChildCancelResponseSchema>;
 export type PiDurableLeadChildTargetRequest = z.output<typeof PiDurableLeadChildTargetRequestSchema>;
 export type PiDurableLeadChildTargetResponse = z.output<typeof PiDurableLeadChildTargetResponseSchema>;
 export type PiDurableLeadChildTarget = z.output<typeof PiDurableLeadChildTargetSchema>;

package/dist/pi-durable-lead.js

@@ -1,4 +1,5 @@
 import { z } from 'zod';
+import { PiDurableQuestionAnswersSchema, PiDurableQuestionRequestIdSchema, } from './pi-durable-questions.js';
 import { ContractVersionSchema, IdentifierSchemas, ModelSelectionFundingViewSchema, ModelSelectionRefSchema, PublicContractManifest, ReadRequestEnvelopeSchema, StateChangingCommandEnvelopeSchema, SuccessResponseEnvelopeSchema, negotiateContractVersion, } from '@adea-ai/contracts';
 import { RuntimeExecutionHandleSchema, RuntimeExecutionProgressSchema, RuntimeExecutionStatusSchema, RuntimeExecutionStateSchema, RuntimeObservedGenerationSchema, } from './adapter.js';
 const IntentId = z.uuid();
@@ -101,6 +102,69 @@ export const PiDurableLeadProgressRequestSchema = PiDurableLeadReadEnvelopeSchem
     })
         .strict(),
 });
+export const PI_DURABLE_LEAD_EVENTS_CONTRACT_VERSION = 1;
+export const PI_DURABLE_LEAD_EVENTS_MAX_PAGE = 256;
+export const PI_DURABLE_LEAD_EVENTS_MAX_WAIT_MS = 8000;
+const LeadEventSeq = z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER);
+export const PiDurableLeadEventsRequestSchema = PiDurableLeadReadEnvelopeSchema.extend({
+    operation: z.literal('pi-durable.lead.events'),
+    parameters: z
+        .object({
+        dispatchId: DispatchId,
+        messageId: z
+            .string()
+            .min(1)
+            .max(128)
+            .regex(/^[A-Za-z0-9._:-]+$/),
+        afterSeq: LeadEventSeq,
+        waitMs: z.number().int().min(0).max(PI_DURABLE_LEAD_EVENTS_MAX_WAIT_MS),
+        limit: z.number().int().min(1).max(PI_DURABLE_LEAD_EVENTS_MAX_PAGE).optional(),
+    })
+        .strict(),
+});
+export const PiDurableLeadTurnEventSchema = z
+    .object({
+    schemaVersion: z.literal(1),
+    eventId: z.string().min(1).max(256),
+    runtimeSessionId: z.string().regex(/^pi-lead:dispatch_[a-f0-9]{32}$/),
+    harnessRunId: z.string().min(1).max(256),
+    generation: z.literal(1),
+    seq: z.string().regex(/^[1-9]\d*$/),
+    occurredAt: z.iso.datetime(),
+    receivedAt: z.iso.datetime(),
+    source: z.literal('native'),
+    sourceEventId: z.string().min(1).max(256),
+    confidence: z.literal('authoritative'),
+    classification: z.enum(['workspace_private', 'restricted_local']),
+    kind: z.string().min(1).max(64),
+    payload: z.record(z.string(), z.unknown()),
+})
+    .strict();
+export const PiDurableLeadEventsDataSchema = z
+    .object({
+    contractVersion: z.literal(PI_DURABLE_LEAD_EVENTS_CONTRACT_VERSION),
+    dispatchId: DispatchId,
+    events: z
+        .array(PiDurableLeadTurnEventSchema)
+        .max(PI_DURABLE_LEAD_EVENTS_MAX_PAGE),
+    nextSeq: LeadEventSeq,
+    complete: z.boolean(),
+})
+    .strict()
+    .superRefine((value, context) => {
+    const first = value.nextSeq - value.events.length + 1;
+    value.events.forEach((event, index) => {
+        if (event.seq !== String(first + index) ||
+            event.runtimeSessionId !== `pi-lead:${value.dispatchId}`)
+            context.addIssue({
+                code: 'custom',
+                path: ['events', index],
+                message: 'Events must be the contiguous seqs of this dispatch ending at nextSeq',
+            });
+    });
+    if (first < 1)
+        context.addIssue({ code: 'custom', path: ['nextSeq'], message: 'nextSeq precedes the page' });
+});
 export const PiDurableLeadChildrenCursorSchema = z
     .object({ acceptedAt: z.iso.datetime(), delegationId: IdentifierSchemas.delegationId })
     .strict()
@@ -129,6 +193,25 @@ export const PiDurableLeadCancelRequestSchema = PiDurableLeadCommandEnvelopeSche
     operation: z.literal('pi-durable.lead.cancel'),
     payload: z.object({ dispatchId: DispatchId }).strict(),
 });
+export const PiDurableLeadQuestionAnswerRequestSchema = PiDurableLeadCommandEnvelopeSchema.extend({
+    operation: z.literal('pi-durable.lead.question-answer'),
+    payload: z
+        .object({
+        dispatchId: DispatchId,
+        requestId: PiDurableQuestionRequestIdSchema,
+        answers: PiDurableQuestionAnswersSchema,
+    })
+        .strict(),
+});
+export const PiDurableLeadChildCancelRequestSchema = PiDurableLeadCommandEnvelopeSchema.extend({
+    operation: z.literal('pi-durable.lead.child-cancel'),
+    payload: z
+        .object({
+        dispatchId: DispatchId,
+        delegationId: IdentifierSchemas.delegationId,
+    })
+        .strict(),
+});
 export const PiDurableLeadReceiptResponseSchema = z
     .object({
     schemaVersion: z.literal('pi-lead-dispatch/v1'),
@@ -247,6 +330,19 @@ export const PiDurableLeadProgressResponseSchema = response.extend({
     }),
 });
 export const PiDurableLeadCancelResponseSchema = PiDurableLeadStatusResponseSchema;
+export const PiDurableLeadQuestionAnswerResponseSchema = response.extend({
+    data: PiDurableLeadReceiptResponseSchema.extend({
+        questionSchemaVersion: z.literal('pi-lead-question-answer/v1'),
+        requestId: PiDurableQuestionRequestIdSchema,
+        requestEventId: z.string().min(1).max(256),
+        outcome: z.enum(['answered', 'already_answered', 'expired']),
+        state: RuntimeExecutionStateSchema,
+        status: RuntimeExecutionStatusSchema,
+    }),
+});
+export const PiDurableLeadEventsResponseSchema = response.extend({
+    data: PiDurableLeadEventsDataSchema,
+});
 const ChildReference = z
     .string()
     .trim()
@@ -313,6 +409,12 @@ export const PiDurableLeadChildrenResponseSchema = response.extend({
             });
     }),
 });
+export const PiDurableLeadChildCancelResponseSchema = response.extend({
+    data: PiDurableLeadReceiptResponseSchema.extend({
+        child: PiDurableLeadChildSchema,
+        attributed: z.boolean(),
+    }),
+});
 export const PiDurableLeadChildTargetSchema = z.strictObject({
     source: z.literal('control_plane_reported'),
     runtimeConnectionId: IdentifierSchemas.runtimeConnectionId,
@@ -443,6 +545,13 @@ export const PiDurableLeadHttpContract = Object.freeze({
         requestSchema: PiDurableLeadProgressRequestSchema,
         responseSchema: PiDurableLeadProgressResponseSchema,
     }),
+    events: Object.freeze({
+        route: 'events',
+        operation: 'pi-durable.lead.events',
+        scope: 'execution:read',
+        requestSchema: PiDurableLeadEventsRequestSchema,
+        responseSchema: PiDurableLeadEventsResponseSchema,
+    }),
     children: Object.freeze({
         route: 'children',
         operation: 'pi-durable.lead.children',
@@ -464,4 +573,18 @@ export const PiDurableLeadHttpContract = Object.freeze({
         requestSchema: PiDurableLeadCancelRequestSchema,
         responseSchema: PiDurableLeadCancelResponseSchema,
     }),
+    questionAnswer: Object.freeze({
+        route: 'questions/answer',
+        operation: 'pi-durable.lead.question-answer',
+        scope: 'execution:write',
+        requestSchema: PiDurableLeadQuestionAnswerRequestSchema,
+        responseSchema: PiDurableLeadQuestionAnswerResponseSchema,
+    }),
+    childCancel: Object.freeze({
+        route: 'child-cancel',
+        operation: 'pi-durable.lead.child-cancel',
+        scope: 'execution:cancel',
+        requestSchema: PiDurableLeadChildCancelRequestSchema,
+        responseSchema: PiDurableLeadChildCancelResponseSchema,
+    }),
 });

package/dist/pi-durable-questions.d.ts

@@ -0,0 +1,106 @@
+import { z } from 'zod';
+export declare const PI_QUESTION_TIMEOUT_DEFAULT_SECONDS: number;
+export declare const PI_QUESTION_TIMEOUT_MIN_SECONDS = 60;
+export declare const PI_QUESTION_TIMEOUT_MAX_SECONDS: number;
+export declare const PI_QUESTIONS_MAX = 8;
+export declare const PI_QUESTION_OPTIONS_MAX = 16;
+export declare const PI_QUESTION_CONTENT_BYTES_MAX: number;
+export declare const PiDurableQuestionRequestIdSchema: z.ZodString;
+export declare const PiDurableQuestionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    prompt: z.ZodString;
+    required: z.ZodBoolean;
+    kind: z.ZodLiteral<"text">;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    prompt: z.ZodString;
+    required: z.ZodBoolean;
+    kind: z.ZodLiteral<"choice">;
+    multiple: z.ZodBoolean;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "kind">;
+export type PiDurableQuestion = z.output<typeof PiDurableQuestionSchema>;
+export declare const PiDurableQuestionsSchema: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    prompt: z.ZodString;
+    required: z.ZodBoolean;
+    kind: z.ZodLiteral<"text">;
+}, z.core.$strict>, z.ZodObject<{
+    id: z.ZodString;
+    prompt: z.ZodString;
+    required: z.ZodBoolean;
+    kind: z.ZodLiteral<"choice">;
+    multiple: z.ZodBoolean;
+    options: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>], "kind">>;
+export declare const PiDurableQuestionAnswerSchema: z.ZodUnion<readonly [z.ZodObject<{
+    questionId: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    questionId: z.ZodString;
+    optionIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    questionId: z.ZodString;
+    skipped: z.ZodLiteral<true>;
+}, z.core.$strict>]>;
+export type PiDurableQuestionAnswer = z.output<typeof PiDurableQuestionAnswerSchema>;
+export declare const PiDurableQuestionAnswersSchema: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+    questionId: z.ZodString;
+    text: z.ZodString;
+}, z.core.$strict>, z.ZodObject<{
+    questionId: z.ZodString;
+    optionIds: z.ZodArray<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    questionId: z.ZodString;
+    skipped: z.ZodLiteral<true>;
+}, z.core.$strict>]>>;
+export declare const PiDurableQuestionRequestSchema: z.ZodObject<{
+    requestId: z.ZodString;
+    callId: z.ZodString;
+    questions: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        id: z.ZodString;
+        prompt: z.ZodString;
+        required: z.ZodBoolean;
+        kind: z.ZodLiteral<"text">;
+    }, z.core.$strict>, z.ZodObject<{
+        id: z.ZodString;
+        prompt: z.ZodString;
+        required: z.ZodBoolean;
+        kind: z.ZodLiteral<"choice">;
+        multiple: z.ZodBoolean;
+        options: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodString;
+            description: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>], "kind">>;
+    expiresAt: z.ZodISODateTime;
+}, z.core.$strict>;
+export type PiDurableQuestionRequest = z.output<typeof PiDurableQuestionRequestSchema>;
+export declare const PiDurableQuestionOutcomeSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    decision: z.ZodLiteral<"answered">;
+    answers: z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        questionId: z.ZodString;
+        text: z.ZodString;
+    }, z.core.$strict>, z.ZodObject<{
+        questionId: z.ZodString;
+        optionIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        questionId: z.ZodString;
+        skipped: z.ZodLiteral<true>;
+    }, z.core.$strict>]>>;
+    decidedAt: z.ZodISODateTime;
+}, z.core.$strict>, z.ZodObject<{
+    decision: z.ZodLiteral<"expired">;
+    decidedAt: z.ZodISODateTime;
+}, z.core.$strict>], "decision">;
+export type PiDurableQuestionOutcome = z.output<typeof PiDurableQuestionOutcomeSchema>;
+export declare function questionAnswersProblem(questions: readonly PiDurableQuestion[], input: unknown): string | undefined;

package/dist/pi-durable-questions.js

@@ -0,0 +1,109 @@
+import { z } from 'zod';
+export const PI_QUESTION_TIMEOUT_DEFAULT_SECONDS = 60 * 60;
+export const PI_QUESTION_TIMEOUT_MIN_SECONDS = 60;
+export const PI_QUESTION_TIMEOUT_MAX_SECONDS = 24 * 60 * 60;
+export const PI_QUESTIONS_MAX = 8;
+export const PI_QUESTION_OPTIONS_MAX = 16;
+export const PI_QUESTION_CONTENT_BYTES_MAX = 32 * 1024;
+const Id = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[A-Za-z0-9][A-Za-z0-9._:-]*$/);
+export const PiDurableQuestionRequestIdSchema = z.string().regex(/^pi-question:[a-f0-9]{32}$/);
+const OptionSchema = z.strictObject({
+    id: Id,
+    label: z.string().trim().min(1).max(512),
+    description: z.string().trim().min(1).max(2048).optional(),
+});
+export const PiDurableQuestionSchema = z.discriminatedUnion('kind', [
+    z.strictObject({
+        id: Id,
+        prompt: z.string().trim().min(1).max(4096),
+        required: z.boolean(),
+        kind: z.literal('text'),
+    }),
+    z.strictObject({
+        id: Id,
+        prompt: z.string().trim().min(1).max(4096),
+        required: z.boolean(),
+        kind: z.literal('choice'),
+        multiple: z.boolean(),
+        options: z
+            .array(OptionSchema)
+            .min(1)
+            .max(PI_QUESTION_OPTIONS_MAX)
+            .refine((options) => unique(options.map((option) => option.id)), 'duplicate option id'),
+    }),
+]);
+export const PiDurableQuestionsSchema = z
+    .array(PiDurableQuestionSchema)
+    .min(1)
+    .max(PI_QUESTIONS_MAX)
+    .refine((questions) => unique(questions.map((question) => question.id)), 'duplicate question id')
+    .refine((questions) => fits(questions), 'questions too large');
+export const PiDurableQuestionAnswerSchema = z.union([
+    z.strictObject({ questionId: Id, text: z.string().min(1).max(16_384) }),
+    z.strictObject({
+        questionId: Id,
+        optionIds: z
+            .array(Id)
+            .min(1)
+            .max(PI_QUESTION_OPTIONS_MAX)
+            .refine((ids) => unique(ids), 'duplicate option id'),
+    }),
+    z.strictObject({ questionId: Id, skipped: z.literal(true) }),
+]);
+export const PiDurableQuestionAnswersSchema = z
+    .array(PiDurableQuestionAnswerSchema)
+    .max(PI_QUESTIONS_MAX)
+    .refine((answers) => unique(answers.map((answer) => answer.questionId)), 'duplicate question id')
+    .refine((answers) => fits(answers), 'answers too large');
+export const PiDurableQuestionRequestSchema = z.strictObject({
+    requestId: PiDurableQuestionRequestIdSchema,
+    callId: z.string().min(1).max(256),
+    questions: PiDurableQuestionsSchema,
+    expiresAt: z.iso.datetime(),
+});
+export const PiDurableQuestionOutcomeSchema = z.discriminatedUnion('decision', [
+    z.strictObject({
+        decision: z.literal('answered'),
+        answers: PiDurableQuestionAnswersSchema,
+        decidedAt: z.iso.datetime(),
+    }),
+    z.strictObject({ decision: z.literal('expired'), decidedAt: z.iso.datetime() }),
+]);
+export function questionAnswersProblem(questions, input) {
+    const parsed = PiDurableQuestionAnswersSchema.safeParse(input);
+    if (!parsed.success)
+        return 'answers are malformed';
+    const answers = new Map(parsed.data.map((answer) => [answer.questionId, answer]));
+    for (const question of questions) {
+        const answer = answers.get(question.id);
+        answers.delete(question.id);
+        if (!answer || 'skipped' in answer) {
+            if (question.required)
+                return 'a required question is unanswered';
+        }
+        else if (question.kind === 'text') {
+            if (!('text' in answer))
+                return 'a text question needs a text answer';
+        }
+        else {
+            if (!('optionIds' in answer))
+                return 'a choice question needs option ids';
+            if (!question.multiple && answer.optionIds.length !== 1)
+                return 'expected a single choice';
+            const known = new Set(question.options.map((option) => option.id));
+            if (answer.optionIds.some((id) => !known.has(id)))
+                return 'unknown option id';
+        }
+    }
+    return answers.size ? 'unknown question id' : undefined;
+}
+function unique(values) {
+    return new Set(values).size === values.length;
+}
+function fits(value) {
+    return Buffer.byteLength(JSON.stringify(value), 'utf8') <= PI_QUESTION_CONTENT_BYTES_MAX;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adea-ai/runtime-sdk",
-  "version": "1.21.1",
+  "version": "1.23.0",
   "description": "SDK for building Control Plane runtimes: adapters, capabilities, conformance, discovery, eligibility, health, sessions, transport, and routing.",
   "keywords": [
     "adapter",
@@ -43,7 +43,7 @@
     "test": "bun test src"
   },
   "dependencies": {
-    "@adea-ai/contracts": "^1.26.0",
+    "@adea-ai/contracts": "^3.0.0",
     "zod": "4.6.6"
   },
   "engines": {