@kitman-sh/sdk 0.7.2 → 0.7.3

package/types/packages/core/src/run-journal.d.ts

@@ -0,0 +1,28 @@
+import * as Effect from 'effect/Effect';
+import * as Exit from 'effect/Exit';
+import * as Schema from 'effect/Schema';
+/** The largest encoded journal entry Kitman stores; larger content belongs in a Run artifact. */
+export declare const journalEntryMaxBytes: number;
+export declare const encodeJournalExit: (exit: Exit.Exit<unknown, unknown>) => Effect.Effect<Schema.Json, Schema.SchemaError, never>;
+export declare const decodeJournalExit: (input: unknown, options?: import("effect/SchemaAST").ParseOptions) => Effect.Effect<Exit.Exit<Schema.Json, Schema.Json>, Schema.SchemaError, never>;
+/** How a deferred resolved by Kitman (an answer, a fired clock) is written to the journal. */
+export declare const journalSuccess: (value: Schema.Json) => Schema.Json;
+/** The SDK's Step failure as the journal holds it, for a Step Kitman fails on a program's behalf. */
+export declare const JournalStepFailed: Schema.TaggedStruct<"StepFailed", {
+    readonly step: Schema.String;
+    readonly reason: Schema.String;
+}>;
+/** The SDK's Child Run failure as the journal holds it. */
+export declare const JournalChildFailed: Schema.TaggedStruct<"ChildFailed", {
+    readonly step: Schema.String;
+    readonly loop: Schema.String;
+    readonly reason: Schema.String;
+}>;
+/** The SDK's `waitFor` timeout as the journal holds it. */
+export declare const JournalWaitTimedOut: Schema.TaggedStruct<"WaitTimedOut", {
+    readonly step: Schema.String;
+    readonly event: Schema.String;
+}>;
+/** A deferred Kitman fails, with the deferred's error already encoded as JSON. */
+export declare const journalFailure: (error: Schema.Json) => Schema.Json;
+export declare const journalEntryBytes: (entry: Schema.Json) => number;

package/types/packages/core/src/run-launch.d.ts

@@ -0,0 +1,67 @@
+import type { JsonObject } from './runtime-type';
+export type LaunchOutcome = 'feature' | 'bug' | 'refactor' | 'investigation' | 'docs' | 'migration';
+/** Where and how a developer launched: their checkout, and the words they typed. */
+export type LaunchContext = {
+    /** The Project the request names; it wins over the repository's. */
+    readonly projectId?: string;
+    readonly remoteUrl?: string;
+    /** A repository chosen outright, as the web's New run form does. */
+    readonly repoBindingId?: string;
+    readonly branch?: string;
+    readonly words?: string;
+};
+/** What the control plane knows that a launch may point at. */
+export type LaunchCandidates = {
+    readonly repositories: readonly {
+        readonly repoBindingId: string;
+        readonly projectId: string;
+        readonly repositoryUrl: string;
+    }[];
+    /** Open ChangeRequests in those repositories. */
+    readonly changeRequests: readonly {
+        readonly id: string;
+        readonly repoBindingId: string;
+        readonly number?: number;
+        readonly sourceBranch?: string;
+    }[];
+};
+export type LaunchTask = {
+    readonly kind: 'tracker';
+    readonly key: string;
+} | {
+    readonly kind: 'words';
+    readonly words: string;
+};
+export type InferredLaunch = {
+    readonly projectId?: string;
+    readonly repoBindingId?: string;
+    readonly branch?: string;
+    readonly changeRequestId?: string;
+    readonly trackerKeys: readonly string[];
+    readonly task?: LaunchTask;
+    readonly outcome?: LaunchOutcome;
+    /** Loop Input fields; `taskId` is left to whoever makes the Task. */
+    readonly input: JsonObject;
+    /** Required Loop Input fields nothing filled. */
+    readonly missing: readonly string[];
+};
+/** host/owner/name of a git remote, so SSH and HTTPS remotes of one repository match. */
+export declare const repositoryKey: (url: string) => string;
+/** A Loop Input JSON Schema's top-level fields, behind a `$ref` if it has one. */
+export declare const launchInputSchema: (schema: JsonObject) => {
+    properties: JsonObject;
+    required: any[];
+};
+/**
+ * What a launch means: the Project, repository, branch, open ChangeRequest, Task and Outcome its context points at,
+ * and the Loop Input they fill. The words fill a `words` field, or else the one required text field left.
+ */
+export declare const inferLaunch: (launch: {
+    readonly context: LaunchContext;
+    readonly loop: {
+        readonly input: JsonObject;
+        readonly outcome?: LaunchOutcome;
+    };
+    readonly candidates: LaunchCandidates;
+    readonly given?: JsonObject;
+}) => InferredLaunch;

