@kitman-sh/loops 0.0.0-stage → 0.6.0

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

@@ -0,0 +1,39 @@
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import type { LoopDefinition } from './define';
+import { type LoopCheck } from './test-loop';
+declare const CheckFailed_base: Schema.Class<CheckFailed, Schema.TaggedStruct<"CheckFailed", {
+    readonly loop: Schema.String;
+    readonly check: Schema.String;
+    readonly reason: Schema.String;
+}>, Cause.YieldableError>;
+export declare class CheckFailed extends CheckFailed_base {
+    get detail(): string;
+    get message(): string;
+}
+declare const StepNamedTwice_base: Schema.Class<StepNamedTwice, Schema.TaggedStruct<"StepNamedTwice", {
+    readonly loop: Schema.String;
+    readonly check: Schema.String;
+    readonly step: Schema.String;
+}>, Cause.YieldableError>;
+export declare class StepNamedTwice extends StepNamedTwice_base {
+    get detail(): string;
+    get message(): string;
+}
+declare const ReplayDiverged_base: Schema.Class<ReplayDiverged, Schema.TaggedStruct<"ReplayDiverged", {
+    readonly loop: Schema.String;
+    readonly check: Schema.String;
+    readonly first: Schema.$Array<Schema.String>;
+    readonly replay: Schema.$Array<Schema.String>;
+    readonly rerun: Schema.$Array<Schema.String>;
+}>, Cause.YieldableError>;
+export declare class ReplayDiverged extends ReplayDiverged_base {
+    get detail(): string;
+    get message(): string;
+}
+export declare const LoopCheckError: Schema.Union<readonly [typeof CheckFailed, typeof StepNamedTwice, typeof ReplayDiverged]>;
+export type LoopCheckError = typeof LoopCheckError.Type;
+/** Runs a check twice, the second time from the first run's journal; the replay must take the same Steps and rerun no Activity. */
+export declare const checkLoop: (loop: LoopDefinition<unknown, unknown, unknown>, check: LoopCheck) => Effect.Effect<void, LoopCheckError>;
+export {};

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

@@ -0,0 +1,68 @@
+import type { KitAssignmentDeclaration, KitInstallationDeclaration, ScheduleDeclaration } from '../../../core/src/package-declarations';
+import type { LoopDefinition } from './define';
+/** Agent instructions inline, or a Markdown file in the Package's repository, read at build. */
+export type AgentInstructions = string | {
+    readonly file: string;
+};
+export type AgentConfig = {
+    /** The Agent this one extends. */
+    readonly extends?: string;
+    readonly instructions?: AgentInstructions;
+    readonly harness?: string;
+    readonly model?: string;
+    /** How hard its harness thinks; a harness without the control ignores it. */
+    readonly effort?: 'low' | 'medium' | 'high' | 'xhigh';
+    /** Kit references. */
+    readonly kits?: readonly string[];
+    /** Hosts its sandboxed Steps may reach beyond the defaults, or `open` for an Agent that browses. */
+    readonly network?: {
+        readonly hosts: readonly string[];
+    } | 'open';
+    /** Runs its Steps only on Runners that run agents in docker, for services or a project image. */
+    readonly sandbox?: 'docker';
+};
+/** A Kit written from the Package's files: its context, and skill directories each holding a `SKILL.md`. */
+export type AuthoredKitConfig = {
+    readonly name: string;
+    readonly kind?: 'technology' | 'brand' | 'domain' | 'process' | 'other';
+    readonly description?: string;
+    readonly context: AgentInstructions;
+    /** Skill directories in the repository; each is named after its directory. */
+    readonly skills?: readonly string[];
+};
+/** An authored Kit, a Marketplace Kit to install, or where a Kit applies. */
+export type KitConfig = AuthoredKitConfig | KitInstallationDeclaration | KitAssignmentDeclaration;
+export type PackageLoop = LoopDefinition<unknown, unknown, unknown>;
+/** A Package's `kitman.config.ts` default export. */
+export type PackageConfig = {
+    readonly loops: readonly PackageLoop[];
+    readonly agents?: {
+        readonly [id: string]: AgentConfig;
+    };
+    readonly schedules?: {
+        readonly [key: string]: ScheduleDeclaration;
+    };
+    readonly kits?: {
+        readonly [key: string]: KitConfig;
+    };
+};
+/** Each element a Loop, whatever its Input, Output and error types. */
+type Loops<L extends readonly unknown[]> = {
+    readonly [K in keyof L]: L[K] extends LoopDefinition<infer In, infer Out, infer E> ? LoopDefinition<In, Out, E> : never;
+};
+/** Declares a Package: its Loops, and its Agents keyed by id. */
+export declare const defineConfig: <const L extends readonly unknown[]>(config: {
+    readonly loops: L & Loops<L>;
+    readonly agents?: {
+        readonly [id: string]: AgentConfig;
+    };
+    /** Recurring starts of a Loop, keyed; the Package owns each Schedule it declares. */
+    readonly schedules?: {
+        readonly [key: string]: ScheduleDeclaration;
+    };
+    /** Kits, keyed; only a Workspace Package may declare them. */
+    readonly kits?: {
+        readonly [key: string]: KitConfig;
+    };
+}) => PackageConfig;
+export {};

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

