@kitman-sh/sdk 0.0.0-stage → 0.7.0

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 {};

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

@@ -0,0 +1,112 @@
+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, IntegrationBranchActivity, MergeChangeRequestActivity, NoteActivity, ReleaseActivity, WriteBackActivity } from './activities';
+import type { LoopCapability, LoopDefinition } from './define';
+import type { VerifyResult } from './evidence';
+import { InputInvalid, LoopHost, LoopRun, 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>>;
+    readonly deferreds: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+}>;
+export type LoopJournal = typeof LoopJournal.Type;
+declare const ScriptedFailure_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Readonly<A> & {
+    readonly _tag: "ScriptedFailure";
+} & import("effect/Pipeable").Pipeable;
+export declare class ScriptedFailure extends ScriptedFailure_base<{
+    readonly reason: string;
+}> {
+}
+/** Scripts a failed agent Step or Child Run. */
+export declare const scriptedFailure: (reason: string) => ScriptedFailure;
+type Scripted = Schema.Json | ScriptedFailure;
+export type HostActivities = {
+    readonly changeRequest: ChangeRequestActivity['Service'];
+    readonly writeBack: WriteBackActivity['Service'];
+    readonly artifact: ArtifactActivity['Service'];
+    readonly note: NoteActivity['Service'];
+    readonly comment: CommentActivity['Service'];
+    readonly createTasks: CreateTasksActivity['Service'];
+    readonly integrationBranch: IntegrationBranchActivity['Service'];
+    readonly mergeChangeRequest: MergeChangeRequestActivity['Service'];
+    readonly release: ReleaseActivity['Service'];
+};
+export type TestLoopScript = {
+    /** The Loop Input as JSON, as a Run receives it. */
+    readonly input: Schema.Json;
+    /** Outputs by Step name; a Step left out fails. */
+    readonly outputs?: {
+        readonly [step: string]: Scripted;
+    };
+    readonly answers?: {
+        readonly [step: string]: string;
+    };
+    readonly children?: {
+        readonly [step: string]: Scripted;
+    };
+    /** Events by Step name; a waitFor left out times out. */
+    readonly events?: {
+        readonly [step: string]: LoopEvent;
+    };
+    /** Verification results by Step name; a verify left out passes with no checks. */
+    readonly verifications?: {
+        readonly [step: string]: VerifyResult | ScriptedFailure;
+    };
+    /** What the control plane grants; the declared capabilities by default. */
+    readonly grant?: readonly LoopCapability[];
+    readonly activities?: Partial<HostActivities>;
+    readonly journal?: LoopJournal;
+    /** Secret values the program reads with `Config`; none by default. */
+    readonly secrets?: {
+        readonly [name: string]: string;
+    };
+};
+/** A check run twice, once from the journal: a Loop's `checks`, or a stored Loop module's `checks` export. */
+export type LoopCheck = {
+    readonly name: string;
+    readonly script: TestLoopScript;
+};
+export type TestLoopResult<Out, E> = {
+    readonly result: Exit.Exit<Out, E | InputInvalid>;
+    readonly steps: readonly StepRecord[];
+    readonly journal: LoopJournal;
+    /** Activities that ran rather than replayed from the journal. */
+    readonly activities: readonly string[];
+    readonly agentLaunches: readonly AgentLaunchRecord[];
+    /** Child Runs admitted, with their Input as JSON, in admission order. */
+    readonly childLaunches: readonly ChildLaunchRecord[];
+};
+type AgentLaunchRecord = {
+    readonly step: string;
+    readonly agent: string;
+    readonly prompt: string;
+    readonly secrets?: readonly string[];
+};
+type ChildLaunchRecord = {
+    readonly step: string;
+    readonly loop: string;
+    readonly input: Schema.Json;
+};
+/** The workflow a Loop's program runs as; a Run is one execution of it. */
+export declare const loopWorkflow: <In, Out, E>(loop: LoopDefinition<In, Out, E>) => Workflow.Workflow<`kitman-loop/${string}`, Schema.Struct<{
+    input: Schema.Codec<Schema.Json, Schema.Json, never, never>;
+}>, import("./define").LoopSchema<Out>, Schema.declare<E | InputInvalid, E | InputInvalid>>;
+export type LoopRuntime = {
+    readonly host: LoopHost['Service'];
+    readonly activities: HostActivities;
+    /** The declared capabilities the control plane granted. */
+    readonly granted: ReadonlySet<LoopCapability>;
+    readonly onRun?: (run: LoopRun['Service']) => void;
+};
+/** Decodes the Loop Input and runs the program with what Kitman lends it; the engine comes from the caller. */
+export declare const executeLoop: <In, Out, E>(loop: LoopDefinition<In, Out, E>, runtime: LoopRuntime) => ({ input }: {
+    readonly input: Schema.Json;
+}) => Effect.Effect<Out, E | InputInvalid, WorkflowEngine.WorkflowEngine | WorkflowEngine.WorkflowInstance>;
+/**
+ * Runs a Loop on Effect's in-memory workflow engine with scripted Outputs, answers, child results and Events.
+ * Given a `journal`, it replays from it.
+ */
+export declare const testLoop: <In, Out, E>(loop: LoopDefinition<In, Out, E>, script: TestLoopScript) => Effect.Effect<TestLoopResult<Out, E>>;
+export {};

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

