@kitman-sh/loops 0.0.0-stage → 0.6.0

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/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.