@kitman-sh/sdk 0.9.0 → 0.10.52

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

@@ -1,6 +1,7 @@
-import type { KitAssignmentDeclaration, KitInstallationDeclaration, ScheduleDeclaration } from '../../../core/src/package-declarations';
+import type { ScheduleDeclaration } from '../../../core/src/kit-declarations';
+import type { KitSetup } from '../../../core/src/kit-setup';
 import type { LoopDefinition } from './define';
-/** Agent instructions inline, or a Markdown file in the Package's repository, read at build. */
+/** Agent instructions inline, or a Markdown file in the Kit's repository, read at build. */
 export type AgentInstructions = string | {
     readonly file: string;
 };
@@ -12,8 +13,19 @@ export type AgentConfig = {
     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[];
+    /**
+     * Harnesses to launch on, in order, when a Runner does not offer this one. A fallback with no effort uses this
+     * Agent's; one with no model uses the Harness's own, not this Agent's.
+     */
+    readonly fallbacks?: readonly {
+        readonly harness: string;
+        readonly model?: string;
+        readonly effort?: 'low' | 'medium' | 'high' | 'xhigh';
+    }[];
+    /** Tools its Steps get beyond the base ones; a list replaces an inherited one and `[]` clears it. */
+    readonly tools?: readonly ('web' | 'subagents' | 'artifacts' | 'browser')[];
+    /** The skills its Steps list; the Run's other Kit skills are loaded by name. A list replaces, `[]` clears. */
+    readonly skills?: readonly string[];
     /** Hosts its sandboxed Steps may reach beyond the defaults, or `open` for an Agent that browses. */
     readonly network?: {
         readonly hosts: readonly string[];
@@ -21,48 +33,43 @@ export type AgentConfig = {
     /** Runs its Steps only on Runners that run agents in docker, for services or a team 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[];
+/**
+ * What the Kit's agents get. Each skill and plugin comes from a local path in the Kit, a git repository or an npm
+ * package, and `instructions` is a Markdown file in the Kit; the build copies them all in.
+ */
+export type KitSetupConfig = KitSetup;
+export type KitLoop = LoopDefinition<unknown, unknown, unknown>;
+/** A Kit's `kitman.config.ts` default export. */
+export type KitConfig = {
+    readonly loops: readonly KitLoop[];
     readonly agents?: {
         readonly [id: string]: AgentConfig;
     };
     readonly schedules?: {
         readonly [key: string]: ScheduleDeclaration;
     };
-    readonly kits?: {
-        readonly [key: string]: KitConfig;
-    };
+    readonly setup?: KitSetupConfig;
+    readonly extends?: readonly 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>;
+/** Declares a Kit: its Loops, its Agents keyed by id, the setup its agents get, and the Kits it extends. */
+export declare const defineKit: <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. */
+    /** Recurring starts of a Loop, keyed; only the Kit a repository deploys may declare them. */
     readonly schedules?: {
         readonly [key: string]: ScheduleDeclaration;
     };
-    /** Kits, keyed; only a Workspace Package may declare them. */
-    readonly kits?: {
-        readonly [key: string]: KitConfig;
-    };
-}) => PackageConfig;
+    readonly setup?: KitSetupConfig;
+    /**
+     * Imported Kits this one builds in, like Nuxt layers: this Kit's entries replace theirs by name, and an earlier
+     * entry's replace a later one's.
+     */
+    readonly extends?: readonly KitConfig[];
+}) => KitConfig;
 export {};

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