@@ -0,0 +1,69 @@
+import { LoopCapabilities, type LoopManifest } from '../../../core/src/package-declarations';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import type { WorkflowEngine } from 'effect/workflow';
+import type { LoopHost, LoopRun } from './steps';
+import type { LoopCheck } from './test-loop';
+import type { ArtifactActivity, ChangeRequestActivity, CommentActivity, CreateTasksActivity, IntegrationBranchActivity, MergeChangeRequestActivity, NoteActivity, ReleaseActivity, WriteBackActivity } from './activities';
+export { LoopCapabilities, type LoopManifest };
+/** What a Loop's program may ask Kitman for; the control plane checks each request against them. */
+export type LoopCapability = (typeof LoopCapabilities)[number];
+export declare const LoopOutcome: Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>;
+export type LoopOutcome = typeof LoopOutcome.Type;
+export type LoopCheckout = 'none' | 'read' | 'write';
+type EventFilterValue = string | number | boolean | null;
+/** Matched by the control plane against Event payload paths: a value, or any of several. */
+export type EventFilter = {
+    readonly [path: string]: EventFilterValue | readonly EventFilterValue[];
+};
+/** Starts a Run on a matching Event, binding Event payload paths into the Loop Input. */
+export type WhenClause = {
+    readonly event: string;
+    readonly filter?: EventFilter;
+    readonly input: {
+        readonly [inputField: string]: string;
+    };
+};
+/** An action shown on a settled Run: start another Loop. */
+export type LoopOffer = {
+    readonly id: string;
+    readonly title: string;
+    readonly loop: string;
+};
+/** The services a Loop's program runs with; a Runner or `testLoop` provides them. */
+export type LoopServices = LoopRun | LoopHost | ChangeRequestActivity | WriteBackActivity | ArtifactActivity | NoteActivity | CommentActivity | CreateTasksActivity | IntegrationBranchActivity | MergeChangeRequestActivity | ReleaseActivity | WorkflowEngine.WorkflowEngine | WorkflowEngine.WorkflowInstance;
+/** A schema a Loop can decode and encode with no services. */
+export type LoopSchema<T> = Schema.Codec<T, unknown>;
+export type LoopDefinition<In, Out, E> = {
+    readonly id: string;
+    readonly title: string;
+    readonly input: LoopSchema<In>;
+    readonly output: LoopSchema<Out>;
+    readonly outcome?: LoopOutcome;
+    /** Agent ids by role; `agentWork` names a role. */
+    readonly agents: {
+        readonly [role: string]: string;
+    };
+    readonly checkout: LoopCheckout;
+    readonly when?: readonly WhenClause[];
+    readonly offers?: readonly LoopOffer[];
+    readonly capabilities: readonly LoopCapability[];
+    /** The Secrets the program reads with `Config.Redacted`, and `agentWork` may put into a Step's sandbox. */
+    readonly secrets?: readonly string[];
+    readonly run: (input: In) => Effect.Effect<Out, E, LoopServices>;
+    /** Scripts a build runs twice, the second time from the journal; not part of the manifest. */
+    readonly checks?: readonly LoopCheck[];
+};
+/** A Loop module's default export. The definition keeps its shape, so a fork spreads it. */
+export declare const defineLoop: <In, Out, E>(definition: LoopDefinition<In, Out, E>) => LoopDefinition<In, Out, E>;
+declare const ManifestInvalid_base: Schema.Class<ManifestInvalid, Schema.TaggedStruct<"ManifestInvalid", {
+    readonly loop: Schema.String;
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
+export declare class ManifestInvalid extends ManifestInvalid_base {
+}
+export declare const jsonSchemaOf: <T>(loop: string, schema: LoopSchema<T>) => Effect.Effect<{
+    readonly [x: string]: Schema.Json;
+}, ManifestInvalid, never>;
+/** The data the control plane reads from a Loop, made without calling `run`. */
+export declare const loopManifest: <In, Out, E>(definition: LoopDefinition<In, Out, E>) => Effect.Effect<LoopManifest, ManifestInvalid>;

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

@@ -0,0 +1,66 @@
+import * as Schema from 'effect/Schema';
+import type { LoopOutcome } from './define';
+import type { ScopeJudgement } from './review';
+/** One approved verification's result at a tree, as a Runner recorded it. */
+export declare const EvidenceCheck: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly command: Schema.String;
+    readonly status: Schema.Literals<readonly ["passed", "failed"]>;
+    /** It also fails on the default branch's head, so the Run did not cause it. */
+    readonly preExisting: Schema.Boolean;
+    readonly durationMs: Schema.Finite;
+    readonly evidenceId: Schema.String;
+}>;
+export type EvidenceCheck = typeof EvidenceCheck.Type;
+/** Evidence for a revision; `tree` is its git tree id, and the evidence holds for any revision with that tree. */
+export declare const VerifyResult: Schema.Struct<{
+    readonly revision: Schema.String;
+    readonly tree: Schema.String;
+    /** Every check passed or already failed on the default branch. */
+    readonly passed: Schema.Boolean;
+    readonly checks: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly command: Schema.String;
+        readonly status: Schema.Literals<readonly ["passed", "failed"]>;
+        /** It also fails on the default branch's head, so the Run did not cause it. */
+        readonly preExisting: Schema.Boolean;
+        readonly durationMs: Schema.Finite;
+        readonly evidenceId: Schema.String;
+    }>>;
+}>;
+export type VerifyResult = typeof VerifyResult.Type;
+/** What closes a Run, by its Outcome; `none` is a Run with no Outcome. */
+export declare const OutcomeTable: {
+    readonly feature: 'Approved verifications pass on the head tree, and review says the scope was met';
+    readonly bug: 'A reproducing check fails on the base and passes on the head';
+    readonly refactor: 'Approved verifications pass on both base and head';
+    readonly investigation: 'A conclusion Output with its sources; no patch needed';
+    readonly docs: 'The documented commands run';
+    readonly migration: 'A rollback check passes';
+    readonly none: 'Only the approved verifications';
+};
+export type EvidenceGateInput = {
+    readonly outcome?: LoopOutcome;
+    readonly head?: VerifyResult;
+    readonly base?: VerifyResult;
+    /** The reviewer's scope judgement; absent when no reviewer judged it, which never reads as met. */
+    readonly review?: ScopeJudgement;
+    /** The check that reproduces a bug. */
+    readonly reproducing?: string;
+    readonly conclusion?: {
+        readonly text: string;
+        readonly sources: readonly string[];
+    };
+    /** The checks that run the documented commands. */
+    readonly documented?: readonly string[];
+    /** The check that rolls a migration back. */
+    readonly rollback?: string;
+};
+export type EvidenceVerdict = {
+    readonly settled: true;
+} | {
+    readonly settled: false;
+    readonly reasons: readonly string[];
+};
+/** Whether the Run's evidence closes its Outcome, per `OutcomeTable`; claims in Outputs never count. */
+export declare const evidenceGate: (input: EvidenceGateInput) => EvidenceVerdict;

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

