import * as _leitwerk_dev_domain from '@leitwerk-dev/domain'; import { SettingsContext, ResolvedSetting, SettingsSubject, ProcessInstance, ProcessProject, TurnId, ProcessTurnTerminalLifecycleStatus, MappedItem, ProcessTurnRecord, WorkerErrorClass, ProcessLeafOutcomeSnapshot, ProcessQuestionRequest, ProcessTurnRecordPathType, TurnAcceptanceState as TurnAcceptanceState$1, ProcessSemanticEntryRefKey, TurnProgressReport, ProcessTurnStartSelection, ProcessLifecycleStatus, InputSource, InputKind, ProcessInputTarget, LaunchModelConfigInput, ProcessCustomizableFields, Actor } from '@leitwerk-dev/domain'; import { ExternalWrites } from '@leitwerk-dev/external-writes'; import { UsageTokenCounts, UsageCostSnapshot, WatcherPresentationField } from '@leitwerk-dev/protocol'; import { ActionFormDefinition } from '@leitwerk-dev/protocol/form-contract'; import { SettingsScopeOverview, SettingMetadata, SettingChoice } from '@leitwerk-dev/protocol/http-contracts'; import { LauncherCardMetadata, LauncherSchemaDefinition, LauncherFieldOptionDefinition, LauncherValidationError, UiLauncherSummaryBase } from '@leitwerk-dev/protocol/launcher-contract'; import { ToolCallRendererDefinition } from '@leitwerk-dev/protocol/tool-renderer-contract'; /** @internal */ type CapabilityCardinality = "single" | "multi"; /** @public */ interface CapabilityToken<_TValue> { /** @internal */ readonly id: string; /** @internal */ readonly cardinality: CapabilityCardinality; } /** @public */ declare function createCapabilityToken(id: string, options?: { /** @internal */ cardinality?: CapabilityCardinality; }): CapabilityToken; /** Non-secret, JSON-compatible setting owned and validated by an extension. @public */ interface SettingDefinition extends SettingMetadata { /** Must reject invalid values without coercing missing overrides into empty values. @public */ schema: { /** @public */ parse(value: unknown): T; }; /** @public */ defaultValue: T; /** Label retained selections synchronously, without remote discovery. @public */ choiceLabel?(value: string): string; /** Dynamic non-secret choices for generic forms. @public */ choices?(context: SettingsContext, request?: { /** Search text supplied by the operator. @public */ search?: string; /** Saved selections that must remain discoverable while searching. @public */ values?: readonly string[]; }): readonly SettingChoice[] | Promise; } /** @public */ interface SettingsScopeDefinition { /** Namespaced; instance and repository are provided by core. @public */ id: string; /** @public */ label: string; /** Optional display names and label grouping for the generic scope overview. @public */ overview?: SettingsScopeOverview; } /** Trusted server-side discovery input. @public */ interface SettingsSubjectInput { /** @public */ scopeType: string; /** Stable identity, independent of the display name. @public */ identity: string; /** @public */ label: string; /** @public */ context?: SettingsContext; /** Normalized locators known by the provider to identify this repository. @public */ aliases?: readonly string[]; } /** Extension-owned purpose; separate from the internal title-generation model purpose. @public */ interface ExecutionPurposeDefinition { /** @public */ id: string; /** @public */ label: string; /** A nullable model-profile setting. Null delegates to YAML/catalog defaults. @public */ modelSettingKey?: string; /** Only these non-secret values are captured and sent to the worker. @public */ settingKeys?: readonly string[]; } /** @public */ interface ScopedSettingsDeclaration { /** @public */ scopes?: readonly SettingsScopeDefinition[]; /** @public */ settings: readonly SettingDefinition[]; /** @public */ purposes?: readonly ExecutionPurposeDefinition[]; } /** Server-only capability. Workers receive immutable start snapshots. @public */ interface ScopedSettingsResolver { /** @public */ resolve(definition: SettingDefinition, context: SettingsContext): ResolvedSetting; /** Read a retained subject by stable identity without discovery or remote requests. @public */ findSubject(scopeType: string, identity: string): SettingsSubject | null; /** Read a retained subject by ID, including retained redirects. @public */ getSubject(id: string): SettingsSubject | null; /** Initialize a field once. Existing overrides and explicit resets are preserved. @public */ seedOverride(subjectId: string, definition: SettingDefinition, value: T): boolean; /** Retains stable subject identities and known aliases across rediscovery. @public */ discover(input: SettingsSubjectInput): SettingsSubject; /** Called only by explicit discovery, never during step preparation. @public */ registerDiscovery(scopeType: string, discover: () => Promise, options?: { /** Limit navigation without deleting retained subjects or overrides. @public */ includesSubject?: (subject: SettingsSubject, context: Readonly>) => boolean; }): void; } /** @public */ declare const scopedSettingsCapability: CapabilityToken; /** Provider origins and stable IDs define identity; clone URLs are aliases. @public */ declare function repositorySettingsIdentity(origin: string, repositoryId: string | number): string; /** @public */ type MaybePromise$1 = T | Promise; /** Graph trigger used by a mapped turn's collection route. @internal */ declare const MAPPED_COLLECT_TRIGGER: "collect"; /** Durable snapshot of process data available to mapped-turn server callbacks. @public */ interface MappedTurnServerContext { /** @public */ readonly process: ProcessInstance; /** @internal */ readonly projects: readonly ProcessProject[]; /** @public */ readonly params: TParams; /** @public */ readonly state: TState; } /** Active item of a mapped LLM turn, as delivered to one worker turn. @public */ interface MappedTurnItemContext { /** Frozen, codec-validated item value. @public */ readonly item: TItem; /** Stable key unique within the run. @public */ readonly itemKey: string; /** Short plain-text label shown to operators. @public */ readonly itemLabel: string; /** Zero-based position in the frozen order. @public */ readonly itemIndex: number; /** Number of frozen items in the run. @public */ readonly itemCount: number; } /** Serialized active item carried by worker payloads and turn records. @internal */ interface MappedTurnIteration extends MappedTurnItemContext { /** @internal */ readonly runId: string; } /** @public */ interface MappedItemInput { /** @public */ readonly item: TItem; /** @public */ readonly index: number; } /** @public */ interface MappedSnapshotInput { /** @public */ readonly params: TParams; /** @public */ readonly state: TState; /** @public */ readonly items: readonly TItem[]; } /** Context passed to a mapped outcome's `yield` callback. @public */ interface MappedOutcomeContext extends MappedTurnServerContext, MappedTurnItemContext { } /** @public */ interface MappedYieldInput { /** @public */ readonly ctx: MappedOutcomeContext; /** @public */ readonly event: ProcessTurnOutcomeEvent; } /** @public */ type MappedItemYield = (input: MappedYieldInput) => MaybePromise$1; /** @public */ type MappedCollect = (ctx: MappedTurnServerContext, orderedResults: readonly TResult[]) => MaybePromise$1; /** Route applied once, after collection. @internal */ type MappedCollectRouting = { /** @internal */ kind: "static"; /** @internal */ to?: TurnId; /** @internal */ lifecycleStatus?: ProcessTurnTerminalLifecycleStatus; } | { /** @internal */ kind: "branches"; /** @internal */ branches: Readonly>; /** @internal */ choose(ctx: MappedTurnServerContext): MaybePromise$1; }; /** * Durable sequential iteration of one LLM turn over frozen items. Items run one * at a time; each item yields a typed result, and business state and routing * change once, when all results are collected. * @public */ interface MappedLlmTurnSpec { /** Evaluated once when the turn is entered. @public */ items(ctx: MappedTurnServerContext): readonly unknown[] | null | undefined; /** @public */ itemCodec: Codec; /** @public */ resultCodec: Codec; /** @public */ key(input: MappedItemInput): string; /** Defaults to the item key. @public */ label?(input: MappedItemInput): string; /** Applied in the freezing transaction, before any item starts. @public */ stateAfterSnapshot?(input: MappedSnapshotInput): TState; /** @internal */ yields: Readonly>>; /** @internal */ collect: MappedCollect; /** @internal */ routing: MappedCollectRouting; } /** @internal */ type FrozenMappedItem = Pick; /** @internal */ interface MappedFreezeResult { /** @internal */ items: FrozenMappedItem[]; /** State to persist in the freezing transaction, when `stateAfterSnapshot` is declared. @internal */ state?: TState; } /** @internal */ interface MappedCollectResult { /** @internal */ state: TState; /** @internal */ route: { /** @internal */ trigger: string; /** @internal */ nextTurnId?: TurnId; /** @internal */ lifecycleStatus?: ProcessTurnTerminalLifecycleStatus; }; } /** Evaluates, validates, and serializes the items of a mapped turn. @internal */ declare function freezeMappedItems(turnId: TurnId, spec: MappedLlmTurnSpec, ctx: MappedTurnServerContext): MappedFreezeResult; /** Maps one item outcome to its serialized, codec-validated result. @internal */ declare function yieldMappedItemResult(input: { /** @internal */ turnId: TurnId; /** @internal */ spec: MappedLlmTurnSpec; /** @internal */ ctx: MappedTurnServerContext; /** @internal */ iteration: MappedTurnIteration; /** @internal */ event: ProcessTurnOutcomeEvent; }): Promise; /** Collects ordered results once and resolves the turn's single business route. @internal */ declare function collectMappedResults(input: { /** @internal */ turnId: TurnId; /** @internal */ spec: MappedLlmTurnSpec; /** @internal */ ctx: MappedTurnServerContext; /** Serialized results in frozen item order. @internal */ resultJsons: readonly string[]; }): Promise>; /** @internal */ interface ProcessCreatedEvent { /** @internal */ instanceId: string; /** @internal */ process: ProcessInstance; /** @internal */ projects: readonly ProcessProject[]; /** @internal */ launcherId?: string | null; } /** @internal */ interface ProcessUpdatedEvent { /** @internal */ instanceId: string; /** @internal */ process: ProcessInstance; /** @internal */ changedFields: readonly string[]; } /** @internal */ interface TurnStartedEvent { /** @internal */ instanceId: string; /** @internal */ turnRecord: ProcessTurnRecord; } /** @internal */ interface TurnFailedEvent { /** @internal */ instanceId: string; /** @internal */ turnRecord: ProcessTurnRecord; /** @internal */ errorSummary: string; /** @internal */ errorClass?: WorkerErrorClass | null; } /** @internal */ interface LeafOutcomeCapturedEvent { /** @internal */ instanceId: string; /** @internal */ snapshot: ProcessLeafOutcomeSnapshot; } /** @internal */ interface ReviewRequestedEvent { /** @internal */ instanceId: string; /** @internal */ workerId?: string; /** @internal */ changedProjects: string[]; } /** @internal */ interface QuestionRequestedEvent { /** @internal */ instanceId: string; /** @internal */ request: ProcessQuestionRequest; } /** @internal */ interface TurnOutcomeEvent { /** @internal */ instanceId: string; /** @internal */ turnRecordId: string; /** @internal */ turnId: string; /** @internal */ outcome: string; /** @internal */ params: Record; /** @internal */ turnResultMarkdown?: string | null; } /** @internal */ interface PlanApprovedEvent { /** @internal */ instanceId: string; /** @internal */ externalId: string | null; /** @internal */ planRevision: number; } /** @internal */ interface PlanRevisionRequestedEvent { /** @internal */ instanceId: string; /** @internal */ message: string; } /** @internal */ interface PlanSavedEvent { /** @internal */ instanceId: string; /** @internal */ planRevision: number; /** @internal */ summary: string; /** @internal */ planMarkdown: string; /** @internal */ acceptanceCriteria: string[]; } /** @internal */ interface ReviewCompletedEvent { /** @internal */ instanceId: string; /** @internal */ hasIssues: boolean; /** @internal */ issueCount: number; /** @internal */ reviewMarkdown?: string; } /** @internal */ interface ServerExtensionEventMap { /** @internal */ process_created: ProcessCreatedEvent; /** @internal */ process_updated: ProcessUpdatedEvent; /** @internal */ turn_started: TurnStartedEvent; /** @internal */ turn_failed: TurnFailedEvent; /** @internal */ leaf_outcome_captured: LeafOutcomeCapturedEvent; /** @internal */ question_requested: QuestionRequestedEvent; /** @internal */ review_requested: ReviewRequestedEvent; /** @internal */ turn_outcome: TurnOutcomeEvent; /** @internal */ plan_approved: PlanApprovedEvent; /** @internal */ plan_revision_requested: PlanRevisionRequestedEvent; /** @internal */ plan_saved: PlanSavedEvent; /** @internal */ review_completed: ReviewCompletedEvent; } /** @internal */ type ServerExtensionEventName = keyof ServerExtensionEventMap; /** @internal */ type ServerExtensionEventPayloadInputMap = { [K in keyof ServerExtensionEventMap]: Omit; }; /** Initial repository bindings resolved before the first execution. @public */ type InitialProcessBinding = Pick, "params" | "metadata" | "settingsContext"> & { /** Complete, nonempty repository set. @public */ projects: readonly ProcessLaunchProjectConfig[]; }; /** A server-owned readiness decision, with no worker attempt. @public */ type TurnWaitDecision = TurnWaitCompletion | TurnWaitNotice | TurnWaitBinding; /** A readiness condition or source cancellation with operator guidance. @public */ interface TurnWaitNotice { /** @internal */ readonly kind: "waiting" | "abort"; /** Safe operator guidance. @public */ readonly message: string; } /** Initial bindings staged by a successful readiness check. @public */ interface TurnWaitBinding { /** @internal */ readonly kind: "bind"; /** @internal */ readonly binding: InitialProcessBinding; } /** A terminal decision returned from a turn's server-side waiting condition. @public */ interface TurnWaitCompletion { /** @internal */ readonly kind: "complete"; } /** Server context for a repeatable condition. External operations must be read-only. @public */ interface TurnWaitContext extends ProcessSnapshotContext { /** Cancelled on timeout or server shutdown. @public */ readonly signal: AbortSignal; /** Resolve an extension-owned server adapter. Never perform external writes here. @public */ require(token: CapabilityToken): T | T[]; /** Stage process state with this check; stale and failed checks discard it. @public */ setState(state: TState): void; /** Wait at the normal polling interval with safe operator guidance. Return this decision. @public */ waiting(message: string): TurnWaitDecision; /** Abort without a worker when the source is cancelled. Return this decision. @public */ abort(message: string): TurnWaitDecision; /** Bind initial params and projects atomically, then check again before starting a worker. Only available before any project or execution exists. @public */ bindInitialProjects(binding: InitialProcessBinding): TurnWaitDecision; /** Finish the process without allocating a worker. Return this decision. @public */ complete(): TurnWaitCompletion; } /** False keeps this turn waiting; true permits execution; complete ends the process. @public */ type TurnWaitPredicate = (process: TurnWaitContext) => boolean | TurnWaitDecision | Promise>; /** A temporary observation failure. Other predicate errors require an explicit retry. @public */ declare class RetryableWaitError extends Error { /** The message must be safe to show to an operator. @public */ constructor(message: string, options?: ErrorOptions); } /** @internal */ interface TurnOptions { /** @internal */ reset?: boolean; } /** @internal */ interface TurnResult { /** @internal */ outcome: T; /** @internal */ params: Record; } /** @public */ declare const PI_BUILT_IN_TOOL_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls"]; /** @public */ type PiBuiltInToolName = (typeof PI_BUILT_IN_TOOL_NAMES)[number]; /** Names integration tools cannot use because Pi or the worker runtime owns them. @internal */ declare const RESERVED_INTEGRATION_TOOL_NAMES: readonly ["read", "bash", "edit", "write", "grep", "find", "ls", "abort_turn", "ask_questions", "markdown_result", "upload_result_images"]; /** @public */ interface ProcessPiConfig { /** * System prompt template. Rendered with Mustache against runtime context. * Use {{variableName}} for escaped values and {{{variableName}}} for raw values. * When omitted, Pi's default system prompt is used. */ /** @internal */ systemPromptTemplate?: string; /** * Additional text appended after the base system prompt/resources. Rendered * with Mustache against runtime context. */ /** @public */ appendSystemPromptTemplate?: string; /** * Code-defined Pi session working directory template. Rendered with Mustache * against runtime context. When omitted, the process workspace root is used. */ /** @public */ sessionCwdTemplate?: string; } /** @internal */ interface ResolvedProcessPiConfig { /** @internal */ systemPrompt?: string; /** @internal */ appendSystemPrompt?: string; /** @internal */ sessionCwd?: string; /** @internal */ availableToolNames: string[]; } /** @public */ type OutcomeToolParameterType = "string" | "number" | "array" | "boolean" | "object"; /** JSON-schema-compatible value declaration nested below an outcome parameter. @public */ interface OutcomeToolArrayItemSpec { /** @public */ type?: OutcomeToolParameterType; /** Alternatives; declare either type or a nonempty anyOf. @public */ anyOf?: readonly OutcomeToolArrayItemSpec[]; /** @public */ description?: string; /** @public */ minItems?: number; /** @public */ items?: OutcomeToolArrayItemSpec; /** @public */ properties?: Record; /** @public */ required?: readonly string[]; /** @public */ additionalProperties?: boolean; /** @public */ enum?: readonly string[]; /** @public */ minLength?: number; /** @public */ minimum?: number; } /** @public */ interface OutcomeToolParameterSpec { /** @internal */ type?: OutcomeToolParameterType; /** Alternatives for this parameter. @public */ anyOf?: readonly OutcomeToolArrayItemSpec[]; /** @public */ minLength?: number; /** @internal */ description: string; /** @internal */ required?: boolean; /** @internal */ requiredErrorCode?: string; /** @internal */ invalidErrorCode?: string; /** @internal */ minItems?: number; /** @internal */ minItemsErrorCode?: string; /** @internal */ minimum?: number; /** @internal */ minimumErrorCode?: string; /** @internal */ items?: OutcomeToolArrayItemSpec; /** @internal */ enum?: readonly string[]; /** Properties of an object parameter. @public */ properties?: Record; /** Required keys inside an object; `required` marks the parameter itself. @public */ requiredProperties?: readonly string[]; /** Whether an object accepts undeclared keys. @public */ additionalProperties?: boolean; } /** @internal */ interface OutcomeToolSpec { /** Opt in to provider enforcement of the complete schema. @internal */ strictSchema?: boolean; /** @internal */ description: string; /** @internal */ parameters: Record; /** Product published from this outcome's turn-result markdown, when selected. @internal */ publishedProduct?: string; /** Outcome parameter whose markdown value is captured as the turn result. @internal */ turnResultMarkdownParameter?: string; /** Outcome parameter containing a concise operator-facing summary. @internal */ resultSummaryParameter?: string; } /** @public */ interface PiTreeEntry { /** @internal */ readonly id: string; /** @internal */ readonly parentId: string | null; /** @public */ readonly type: string; /** @internal */ readonly timestamp: string; /** @public */ readonly message?: { /** @internal */ readonly role?: string; /** @public */ readonly content?: unknown; }; /** Pi custom-message fields. Details are intentionally excluded from model context. @internal */ readonly customType?: string; /** @public */ readonly content?: unknown; /** @internal */ readonly details?: unknown; /** @internal */ readonly targetId?: string; /** @internal */ readonly label?: string; } /** @internal */ interface PiTreeNode { /** @internal */ readonly entry: PiTreeEntry; /** @internal */ readonly children: readonly PiTreeNode[]; /** @internal */ readonly label?: string; /** @internal */ readonly labelTimestamp?: string; } /** @public */ interface PiTurnExecutionResult { /** @internal */ startLeafId: string | null; /** @internal */ endLeafId: string | null; /** @internal */ createdEntryIds: string[]; /** @internal */ resultEntryId: string; /** Final assistant markdown captured from the Pi assistant message for this turn, when available. @internal */ assistantMarkdown?: string | null; } /** @internal */ type PiEventType = "inspection" | "turn.start" | "turn.end" | "stream.delta" | "tool.call" | "tool.update" | "tool.result" | "toolcall.start" | "toolcall.delta" | "toolcall.end" | "compaction.start" | "compaction.end" | "label.changed" | "error" | "retry.start" | "retry.end" | "usage"; /** @internal */ interface PiEvent { /** @internal */ type: PiEventType; /** @internal */ turnId: string; /** @internal */ data: Record; /** @internal */ timestamp: string; } /** @internal */ type PiEventHandler = (event: PiEvent) => void; /** @internal */ type PiSessionDiagnosticLevel = "debug" | "info" | "warn" | "error"; /** @internal */ interface PiSessionDiagnostic { /** @internal */ level: PiSessionDiagnosticLevel; /** @internal */ code: string; /** @internal */ message: string; /** @internal */ timestamp: string; /** @internal */ turnId?: string; /** @internal */ details?: Record; } /** @internal */ type PiSessionDiagnosticHandler = (diagnostic: PiSessionDiagnostic) => void; /** @public */ interface PiCustomToolExecutionContext { /** Pi's identity for this exact invocation; stable across the paused call. @public */ toolCallId: string; /** Aborted when the active turn is stopped or torn down. @public */ signal: AbortSignal; /** Pause model-execution budgets while this custom tool awaits durable operator input. @internal */ suspendPromptGuards?: () => () => void; } /** @public */ interface PiCustomTool { /** Opt in to provider schema enforcement. @internal */ strictSchema?: boolean; /** Hidden tools remain callable by runtime callbacks. @internal */ modelVisible?: boolean; /** @public */ name: string; /** @internal */ description: string; /** @internal */ parameters: Record; /** @internal */ executionMode?: "sequential" | "parallel"; /** @public */ execute(args: Record, context?: PiCustomToolExecutionContext): Promise; } /** @internal */ interface PiUsageData extends UsageTokenCounts { /** @internal */ cost: UsageCostSnapshot; /** @internal */ cacheHitRate: number; } /** @internal */ interface PiRunDetails { /** @internal */ loadedAgentsFiles: Array<{ /** @internal */ path: string; /** @internal */ sizeBytes: number; }>; /** @internal */ loadedSkills: Array<{ /** @internal */ name: string; /** @internal */ path: string; }>; /** @internal */ availableToolNames: string[]; } /** @public */ interface PiCustomMessageInput { /** @internal */ content: string; /** @internal */ details: unknown; /** @internal */ display?: boolean; } /** @internal */ type PiTerminalAcknowledgementState = "open" | "outcome_accepted" | "acknowledgement_succeeded" | "acknowledgement_failed_ignored"; /** @internal */ interface PiTerminalAcknowledgementControl { /** @internal */ readonly timeoutMs: number; /** @internal */ state(): PiTerminalAcknowledgementState; /** @internal */ isOperatorAbortRequested(): boolean; /** @internal */ markSucceeded(): void; /** @internal */ markFailed(reason: string): void; } /** @public */ interface PiPromptOptions { /** @public */ tools?: readonly PiCustomTool[]; /** @internal */ activeTools?: readonly string[]; /** @internal Runtime-only hook used by the worker Pi adapter before a tool executes. */ shouldBlockToolCall?: (toolName: string) => string | null; /** @internal Return control to the worker after a model response and its tool results. */ shouldStopAfterTurn?: (toolResults: readonly unknown[]) => boolean; /** @internal Guard suspension used by durable interactive tools. */ suspendPromptGuards?: () => () => void; /** @internal Runtime-only terminal outcome acknowledgement state. */ terminalAcknowledgement?: PiTerminalAcknowledgementControl; } /** @public */ interface PiTreeHandle { /** @internal */ readonly sessionId: string; /** @internal */ readonly treeFile: string; /** @internal */ readonly isResumed: boolean; /** @internal */ getRunDetails(): PiRunDetails; /** @internal */ getLeafId(): string | null; /** @internal */ getEntry(id: string): PiTreeEntry | undefined; /** @internal */ getBranch(fromId?: string): PiTreeEntry[]; /** @internal */ getChildren(parentId: string): PiTreeEntry[]; /** @internal */ getTree(): PiTreeNode[]; /** @internal */ branch(entryId: string): void | Promise; /** @internal */ branchFromRoot(): void | Promise; /** @internal */ resetLeaf(): void | Promise; /** * Compact the current Pi context. `details` is persisted with the resulting * compaction entry, but deliberately remains outside model context. */ /** @internal */ compact?(customInstructions?: string, details?: unknown): Promise; /** @public */ prompt(text: string, options?: PiPromptOptions): Promise; /** @public */ promptLiteral(text: string, options?: PiPromptOptions): Promise; /** @public */ promptCustom(input: PiCustomMessageInput, options?: PiPromptOptions): Promise; /** @public */ continueTurn(options?: PiPromptOptions): Promise; /** @internal */ appendCustomMessage?(input: PiCustomMessageInput): Promise; /** @internal */ steer(text: string): Promise; /** @internal */ abortTurn(): Promise; /** @internal */ subscribe(handler: PiEventHandler): () => void; /** @internal */ subscribeDiagnostics?(handler: PiSessionDiagnosticHandler): () => void; /** @internal */ close(): Promise; } /** @public */ declare const TURN_CONTEXT_MODES: readonly ["full", "compacted", "fresh", "fresh_seeded"]; /** @public */ type TurnContextMode = (typeof TURN_CONTEXT_MODES)[number]; /** @public */ declare const TURN_COMPLETION_MODES: readonly ["turn_end"]; /** @public */ type TurnCompletionMode = (typeof TURN_COMPLETION_MODES)[number]; /** @public */ type TurnBranchType = ProcessTurnRecordPathType; /** @public */ interface TurnResultMarkdownNoneBehavior { /** @internal */ mode: "none"; } /** @public */ interface TurnResultMarkdownAssistantOutputBehavior { /** @internal */ mode: "assistant_output"; /** @internal */ required?: boolean; } /** @public */ interface TurnResultMarkdownToolCallBehavior { /** @internal */ mode: "tool_call"; /** @internal */ toolName: string; /** @internal */ source?: "arguments" | "result"; /** @internal */ path: string; /** @internal */ required?: boolean; } /** @public */ interface TurnResultMarkdownOutcomeToolArgumentBehavior { /** @internal */ mode: "outcome_tool_argument"; /** @internal */ parameterName: string; /** @internal */ required?: boolean; } /** @public */ type TurnResultMarkdownBehavior = TurnResultMarkdownNoneBehavior | TurnResultMarkdownAssistantOutputBehavior | TurnResultMarkdownToolCallBehavior | TurnResultMarkdownOutcomeToolArgumentBehavior; /** @public */ type TurnAcceptanceState = TurnAcceptanceState$1; /** @public */ interface ProcessActionSchedulingFixedTurnPreview { /** @public */ kind: "fixed_turn"; /** @public */ turnId: TurnId | null; } /** @public */ interface ProcessActionSchedulingTriggerPreview { /** @public */ kind: "trigger"; /** @internal */ trigger: string; } /** @public */ interface ProcessActionSchedulingTerminalPreview { /** @public */ kind: "terminal"; /** @internal */ lifecycleStatus: ProcessTurnTerminalLifecycleStatus; } /** @public */ type ProcessActionSchedulingPreview = ProcessActionSchedulingFixedTurnPreview | ProcessActionSchedulingTriggerPreview | ProcessActionSchedulingTerminalPreview; /** @public */ type ProcessActionPreviewDefinition = ProcessActionSchedulingPreview; /** @internal */ interface ProcessActionSchedulingDefinition { /** @internal */ preview: ProcessActionSchedulingPreview; } /** @internal */ interface HumanTurnActionView { /** @internal */ actionId: string; /** @internal */ acceptanceState: TurnAcceptanceState; /** @internal */ label?: string; /** @internal */ description?: string; /** @internal */ preview?: ProcessActionPreviewDefinition; /** @internal */ scheduling?: ProcessActionSchedulingDefinition; } /** @internal */ interface HumanTurnNotesField { /** @internal */ id: string; /** @internal */ label: string; /** @internal */ description?: string; /** @internal */ placeholder?: string; /** @internal */ required?: boolean; } /** @internal */ interface HumanTurnExternalTrigger { /** @internal */ id: string; /** @internal */ actionId: string; /** @internal */ label: string; /** @internal */ description: string; } /** @internal */ interface EventBus> { /** @internal */ emit(event: K, data: TEventMap[K]): void; /** @internal */ on(event: K, handler: (data: TEventMap[K]) => void | Promise): void; /** @internal */ off(event: K, handler: (data: TEventMap[K]) => void | Promise): void; } /** @internal */ type ProcessEventName = keyof ServerExtensionEventMap & string; /** @internal */ type ProcessEmittedEvent = { /** @internal */ type: ProcessEventName; /** @internal */ data: unknown; }; /** @public */ type ProcessQueuedInput = Parameters[0]; /** @public */ type MaybePromise = T | Promise; /** @public */ type StaticRouteTarget = { /** @public */ to?: TurnId; /** @internal */ complete?: boolean; /** @public */ lifecycleStatus?: ProcessTurnTerminalLifecycleStatus; }; /** @public */ interface ProcessRuntimeTurnContext extends WorkerProcessContext { } /** An outcome-tool submission awaiting acceptance. @public */ interface LlmOutcomeSubmission { /** @public */ outcome: string; /** @public */ params: Record; } /** @internal */ interface LlmTurnPreparationContext extends ProcessRuntimeTurnContext { /** @internal */ callIntegrationTool(name: string, args: Record): Promise; /** @internal */ reportProgress(report: TurnProgressReport): void; } /** @public */ interface ProcessServerRuntimeContext { /** @internal */ readonly process: ServerProcessContext["process"]; /** @internal */ readonly projects: ServerProcessContext["projects"]; /** @internal */ readonly params: TParams; /** @public */ readonly state: TState; /** @internal */ readSemanticTurnResultMarkdown(ref: ProcessSemanticEntryRefKey): string | null; /** @internal */ readProductTurnResultMarkdown(productName: string): string | null; /** @internal */ reportProgress?(report: TurnProgressReport): void; } /** @internal */ interface ProcessBroadcastEffect { /** @internal */ type: string; /** @internal */ payload: Record; } /** @public */ type ProcessPatchEffect = Partial>; /** @public */ interface ProcessLifecycleEffects { /** @public */ processPatch?: ProcessPatchEffect; /** @internal */ broadcasts?: readonly ProcessBroadcastEffect[]; } /** @public */ interface ProcessEffectPlan extends ProcessLifecycleEffects { /** @public */ state?: TState; /** @internal */ emit?: readonly ProcessEmittedEvent[]; /** @public */ queueInput?: readonly ProcessQueuedInput[]; } /** @public */ interface ProcessActionExecution { /** @public */ readonly ctx: ProcessServerRuntimeContext; /** @public */ readonly input: Record; /** @internal */ readonly turnId: TurnId; /** @internal */ readonly actionId: string; /** @internal */ readonly selectedBranchId?: string; } /** @public */ interface ProcessOutcomeExecution { /** @internal */ readonly ctx: ProcessServerRuntimeContext; /** @internal */ readonly event: ProcessTurnOutcomeEvent; /** @internal */ readonly turnId: TurnId; /** @internal */ readonly outcome: string; } /** @public */ type ProcessActionEffect = (input: ProcessActionExecution) => MaybePromise | undefined>; /** @public */ type ProcessActionBranchSelector = (input: Omit, "selectedBranchId">) => MaybePromise; /** @public */ type ProcessOutcomeEffect = (input: ProcessOutcomeExecution) => MaybePromise | undefined>; /** @internal */ type ProcessOutcomeBranchSelector = (input: ProcessOutcomeExecution) => MaybePromise; /** Branch route and display metadata for state-routed outcomes. @public */ interface ProcessOutcomeBranchSpec extends StaticRouteTarget { /** @internal */ trigger?: string; /** Display name for the branch condition in the workflow graph. @public */ label?: string; /** Explains the condition without evaluating runtime state. @public */ description?: string; } /** @internal */ interface ProcessActionExternalTrigger { /** @internal */ id: string; /** @internal */ label: string; /** @internal */ description: string; } /** @internal */ interface ExternalActionInputPublication { /** @internal */ productName: string; /** @internal */ inputField: string; } /** @public */ interface ProcessHumanTurnExternalActionSpec = Record> extends StaticRouteTarget { /** @internal */ id: string; /** @internal */ source: ExternalActionSource; /** Arms and exposes this action only when the current process snapshot matches. @public */ when?: (ctx: ExternalSourceResolveContext) => boolean; /** @internal */ label?: string; /** @internal */ description?: string; /** @internal */ publishInput?: ExternalActionInputPublication; /** @public */ effect?: ExternalSourceEffect; } /** @public */ interface ProcessActionBranchSpec extends StaticRouteTarget { /** @internal */ trigger?: string; } /** @public */ type StaticActionRouting = StaticRouteTarget & { /** @internal */ trigger?: string; }; /** @public */ type BranchingActionRouting = { /** @public */ branches: Record; /** @public */ choose: ProcessActionBranchSelector; }; /** @public */ interface BaseActionSpec { /** @public */ label: string; /** @public */ description?: string; /** @internal */ form?: ActionFormDefinition; /** @public */ preview?: ProcessActionPreviewDefinition; /** @public */ schedulable?: boolean; /** @public */ effect?: ProcessActionEffect; } /** @public */ type ProcessHumanTurnActionSpec = BaseActionSpec & { /** @public */ acceptanceState: TurnAcceptanceState; /** @internal */ externalTriggers?: readonly ProcessActionExternalTrigger[]; } & (StaticActionRouting | BranchingActionRouting); /** Pure inputs for resolving a tool contract before worker preparation. @public */ interface OutcomeParameterContext { /** @public */ readonly params: TParams; /** @public */ readonly state: TState; } /** @public */ interface ProcessToolOutcomeBaseSpec { /** Resolve parameters synchronously from captured process data. @public */ resolveParameters?: (ctx: OutcomeParameterContext) => Record; /** Opt in to provider schema enforcement. @public */ strictSchema?: boolean; /** @internal */ description: string; /** @internal */ parameters: Record; /** Product published from this outcome's turn-result markdown, when this outcome is selected. @internal */ publishedProduct?: string; /** Outcome parameter whose markdown value is captured as the turn result. @internal */ turnResultMarkdownParameter?: string; /** Outcome parameter containing a concise operator-facing summary. @internal */ resultSummaryParameter?: string; /** @internal */ effect?: ProcessOutcomeEffect; } /** @public */ type ProcessToolOutcomeSpec = ProcessToolOutcomeBaseSpec & (StaticRouteTarget | { /** @internal */ branches: Record; /** @internal */ choose: ProcessOutcomeBranchSelector; }); /** @public */ type HumanTurnOperatorAttention = "required" | "passive"; /** @public */ interface HumanTurnDefinition { /** @public */ kind: "human"; /** @public */ description: string; /** Named product rendered as the subject of this human review turn. @internal */ reviewProduct?: string; /** @internal */ reviewSemanticRef?: ProcessSemanticEntryRefKey; /** Controls whether entering this turn should raise an action-required toast. @public */ operatorAttention?: HumanTurnOperatorAttention; /** @internal */ notesFields?: readonly HumanTurnNotesField[]; /** @internal */ commentary?: string; /** @public */ actions: Record>; /** @internal */ externalActions?: Record>; } /** @public */ interface ProcessTurnEndSpec extends StaticRouteTarget { /** @public */ outcome: TOutcome; /** @public */ params?: Record; /** @public */ effect?: ProcessOutcomeEffect; } /** @internal */ type OutcomeRouteSpec = StaticRouteTarget & Partial, "description" | "parameters" | "effect">>; /** @internal */ interface OutcomeRouteOptions { /** @internal */ strict?: boolean; } /** @internal */ type LlmModelPurpose = "process_title_generation"; /** @public */ interface LlmTurnDefinition { /** @public */ kind: "llm"; /** @public */ description: string; /** Server-side entry condition, evaluated before worker allocation. @public */ waitFor?: TurnWaitPredicate; /** External events armed while this LLM turn is selected and waiting. @public */ externalActions?: Record>; /** Code-defined model policy purpose. Purpose selections cannot be overridden per launch/action. @internal */ modelPurpose?: LlmModelPurpose; /** Extension-defined scoped settings consumed by this turn. @public */ executionPurpose?: string; /** Built-in Pi tools active while this turn runs. @public */ availableTools: readonly PiBuiltInToolName[]; /** Server-owned integration tools proxied over authenticated worker IPC. @internal */ integrationTools?: readonly string[]; /** Resolve a constrained tool set from validated durable process data at turn start. @public */ resolveIntegrationTools?: (params: TParams, state: TState) => readonly string[]; /** Opt in to the durable, operator-facing ask_questions custom tool. @internal */ askQuestions?: boolean; /** Constrain questions using captured process data and completed preparation before prompting. @public */ resolveAskQuestions?: (ctx: ProcessRuntimeTurnContext) => boolean; /** Deterministic worker preparation that must complete before Pi is prompted. @internal */ prepare?(ctx: LlmTurnPreparationContext): MaybePromise; /** Return actionable errors before an outcome is accepted; no durable effects. @internal */ validateOutcome?(ctx: LlmTurnPreparationContext, outcome: LlmOutcomeSubmission): MaybePromise; /** @public */ completionMode?: TurnCompletionMode; /** @public */ branchType: TurnBranchType; /** @public */ context: TurnContextMode; /** @internal */ startFrom?: ProcessTurnStartSelection; /** @internal */ restorePrimaryLeafAfterTurn?: boolean; /** @public */ prompt(ctx: ProcessRuntimeTurnContext): string | Promise; /** @public */ outcomes?: Partial>>; /** @public */ turnEnd?: ProcessTurnEndSpec; /** @public */ turnResultMarkdown?: TurnResultMarkdownBehavior; /** @internal */ reviewSemanticRef?: ProcessSemanticEntryRefKey; /** @internal */ resultSemanticRef?: ProcessSemanticEntryRefKey; /** @internal */ publishedProduct?: string; /** @internal */ consumedProducts?: readonly string[]; /** @internal */ optionalConsumedProducts?: readonly string[]; /** @internal */ requiredSemanticMarkdownRefs?: readonly ProcessSemanticEntryRefKey[]; /** @internal */ optionalSemanticMarkdownRefs?: readonly ProcessSemanticEntryRefKey[]; /** Runs this turn once per frozen item, then collects and routes once. @public */ forEach?: MappedLlmTurnSpec; } /** @public */ interface AutomaticTurnDefinition { /** @public */ kind: "automatic"; /** @public */ description: string; /** Server-side entry condition, evaluated before worker allocation. @public */ waitFor?: TurnWaitPredicate; /** Server-owned integration tools callable by this deterministic worker turn. @internal */ integrationTools?: readonly string[]; /** External events armed while this automatic turn is selected and waiting. @public */ externalActions?: Record>; /** @internal */ outcomes?: Partial>>; /** @internal */ turnEnd?: ProcessTurnEndSpec; /** @internal */ reviewSemanticRef?: ProcessSemanticEntryRefKey; /** @public */ run(ctx: ProcessRuntimeTurnContext): Promise> | WorkerCompleteInput; } /** @internal */ interface ExternalSourceTransition = Record> extends StaticRouteTarget { /** @internal */ source: ExternalActionSource; /** @internal */ effect?: ExternalSourceEffect; } /** @public */ interface ExternalTurnDefinition { /** @public */ kind: "external"; /** @public */ description: string; /** @internal */ transitions: readonly ExternalSourceTransition[]; /** @internal */ reviewSemanticRef?: ProcessSemanticEntryRefKey; } /** @public */ type TurnDefinition = LlmTurnDefinition | AutomaticTurnDefinition | HumanTurnDefinition | ExternalTurnDefinition; /** @public */ type TurnDefinitionRecord = Record>; /** @public */ interface DefinedProcessInput extends Omit, "entryTurnId" | "alternateEntryTurnIds" | "turns"> { /** Primary entry used when a launch does not select a start turn explicitly. @public */ entry: TurnId; /** Additional entry turns that launchers may select explicitly. @public */ alternateEntries?: readonly TurnId[]; /** @public */ turns: TurnDefinitionRecord; } /** @internal */ declare function getExternalSourceTransitionId(input: { /** @internal */ turnId: TurnId; /** @internal */ source: ExternalActionSource; /** @internal */ index: number; }): string; /** @internal */ declare function getExternalActionArmingId(input: { /** @internal */ turnId: TurnId; /** @internal */ externalActionId: string; }): string; /** @internal */ declare function getExternalActionTransitionTrigger(input: { /** @internal */ externalActionId: string; }): string; /** @internal */ declare function resolveHumanTurnView(input: { /** @internal */ turnId: TurnId; /** @internal */ turn: HumanTurnDefinition; }): { /** @internal */ actions: readonly HumanTurnActionView[]; /** @internal */ externalTriggers: readonly HumanTurnExternalTrigger[]; }; /** Recheck declaration metadata and retained graph facts without executing author callbacks. @internal */ declare function validateProcessDefinition(process: ExtensionProcessDefinition): readonly string[]; /** @public */ declare function defineProcess(input: DefinedProcessInput): ExtensionProcessDefinition; /** @internal */ type RoutableTurnDefinition = LlmTurnDefinition | AutomaticTurnDefinition; /** @internal */ type RoutableOutcome = TTurn extends RoutableTurnDefinition ? TOutcome : never; /** @internal */ type RoutableParams = TTurn extends RoutableTurnDefinition ? TParams : never; /** @internal */ type RoutableState = TTurn extends RoutableTurnDefinition ? TState : never; /** @internal */ declare function routeTurnOutcomes>(baseTurn: TTurn, routes: Partial, OutcomeRouteSpec, RoutableState>>>, options?: OutcomeRouteOptions): TTurn; /** @public */ declare function llmTurn(input: Omit, "kind">): LlmTurnDefinition; /** @internal */ declare function automaticTurn(input: Omit, "kind">): AutomaticTurnDefinition; /** @public */ declare function humanTurn(input: Omit, "kind">): HumanTurnDefinition; /** JSON values that may cross the server/worker bootstrap boundary. @public */ type ProviderJsonPrimitive = string | number | boolean | null; /** @public */ type ProviderJsonValue = ProviderJsonPrimitive | ProviderJsonValue[] | { /** @internal */ [key: string]: ProviderJsonValue; }; /** @public */ type ProviderJsonObject = { /** @internal */ [key: string]: ProviderJsonValue; }; /** @public */ interface ConfiguredProviderModel { /** @public */ readonly profileId: string; /** @public */ readonly modelId: string; } /** @public */ type ProviderAvailability = "available" | "unavailable" | "stale"; /** @public */ interface ProviderModelStatus { /** @public */ readonly modelId: string; /** @public */ readonly availability: ProviderAvailability; /** Safe operator-facing reason. It must not contain credential material. @internal */ readonly safeReason?: string; } /** @public */ interface ProviderCredentialStatus { /** @public */ readonly available: boolean; /** @public */ readonly revision: number | null; } /** @public */ interface ModelProviderModelsContext { /** @internal */ readonly config: TConfig; /** @public */ readonly configuredModels: readonly ConfiguredProviderModel[]; /** @public */ readonly credentialStatus: ProviderCredentialStatus; } /** @public */ interface ProviderOptionChoice { /** @internal */ readonly value: string; /** @internal */ readonly label: string; } /** @public */ interface ProviderOptionChoicesContext { /** @internal */ readonly config: TConfig; /** @internal */ readonly credentialStatus: ProviderCredentialStatus; } /** @internal */ interface ProviderOptionDefaultContext { /** @internal */ readonly config: TConfig; } /** @public */ interface ProviderOptionField { /** @public */ readonly label: string; /** @public */ readonly required?: boolean; /** @internal */ readonly minLength?: number; /** @public */ readonly maxLength?: number; /** * Explicit provider default. Dynamic choices are advisory and are never used * as an implicit default. */ /** @internal */ readonly defaultValue?: string | null | ((ctx: ProviderOptionDefaultContext) => string | null | undefined); } /** @public */ interface ProviderOptionsDefinition { /** @public */ readonly fields: Readonly>>; /** @public */ choices?(ctx: ProviderOptionChoicesContext): Readonly> | Promise>>; } /** @public */ declare function defineProviderOptions(definition: ProviderOptionsDefinition): ProviderOptionsDefinition; /** @internal */ interface ProviderOptionsResolutionInput { /** @internal */ readonly definition: ProviderOptionsDefinition | null | undefined; /** @internal */ readonly config: TConfig; /** @internal */ readonly explicit?: Readonly> | null; /** @internal */ readonly profileDefaults?: Readonly> | null; } /** @internal */ interface ProviderOptionValidationIssue { /** @internal */ readonly fieldId: string; /** @internal */ readonly code: "unknown" | "not_string" | "too_short" | "too_long" | "required"; /** @internal */ readonly message: string; } /** @internal */ type ProviderOptionsResolution = { /** @internal */ readonly ok: true; /** @internal */ readonly value: Readonly>; } | { /** @internal */ readonly ok: false; /** @internal */ readonly issues: readonly ProviderOptionValidationIssue[]; }; /** * Resolve explicit values, profile defaults, then declared provider defaults. * Dynamic choices deliberately do not participate in validation or fallback. */ /** @internal */ declare function resolveProviderOptions(input: ProviderOptionsResolutionInput): ProviderOptionsResolution; /** Keep only fields declared by a newly selected provider. @internal */ declare function filterProviderOptionsForDefinition(definition: ProviderOptionsDefinition | null | undefined, values: Readonly>): Readonly>; /** * Runtime-independent schema boundary for non-secret provider worker config. * Adapters may wrap Valibot, TypeBox, Zod, or another validator behind parse. */ /** @public */ interface ProviderWorkerConfigSchema { /** @public */ parse(value: unknown): TValue; } /** @public */ interface ProviderWorkerConfigContext { /** @public */ readonly config: TConfig; /** @internal */ readonly options: Readonly>; } /** @public */ interface ProviderWorkerConfigDefinition { /** @public */ readonly version: number; /** @public */ readonly schema: ProviderWorkerConfigSchema; /** @public */ resolve(ctx: ProviderWorkerConfigContext): TValue; } /** @public */ declare function defineWorkerConfig(definition: ProviderWorkerConfigDefinition): ProviderWorkerConfigDefinition; /** @public */ interface PiWorkerReference { /** @public */ readonly kind: "extension_pi_worker"; /** @internal */ readonly config?: ProviderWorkerConfigDefinition; /** Mutable, flat JSON credential files required by this provider's Pi extension. @internal */ readonly credentialFiles?: readonly string[]; } /** @public */ interface PiServerReference { /** @internal */ readonly kind: "extension_pi_server"; } /** @public */ interface PiServerGenerateTextInput { /** @public */ readonly providerId: string; /** @public */ readonly modelId: string; /** @public */ readonly thinkingLevel: string; /** @public */ readonly prompt: string; /** @public */ readonly systemPrompt: string; /** @public */ readonly maxTokens: number; /** @public */ readonly config: TConfig; /** @public */ readonly options: Readonly>; /** @public */ readonly secrets: Readonly>; /** @public */ readonly request: { /** @public */ readonly timeoutMs?: number; /** @internal */ readonly maxRetries?: number; /** @public */ readonly maxRetryDelayMs: number; }; } /** Server-only provider boundary for title generation and future cheap LLM consumers. @public */ interface PiServerAdapter { /** @public */ generateText(input: PiServerGenerateTextInput): Promise; } /** @public */ declare function definePiServerAdapter(adapter: PiServerAdapter): PiServerAdapter; /** @public */ interface BuiltinPiProviderReference { /** @public */ readonly kind: "builtin_pi_provider"; /** @internal */ readonly providerId: string; } /** @public */ interface ConfiguredPiProviderReference { /** @public */ readonly kind: "configured_pi_provider"; /** @internal */ readonly providerId: string; /** Resolve the credential-blind models.json document pinned into each worker snapshot. @internal */ resolveModels(ctx: { /** @internal */ readonly config: TConfig; }): ProviderJsonObject; } /** @public */ declare function piWorker(input?: { /** @public */ config?: ProviderWorkerConfigDefinition; /** @public */ credentialFiles?: readonly string[]; }): PiWorkerReference; /** @public */ declare function piServer(): PiServerReference; /** @public */ declare function builtinPiProvider(providerId: string): BuiltinPiProviderReference; /** @internal */ declare function configuredPiProvider(providerId: string, resolveModels: ConfiguredPiProviderReference["resolveModels"]): ConfiguredPiProviderReference; /** @public */ type ModelProviderWorker = PiWorkerReference | BuiltinPiProviderReference | ConfiguredPiProviderReference; /** @public */ type ModelProviderServer = PiServerReference | BuiltinPiProviderReference; /** @public */ interface ModelProviderSecretsContext { /** @internal */ readonly config: TConfig; /** @public */ readonly credential: TCredential | null; /** @internal */ readonly options: Readonly>; } /** @public */ interface ParsedModelProviderConfig { /** Restart-scoped, non-secret provider configuration. @public */ readonly config: TConfig; /** Optional credential used only to initialize an empty durable credential store. @internal */ readonly credential?: TCredential; } /** @public */ interface ModelProviderCredentialDefinition { /** Validates configured, durable, and worker-refreshed credential data. @public */ parse?(value: unknown): TCredential; } /** @public */ interface ModelProviderDefinition { /** @public */ readonly id: string; /** @public */ parseConfig(raw: unknown): ParsedModelProviderConfig; /** @public */ readonly worker: ModelProviderWorker; /** @public */ readonly server?: ModelProviderServer; /** @public */ models(ctx: ModelProviderModelsContext): readonly ProviderModelStatus[] | Promise; /** @public */ readonly options?: ProviderOptionsDefinition; /** @public */ secrets(ctx: ModelProviderSecretsContext): Readonly>; /** @public */ readonly credential?: ModelProviderCredentialDefinition; } /** @public */ declare function defineModelProvider(definition: ModelProviderDefinition): ModelProviderDefinition; /** Type-erased provider definition used after its typed boundary has been established. @public */ type ErasedModelProviderDefinition = ModelProviderDefinition; /** @public */ interface ModelProviderSetEntry { /** @public */ readonly definition: ErasedModelProviderDefinition; /** Owner-scoped fragment passed to this provider's parseConfig(). @public */ readonly rawConfig: unknown; } /** Resolves every provider owned by one extension from its owner-scoped configuration. @public */ type ModelProviderSet = (ownerConfig: unknown) => readonly ModelProviderSetEntry[]; /** @public */ declare function defineModelProviders(resolve: ModelProviderSet): ModelProviderSet; /** @public */ interface PiWorkerSecretBag { /** @public */ get(key: string): string | undefined; /** @public */ require(key: string): string; /** @public */ keys(): readonly string[]; } /** @public */ interface PiWorkerContributionContext { /** @public */ readonly model: { /** @public */ readonly providerId: string; /** @public */ readonly modelId: string; }; /** @public */ readonly options: Readonly>; /** @public */ readonly workerConfig: ProviderJsonObject | null; /** @public */ readonly secrets: PiWorkerSecretBag; /** @public */ report(event: Readonly>): void; } /** @public */ type PiWorkerContribution = (pi: { /** @public */ registerProvider(name: string, config: object): void; }, ctx: PiWorkerContributionContext) => void | Promise; /** @public */ declare function definePiWorker(contribution: PiWorkerContribution): PiWorkerContribution; /** * Report each distinct configured model as available or unavailable based solely * on credential status. Providers that do not perform runtime model probing can * delegate their `models()` callback to this helper. */ /** @public */ declare function credentialBasedModelStatuses(configuredModels: readonly ConfiguredProviderModel[], credentialStatus: ProviderCredentialStatus, unavailableReason: string): readonly ProviderModelStatus[]; /** @public */ interface Codec { /** @public */ parse(value: unknown): T; /** @public */ serialize(value: T): unknown; } /** @internal */ interface LauncherModelProfileSummary { /** @internal */ readonly id: string; /** @internal */ readonly provider: string; /** @internal */ readonly modelId: string; /** @internal */ readonly thinkingLevel: string; } /** @public */ interface LauncherContext { /** @internal */ readonly process?: ProcessInstance; /** @internal */ readonly projects?: readonly ProcessProject[]; /** * Effective model profiles available to this launch path. * The server may filter this list per process (for example via process allowlists) * before invoking UI launcher or process watcher code. */ /** @internal */ readonly modelProfiles?: readonly LauncherModelProfileSummary[]; } /** @public */ type LauncherVisibility = "ui"; /** @public */ interface ProcessLaunchProjectConfig { /** Provider-verified identity and clone aliases from launcher discovery. @public */ settingsRepository?: { /** @public */ origin: string; /** @public */ repositoryId: string | number; /** @public */ aliases?: readonly string[]; }; /** @public */ key: string; /** @public */ repoLocator: string; /** @public */ baseBranch: string; /** @public */ workBranch?: string | null; /** @public */ externalId?: string | null; /** @public */ externalUrl?: string | null; /** @public */ metadata?: Record | null; } /** @public */ interface ProcessTitleSourceField { /** Short label shown to the title-generation model, e.g. "Prompt" or "Summary". @public */ label: string; /** Launcher-selected descriptive text to summarize into a short operator-facing title. @public */ value: string; } /** @public */ interface ProcessLaunchConfig { /** Repository key used for process-wide scoped model defaults. @public */ primaryRepositoryKey?: string; /** Trusted integration scope bindings, retained with the process. @public */ settingsContext?: _leitwerk_dev_domain.SettingsContext; /** @public */ processId: string; /** @public */ params: TParams; /** @public */ startTurnId?: TurnId | null; /** Explicit operator-facing title. UI launches may override this with the built-in title input before persistence. @public */ title?: string | null; /** Explicit launcher-selected fields for optional server-side title generation when title is blank. @public */ titleSourceFields?: readonly ProcessTitleSourceField[]; /** @public */ externalId?: string | null; /** @public */ externalUrl?: string | null; /** @public */ metadata?: Record | null; /** @internal */ defaultModelProfileId?: string | null; /** @internal */ turnConfigs?: Record; /** Skill ids resolved to active immutable revisions before process creation. @internal */ skillIds?: readonly string[]; /** @public */ projects?: readonly ProcessLaunchProjectConfig[]; } /** @public */ type UiLauncherConfigResolution = { /** @public */ ok: true; /** @public */ launchConfig: ProcessLaunchConfig; } | { /** @public */ ok: false; /** @public */ errors: readonly LauncherValidationError[]; }; /** @public */ interface LaunchPreparationContext { /** @public */ readonly signal: AbortSignal; /** @public */ readonly launchConfig: ProcessLaunchConfig; /** @public */ readonly logger: { /** @internal */ info(message: string): void; /** @public */ warn(message: string): void; }; } /** @public */ interface LaunchPreparationCheck { /** @public */ readonly id: string; /** @public */ readonly label: string; /** @public */ run(ctx: LaunchPreparationContext): Promise; } /** A launcher check may throw this error to expose bounded operator-safe remediation. @public */ declare class SafeLaunchPreparationError extends Error { /** @internal */ readonly safeSummary: string; /** @public */ constructor(message: string, /** @internal */ safeSummary: string); } /** @public */ interface UiLauncherDefinition { /** @public */ card: LauncherCardMetadata; /** @public */ launchConfigSchema: LauncherSchemaDefinition; /** @public */ resolveDefaults?(ctx: LauncherContext): Record | Promise>; /** @public */ resolveOptions?(input: Record, ctx: LauncherContext): Record | Promise>; /** * Convert persisted operator input into a new-launch draft. The default preserves * the complete input. Launchers override this only for values that must be rebuilt. */ /** @public */ resolveRelaunchInput?(previousInput: Record, ctx: LauncherContext): Record | Promise>; /** @public */ preparationChecks?(input: Record, launchConfig: ProcessLaunchConfig): readonly LaunchPreparationCheck[]; /** * Resolve form validation and model settings without preparing execution resources. * May omit projects that do not affect model/settings resolution. Params must pass * the process codec. Never used for submission; falls back to resolveLaunchConfig. * @public */ resolvePreviewConfig?(input: Record, ctx: LauncherContext): UiLauncherConfigResolution | Promise>; /** @public */ resolveLaunchConfig(input: Record, ctx: LauncherContext): UiLauncherConfigResolution | Promise>; } /** @public */ interface ProcessWatcherPresentation { /** @public */ readonly targetSummary: string; /** @public */ readonly details?: readonly WatcherPresentationField[]; } /** @public */ interface ParsedProcessWatcherConfig { /** @public */ readonly config: TConfig; /** @public */ readonly enabled: boolean; /** @public */ readonly launchModelConfig?: LaunchModelConfigInput; } /** A watcher source is defined and owned by the extension that implements it. @public */ interface ProcessWatcherSource { /** @public */ readonly id: string; /** @public */ readonly label: string; /** Type-only marker used to carry the provider event type across the source seam. @internal */ readonly eventType?: TEvent; /** @public */ parseConfig(raw: unknown): ParsedProcessWatcherConfig; /** @public */ presentConfig(config: TConfig): ProcessWatcherPresentation; } /** @public */ interface ProcessWatcherDefinition { /** @public */ id: string; /** @public */ label: string; /** @public */ description: string; /** @public */ source: ProcessWatcherSource; /** @internal */ matches?(event: TEvent, ctx: LauncherContext): boolean | Promise; /** @public */ preparationChecks?(event: TEvent, launchConfig: ProcessLaunchConfig): readonly LaunchPreparationCheck[]; /** @public */ resolveLaunchConfig(event: TEvent, ctx: LauncherContext): ProcessLaunchConfig | Promise>; } /** @public */ interface ProcessLauncherDefinition { /** @public */ id: string; /** @public */ label: string; /** @public */ description: string; /** @public */ visibility: LauncherVisibility; /** @public */ ui: UiLauncherDefinition; } /** @internal */ interface ProcessLaunchPlanProcessInput extends ProcessCustomizableFields { /** @internal */ processId: string; /** @internal */ selectedTurnId: string | null; /** @internal */ lifecycleStatus: ProcessLifecycleStatus; /** @internal */ paramsJson: string | null; /** @internal */ stateJson: string | null; } /** @internal */ interface ProcessLaunchPlan { /** A form/model preview; execution resources may be omitted and this plan must not be committed. @internal */ preview?: true; /** @internal */ launcherId: string; /** @internal */ processId: string; /** @internal */ processInput: ProcessLaunchPlanProcessInput; /** Optional server-owned idempotency key for cross-process handoffs. @internal */ handoffDedupKey?: string | null; /** Carry-forward launcher-selected fields for optional server-side title generation. @internal */ titleSourceFields?: readonly ProcessTitleSourceField[]; /** @internal */ projectInputs: readonly ProcessLaunchProjectConfig[]; /** @internal */ startTurnId: TurnId | null; /** @internal */ skillIds?: readonly string[]; } /** @internal */ interface ResolvedProcessLauncher { /** @internal */ launcherId: string; /** @internal */ processId: string; /** @internal */ displayName: string; /** @internal */ launchConfig: ProcessLaunchConfig; /** @internal */ launchPlan: ProcessLaunchPlan; } /** @internal */ type UiLauncherResolutionResult = { /** @internal */ ok: true; /** @internal */ launcher: ResolvedProcessLauncher; } | { /** @internal */ ok: false; /** @internal */ errors: readonly LauncherValidationError[]; }; /** @internal */ interface UiLauncherSummary extends UiLauncherSummaryBase { } /** @internal */ interface ProcessLauncherService { /** @internal */ listUiLaunchers(): readonly UiLauncherSummary[]; /** @internal */ resolveUiDefaults(launcherId: string, ctx?: LauncherContext): Promise>; /** @internal */ resolveUiOptions(launcherId: string, input: Record, ctx?: LauncherContext): Promise>; /** @internal */ resolveUiRelaunchInput(launcherId: string, previousInput: Record, ctx?: LauncherContext): Promise>; /** @internal */ resolvePreparationChecks?(launcherId: string, input: Record, launchConfig: ProcessLaunchConfig): readonly LaunchPreparationCheck[]; /** @internal */ resolveUiLauncher(launcherId: string, input: Record, ctx?: LauncherContext): Promise; /** Resolve only for form validation/defaults/model preview; never commit this result. @internal */ resolveUiLauncherPreview(launcherId: string, input: Record, ctx?: LauncherContext): Promise; } /** Resolve a UI launcher summary by id, returning `null` when it is unknown. @internal */ declare function findUiLauncherById(launcherService: Pick, launcherId: string): UiLauncherSummary | null; /** @public */ interface ProcessTurnOutcomeEvent { /** @internal */ turnRecordId: string; /** @internal */ turnId: string; /** @internal */ outcome: string; /** @public */ params: Record; /** @internal */ turnResultMarkdown?: string | null; /** Durable output produced by this turn's preparation phase. @public */ prepared?: unknown; } /** Expected outcome-planning rejection safe to persist and show to operators. @public */ declare class SafeOutcomePlanningError extends Error { /** Stable machine-readable failure code. @public */ readonly code: string; /** @public */ constructor( /** Stable machine-readable failure code. @public */ code: string, message: string); } /** @internal */ type ProcessCleanupReason = "abort"; /** @internal */ interface ProcessCleanupResult extends ProcessLifecycleEffects { /** @internal */ state?: TState; } /** @internal */ interface ProcessCleanupContext extends ProcessSnapshotContext { /** @internal */ readonly reason: ProcessCleanupReason; } /** @internal */ type ProcessCleanupHandler = (ctx: ProcessCleanupContext) => undefined | ProcessCleanupResult | Promise | undefined>; /** @internal */ interface LeafOutcomeCaptureContext extends ProcessSnapshotContext { /** @internal */ readonly leaf: { /** @internal */ entryId: string; /** @internal */ turnRecordId: string | null; }; /** @internal */ readonly turnRecord: ProcessTurnRecord | null; /** Accepted result of this mapped item, when available. @internal */ readonly mappedResult?: unknown; /** @internal */ readTreeEntry(entryId: string): PiTreeEntry | null; /** @internal */ readLeafEntry(): PiTreeEntry | null; /** @internal */ readTurnRecord(turnRecordId: string): ProcessTurnRecord | null; } /** @internal */ interface LeafOutcomeCaptureResult { /** @internal */ rendererId: string; /** @internal */ schemaVersion?: number; /** @internal */ props: Record; /** @internal */ fallbackMarkdown?: string | null; } /** @internal */ interface ProcessLeafOutcomeDefinition { /** @internal */ rendererId: string; /** @internal */ capture(ctx: LeafOutcomeCaptureContext): Promise | LeafOutcomeCaptureResult | null; } /** @internal */ interface ProcessActionDefinition { /** @internal */ id: string; /** @internal */ label: string; /** @internal */ form?: ActionFormDefinition; /** @internal */ preview?: ProcessActionPreviewDefinition; /** @internal */ scheduling?: ProcessActionSchedulingDefinition; /** * Explicitly marks an action as an immediate-only side-effect command. Such * actions must declare execute(...), cannot participate in pure preview or * scheduling flows, and are run only by immediate action execution. */ /** @internal */ executionMode?: "side_effect"; /** * Optional pure planner used for side-effect-free previews, scheduling validation, * and immediate execution. The shared server runtime collects the declared * transition/input/event plan from this hook without committing side effects * while the hook runs. */ /** @internal */ plan?(input: Record, ctx: ServerProcessContext): Promise; /** * Imperative hook for actions with executionMode: "side_effect". Use only for * immediate side effects that cannot be represented as a pure plan(...). */ /** @internal */ execute?(input: Record, ctx: ServerProcessContext): Promise; } /** @internal */ type ServerTransitionRuntime = "reconcile" | "restart_worker"; /** @internal */ interface ServerTransitionEffect { /** * Declares how the server runtime should handle the worker context after the * durable transition is committed. */ /** @internal */ runtime?: ServerTransitionRuntime; } /** @internal */ interface ServerTransitionRequest { /** @internal */ lifecycleStatus?: ProcessLifecycleStatus; /** @internal */ turnId?: TurnId | null; /** @internal */ state?: TState; /** State machine trigger for the selected-turn graph. @internal */ trigger?: string; /** @internal */ effect?: ServerTransitionEffect; } /** @public */ interface ProcessSnapshotContext { /** @public */ readonly process: ProcessInstance; /** @public */ readonly projects: readonly ProcessProject[]; /** @public */ readonly params: TParams; /** @public */ readonly state: TState; } /** @public */ type ExternalSourceInputMode = "none" | "input" | "instruction"; /** @public */ interface ExternalSourceResolveContext extends ProcessSnapshotContext { } /** @public */ interface ExternalSourceEffectContext = Record> extends ProcessSnapshotContext { /** @public */ readonly event: TEvent; /** @internal */ readonly input: TInput; } /** @public */ type ExternalSourceEffect = Record> = (ctx: ExternalSourceEffectContext) => ProcessEffectPlan | Promise