@@ -0,0 +1,22 @@
+import * as Schema from 'effect/Schema';
+/**
+ * What an earlier Run left on a Task: its open ChangeRequest and branch, which a new write Run on the Task continues.
+ * Kitman adds it to the Input of a Loop that declares `continuing: Schema.optional(Continuing)`.
+ */
+export declare const Continuing: Schema.Struct<{
+    readonly changeRequestId: Schema.String;
+    /** The forge's number for the ChangeRequest. */
+    readonly number: Schema.String;
+    readonly url: Schema.String;
+    readonly branch: Schema.String;
+    /** The branch the ChangeRequest merges into. */
+    readonly targetBranch: Schema.String;
+    /** The branch head the earlier Run last pushed; the forge's may be newer if someone pushed since. */
+    readonly revision: Schema.optional<Schema.String>;
+    readonly lastRunId: Schema.optional<Schema.String>;
+    readonly lastRunStatus: Schema.optional<Schema.String>;
+    readonly lastRunSummary: Schema.optional<Schema.String>;
+}>;
+export type Continuing = typeof Continuing.Type;
+/** Tells an agent what is already on the branch it starts from, and where to find what was left unsettled. */
+export declare const continuingBrief: (continuing: Continuing) => string;

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

@@ -1,15 +1,15 @@
-import { LoopCapabilities, type LoopManifest } from '../../../core/src/package-declarations';
+import { LoopCapabilities, type LoopManifest } from '../../../core/src/kit-declarations';
 import type { ScheduleRule } from '../../../core/src/schedule';
 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, FileActivity, IntegrationBranchActivity, MergeChangeRequestActivity, NoteActivity, ProjectActivityActivity, DraftUpdateActivity, ProposeActivity, ReleaseActivity, TranscriptsActivity, WriteBackActivity } from './activities';
+import type { ArtifactActivity, ChangeRequestActivity, CommentActivity, AlertTaskActivity, CreateTasksActivity, FileActivity, IntegrationBranchActivity, MergeChangeRequestActivity, NoteActivity, ProjectActivityActivity, DraftUpdateActivity, ProposeActivity, ReleaseActivity, TranscriptsActivity, ChangeRequestReadActivity, 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 declare const LoopOutcome: Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration", "performance"]>;
 export type LoopOutcome = typeof LoopOutcome.Type;
 export type LoopCheckout = 'none' | 'read' | 'write';
 type EventFilterValue = string | number | boolean | null;
@@ -17,27 +17,40 @@ type EventFilterValue = string | number | boolean | null;
 export type EventFilter = {
     readonly [path: string]: EventFilterValue | readonly EventFilterValue[];
 };
-/** Starts a Run on a matching Event, binding Event payload paths into the Loop Input. */
+/**
+ * Starts a Run on a matching Event, binding Event payload paths into the Loop Input. `values` are Input fields every
+ * such Run gets, so the Kit that declares the Loop for a Team sets them for that Team.
+ */
 export type WhenClause = {
     readonly event: string;
     readonly filter?: EventFilter;
     readonly input: {
         readonly [inputField: string]: string;
     };
+    readonly values?: {
+        readonly [inputField: string]: Schema.Json;
+    };
 };
 /** An action shown on a settled Run: start another Loop. */
+/**
+ * A Loop the settled Run offers to start, with the Run's Input fields it declares. With `from`, the offer is built from
+ * the Output: it shows only when the Output has that field, an object whose fields are given to the offered Loop too.
+ */
 export type LoopOffer = {
     readonly id: string;
     readonly title: string;
     readonly loop: string;
+    readonly from?: string;
 };
 /** The services a Loop's program runs with; a Runner or `testLoop` provides them. */
-export type LoopServices = LoopRun | LoopHost | ChangeRequestActivity | WriteBackActivity | ArtifactActivity | FileActivity | NoteActivity | CommentActivity | CreateTasksActivity | IntegrationBranchActivity | MergeChangeRequestActivity | ReleaseActivity | TranscriptsActivity | ProposeActivity | ProjectActivityActivity | DraftUpdateActivity | WorkflowEngine.WorkflowEngine | WorkflowEngine.WorkflowInstance;
+export type LoopServices = LoopRun | LoopHost | ChangeRequestActivity | WriteBackActivity | ArtifactActivity | FileActivity | NoteActivity | CommentActivity | CreateTasksActivity | AlertTaskActivity | IntegrationBranchActivity | MergeChangeRequestActivity | ReleaseActivity | TranscriptsActivity | ChangeRequestReadActivity | ProposeActivity | ProjectActivityActivity | DraftUpdateActivity | 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;
+    /** Semver, shown under the title: bump major for a changed input, output or behaviour people rely on. */
+    readonly version?: string;
     readonly input: LoopSchema<In>;
     readonly output: LoopSchema<Out>;
     readonly outcome?: LoopOutcome;
@@ -49,6 +62,11 @@ export type LoopDefinition<In, Out, E> = {
     readonly when?: readonly WhenClause[];
     readonly offers?: readonly LoopOffer[];
     readonly capabilities: readonly LoopCapability[];
+    /**
+     * The Loops it runs as Child Runs with `call`. A Child Run is granted no more than its parent, so the manifest
+     * declares their capabilities, and `call`, besides the Loop's own.
+     */
+    readonly calls?: () => readonly CalledLoop[];
     /** The Secrets the program reads with `Config.Redacted`, and `agentWork` may put into a Step's sandbox. */
     readonly secrets?: readonly string[];
     /**
@@ -67,6 +85,13 @@ export type LoopDefinition<In, Out, E> = {
     /** Scripts a build runs twice, the second time from the journal; not part of the manifest. */
     readonly checks?: readonly LoopCheck[];
 };
+/** What a parent needs of a Loop it calls. A function, so Loops that call each other can name each other. */
+export type CalledLoop = {
+    readonly capabilities: readonly LoopCapability[];
+    readonly calls?: () => readonly CalledLoop[];
+};
+/** A Loop's own capabilities, and those of every Loop it calls, however deep. */
+export declare const capabilitiesOf: (loop: CalledLoop) => readonly LoopCapability[];
 /** 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", {

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

@@ -1,31 +1,42 @@
 import * as Schema from 'effect/Schema';
 import type { LoopOutcome } from './define';
+import type { Measurement } from './measure';
 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. */
+    /** It also fails on the head of the baseline, so the Run did not cause it. */
     readonly preExisting: Schema.Boolean;
     readonly durationMs: Schema.Finite;
     readonly evidenceId: Schema.String;
+    /** The end of what a failed check printed. */
+    readonly outputTail: Schema.optionalKey<Schema.String>;
+    /** An agent suggested it because the repository has none approved; a person should check it. */
+    readonly suggested: Schema.optionalKey<Schema.Boolean>;
 }>;
 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. */