@@ -0,0 +1,9 @@
+export * from './define';
+export * from './steps';
+export * from './activities';
+export * from './test-loop';
+export * from './evidence';
+export * from './review';
+export * from './plan';
+export * from './check';
+export * from './config';

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

@@ -0,0 +1,43 @@
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+/** One unit of a plan, which Implement now turns into a Task and builds. */
+export declare const PlanTicket: Schema.Struct<{
+    /** Short and unique within the plan; blockers name it. */
+    readonly key: Schema.String;
+    readonly title: Schema.String;
+    readonly body: Schema.String;
+    readonly acceptanceCriteria: Schema.$Array<Schema.String>;
+    /** The repository it changes; the Project's default when left out. */
+    readonly repoBindingId: Schema.optional<Schema.String>;
+    /** Keys of the tickets that must be built first. */
+    readonly blockedBy: Schema.$Array<Schema.String>;
+    /** The kind of change; its Task gets the first Task Type with this Outcome. */
+    readonly outcome: Schema.optional<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>>;
+}>;
+export type PlanTicket = typeof PlanTicket.Type;
+/** A plan's tickets; a blocker must name another ticket, and no tickets may block each other in a cycle. */
+export declare const PlanTickets: Schema.$Array<Schema.Struct<{
+    /** Short and unique within the plan; blockers name it. */
+    readonly key: Schema.String;
+    readonly title: Schema.String;
+    readonly body: Schema.String;
+    readonly acceptanceCriteria: Schema.$Array<Schema.String>;
+    /** The repository it changes; the Project's default when left out. */
+    readonly repoBindingId: Schema.optional<Schema.String>;
+    /** Keys of the tickets that must be built first. */
+    readonly blockedBy: Schema.$Array<Schema.String>;
+    /** The kind of change; its Task gets the first Task Type with this Outcome. */
+    readonly outcome: Schema.optional<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>>;
+}>>;
+declare const BlockingCycle_base: Schema.Class<BlockingCycle, Schema.TaggedStruct<"BlockingCycle", {
+    readonly tickets: Schema.$Array<Schema.String>;
+}>, import("effect/Cause").YieldableError>;
+export declare class BlockingCycle extends BlockingCycle_base {
+    get message(): string;
+}
+/**
+ * Orders tickets into waves: a ticket is in the wave after its last blocker's, and each wave is grouped by
+ * RepoBinding. Every ticket in a wave can be built at once.
+ */
+export declare const planWaves: (tickets: readonly PlanTicket[]) => Effect.Effect<readonly PlanTicket[][], BlockingCycle>;
+export {};

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

