@kitman-sh/sdk 0.9.0 → 0.10.53

package/types/packages/sdk/src/loop/steps.d.ts

@@ -3,7 +3,9 @@ import * as Context from 'effect/Context';
 import * as Duration from 'effect/Duration';
 import * as Effect from 'effect/Effect';
 import * as Schema from 'effect/Schema';
-import { DurableDeferred } from 'effect/workflow';
+import { Activity, DurableDeferred } from 'effect/workflow';
+import { type QuestionAdvice, type QuestionOption } from '../../../core/src/question-recommendation';
+import type { MeasurePlan } from '../../../core/src/work-unit';
 import { type EventFilter, type LoopCapability, type LoopDefinition, type LoopSchema } from './define';
 declare const StepFailed_base: Schema.Class<StepFailed, Schema.TaggedStruct<"StepFailed", {
     readonly step: Schema.String;
@@ -31,6 +33,13 @@ declare const WaitTimedOut_base: Schema.Class<WaitTimedOut, Schema.TaggedStruct<
 }>, Cause.YieldableError>;
 export declare class WaitTimedOut extends WaitTimedOut_base {
 }
+declare const ChangeRequestClosed_base: Schema.Class<ChangeRequestClosed, Schema.TaggedStruct<"ChangeRequestClosed", {
+    readonly step: Schema.String;
+    readonly merged: Schema.Boolean;
+}>, Cause.YieldableError>;
+/** The ChangeRequest a wait was on was closed or merged before the Event it waited for came. */
+export declare class ChangeRequestClosed extends ChangeRequestClosed_base {
+}
 declare const ChildFailed_base: Schema.Class<ChildFailed, Schema.TaggedStruct<"ChildFailed", {
     readonly step: Schema.String;
     readonly loop: Schema.String;
@@ -41,7 +50,7 @@ export declare class ChildFailed extends ChildFailed_base {
 }
 declare const CapabilityDenied_base: Schema.Class<CapabilityDenied, Schema.TaggedStruct<"CapabilityDenied", {
     readonly step: Schema.String;
-    readonly capability: Schema.Literals<readonly ["agent_work", "ask", "call", "verify", "change_request", "write_back", "post_comment", "create_tasks", "merge_change_request", "publish_release", "read_transcripts", "propose", "read_project", "draft_update"]>;
+    readonly capability: Schema.Literals<readonly ["agent_work", "ask", "call", "verify", "change_request", "write_back", "post_comment", "create_tasks", "merge_change_request", "approve_change_request", "publish_release", "read_transcripts", "read_change_request", "measure", "claim", "propose", "read_project", "draft_update"]>;
     /** A Secret the Step names that its Loop does not declare. */
     readonly secret: Schema.optionalKey<Schema.String>;
 }>, Cause.YieldableError>;
@@ -64,7 +73,7 @@ export declare const LoopEvent: Schema.Struct<{
     readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
 }>;
 export type LoopEvent = typeof LoopEvent.Type;
-export type StepKind = 'agent_work' | 'ask' | 'call' | 'wait_for' | 'verify' | 'change_request' | 'write_back' | 'artifact' | 'file' | 'note' | 'comment' | 'create_tasks' | 'integration_branch' | 'merge_change_request' | 'release' | 'transcripts' | 'propose' | 'project_activity' | 'draft_update';
+export type StepKind = 'agent_work' | 'ask' | 'call' | 'wait_for' | 'verify' | 'change_request' | 'write_back' | 'artifact' | 'file' | 'note' | 'comment' | 'create_tasks' | 'integration_branch' | 'merge_change_request' | 'approve_change_request' | 'close_change_request' | 'rerun_pipeline' | 'report_pipeline' | 'release' | 'transcripts' | 'propose' | 'project_activity' | 'draft_update' | 'pipeline_status' | 'review_threads' | 'open_change_requests' | 'own_change_requests' | 'measure' | 'claim' | 'let_go';
 /** A Step a Run took, as its program saw it. */
 export type StepRecord = {
     readonly name: string;
@@ -96,23 +105,34 @@ type Launch = {
     readonly token: DurableDeferred.Token;
 };
 export type AgentWorkLaunch = Launch & {
+    /** The journal name its Output resolves; a base sync's starts with `sync/`. */
+    readonly deferredName: string;
     readonly role: string;
     readonly agent: string;
     readonly prompt: string;
+    /** The skill the Step runs, whose body Kitman puts ahead of the prompt. */
+    readonly skill?: string;
     /** JSON Schema the Output must match. */
     readonly output: Schema.Json;
     /** Secrets for the agent's sandbox environment. */
     readonly secrets?: readonly string[];
+    /** The Step's time budget across its attempts. */
+    readonly timeoutMillis?: number;
+    /** The branch whose head the Runner merges into the checkout before the agent starts. */
+    readonly mergeTarget?: string;
 };
-/** A verification a human may approve for the repository; nothing runs it until they do. */
+/** A verification a human may approve for the repository; only `verify`'s `suggested` runs it before they do. */
 export type SuggestedVerification = {
     readonly name: string;
     readonly command: string;
     readonly workingDirectory?: string;
 };
-export type QuestionLaunch = Launch & {
+export type QuestionLaunch = Launch & QuestionAdvice & {
     readonly prompt: string;
     readonly options?: readonly string[];
+    /** Taken when the Run is unattended, or when nobody answers within `timeoutMillis`. */
+    readonly default?: string;
+    readonly timeoutMillis?: number;
     /** Approving the Question approves this verification. */
     readonly verification?: SuggestedVerification;
 };
@@ -121,15 +141,37 @@ export type VerificationLaunch = Launch & {
     readonly revision?: string;
     /** Approved verifications by name; all of them when left out. */
     readonly checks?: readonly string[];
+    /** Run in place of approved checks when the repository has none approved, labelled as suggested. */
+    readonly suggested?: readonly SuggestedVerification[];
+    /** Benchmarks the revision against `base` (the Run's base branch head when left out) in place of checks. */
+    readonly measure?: MeasureLaunch;
+};
+export type MeasureLaunch = {
+    readonly base?: string;
+    readonly plan: MeasurePlan;
+    readonly samples: number;
+    readonly calibrate: boolean;
+};
+export type ClaimLaunch = Launch & {
+    readonly resource: string;
+    readonly action: 'claim' | 'take_over' | 'let_go';
 };
 export type ChildLaunch = Launch & {
     readonly loop: string;
     readonly input: Schema.Json;
 };
+/** An Event that settles a wait besides its own, with its own filter and `since`. */
+export type OtherEvent = {
+    readonly event: string;
+    readonly filter?: EventFilter;
+    readonly since?: string;
+};
 export type EventWaitLaunch = Launch & {
     readonly event: string;
     readonly filter?: EventFilter;
     readonly timeoutMillis: number;
+    readonly since?: string;
+    readonly or?: readonly OtherEvent[];
 };
 declare const LoopHost_base: Context.ServiceClass<LoopHost, "@kitman-sh/sdk/loop/LoopHost", {
     readonly startAgentWork: (launch: AgentWorkLaunch) => Effect.Effect<void, StepFailed>;
@@ -137,6 +179,7 @@ declare const LoopHost_base: Context.ServiceClass<LoopHost, "@kitman-sh/sdk/loop
     readonly admitChild: (launch: ChildLaunch) => Effect.Effect<void, StepFailed>;
     readonly awaitEvent: (launch: EventWaitLaunch) => Effect.Effect<void, StepFailed>;
     readonly startVerification: (launch: VerificationLaunch) => Effect.Effect<void, StepFailed>;
+    readonly claimResource: (launch: ClaimLaunch) => Effect.Effect<void, StepFailed>;
 }>;
 /**
  * What Kitman lends a program: each launch hands Kitman a deferred token, and Kitman resolves it with the
@@ -144,7 +187,11 @@ declare const LoopHost_base: Context.ServiceClass<LoopHost, "@kitman-sh/sdk/loop
  */
 export declare class LoopHost extends LoopHost_base {
 }
+/** The journal entry an agent Step's Output resolves, by its full name. */
+export declare const agentDeferredNamed: (deferredName: string) => DurableDeferred.DurableDeferred<Schema.Codec<Schema.Json, Schema.Json, never, never>, typeof StepFailed>;
 export declare const agentWorkDeferred: (step: string) => DurableDeferred.DurableDeferred<Schema.Codec<Schema.Json, Schema.Json, never, never>, typeof StepFailed>;
+/** A base sync's agent Step, named apart so the host hands it no steers or Corrections meant for the work. */
+export declare const syncDeferred: (step: string) => DurableDeferred.DurableDeferred<Schema.Codec<Schema.Json, Schema.Json, never, never>, typeof StepFailed>;
 export declare const answerDeferred: (step: string) => DurableDeferred.DurableDeferred<Schema.String, typeof StepFailed>;
 export declare const childDeferred: (step: string) => DurableDeferred.DurableDeferred<Schema.Codec<Schema.Json, Schema.Json, never, never>, typeof ChildFailed>;
 export declare const eventDeferred: (step: string) => DurableDeferred.DurableDeferred<Schema.Struct<{
@@ -155,6 +202,7 @@ export declare const verifyDeferred: (step: string) => DurableDeferred.DurableDe
     readonly revision: Schema.String;
     readonly tree: Schema.String;
     readonly passed: Schema.Boolean;
+    readonly unchanged: Schema.optionalKey<Schema.Boolean>;
     readonly checks: Schema.$Array<Schema.Struct<{
         readonly name: Schema.String;
         readonly command: Schema.String;
@@ -162,54 +210,114 @@ export declare const verifyDeferred: (step: string) => DurableDeferred.DurableDe
         readonly preExisting: Schema.Boolean;
         readonly durationMs: Schema.Finite;
         readonly evidenceId: Schema.String;
+        readonly outputTail: Schema.optionalKey<Schema.String>;
+        readonly suggested: Schema.optionalKey<Schema.Boolean>;
     }>>;
 }>, typeof StepFailed>;
 /** Claims the Step name for this Run and checks its capability before running it. */
 export declare const takeStep: <A, E, R>(name: string, kind: StepKind, capability: LoopCapability | undefined, body: Effect.Effect<A, E, R>) => Effect.Effect<A, E | DuplicateStep | CapabilityDenied, R | LoopRun>;
+/** An Activity that only launches; its result arrives through the Step's deferred. */
+export declare const launch: <Success extends Schema.Constraint, Error extends Schema.Constraint>(deferred: DurableDeferred.DurableDeferred<Success, Error>, start: (host: LoopHost['Service'], token: DurableDeferred.Token) => Effect.Effect<void, StepFailed>) => Activity.Activity<Schema.Void, typeof StepFailed, LoopHost>;
 /**
  * An agent does one named Step and submits an Output that decodes against `output`. The named `secrets`, which the
- * Loop must declare, are in its sandbox's environment.
+ * Loop must declare, are in its sandbox's environment. With `timeout`, the Step fails once it has run that long, across
+ * its attempts, and its agent is stopped. Without one, the Runner stops its agent after 30 minutes. With `skill`, the
+ * Step runs that skill of the Run's Kits as a person runs a slash command: its body comes ahead of the prompt.
  */
-export declare const agentWork: <Out>(name: string, options: {
+export declare const agentWork: <Out>(name: string, options: AgentWorkOptions<Out>) => Effect.Effect<Out, CapabilityDenied | DuplicateStep | OutputInvalid | StepFailed, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+type AgentWorkOptions<Out> = {
     readonly agent: string;
     readonly prompt: string;
+    readonly skill?: string;
     readonly output: LoopSchema<Out>;
     readonly secrets?: readonly string[];
+    readonly timeout?: Duration.Input;
+};
+/** `agentWork` journaled under `deferredOf(name)`, as a base sync is. */
+export declare const agentWorkAs: <Out>(deferredOf: (step: string) => ReturnType<typeof agentDeferredNamed>, name: string, options: AgentWorkOptions<Out> & {
+    readonly mergeTarget?: string;
+    /** What the agent is asked to submit, when Kitman adds to it before `output` decodes it. */
+    readonly answer?: LoopSchema<unknown>;
 }) => Effect.Effect<Out, CapabilityDenied | DuplicateStep | OutputInvalid | StepFailed, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
-type Question<Options extends readonly string[]> = {
+/**
+ * `agentWork` that, when the Output fails to decode, runs once more as `<name>:again` with why in its brief: a planner
+ * whose tickets block each other in a cycle is sent back once with the reason.
+ */
+export declare const agentWorkOnce: <Out>(name: string, options: Parameters<typeof agentWork<Out>>[1]) => Effect.Effect<Out, CapabilityDenied | DuplicateStep | OutputInvalid | StepFailed, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+/**
+ * What the Run takes when nobody answers: at once when nobody is attending (a Schedule or an Event started it), else
+ * once `timeout` passes, never sooner than a minute. With no `default`, that is the recommended answer when it is safe to
+ * store; `null` makes the Question wait for a person, as one that only a person may approve should.
+ */
+type Fallback<Value extends string> = {
+    readonly default?: Value | null;
+    readonly timeout?: Duration.Input;
+};
+/** The answer the Loop would pick and why, in one or two sentences. */
+type Recommended<Value extends string> = {
+    readonly recommended: Value;
+    readonly recommendationReason: string;
+};
+type InformationOnly = {
+    readonly informationOnly: true;
+    readonly recommendationReason: string;
+};
+type OptionValue<Option> = Option extends {
+    readonly value: infer Value extends string;
+} ? Value : Option;
+type Question<Options extends readonly QuestionOption[]> = ({
     readonly prompt: string;
     readonly options: Options;
-} | {
+} & Recommended<OptionValue<Options[number]>> & Fallback<OptionValue<Options[number]>>) | ({
     readonly prompt: string;
     readonly freeText: true;
-};
-/** Puts a Question to a human; an answer outside `options` is refused. */
-export declare const ask: <const Options extends readonly string[]>(name: string, question: Question<Options>) => Effect.Effect<string, CapabilityDenied | DuplicateStep | QuestionRefused | StepFailed, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
-/** Starts a Child Run of `loop` and awaits its output. */
-export declare const call: <In, Out, E>(name: string, loop: LoopDefinition<In, Out, E>, input: In) => Effect.Effect<Out, CapabilityDenied | ChildFailed | DuplicateStep | StepFailed, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
-/** Waits for an Event matching `filter`, which is data the control plane matches. */
+} & (Recommended<string> | InformationOnly) & Fallback<string>);
+/**
+ * Puts a Question to a human; an answer outside `options` is refused. Keep the prompt to the context and the decision:
+ * an option can carry a short `description` of its trade-off, and every Question recommends an answer and says why.
+ */
+export declare const ask: <const Options extends readonly QuestionOption[]>(name: string, question: Question<Options>) => Effect.Effect<OptionValue<Options[number]>, CapabilityDenied | DuplicateStep | QuestionRefused | StepFailed, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+/** Starts a Child Run of `loop`, a Loop or its id and schemas, and awaits its output. */
+export declare const call: <In, Out>(name: string, loop: Pick<LoopDefinition<In, Out, unknown>, 'id' | 'input' | 'output'>, input: In) => Effect.Effect<Out, CapabilityDenied | ChildFailed | DuplicateStep | StepFailed, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+/**
+ * Waits for an Event matching `filter`, which is data the control plane matches. A wait on a ChangeRequest's Event
+ * fails with ChangeRequestClosed once that ChangeRequest is closed or merged, rather than waiting out its timeout.
+ */
 export declare const waitFor: (name: string, wait: {
     readonly event: string;
     readonly filter?: EventFilter;
     readonly timeout: Duration.Input;
+    /**
+     * An ISO time, such as a `pipelineStatus` read's `readAt`: a ChangeRequest state Event received before it does not
+     * settle the wait, since the read already superseded it.
+     */
+    readonly since?: string;
+    /** Other Events that settle the wait too, as a review comment wakes a wait for approval; read the Event's `type`. */
+    readonly or?: readonly OtherEvent[];
 }) => Effect.Effect<{
     readonly type: string;
     readonly payload: {
         readonly [x: string]: Schema.Json;
     };
-}, CapabilityDenied | DuplicateStep | StepFailed | WaitTimedOut, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+}, CapabilityDenied | ChangeRequestClosed | DuplicateStep | StepFailed | WaitTimedOut, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
 /**
  * Runs the repository's approved verifications at `revision`, or by default at the Run's head (what its Steps last
  * pushed, else its base branch), on an eligible Runner, with no agent. The result is evidence bound to the
- * revision's tree; a failure that is also on the default branch is marked pre-existing.
+ * revision's tree; a failure that is also on the baseline is marked pre-existing.
  */
 export declare const verify: (name: string, request: {
     readonly revision?: string;
     readonly checks?: readonly string[];
+    /**
+     * Checks to run, labelled as suggested, when the repository has no approved ones, so a repository nobody has set
+     * up still gets evidence; ignored once any check is approved.
+     */
+    readonly suggested?: readonly SuggestedVerification[];
 }) => Effect.Effect<{
     readonly revision: string;
     readonly tree: string;
     readonly passed: boolean;
+    readonly unchanged?: boolean;
     readonly checks: readonly {
         readonly name: string;
         readonly command: string;
@@ -217,6 +325,8 @@ export declare const verify: (name: string, request: {
         readonly preExisting: boolean;
         readonly durationMs: number;
         readonly evidenceId: string;
+        readonly outputTail?: string;
+        readonly suggested?: boolean;
     }[];
 }, CapabilityDenied | DuplicateStep | StepFailed, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
 /** Asks a human to approve a verification, for example one an agent's Output suggested. */

package/types/packages/sdk/src/loop/sync.d.ts

@@ -0,0 +1,53 @@
+import * as Schema from 'effect/Schema';
+/**
+ * What a base sync did: nothing to take, a merge that went in, or the files it could not settle. A merge carries the
+ * Runner's `catchUp` report of what it did to the branch's own change, when the Runner made one.
+ */
+export declare const BaseSync: Schema.Union<readonly [Schema.Struct<{
+    readonly status: Schema.Literal<"up_to_date">;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"merged">;
+    readonly settled: Schema.$Array<Schema.String>;
+    readonly catchUp: Schema.optionalKey<Schema.Struct<{
+        readonly from: Schema.String;
+        readonly head: Schema.String;
+        readonly conflicted: Schema.$Array<Schema.String>;
+        readonly rewritten: Schema.$Array<Schema.String>;
+        readonly changed: Schema.$Array<Schema.String>;
+        readonly truncated: Schema.Boolean;
+    }>>;
+}>, Schema.Struct<{
+    readonly status: Schema.Literal<"conflict">;
+    /** The files it could not settle; the merge was aborted, so the branch is as it was. */
+    readonly files: Schema.NonEmptyArray<Schema.String>;
+    readonly reason: Schema.String;
+}>]>;
+export type BaseSync = typeof BaseSync.Type;
+/**
+ * Merges the target branch's head into the Run's branch, so a review sees what will merge and a conflict is met while
+ * it is small. The Runner merges outside the agent's sandbox, which cannot write the git directory, and `agent` settles
+ * conflicts in one short Step; it is handed no steers or Corrections, which wait for the next Step that works on the
+ * change. The Runner commits the merge only on `merged`, so `conflict` comes back with the branch unchanged. `target`
+ * is the branch to merge in; the default branch when left out.
+ */
+export declare const syncBase: (name: string, options: {
+    readonly agent: string;
+    readonly target?: string;
+}) => import("effect/Effect").Effect<{
+    readonly status: "up_to_date";
+} | {
+    readonly status: "merged";
+    readonly settled: readonly string[];
+    readonly catchUp?: {
+        readonly from: string;
+        readonly head: string;
+        readonly conflicted: readonly string[];
+        readonly rewritten: readonly string[];
+        readonly changed: readonly string[];
+        readonly truncated: boolean;
+    };
+} | {
+    readonly status: "conflict";
+    readonly files: readonly [string, ...string[]];
+    readonly reason: string;
+}, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | import("./steps").OutputInvalid | import("./steps").StepFailed, import("./steps").LoopHost | import("./steps").LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;

package/types/packages/sdk/src/loop/test-loop.d.ts

@@ -2,10 +2,12 @@ import * as Effect from 'effect/Effect';
 import * as Exit from 'effect/Exit';
 import * as Schema from 'effect/Schema';
 import { Workflow, WorkflowEngine } from 'effect/workflow';
-import { ArtifactActivity, ChangeRequestActivity, CommentActivity, CreateTasksActivity, FileActivity, IntegrationBranchActivity, MergeChangeRequestActivity, NoteActivity, ProjectActivityActivity, DraftUpdateActivity, ProposeActivity, ReleaseActivity, TranscriptsActivity, WriteBackActivity } from './activities';
-import type { LoopCapability, LoopDefinition } from './define';
+import { ArtifactActivity, ChangeRequestActivity, CommentActivity, AlertTaskActivity, CreateTasksActivity, FileActivity, IntegrationBranchActivity, MergeChangeRequestActivity, NoteActivity, ProjectActivityActivity, DraftUpdateActivity, ProposeActivity, ReleaseActivity, TranscriptsActivity, ChangeRequestReadActivity, WriteBackActivity } from './activities';
+import { type LoopCapability, type LoopDefinition } from './define';
+import type { MeasureEvidence } from '../../../core/src/work-unit';
 import type { VerifyResult } from './evidence';
-import { InputInvalid, LoopHost, LoopRun, type LoopEvent, type StepRecord } from './steps';
+import { type ClaimResult } from './claims';
+import { InputInvalid, LoopHost, LoopRun, type EventWaitLaunch, type LoopEvent, type StepRecord } from './steps';
 /** Activity and deferred results, encoded as JSON; replaying from it runs no Activity again. */
 export declare const LoopJournal: Schema.Struct<{
     readonly activities: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
@@ -30,10 +32,12 @@ export type HostActivities = {
     readonly note: NoteActivity['Service'];
     readonly comment: CommentActivity['Service'];
     readonly createTasks: CreateTasksActivity['Service'];
+    readonly alertTask: AlertTaskActivity['Service'];
     readonly integrationBranch: IntegrationBranchActivity['Service'];
     readonly mergeChangeRequest: MergeChangeRequestActivity['Service'];
     readonly release: ReleaseActivity['Service'];
     readonly transcripts: TranscriptsActivity['Service'];
+    readonly changeRequestRead: ChangeRequestReadActivity['Service'];
     readonly propose: ProposeActivity['Service'];
     readonly projectActivity: ProjectActivityActivity['Service'];
     readonly draftUpdate: DraftUpdateActivity['Service'];
@@ -55,13 +59,24 @@ export type TestLoopScript = {
     readonly events?: {
         readonly [step: string]: LoopEvent;
     };
-    /** Verification results by Step name; a verify left out passes with no checks. */
+    /** Verification results by Step name; a verify left out passes with the suggested checks it was given, if any. */
     readonly verifications?: {
         readonly [step: string]: VerifyResult | ScriptedFailure;
     };
+    /** Samples by `measure` Step name; a measure left out measures base and head the same. */
+    readonly measurements?: {
+        readonly [step: string]: MeasureEvidence | ScriptedFailure;
+    };
+    /** What each `claim` Step came to; a claim left out is granted. */
+    readonly claims?: {
+        readonly [step: string]: ClaimResult;
+    };
     /** What the control plane grants; the declared capabilities by default. */
     readonly grant?: readonly LoopCapability[];
-    readonly activities?: Partial<HostActivities>;
+    /** Replaces the default host Activities method by method; a method left out keeps its default. */
+    readonly activities?: {
+        readonly [K in keyof HostActivities]?: Partial<HostActivities[K]>;
+    };
     readonly journal?: LoopJournal;
     /** Secret values the program reads with `Config`; none by default. */
     readonly secrets?: {
@@ -82,12 +97,17 @@ export type TestLoopResult<Out, E> = {
     readonly agentLaunches: readonly AgentLaunchRecord[];
     /** Child Runs admitted, with their Input as JSON, in admission order. */
     readonly childLaunches: readonly ChildLaunchRecord[];
+    /** Every `waitFor` started, in order. */
+    readonly waits: readonly WaitRecord[];
 };
+type WaitRecord = Pick<EventWaitLaunch, 'step' | 'event' | 'filter' | 'since' | 'or'>;
 type AgentLaunchRecord = {
     readonly step: string;
     readonly agent: string;
     readonly prompt: string;
+    readonly skill?: string;
     readonly secrets?: readonly string[];
+    readonly mergeTarget?: string;
 };
 type ChildLaunchRecord = {
     readonly step: string;

package/types/packages/sdk/src/program/engine.d.ts

@@ -1,5 +1,6 @@
 import { type OrchestrationWorkUnit, type ProgramWorkUnit, type RunFilePartUrl, type RunFileRecord, type RunFileUpload } from '../../../core/src/index';
-import { type ChangeRequestResult, type EventFilter, type IntegrationBranch, type LoopDefinition, type MergeResult, type ReleaseResult, type PlanTicket, type ProposeRequest, type TranscriptsResult, type DraftUpdateRequest, type ProjectActivityResult, type WriteBackMilestones, type SuggestedVerification } from '../loop';
+import { type QuestionAdvice } from '../../../core/src/question-recommendation';
+import { StepFailed, type MeasureLaunch, type ChangeRequestResult, type EventFilter, type OtherEvent, type IntegrationBranch, type LoopDefinition, type MergeResult, type ReleaseResult, type PlanTicket, type ProposeRequest, type TranscriptsResult, type AlertTaskResult, type PipelineStatus, type ReportPipelineResult, type ReviewThreads, type OpenChangeRequests, type OwnChangeRequests, type DraftUpdateRequest, type ProjectActivityResult, type WriteBackMilestones, type SuggestedVerification } from '../loop';
 import * as Cause from 'effect/Cause';
 import * as Effect from 'effect/Effect';
 import * as FileSystem from 'effect/FileSystem';
@@ -35,11 +36,13 @@ export type ProgramJournal = {
 };
 /** The domain calls a program's Loop makes under its orchestration lease. */
 export type ProgramCapabilities = {
-    readonly putQuestion: (question: {
+    readonly putQuestion: (question: QuestionAdvice & {
         readonly step: string;
         readonly prompt: string;
         readonly options?: readonly string[];
         readonly verification?: SuggestedVerification;
+        readonly default?: string;
+        readonly timeoutMillis?: number;
         readonly deferredName: string;
     }) => Effect.Effect<{
         readonly questionId: string;
@@ -49,6 +52,8 @@ export type ProgramCapabilities = {
         readonly deferredName: string;
         readonly revision?: string;
         readonly checks?: readonly string[];
+        readonly suggested?: readonly SuggestedVerification[];
+        readonly measure?: MeasureLaunch;
     }) => Effect.Effect<{
         readonly verificationId: string;
     }, Error>;
@@ -58,8 +63,11 @@ export type ProgramCapabilities = {
         readonly role: string;
         readonly agentId: string;
         readonly prompt: string;
+        readonly skill?: string;
         readonly outputSchema: Schema.Json;
         readonly secrets?: readonly string[];
+        readonly timeoutMillis?: number;
+        readonly mergeTarget?: string;
     }) => Effect.Effect<{
         readonly stepAttemptId: string;
     }, Error>;
@@ -69,6 +77,14 @@ export type ProgramCapabilities = {
         readonly event: string;
         readonly filter?: EventFilter;
         readonly timeoutMillis: number;
+        readonly since?: string;
+        readonly or?: readonly OtherEvent[];
+    }) => Effect.Effect<void, Error>;
+    readonly claimResource: (claim: {
+        readonly step: string;
+        readonly deferredName: string;
+        readonly resource: string;
+        readonly action: 'claim' | 'take_over' | 'let_go';
     }) => Effect.Effect<void, Error>;
     readonly admitChild: (child: {
         readonly step: string;
@@ -121,6 +137,13 @@ export type ProgramCapabilities = {
             readonly kind: 'post_comment';
             readonly changeRequestId: string;
             readonly body: string;
+            readonly threadId?: string;
+            readonly summary?: string;
+            readonly anchors?: readonly {
+                readonly file: string;
+                readonly line: number;
+                readonly body: string;
+            }[];
         } | {
             readonly kind: 'change_request';
             readonly title: string;
@@ -132,20 +155,49 @@ export type ProgramCapabilities = {
             readonly changeRequestUrl?: string;
         };
     }) => Effect.Effect<ChangeRequestResult | undefined, Error>;
-    readonly createPlanTasks: (tickets: readonly PlanTicket[]) => Effect.Effect<readonly {
+    readonly createPlanTasks: (tickets: readonly PlanTicket[], projectId?: string) => Effect.Effect<readonly {
         readonly key: string;
         readonly taskId: string;
     }[], Error>;
+    readonly alertTask: (request: {
+        readonly step: string;
+        readonly fingerprint: string;
+        readonly title: string;
+        readonly windowHours: number;
+        readonly resolved?: boolean;
+        readonly priority?: 'urgent' | 'high' | 'medium' | 'low';
+    }) => Effect.Effect<AlertTaskResult, Error>;
     readonly readTranscripts: (request: {
         readonly step: string;
         readonly days: number;
     }) => Effect.Effect<TranscriptsResult, Error>;
+    readonly pipelineStatus: (request: {
+        readonly step: string;
+        readonly changeRequestId: string;
+    }) => Effect.Effect<PipelineStatus, Error>;
+    readonly reportPipeline: (request: {
+        readonly step: string;
+        readonly changeRequestId: string;
+        readonly verification: string;
+    }) => Effect.Effect<ReportPipelineResult, Error>;
+    readonly reviewThreads: (request: {
+        readonly step: string;
+        readonly changeRequestId: string;
+    }) => Effect.Effect<ReviewThreads, Error>;
+    readonly openChangeRequests: (request: {
+        readonly step: string;
+        readonly authors: readonly [string, ...string[]];
+    }) => Effect.Effect<OpenChangeRequests, Error>;
+    readonly ownChangeRequests: (request: {
+        readonly step: string;
+    }) => Effect.Effect<OwnChangeRequests, Error>;
     readonly propose: (request: {
         readonly step: string;
         readonly proposal: ProposeRequest;
     }) => Effect.Effect<{
         readonly kind: 'memory' | 'task';
         readonly id: string;
+        readonly matched?: boolean;
     }, Error>;
     readonly readProject: (request: {
         readonly step: string;
@@ -160,7 +212,42 @@ export type ProgramCapabilities = {
     readonly mergeChangeRequest: (request: {
         readonly step: string;
         readonly changeRequestId: string;
+        readonly head?: string;
     }) => Effect.Effect<MergeResult, Error>;
+    readonly closeChangeRequest: (request: {
+        readonly step: string;
+        readonly number: string;
+        readonly head: string;
+        readonly note: string;
+    }) => Effect.Effect<{
+        readonly closed: boolean;
+        readonly head?: string;
+    }, Error>;
+    readonly approveChangeRequest: (request: {
+        readonly step: string;
+        readonly changeRequestId: string;
+        readonly head: string;
+        readonly summary: string;
+        readonly review?: string;
+        readonly carries?: string;
+    }) => Effect.Effect<{
+        readonly approved: true;
+        readonly reviewId: string;
+    } | {
+        readonly approved: false;
+        readonly reason: string;
+    }, Error>;
+    readonly rerunPipeline: (request: {
+        readonly step: string;
+    } & ({
+        readonly changeRequestId: string;
+    } | {
+        readonly ref: string;
+        readonly all?: boolean;
+    })) => Effect.Effect<{
+        readonly head: string;
+        readonly pipelines: number;
+    }, Error>;
     readonly publishRelease: (request: {
         readonly step: string;
         readonly tag: string;
@@ -184,6 +271,11 @@ export declare class JournalWriteFailed extends JournalWriteFailed_base<{
 }
 /** A refusal of the request itself, as opposed to a lost lease or a failure of Kitman's. */
 export declare const refusedStep: (cause: Error) => boolean;
+/**
+ * A refused capability or request (a 4xx such as an unpublished child Loop) fails the Step; a lost lease or a failure
+ * of Kitman's means this turn ends, and a replay asks again.
+ */
+export declare const requested: <A, R>(step: string, request: Effect.Effect<A, Error, R>) => Effect.Effect<A, StepFailed, R>;
 /** What uploading a Run File asks of Kitman, under whichever lease its maker holds. */
 export type RunFileClient = Pick<ProgramCapabilities, 'createRunFile' | 'runFileParts' | 'completeRunFile'>;
 type FileServices = FileSystem.FileSystem | HttpClient.HttpClient;