+    /** Every check passed or already failed on the baseline. */
     readonly passed: Schema.Boolean;
+    /** The tree is the baseline's, so no baseline ran: a failure here is the baseline's, though not `preExisting`. */
+    readonly unchanged: Schema.optionalKey<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. */
+        /** It also fails on the head of the baseline, so the Run did not cause it. */
         readonly preExisting: Schema.Boolean;
         readonly durationMs: Schema.Finite;
         readonly evidenceId: Schema.String;
+        /** The end of what a failed check printed. */
+        readonly outputTail: Schema.optionalKey<Schema.String>;
+        /** An agent suggested it because the repository has none approved; a person should check it. */
+        readonly suggested: Schema.optionalKey<Schema.Boolean>;
     }>>;
 }>;
 export type VerifyResult = typeof VerifyResult.Type;
@@ -37,6 +48,7 @@ export declare const OutcomeTable: {
     readonly investigation: 'A conclusion Output with its sources; no patch needed';
     readonly docs: 'The documented commands run';
     readonly migration: 'A rollback check passes';
+    readonly performance: 'A kept final measurement against the merge base shows a gain, and approved verifications pass on the head';
     readonly none: 'Only the approved verifications';
 };
 export type EvidenceGateInput = {
@@ -55,6 +67,8 @@ export type EvidenceGateInput = {
     readonly documented?: readonly string[];
     /** The check that rolls a migration back. */
     readonly rollback?: string;
+    /** The final measurement of the head against its merge base, which the Run kept. */
+    readonly measurement?: Measurement;
 };
 export type EvidenceVerdict = {
     readonly settled: true;
@@ -62,5 +76,6 @@ export type EvidenceVerdict = {
     readonly settled: false;
     readonly reasons: readonly string[];
 };
+export declare const failsOn: (side: 'base' | 'head', name: string, tree: string | undefined) => 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

@@ -7,3 +7,7 @@ export * from './review';
 export * from './plan';
 export * from './check';
 export * from './config';
+export * from './sync';
+export * from './continuing';
+export * from './measure';
+export * from './claims';

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

@@ -0,0 +1,132 @@
+import { MeasureEvidence, MeasurePlan } from '../../../core/src/work-unit';
+import * as Effect from 'effect/Effect';
+import * as Schema from 'effect/Schema';
+import { DurableDeferred } from 'effect/workflow';
+import { LoopRun, StepFailed } from './steps';
+export { MeasurePlan };
+export declare const MetricStats: Schema.Struct<{
+    readonly samples: Schema.Finite;
+    readonly median: Schema.Finite;
+    readonly mean: Schema.Finite;
+    readonly min: Schema.Finite;
+    readonly max: Schema.Finite;
+    readonly stdev: Schema.Finite;
+}>;
+export type MetricStats = typeof MetricStats.Type;
+export declare const MeasureVerdict: Schema.Literals<readonly ["gain", "no_gain", "guardrail_regressed", "too_noisy"]>;
+export type MeasureVerdict = typeof MeasureVerdict.Type;
+/**
+ * What the host measured, and its verdict. `change` is the head's improvement over the base as a fraction of the
+ * base's median, positive when better in the metric's direction; `noise` is the base measured against itself.
+ */
+export declare const Measurement: Schema.Struct<{
+    readonly verdict: Schema.Literals<readonly ["gain", "no_gain", "guardrail_regressed", "too_noisy"]>;
+    /** Why the verdict, in a line a ChangeRequest body can carry. */
+    readonly reason: Schema.String;
+    readonly metrics: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly role: Schema.Literals<readonly ["primary", "guardrail"]>;
+        readonly direction: Schema.Literals<readonly ["lower", "higher"]>;
+        readonly base: Schema.Struct<{
+            readonly samples: Schema.Finite;
+            readonly median: Schema.Finite;
+            readonly mean: Schema.Finite;
+            readonly min: Schema.Finite;
+            readonly max: Schema.Finite;
+            readonly stdev: Schema.Finite;
+        }>;
+        readonly head: Schema.Struct<{
+            readonly samples: Schema.Finite;
+            readonly median: Schema.Finite;
+            readonly mean: Schema.Finite;
+            readonly min: Schema.Finite;
+            readonly max: Schema.Finite;
+            readonly stdev: Schema.Finite;
+        }>;
+        readonly change: Schema.Finite;
+        readonly noise: Schema.Finite;
+    }>>;
+    /** On `too_noisy`, what to judge on instead. */
+    readonly suggestion: Schema.optional<Schema.String>;
+    readonly evidence: Schema.Struct<{
+        readonly base: Schema.$Array<Schema.$Record<Schema.String, Schema.Finite>>;
+        readonly head: Schema.$Array<Schema.$Record<Schema.String, Schema.Finite>>;
+        readonly baseAgain: Schema.optionalKey<Schema.$Array<Schema.$Record<Schema.String, Schema.Finite>>>;
+    }>;
+}>;
+export type Measurement = typeof Measurement.Type;
+/** The noise floor by metric, from the Run's first measurement. */
+export type NoiseFloor = {
+    readonly [metric: string]: number;
+};
+export declare const measureDeferred: (step: string) => DurableDeferred.DurableDeferred<Schema.Struct<{
+    readonly base: Schema.$Array<Schema.$Record<Schema.String, Schema.Finite>>;
+    readonly head: Schema.$Array<Schema.$Record<Schema.String, Schema.Finite>>;
+    readonly baseAgain: Schema.optionalKey<Schema.$Array<Schema.$Record<Schema.String, Schema.Finite>>>;
+}>, typeof StepFailed>;
+/**
+ * The noise floor of each metric: how far the base strays from itself, as the larger of its spread and the gap
+ * between its two medians.
+ */
+export declare const noiseFloor: (plan: MeasurePlan, evidence: MeasureEvidence) => NoiseFloor;
+/**
+ * Judges a measurement: `too_noisy` when the primary metric's noise floor exceeds `threshold`; else
+ * `guardrail_regressed` when a guardrail got worse by more than `tolerance` beyond its noise, whatever the primary
+ * did; else `gain` when the primary improved by more than `threshold` beyond its noise; else `no_gain`.
+ */
+export declare const judgeMeasurement: (plan: MeasurePlan, evidence: MeasureEvidence, noise: NoiseFloor, limits: {
+    readonly threshold: number;
+    readonly tolerance: number;
+}) => Measurement;
+/**
+ * Benchmarks `head` (the Run's head when left out) against `base` (its base branch's head when left out) on a Runner,
+ * with no agent: `samples` of each, interleaved, after the plan's warmup. The Run's first measurement also measures
+ * the base against itself, and every verdict allows for that noise floor. `threshold` is the smallest gain that
+ * counts and `tolerance` how much worse a guardrail may get, both fractions of the base.
+ */
+export declare const measure: (name: string, request: {
+    readonly plan: MeasurePlan;
+    readonly base?: string;
+    readonly head?: string;
+    readonly samples?: number;
+    readonly threshold?: number;
+    readonly tolerance?: number;
+}) => Effect.Effect<{
+    readonly verdict: "gain" | "guardrail_regressed" | "no_gain" | "too_noisy";
+    readonly reason: string;
+    readonly metrics: readonly {
+        readonly name: string;
+        readonly role: "guardrail" | "primary";
+        readonly direction: "higher" | "lower";
+        readonly base: {
+            readonly samples: number;
+            readonly median: number;
+            readonly mean: number;
+            readonly min: number;
+            readonly max: number;
+            readonly stdev: number;
+        };
+        readonly head: {
+            readonly samples: number;
+            readonly median: number;
+            readonly mean: number;
+            readonly min: number;
+            readonly max: number;
+            readonly stdev: number;
+        };
+        readonly change: number;
+        readonly noise: number;
+    }[];
+    readonly suggestion?: string | undefined;
+    readonly evidence: {
+        readonly base: readonly {
+            readonly [x: string]: number;
+        }[];
+        readonly head: readonly {
+            readonly [x: string]: number;
+        }[];
+        readonly baseAgain?: readonly {
+            readonly [x: string]: number;
+        }[];
+    };
+}, import("./steps").CapabilityDenied | import("./steps").DuplicateStep | StepFailed, import("./steps").LoopHost | LoopRun | import("effect/workflow/WorkflowEngine").WorkflowEngine | import("effect/workflow/WorkflowEngine").WorkflowInstance>;

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

@@ -12,7 +12,7 @@ export declare const PlanTicket: Schema.Struct<{
     /** 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"]>>;
+    readonly outcome: Schema.optional<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration", "performance"]>>;
 }>;
 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. */
@@ -27,7 +27,7 @@ export declare const PlanTickets: Schema.$Array<Schema.Struct<{
     /** 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"]>>;
+    readonly outcome: Schema.optional<Schema.Literals<readonly ["feature", "bug", "refactor", "investigation", "docs", "migration", "performance"]>>;
 }>>;
 declare const BlockingCycle_base: Schema.Class<BlockingCycle, Schema.TaggedStruct<"BlockingCycle", {
     readonly tickets: Schema.$Array<Schema.String>;