@@ -0,0 +1,86 @@
+import * as Schema from 'effect/Schema';
+export declare const Severity: Schema.Literals<readonly ["blocker", "major", "minor"]>;
+export type Severity = typeof Severity.Type;
+/** What one reviewer seat found. */
+export declare const Finding: Schema.Struct<{
+    readonly severity: Schema.Literals<readonly ["blocker", "major", "minor"]>;
+    readonly file: Schema.String;
+    readonly line: Schema.Int;
+    readonly detail: Schema.String;
+}>;
+export type Finding = typeof Finding.Type;
+/** A finding after the panel's findings are merged; `id` is its file and line. */
+export declare const MergedFinding: Schema.Struct<{
+    readonly severity: Schema.Literals<readonly ["blocker", "major", "minor"]>;
+    readonly file: Schema.String;
+    readonly line: Schema.Int;
+    readonly detail: Schema.String;
+    readonly id: Schema.String;
+    readonly seats: Schema.$Array<Schema.String>;
+}>;
+export type MergedFinding = typeof MergedFinding.Type;
+export declare const Rebuttal: Schema.Struct<{
+    readonly findingId: Schema.String;
+    readonly reason: Schema.String;
+}>;
+export type Rebuttal = typeof Rebuttal.Type;
+export declare const RebuttalVerdict: Schema.Struct<{
+    readonly findingId: Schema.String;
+    readonly accepted: Schema.Boolean;
+}>;
+export type RebuttalVerdict = typeof RebuttalVerdict.Type;
+/** Whether a change does what its Task asks; `unmet` names each criterion or part of the description not done. */
+export declare const ScopeJudgement: Schema.Struct<{
+    readonly met: Schema.Boolean;
+    readonly unmet: Schema.$Array<Schema.String>;
+}>;
+export type ScopeJudgement = typeof ScopeJudgement.Type;
+export type Disputed = {
+    readonly finding: MergedFinding;
+    readonly rebuttal: Rebuttal;
+};
+export declare const isBlocking: (finding: Pick<Finding, 'severity'>) => boolean;
+/** One finding per file and line; the worst severity's detail wins, and every seat that raised it is kept. */
+export declare const mergeFindings: (bySeat: {
+    readonly [seat: string]: readonly Finding[];
+}) => readonly MergedFinding[];
+export declare const splitDisputed: (findings: readonly MergedFinding[], rebuttals: readonly Rebuttal[]) => {
+    disputed: Disputed[];
+    undisputed: {
+        readonly severity: "blocker" | "major" | "minor";
+        readonly file: string;
+        readonly line: number;
+        readonly detail: string;
+        readonly id: string;
+        readonly seats: readonly string[];
+    }[];
+};
+export type SettledRound = {
+    /** Findings still to fix. */
+    readonly open: readonly MergedFinding[];
+    /** Rebutted, and the reviewers accepted the rebuttal. */
+    readonly withdrawn: readonly Disputed[];
+    /** Rebutted, and the reviewers did not accept the rebuttal. */
+    readonly standing: readonly Disputed[];
+};
+/** A rebutted finding is withdrawn only when every verdict on it accepts the rebuttal. */
+export declare const settleRound: (round: {
+    readonly findings: readonly MergedFinding[];
+    readonly rebuttals: readonly Rebuttal[];
+    readonly verdicts: readonly RebuttalVerdict[];
+}) => SettledRound;
+export type RallyStopReason = 'settled' | 'dispute_stands' | 'findings_returned' | 'round_cap';
+export type RallyDecision = {
+    readonly stop: false;
+} | {
+    readonly stop: true;
+    readonly reason: RallyStopReason;
+    readonly unsettled: readonly string[];
+};
+/** Whether the rally ends after this round; `previous` is the last round's blocking finding ids. */
+export declare const rallyStop: (input: {
+    readonly round: number;
+    readonly maxRounds: number;
+    readonly settled: SettledRound;
+    readonly previous?: readonly string[];
+}) => RallyDecision;

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