@@ -0,0 +1,144 @@
+import { type OrchestrationWorkUnit, type ProgramWorkUnit } from '../../../core/src/index';
+import { type ChangeRequestResult, type EventFilter, type IntegrationBranch, type LoopDefinition, type MergeResult, type ReleaseResult, type PlanTicket, type WriteBackMilestones, type SuggestedVerification } from '../loop';
+import * as Cause from 'effect/Cause';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { type ProgramLease } from '../../../live/src/rpc/runner-group';
+import type { RunnerRpcClient } from '../../../live/src/rpc/runner-client';
+type WriteBackMilestone = (typeof WriteBackMilestones)[number];
+/** The journal writes one orchestration lease may make; the control plane fences each one. */
+export type ProgramJournal = {
+    readonly recordActivity: (entry: {
+        readonly name: string;
+        readonly attempt: number;
+        readonly exit: Schema.Json;
+    }) => Effect.Effect<void, Error>;
+    readonly deferredDone: (entry: {
+        readonly name: string;
+        readonly exit: Schema.Json;
+    }) => Effect.Effect<void, Error>;
+    readonly scheduleClock: (clock: {
+        readonly name: string;
+        readonly deferredName: string;
+        readonly durationMillis: number;
+    }) => Effect.Effect<void, Error>;
+    readonly putQuestion: (question: {
+        readonly step: string;
+        readonly prompt: string;
+        readonly options?: readonly string[];
+        readonly verification?: SuggestedVerification;
+        readonly deferredName: string;
+    }) => Effect.Effect<{
+        readonly questionId: string;
+    }, Error>;
+    readonly startVerification: (verification: {
+        readonly step: string;
+        readonly deferredName: string;
+        readonly revision?: string;
+        readonly checks?: readonly string[];
+    }) => Effect.Effect<{
+        readonly verificationId: string;
+    }, Error>;
+    readonly startAgentStep: (step: {
+        readonly step: string;
+        readonly deferredName: string;
+        readonly role: string;
+        readonly agentId: string;
+        readonly prompt: string;
+        readonly outputSchema: Schema.Json;
+        readonly secrets?: readonly string[];
+    }) => Effect.Effect<{
+        readonly stepAttemptId: string;
+    }, Error>;
+    readonly awaitEvent: (wait: {
+        readonly step: string;
+        readonly deferredName: string;
+        readonly event: string;
+        readonly filter?: EventFilter;
+        readonly timeoutMillis: number;
+    }) => Effect.Effect<void, Error>;
+    readonly admitChild: (child: {
+        readonly step: string;
+        readonly loop: string;
+        readonly input: Schema.Json;
+        readonly deferredName: string;
+    }) => Effect.Effect<{
+        readonly runId: string;
+    }, Error>;
+    readonly storeArtifact: (artifact: {
+        readonly step: string;
+        readonly kind: string;
+        readonly title: string;
+        readonly text: string;
+        readonly data?: Schema.Json | undefined;
+    }) => Effect.Effect<{
+        readonly artifactId: string;
+    }, Error>;
+    readonly recordNote: (note: {
+        readonly step: string;
+        readonly text: string;
+        readonly artifactId?: string | undefined;
+    }) => Effect.Effect<void, Error>;
+    readonly performHostEffect: (request: {
+        readonly step: string;
+        readonly effect: {
+            readonly kind: 'post_comment';
+            readonly changeRequestId: string;
+            readonly body: string;
+        } | {
+            readonly kind: 'change_request';
+            readonly title: string;
+            readonly body: string;
+            readonly integration?: string;
+        } | {
+            readonly kind: 'write_back';
+            readonly milestone?: WriteBackMilestone;
+            readonly changeRequestUrl?: string;
+        };
+    }) => Effect.Effect<ChangeRequestResult | undefined, Error>;
+    readonly createPlanTasks: (tickets: readonly PlanTicket[]) => Effect.Effect<readonly {
+        readonly key: string;
+        readonly taskId: string;
+    }[], Error>;
+    readonly integrationBranch: (repoBindingId?: string) => Effect.Effect<IntegrationBranch, Error>;
+    readonly mergeChangeRequest: (request: {
+        readonly step: string;
+        readonly changeRequestId: string;
+    }) => Effect.Effect<MergeResult, Error>;
+    readonly publishRelease: (request: {
+        readonly step: string;
+        readonly tag: string;
+        readonly revision?: string;
+        readonly title: string;
+        readonly notes: string;
+    }) => Effect.Effect<ReleaseResult, Error>;
+    readonly suspend: Effect.Effect<void, Error>;
+    readonly finish: (outcome: {
+        readonly status: 'completed';
+        readonly output: Schema.Json;
+    } | {
+        readonly status: 'failed';
+        readonly failureSummary: string;
+    }) => Effect.Effect<void, Error>;
+};
+declare const JournalWriteFailed_base: new <A extends Record<string, any> = {}>(args: import("effect/Types").VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P]; }>) => Cause.YieldableError & {
+    readonly _tag: "JournalWriteFailed";
+} & Readonly<A>;
+/** The control plane refused a journal write, so this replica no longer owns the Run and must report nothing. */
+export declare class JournalWriteFailed extends JournalWriteFailed_base<{
+    readonly cause: Error;
+}> {
+    get message(): string;
+}
+/** 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;
+/**
+ * Runs or replays a Run's program for one orchestration lease, and reports what became of it: suspended, with the
+ * lease given back; completed; or failed. A refused journal write means the lease is gone, so nothing is reported.
+ */
+export declare const runProgram: <In, Out, E>(loop: LoopDefinition<In, Out, E>, work: ProgramWorkUnit, journal: ProgramJournal) => Effect.Effect<'suspended' | 'completed' | 'failed', JournalWriteFailed>;
+/** A Work Unit's lease as the Runner RPC calls carry it. */
+export declare const programLease: (work: Pick<OrchestrationWorkUnit, 'id' | 'lease'>) => ProgramLease;
+/** The journal over the Runner RPC channel, each write under the Work Unit's lease. */
+export declare const rpcProgramJournal: (rpc: RunnerRpcClient, work: ProgramWorkUnit) => ProgramJournal;
+export {};

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