package/types/packages/core/src/runner-eligibility.d.ts

@@ -0,0 +1,43 @@
+import { type Runner, type RunnerCapabilities } from './runner';
+import type { RunnerExecutionRouting } from './runner-routing';
+export declare const RunnerEligibilityReasonCodes: readonly ['workspace_mismatch', 'project_access_denied', 'personal_owner_attribution_required', 'personal_owner_project_access_denied', 'agent_identity_authority_missing', 'foreground_target_required', 'foreground_target_mismatch', 'foreground_target_not_personal', 'runner_requirements_mismatch', 'runner_replica_unavailable'];
+export type RunnerEligibilityReasonCode = (typeof RunnerEligibilityReasonCodes)[number];
+export type RunnerSchedulingAuthority = {
+    readonly kind: 'direct_human';
+    readonly userId: string;
+} | {
+    readonly kind: 'durable_delegation';
+    readonly ownerUserId: string;
+    readonly delegationId: string;
+} | {
+    readonly kind: 'agent';
+    readonly agentIdentityId: string;
+} | {
+    readonly kind: 'system';
+};
+export interface RunnerEligibilityInput {
+    readonly runner: Runner;
+    readonly workspaceId: string;
+    readonly projectId: string;
+    readonly schedulingAuthority: RunnerSchedulingAuthority;
+    readonly routing?: RunnerExecutionRouting;
+    readonly ownerHasProjectAccess: boolean;
+    readonly agentIdentityAuthorized: boolean;
+    readonly requirementsMatch: boolean;
+    readonly replicaReady: boolean;
+}
+export interface RunnerEligibilityResult {
+    readonly eligible: boolean;
+    readonly reasons: readonly RunnerEligibilityReasonCode[];
+}
+/**
+ * The only scope/authority predicate used by runner admission callers.
+ * Inputs such as labels, claimed Project IDs, or runner metadata are
+ * deliberately absent; callers must resolve them from trusted control-plane
+ * state before invoking this function.
+ */
+export declare function evaluateRunnerEligibility(input: RunnerEligibilityInput): RunnerEligibilityResult;
+/** The owner's choice while the Runner offers it, else the first offered of Pi, Claude Code and Codex. */
+export declare function runnerDefaultHarness(harnesses: readonly string[], chosen: string | undefined): string | undefined;
+/** The Harness this Runner would launch an Agent on, or undefined when the Agent's Step is not this Runner's. */
+export declare function agentStepHarness(capabilities: Pick<RunnerCapabilities, 'harnesses' | 'defaultHarness'>, agentHarness: string | undefined): string | undefined;

package/types/packages/core/src/runner-routing.d.ts

@@ -0,0 +1,11 @@
+import * as Schema from 'effect/Schema';
+export declare const RunnerExecutionRouting: Schema.Union<readonly [Schema.Struct<{
+    readonly mode: Schema.Literal<"background">;
+    readonly requestedByUserId: Schema.optionalKey<Schema.String>;
+}>, Schema.Struct<{
+    readonly mode: Schema.Literal<"foreground">;
+    readonly requestedByUserId: Schema.String;
+    readonly targetPersonalRunnerId: Schema.String;
+    readonly interaction: Schema.Literal<"observable">;
+}>]>;
+export type RunnerExecutionRouting = (typeof RunnerExecutionRouting)['Type'];