@@ -0,0 +1,224 @@
+import * as Cause from 'effect/Cause';
+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 { type EventFilter, type LoopCapability, type LoopDefinition, type LoopSchema } from './define';
+declare const StepFailed_base: Schema.Class<StepFailed, Schema.TaggedStruct<"StepFailed", {
+    readonly step: Schema.String;
+    readonly reason: Schema.String;
+}>, Cause.YieldableError>;
+export declare class StepFailed extends StepFailed_base {
+    get message(): string;
+}
+declare const OutputInvalid_base: Schema.Class<OutputInvalid, Schema.TaggedStruct<"OutputInvalid", {
+    readonly step: Schema.String;
+    readonly message: Schema.String;
+}>, Cause.YieldableError>;
+export declare class OutputInvalid extends OutputInvalid_base {
+}
+declare const QuestionRefused_base: Schema.Class<QuestionRefused, Schema.TaggedStruct<"QuestionRefused", {
+    readonly step: Schema.String;
+    readonly answer: Schema.String;
+    readonly options: Schema.$Array<Schema.String>;
+}>, Cause.YieldableError>;
+export declare class QuestionRefused extends QuestionRefused_base {
+}
+declare const WaitTimedOut_base: Schema.Class<WaitTimedOut, Schema.TaggedStruct<"WaitTimedOut", {
+    readonly step: Schema.String;
+    readonly event: Schema.String;
+}>, Cause.YieldableError>;
+export declare class WaitTimedOut extends WaitTimedOut_base {
+}
+declare const ChildFailed_base: Schema.Class<ChildFailed, Schema.TaggedStruct<"ChildFailed", {
+    readonly step: Schema.String;
+    readonly loop: Schema.String;
+    readonly reason: Schema.String;
+}>, Cause.YieldableError>;
+export declare class ChildFailed extends ChildFailed_base {
+    get message(): string;
+}
+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"]>;
+    /** A Secret the Step names that its Loop does not declare. */
+    readonly secret: Schema.optionalKey<Schema.String>;
+}>, Cause.YieldableError>;
+export declare class CapabilityDenied extends CapabilityDenied_base {
+    get message(): string;
+}
+declare const DuplicateStep_base: Schema.Class<DuplicateStep, Schema.TaggedStruct<"DuplicateStep", {
+    readonly step: Schema.String;
+}>, Cause.YieldableError>;
+export declare class DuplicateStep extends DuplicateStep_base {
+}
+declare const InputInvalid_base: Schema.Class<InputInvalid, Schema.TaggedStruct<"InputInvalid", {
+    readonly loop: Schema.String;
+    readonly message: Schema.String;
+}>, Cause.YieldableError>;
+export declare class InputInvalid extends InputInvalid_base {
+}
+export declare const LoopEvent: Schema.Struct<{
+    readonly type: Schema.String;
+    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' | 'note' | 'comment' | 'create_tasks' | 'integration_branch' | 'merge_change_request' | 'release';
+/** A Step a Run took, as its program saw it. */
+export type StepRecord = {
+    readonly name: string;
+    readonly kind: StepKind;
+    readonly status: 'succeeded';
+    readonly result: unknown;
+} | {
+    readonly name: string;
+    readonly kind: StepKind;
+    readonly status: 'failed';
+    readonly error: unknown;
+};
+declare const LoopRun_base: Context.ServiceClass<LoopRun, "@kitman-sh/sdk/loop/LoopRun", {
+    readonly loop: string;
+    readonly agents: {
+        readonly [role: string]: string;
+    };
+    readonly granted: ReadonlySet<LoopCapability>;
+    /** The Secrets the Loop declares. */
+    readonly secrets: ReadonlySet<string>;
+    readonly names: Set<string>;
+    readonly steps: StepRecord[];
+}>;
+/** One execution of a Run's program; a replay starts a fresh one. */
+export declare class LoopRun extends LoopRun_base {
+}
+type Launch = {
+    readonly step: string;
+    readonly token: DurableDeferred.Token;
+};
+export type AgentWorkLaunch = Launch & {
+    readonly role: string;
+    readonly agent: string;
+    readonly prompt: string;
+    /** JSON Schema the Output must match. */
+    readonly output: Schema.Json;
+    /** Secrets for the agent's sandbox environment. */
+    readonly secrets?: readonly string[];
+};
+/** A verification a human may approve for the repository; nothing runs it until they do. */
+export type SuggestedVerification = {
+    readonly name: string;
+    readonly command: string;
+    readonly workingDirectory?: string;
+};
+export type QuestionLaunch = Launch & {
+    readonly prompt: string;
+    readonly options?: readonly string[];
+    /** Approving the Question approves this verification. */
+    readonly verification?: SuggestedVerification;
+};
+export type VerificationLaunch = Launch & {
+    /** The Run's head when left out. */
+    readonly revision?: string;
+    /** Approved verifications by name; all of them when left out. */
+    readonly checks?: readonly string[];
+};
+export type ChildLaunch = Launch & {
+    readonly loop: string;
+    readonly input: Schema.Json;
+};
+export type EventWaitLaunch = Launch & {
+    readonly event: string;
+    readonly filter?: EventFilter;
+    readonly timeoutMillis: number;
+};
+declare const LoopHost_base: Context.ServiceClass<LoopHost, "@kitman-sh/sdk/loop/LoopHost", {
+    readonly startAgentWork: (launch: AgentWorkLaunch) => Effect.Effect<void, StepFailed>;
+    readonly putQuestion: (launch: QuestionLaunch) => Effect.Effect<void, StepFailed>;
+    readonly admitChild: (launch: ChildLaunch) => Effect.Effect<void, StepFailed>;
+    readonly awaitEvent: (launch: EventWaitLaunch) => Effect.Effect<void, StepFailed>;
+    readonly startVerification: (launch: VerificationLaunch) => Effect.Effect<void, StepFailed>;
+}>;
+/**
+ * What Kitman lends a program: each launch hands Kitman a deferred token, and Kitman resolves it with the
+ * Output, answer, child result or Event.
+ */
+export declare class LoopHost extends LoopHost_base {
+}
+export declare const agentWorkDeferred: (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<{
+    readonly type: Schema.String;
+    readonly payload: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>, typeof WaitTimedOut>;
+export declare const verifyDeferred: (step: string) => DurableDeferred.DurableDeferred<Schema.Struct<{
+    readonly revision: Schema.String;
+    readonly tree: Schema.String;
+    readonly passed: Schema.Boolean;
+    readonly checks: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly command: Schema.String;
+        readonly status: Schema.Literals<readonly ["passed", "failed"]>;
+        readonly preExisting: Schema.Boolean;
+        readonly durationMs: Schema.Finite;
+        readonly evidenceId: Schema.String;
+    }>>;
+}>, 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 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.
+ */
+export declare const agentWork: <Out>(name: string, options: {
+    readonly agent: string;
+    readonly prompt: string;
+    readonly output: LoopSchema<Out>;
+    readonly secrets?: readonly string[];
+}) => 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[]> = {
+    readonly prompt: string;
+    readonly options: Options;
+} | {
+    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. */
+export declare const waitFor: (name: string, wait: {
+    readonly event: string;
+    readonly filter?: EventFilter;
+    readonly timeout: Duration.Input;
+}) => 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>;
+/**
+ * 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.
+ */
+export declare const verify: (name: string, request: {
+    readonly revision?: string;
+    readonly checks?: readonly string[];
+}) => Effect.Effect<{
+    readonly revision: string;
+    readonly tree: string;
+    readonly passed: boolean;
+    readonly checks: readonly {
+        readonly name: string;
+        readonly command: string;
+        readonly status: "failed" | "passed";
+        readonly preExisting: boolean;
+        readonly durationMs: number;
+        readonly evidenceId: string;
+    }[];
+}, 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. */
+export declare const suggestVerification: (name: string, verification: SuggestedVerification) => Effect.Effect<"approved" | "rejected", CapabilityDenied | DuplicateStep | StepFailed, LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;
+export {};