@@ -0,0 +1,70 @@
+import type { ProgramLease } from '../../../live/src/rpc/runner-group';
+import { makeRunnerRpcClient } from '../../../live/src/rpc/runner-client';
+import * as Effect from 'effect/Effect';
+import * as Option from 'effect/Option';
+import * as Schema from 'effect/Schema';
+import type { PackageConfig } from '../loop/config';
+import { ManifestInvalid } from '../loop/define';
+import { type ProgramJournal } from './engine';
+/** Asks a bundle for its declarations and check results instead of running a program. */
+export declare const describeFlag = "--kitman-describe";
+export declare const Described: Schema.Union<readonly [Schema.TaggedStruct<"Described", {
+    readonly loops: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly title: Schema.String;
+        readonly input: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly output: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+        readonly outcome: Schema.optionalKey<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration"]>>;
+        readonly agents: Schema.$Record<Schema.String, Schema.String>;
+        readonly checkout: Schema.Literals<readonly ["none", "read", "write"]>;
+        readonly when: Schema.$Array<Schema.Struct<{
+            readonly event: Schema.String;
+            readonly filter: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Union<readonly [Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.Null]>, Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Finite, Schema.Boolean, Schema.Null]>>]>>>;
+            readonly input: Schema.$Record<Schema.String, Schema.String>;
+        }>>;
+        readonly offers: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly title: Schema.String;
+            readonly loop: Schema.String;
+        }>>;
+        readonly capabilities: Schema.$Array<Schema.Literals<readonly ["agent_work", "ask", "call", "verify", "change_request", "write_back", "post_comment", "create_tasks", "merge_change_request", "publish_release"]>>;
+        readonly secrets: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly network: Schema.optionalKey<Schema.Union<readonly [Schema.Struct<{
+            readonly hosts: Schema.$Array<Schema.String>;
+        }>, Schema.Literal<"open">]>>;
+    }>>;
+    readonly agents: Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+    readonly schedules: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+    readonly kits: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+}>, Schema.TaggedStruct<"Refused", {
+    readonly error: Schema.Union<readonly [typeof ManifestInvalid, Schema.Union<readonly [typeof import("../loop").CheckFailed, typeof import("../loop").StepNamedTwice, typeof import("../loop").ReplayDiverged]>]>;
+}>]>;
+type SecretsRpc = Pick<Effect.Success<ReturnType<typeof makeRunnerRpcClient>>, 'programSecrets' | 'finishProgram'>;
+/**
+ * The Secrets the Loop declares, or none when Kitman refuses them (one deleted while the Run waited): the Run fails
+ * then, saying why, since a replay would only be refused again.
+ */
+export declare const programSecrets: (rpc: SecretsRpc, lease: ProgramLease) => Effect.Effect<Option.Option<never> | Option.Option<{
+    readonly [x: string]: string;
+}>, Error | import("effect/rpc/RpcClientError").RpcClientError | import("../../../live/src/rpc/runner-group").RunnerRpcError, never>;
+/** Kitman's API host and the Loop's declared hosts, comma-separated, as the Runner passes them; unset for `open`. */
+export declare const programHostsEnv = "KITMAN_PROGRAM_HOSTS";
+/** `fail` where the Runner sandboxes the program, `warn` where it runs on its owner's host. */
+export declare const undeclaredHostsEnv = "KITMAN_UNDECLARED_HOSTS";
+type Fetch = (resource: string | URL | Request, init?: RequestInit) => Promise<Response>;
+/**
+ * `fetch` limited to `hosts`, redirect hops included. An undeclared host is refused, and fails the Run with its name
+ * whatever the program then reports; under `warn` it is let through, with one warning per host.
+ */
+export declare const networkGuard: (input: {
+    readonly hosts: readonly string[];
+    readonly undeclared: 'fail' | 'warn';
+    readonly fetch: Fetch;
+    readonly warn: (line: string) => void;
+}) => {
+    fetch: Fetch;
+    journal: <Journal extends Pick<ProgramJournal, 'suspend' | 'finish'>>(journal: Journal) => Journal;
+};
+/** The entry of every Package bundle. */
+export declare const runPackage: (config: PackageConfig) => void;
+export {};

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

@@ -0,0 +1,2 @@
+export * from './engine';
+export * from './host';

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.