package/types/packages/core/src/runner-trust.d.ts

@@ -0,0 +1,67 @@
+export declare const RunnerArchitecture: readonly ['amd64', 'arm64'];
+export type RunnerArchitecture = (typeof RunnerArchitecture)[number];
+declare const RunnerArtifactKinds: readonly ['host_package', 'oci_image'];
+type RunnerArtifactKind = (typeof RunnerArtifactKinds)[number];
+declare const RunnerArtifactTrustErrorCodes: readonly ['artifact_signature_invalid', 'artifact_sbom_invalid', 'artifact_provenance_invalid', 'artifact_expired', 'artifact_signed_in_future', 'artifact_architecture_mismatch', 'artifact_digest_not_allowed', 'artifact_profile_mismatch', 'artifact_sbom_mismatch', 'artifact_provenance_mismatch', 'artifact_metadata_rollback', 'artifact_metadata_expired', 'artifact_subject_mismatch', 'artifact_index_invalid'];
+type RunnerArtifactTrustErrorCode = (typeof RunnerArtifactTrustErrorCodes)[number];
+declare const RunnerArtifactTrustError_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]; }>) => import("effect/Cause").YieldableError & {
+    readonly _tag: "RunnerArtifactTrustError";
+} & Readonly<A>;
+export declare class RunnerArtifactTrustError extends RunnerArtifactTrustError_base<{
+    readonly code: RunnerArtifactTrustErrorCode;
+    readonly message: string;
+}> {
+    constructor(code: RunnerArtifactTrustErrorCode);
+}
+export type RunnerArtifactManifest = {
+    readonly contractVersion: 'runner-trust-distribution.v1';
+    readonly artifactId: string;
+    readonly kind: RunnerArtifactKind;
+    readonly version: string;
+    readonly channel: string;
+    readonly architecture: RunnerArchitecture;
+    readonly platform: 'linux';
+    readonly subjectDigest: string;
+    readonly subjectLength: number;
+    readonly profileDigest: string;
+    readonly certificationDigest: string;
+    readonly sbomDigest: string;
+    readonly provenanceDigest: string;
+    readonly metadataVersion: number;
+    readonly rollbackFloor: number;
+    readonly signedAt: string;
+    readonly expiresAt: string;
+};
+type RunnerArtifactManifestInput = Omit<RunnerArtifactManifest, 'contractVersion' | 'kind' | 'platform' | 'signedAt' | 'expiresAt'> & {
+    readonly kind?: RunnerArtifactKind;
+    readonly platform?: 'linux';
+    readonly signedAt: Date | string;
+    readonly expiresAt: Date | string;
+};
+type RunnerArtifactVerificationResult = {
+    readonly ok: boolean;
+    readonly reasons: readonly RunnerArtifactTrustErrorCode[];
+};
+type RunnerOciManifest = {
+    readonly digest: string;
+    readonly size: number;
+    readonly platform: {
+        readonly os: 'linux';
+        readonly architecture: RunnerArchitecture;
+    };
+    readonly artifactDigest: string;
+};
+export type RunnerOciIndex = {
+    readonly schemaVersion: 2;
+    readonly mediaType: 'application/vnd.oci.image.index.v1+json';
+    readonly indexDigest: string;
+    readonly manifests: readonly RunnerOciManifest[];
+};
+export declare function createRunnerArtifactManifest(input: RunnerArtifactManifestInput): RunnerArtifactManifest;
+export declare function verifyRunnerOciIndex(index: RunnerOciIndex): RunnerArtifactVerificationResult;
+export declare function createRunnerOciIndex(artifacts: readonly RunnerArtifactManifest[], options?: {
+    readonly digest?: string;
+}): RunnerOciIndex;
+export declare function runnerCanonicalJson<ValueType>(value: ValueType): string;
+export declare function sha256(value: string): string;
+export {};