@kitman-sh/sdk 0.0.0-stage → 0.7.0

package/types/packages/core/src/runtime-type.d.ts

@@ -0,0 +1,36 @@
+type RuntimeTypeName = 'bigint' | 'boolean' | 'function' | 'number' | 'object' | 'string' | 'symbol' | 'undefined';
+type JsonPrimitive = null | boolean | number | string;
+export type JsonValue = JsonPrimitive | readonly JsonValue[] | JsonObject;
+export type JsonObject = {
+    readonly [key: string]: JsonValue;
+};
+/** In-memory structured data, before normalization for a JSON boundary. */
+export type StructuredValue = JsonValue | undefined | Date | readonly StructuredValue[] | StructuredObject;
+export type StructuredObject = {
+    readonly [key: string]: StructuredValue;
+};
+/** Normalize a JavaScript value into data that serializes without information loss. */
+export declare function toJsonValue<ValueType>(value: ValueType): JsonValue;
+/** Narrow a value to one member of a readonly literal list. */
+export declare function isOneOf<const Literal extends string | number, Value>(values: readonly Literal[], value: Value): value is Value & Literal;
+/** Narrow a value to one member of a readonly literal set. */
+export declare function isMemberOf<const Literal extends string | number, Value>(values: ReadonlySet<Literal>, value: Value): value is Value & Literal;
+/** Narrow a property key to an own key of a lookup record. */
+export declare function isKeyOf<Lookup extends object>(record: Lookup, key: PropertyKey): key is keyof Lookup;
+/** Read an own data property of untrusted input as JSON; undefined when missing or not JSON. */
+export declare function jsonProperty<Value extends object>(value: Value, key: string): JsonValue | undefined;
+export declare function toJsonObject<ValueType>(value: ValueType): JsonObject;
+type RuntimeNarrow<Value, Target, Fallback = Target> = [Extract<Value, Target>] extends [never] ? Value & Fallback : Extract<Value, Target>;
+/** Runtime predicates for values entering an untyped boundary. */
+export declare function isBigInt<Value>(value: Value): value is RuntimeNarrow<Value, bigint>;
+export declare function isBoolean<Value>(value: Value): value is RuntimeNarrow<Value, boolean>;
+export declare function isFunction<Value>(value: Value): value is RuntimeNarrow<Value, globalThis.Function>;
+export declare function isNumber<Value>(value: Value): value is RuntimeNarrow<Value, number>;
+export declare function isObject<Value>(value: Value): value is Value & object;
+export declare function isJsonObject(value: JsonValue | undefined): value is JsonObject;
+export declare function isString<Value>(value: Value): value is RuntimeNarrow<Value, string>;
+export declare function isSymbol<Value>(value: Value): value is RuntimeNarrow<Value, symbol>;
+export declare function isUndefined<Value>(value: Value): value is RuntimeNarrow<Value, undefined>;
+/** Return the ECMAScript runtime category after checking every primitive schema. */
+export declare function kindOf<Value>(value: Value): RuntimeTypeName;
+export {};

package/types/packages/core/src/schedule.d.ts

@@ -0,0 +1,136 @@
+import * as Schema from 'effect/Schema';
+import type { TriggerIngress } from './trigger-dispatch';
+import { SafeJson } from './run';
+export declare const ScheduleMisfirePolicies: readonly ['skip', 'fire_once', 'catch_up'];
+export type ScheduleMisfirePolicy = (typeof ScheduleMisfirePolicies)[number];
+export declare const ScheduleOverlapPolicies: readonly ['allow', 'skip', 'coalesce'];
+export type ScheduleOverlapPolicy = (typeof ScheduleOverlapPolicies)[number];
+export declare const ScheduleVersionStatuses: readonly ['draft', 'published', 'disabled', 'archived'];
+declare const ScheduleDispositions: readonly ['on_time', 'catch_up', 'catch_up_bounded', 'misfire_skipped', 'dst_gap_skipped', 'overlap_skipped', 'overlap_coalesced'];
+export type ScheduleDisposition = (typeof ScheduleDispositions)[number];
+export declare const ScheduleRule: Schema.Union<readonly [Schema.Struct<{
+    readonly frequency: Schema.Literals<readonly ["daily", "weekly"]>;
+    readonly hour: Schema.Int;
+    readonly minute: Schema.Int;
+    readonly second: Schema.optionalKey<Schema.Int>;
+    readonly daysOfWeek: Schema.optionalKey<Schema.$Array<Schema.Int>>;
+}>, Schema.Struct<{
+    readonly cron: Schema.String;
+}>]>;
+export type ScheduleRule = (typeof ScheduleRule)['Type'];
+/** Whether `value` is a Schedule rule: a calendar rule, or cron whose every field is in range. */
+export declare function isScheduleRule(value: unknown): value is ScheduleRule;
+export declare const ScheduleVersion: Schema.Struct<{
+    readonly contractVersion: Schema.Literal<"schedule.v1">;
+    readonly id: Schema.String;
+    readonly scheduleId: Schema.String;
+    readonly workspaceId: Schema.String;
+    readonly projectId: Schema.optionalKey<Schema.String>;
+    /** New versions bind one stable Loop; historical rows may not have a binding. */
+    readonly loopId: Schema.optionalKey<Schema.String>;
+    readonly name: Schema.optionalKey<Schema.String>;
+    readonly version: Schema.Int;
+    readonly status: Schema.Literals<readonly ["draft", "published", "disabled", "archived"]>;
+    readonly timezone: Schema.String;
+    readonly rule: Schema.Union<readonly [Schema.Struct<{
+        readonly frequency: Schema.Literals<readonly ["daily", "weekly"]>;
+        readonly hour: Schema.Int;
+        readonly minute: Schema.Int;
+        readonly second: Schema.optionalKey<Schema.Int>;
+        readonly daysOfWeek: Schema.optionalKey<Schema.$Array<Schema.Int>>;
+    }>, Schema.Struct<{
+        readonly cron: Schema.String;
+    }>]>;
+    readonly misfirePolicy: Schema.Literals<readonly ["skip", "fire_once", "catch_up"]>;
+    readonly overlapPolicy: Schema.Literals<readonly ["allow", "skip", "coalesce"]>;
+    readonly maxCatchUp: Schema.Int;
+    readonly misfireGraceSeconds: Schema.optionalKey<Schema.Int>;
+    readonly inputSchemaRef: Schema.optionalKey<Schema.Struct<{
+        readonly kind: Schema.Literal<"typebox_ref">;
+        readonly name: Schema.String;
+        readonly version: Schema.optionalKey<Schema.String>;
+        readonly sha256: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly input: Schema.optionalKey<Schema.Codec<SafeJson, SafeJson, never, never>>;
+    readonly createdAt: Schema.String;
+}>;
+export type ScheduleVersion = (typeof ScheduleVersion)['Type'];
+export interface ScheduleCursor {
+    readonly lastEvaluatedAt?: string;
+    readonly lastFireKey?: string;
+    readonly resourceVersion?: number;
+}
+export declare function scheduleDefinitionDigest(version: Pick<ScheduleVersion, 'timezone' | 'rule' | 'misfirePolicy' | 'overlapPolicy' | 'maxCatchUp' | 'misfireGraceSeconds' | 'loopId'> & Partial<Pick<ScheduleVersion, 'status' | 'inputSchemaRef' | 'input' | 'name'>>): string;
+interface FireIdentityInput {
+    readonly scheduleId: string;
+    readonly scheduleVersion: number;
+    readonly bindingId: string;
+    readonly localDate: string;
+    readonly localTime: string;
+    readonly fold: 0 | 1;
+}
+export declare function fireIdentity(input: FireIdentityInput): string;
+type ResolvedLocalDateTime = {
+    readonly kind: 'gap';
+    readonly instants: readonly [];
+} | {
+    readonly kind: 'unique';
+    readonly instants: readonly [Date];
+} | {
+    readonly kind: 'fold';
+    readonly instants: readonly [Date, Date];
+};
+/**
+ * Resolve a wall-clock time without silently normalizing gaps or folds. Each Schedule Host tick re-enumerates the days
+ * around now for every Schedule, and each resolution costs several Intl calls, so resolutions are kept.
+ */
+export declare function resolveLocalDateTime(timezone: string, date: string, time: string): ResolvedLocalDateTime;
+export interface ScheduleCandidate {
+    readonly fireKey: string;
+    readonly scheduleId: string;
+    readonly scheduleVersion: number;
+    readonly bindingId: string;
+    readonly timezone: string;
+    readonly localDate: string;
+    readonly localTime: string;
+    readonly fold: 0 | 1;
+    readonly scheduledAt?: string;
+    readonly resolution: 'unique' | 'fold' | 'gap';
+}
+/**
+ * Create one explicit test occurrence without advancing or colliding with the
+ * Schedule's normal calendar binding. Repeating a request with the same key
+ * produces the same durable Event identity.
+ */
+export declare function scheduleTestCandidate(input: {
+    readonly version: ScheduleVersion;
+    readonly idempotencyKey: string;
+    readonly requestedAt: string;
+}): ScheduleCandidate;
+/** Enumerate deterministic local-time candidates. Fold candidates are deliberately separate fires. */
+export declare function enumerateScheduleCandidates(input: {
+    readonly version: ScheduleVersion;
+    readonly bindingId: string;
+    readonly from: string;
+    readonly to: string;
+}): readonly ScheduleCandidate[];
+export interface ScheduleDecision extends ScheduleCandidate {
+    readonly disposition: ScheduleDisposition;
+    readonly shouldIngress: boolean;
+}
+export declare function planSchedule(input: {
+    readonly version: ScheduleVersion;
+    readonly candidates: readonly ScheduleCandidate[];
+    readonly now: string;
+    readonly cursor: ScheduleCursor;
+    readonly activeBindingRuns?: ReadonlySet<string>;
+}): readonly ScheduleDecision[];
+export declare function scheduleTriggerIngress(input: {
+    readonly version: ScheduleVersion;
+    readonly candidate: ScheduleCandidate;
+    readonly loopId: string;
+    readonly projectId?: string;
+    readonly receivedAt: string;
+    readonly misfireDisposition?: 'on_time' | 'catch_up' | 'coalesced';
+}): TriggerIngress;
+export {};

package/types/packages/core/src/schema.d.ts

@@ -0,0 +1,89 @@
+import * as JsonSchema from 'effect/JsonSchema';
+import * as Schema from 'effect/Schema';
+import type { StandardSchemaV1 } from 'effect/StandardSchema';
+import { type JsonObject, type JsonValue } from './runtime-type';
+/** An RFC 3339 date-time string with a zone, as JSON Schema's `date-time` format requires. */
+export declare const isDateTime: import("effect/SchemaAST").Filter<string>;
+/** A number, or a numeric string read as one, as a query or a JSON body may carry it. */
+export declare const Numeric: Schema.Union<readonly [Schema.Finite, Schema.FiniteFromString]>;
+/**
+ * A whole `Numeric`. Its JSON Schema is `multipleOf: 1`, which holds for the string a query carries where `isInt`'s
+ * `type: integer` would not.
+ */
+export declare const isWholeNumber: import("effect/SchemaAST").Filter<number>;
+/**
+ * A type guard that holds only when `input` already is a `schema` value, without properties the schema does not model,
+ * as a TypeBox `Check` of a closed object did: no transformation or decoding default applies.
+ */
+export declare function guard<S extends Schema.ConstraintDecoder<unknown>>(schema: S): <I>(input: I) => input is I & S['Type'];
+/** `Schema.toStandardSchemaV1(schema)`, with a passing value decoded synchronously first. */
+export declare function standardSchemaV1<S extends Schema.ConstraintDecoder<unknown>>(schema: S): StandardSchemaV1<S["Encoded"], S["Type"]> & S & {
+    '~standard': {
+        version: 1;
+        vendor: string;
+        types?: import("effect/StandardSchema").StandardTypedV1.Types<S["Encoded"], S["Type"]> | undefined;
+        validate: <Value>(value: Value) => Promise<StandardSchemaV1.Result<S["Type"]>> | StandardSchemaV1.Result<S["Type"]>;
+    };
+};
+/** The JSON Schema (draft 2020-12) of `schema`, with objects closed to the properties they model. */
+export declare function jsonSchema(schema: Schema.Top): JsonSchema.JsonSchema;
+/**
+ * `value` with every `$defs` entry inside it moved out to `definitions`, and its `#/$defs/` refs pointed at `prefix`. A
+ * ref resolves against the whole document, so once a schema that carries its own `$defs` is embedded in a larger one,
+ * such as an OpenAPI operation, its refs hold only after the entries sit where `prefix` names. Each schema names its
+ * entries on its own, so an entry that would replace a different one under the same name, `known` ones included, moves
+ * under a new name.
+ */
+export declare function hoistDefinitions(value: JsonValue, prefix: string, known?: JsonObject): {
+    value: JsonValue;
+    definitions: {
+        [k: string]: JsonValue;
+    };
+};
+/**
+ * `schema` as a Standard Schema validator with its JSON Schema, for Elysia routes and their OpenAPI. Validation strips
+ * properties the schema does not model; the JSON Schema closes objects, as the TypeBox contracts did. An invalid value
+ * answers `status`, 400 as TypeBox routes did, with `refused` in place of the message, which otherwise quotes the
+ * value. The validator is a copy, so the shared schema stays as it is.
+ */
+export declare function standard<S extends Schema.Top & Schema.ConstraintDecoder<unknown>>(schema: S, options?: {
+    readonly refused?: string;
+    readonly status?: number;
+}): StandardSchemaV1<S["Encoded"], S["Type"]> & S & {
+    invalidStatus: number;
+    refused?: string;
+    '~standard': {
+        version: 1;
+        vendor: string;
+        types?: import("effect/StandardSchema").StandardTypedV1.Types<S["Encoded"], S["Type"]> | undefined;
+        validate: <Value>(value: Value) => Promise<StandardSchemaV1.Result<S["Type"]>> | StandardSchemaV1.Result<S["Type"]>;
+        jsonSchema: {
+            input: (target: {
+                readonly target: string;
+            }) => JsonSchema.JsonSchema;
+            output: (target: {
+                readonly target: string;
+            }) => JsonSchema.JsonSchema;
+        };
+    };
+};
+/**
+ * `schema` as an Elysia response validator: the handler's value encodes to what the wire carries, without properties
+ * the schema does not model, and the JSON Schema on both sides is that encoded form.
+ */
+export declare function standardResponse<S extends Schema.Top & Schema.ConstraintEncoder<unknown>>(schema: S): StandardSchemaV1<(S extends Schema.flip<infer F extends Schema.Top> ? F["Rebuild"] : Schema.flip<S>)["Encoded"], (S extends Schema.flip<infer F extends Schema.Top> ? F["Rebuild"] : Schema.flip<S>)["Type"]> & (S extends Schema.flip<infer F extends Schema.Top> ? F["Rebuild"] : Schema.flip<S>) & {
+    '~standard': {
+        version: 1;
+        vendor: string;
+        types?: import("effect/StandardSchema").StandardTypedV1.Types<(S extends Schema.flip<infer F extends Schema.Top> ? F["Rebuild"] : Schema.flip<S>)["Encoded"], (S extends Schema.flip<infer F extends Schema.Top> ? F["Rebuild"] : Schema.flip<S>)["Type"]> | undefined;
+        validate: <Value>(value: Value) => Promise<StandardSchemaV1.Result<(S extends Schema.flip<infer F extends Schema.Top> ? F["Rebuild"] : Schema.flip<S>)["Type"]>> | StandardSchemaV1.Result<(S extends Schema.flip<infer F extends Schema.Top> ? F["Rebuild"] : Schema.flip<S>)["Type"]>;
+        jsonSchema: {
+            input: (options: {
+                readonly target: string;
+            }) => JsonSchema.JsonSchema;
+            output: (options: {
+                readonly target: string;
+            }) => JsonSchema.JsonSchema;
+        };
+    };
+};

package/types/packages/core/src/scope-directory.d.ts

@@ -0,0 +1,100 @@
+import * as Schema from 'effect/Schema';
+export declare const ScopeDirectoryPageSize = 50;
+export declare const ScopeDirectoryPageSizeMaximum = 100;
+export declare const ScopeDirectoryIncludedMaximum = 8;
+export declare const ScopeDirectoryIdMaximum = 128;
+export declare const ScopeDirectoryCursorMaximum = 512;
+export declare const ScopeDirectoryId: Schema.String;
+export declare const WorkspaceSelectorItem: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly name: Schema.String;
+}>;
+export declare const ProjectSelectorItem: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly workspaceId: Schema.String;
+    readonly name: Schema.String;
+}>;
+export declare const ScopeDirectoryPageInfo: Schema.Union<readonly [Schema.Struct<{
+    readonly hasNextPage: Schema.Literal<false>;
+}>, Schema.Struct<{
+    readonly hasNextPage: Schema.Literal<true>;
+    readonly endCursor: Schema.String;
+}>]>;
+export declare const WorkspaceSelectorPage: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly name: Schema.String;
+    }>>;
+    readonly included: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly name: Schema.String;
+    }>>;
+    readonly pageInfo: Schema.Union<readonly [Schema.Struct<{
+        readonly hasNextPage: Schema.Literal<false>;
+    }>, Schema.Struct<{
+        readonly hasNextPage: Schema.Literal<true>;
+        readonly endCursor: Schema.String;
+    }>]>;
+}>;
+export declare const ProjectSelectorPage: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly workspaceId: Schema.String;
+        readonly name: Schema.String;
+    }>>;
+    readonly included: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly workspaceId: Schema.String;
+        readonly name: Schema.String;
+    }>>;
+    readonly pageInfo: Schema.Union<readonly [Schema.Struct<{
+        readonly hasNextPage: Schema.Literal<false>;
+    }>, Schema.Struct<{
+        readonly hasNextPage: Schema.Literal<true>;
+        readonly endCursor: Schema.String;
+    }>]>;
+}>;
+export declare const ScopeDirectoryPageQuery: Schema.Struct<{
+    readonly limit: Schema.optionalKey<Schema.Union<readonly [Schema.Finite, Schema.FiniteFromString]>>;
+    readonly cursor: Schema.optionalKey<Schema.String>;
+    readonly includeIds: Schema.optionalKey<Schema.String>;
+}>;
+export declare const parseWorkspaceSelectorPage: <ValueType>(value: ValueType) => {
+    readonly items: readonly {
+        readonly id: string;
+        readonly name: string;
+    }[];
+    readonly included: readonly {
+        readonly id: string;
+        readonly name: string;
+    }[];
+    readonly pageInfo: {
+        readonly hasNextPage: false;
+    } | {
+        readonly hasNextPage: true;
+        readonly endCursor: string;
+    };
+};
+export declare const parseProjectSelectorPage: <ValueType>(value: ValueType, workspaceId: string) => {
+    readonly items: readonly {
+        readonly id: string;
+        readonly workspaceId: string;
+        readonly name: string;
+    }[];
+    readonly included: readonly {
+        readonly id: string;
+        readonly workspaceId: string;
+        readonly name: string;
+    }[];
+    readonly pageInfo: {
+        readonly hasNextPage: false;
+    } | {
+        readonly hasNextPage: true;
+        readonly endCursor: string;
+    };
+};
+export type WorkspaceSelectorItem = (typeof WorkspaceSelectorItem)['Type'];
+export type ProjectSelectorItem = (typeof ProjectSelectorItem)['Type'];
+export type WorkspaceSelectorPage = (typeof WorkspaceSelectorPage)['Type'];
+export type ProjectSelectorPage = (typeof ProjectSelectorPage)['Type'];
+export type ScopeDirectoryPageInfo = (typeof ScopeDirectoryPageInfo)['Type'];

package/types/packages/core/src/secret.d.ts

@@ -0,0 +1,37 @@
+import * as Schema from 'effect/Schema';
+/** A Secret's name, which a Loop reads through Effect `Config`. */
+export declare const SecretName: Schema.String;
+export declare const SecretScope: Schema.Union<readonly [Schema.Literal<"workspace">, Schema.Literal<"project">]>;
+export type SecretScope = (typeof SecretScope)['Type'];
+/** A Secret as anyone may see it: never its value. */
+export declare const SecretSummary: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly scope: Schema.Union<readonly [Schema.Literal<"workspace">, Schema.Literal<"project">]>;
+    readonly projectId: Schema.optionalKey<Schema.String>;
+    readonly setByActorType: Schema.Union<readonly [Schema.Literal<"human">, Schema.Literal<"delegated_agent">, Schema.Literal<"agent">]>;
+    readonly setByActorId: Schema.String;
+    readonly setAt: Schema.String;
+}>;
+export type SecretSummary = (typeof SecretSummary)['Type'];
+export declare const SecretList: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly scope: Schema.Union<readonly [Schema.Literal<"workspace">, Schema.Literal<"project">]>;
+        readonly projectId: Schema.optionalKey<Schema.String>;
+        readonly setByActorType: Schema.Union<readonly [Schema.Literal<"human">, Schema.Literal<"delegated_agent">, Schema.Literal<"agent">]>;
+        readonly setByActorId: Schema.String;
+        readonly setAt: Schema.String;
+    }>>;
+}>;
+export type SecretList = (typeof SecretList)['Type'];
+export declare const secretSetRefused = "A Secret takes a value of 1 to 65536 characters and an optional projectId";
+/** Sets a Secret for the Workspace, or for one of its Projects; a refusal never quotes the value. */
+export declare const SecretSet: Schema.Struct<{
+    readonly value: Schema.String;
+    readonly projectId: Schema.optionalKey<Schema.String>;
+}>;
+export type SecretSet = (typeof SecretSet)['Type'];
+export declare const SecretScopeQuery: Schema.Struct<{
+    readonly projectId: Schema.optionalKey<Schema.String>;
+}>;
+export type SecretScopeQuery = (typeof SecretScopeQuery)['Type'];

package/types/packages/core/src/session.d.ts

@@ -0,0 +1,90 @@
+import * as Schema from 'effect/Schema';
+export declare const SessionStatuses: readonly ['active', 'ended'];
+export declare const DefaultSessionStatus = "active";
+export declare const SessionStatus: Schema.Union<readonly [Schema.Literal<"active">, Schema.Literal<"ended">]>;
+export declare const SessionUpdateKind: Schema.Union<readonly [Schema.Literal<"note">, Schema.Literal<"question">, Schema.Literal<"answer">, Schema.Literal<"decision">, Schema.Literal<"blocker">, Schema.Literal<"finding">, Schema.Literal<"handoff">, Schema.Literal<"test_result">, Schema.Literal<"file_reference">, Schema.Literal<"status_change">, Schema.Literal<"assignment_change">, Schema.Literal<"link">]>;
+export declare const Session: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly workspaceId: Schema.String;
+    readonly projectId: Schema.optionalKey<Schema.String>;
+    readonly taskId: Schema.String;
+    readonly actorType: Schema.Union<readonly [Schema.Literal<"human">, Schema.Literal<"delegated_agent">, Schema.Literal<"agent">]>;
+    readonly actorId: Schema.String;
+    readonly actorName: Schema.optionalKey<Schema.String>;
+    readonly delegatedByUserId: Schema.optionalKey<Schema.String>;
+    readonly agentName: Schema.optionalKey<Schema.String>;
+    readonly agentIdentityId: Schema.optionalKey<Schema.String>;
+    readonly runtimeMetadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+    readonly modelMetadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+    readonly status: Schema.Union<readonly [Schema.Literal<"active">, Schema.Literal<"ended">]>;
+    readonly summary: Schema.optionalKey<Schema.String>;
+    readonly startedAt: Schema.String;
+    readonly endedAt: Schema.optionalKey<Schema.String>;
+    readonly createdAt: Schema.String;
+    readonly updatedAt: Schema.String;
+}>;
+export declare const SessionCreate: Schema.Struct<{
+    readonly summary: Schema.optionalKey<Schema.String>;
+    readonly agentIdentityId: Schema.optionalKey<Schema.String>;
+    readonly runtimeMetadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+    readonly modelMetadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+export declare const SessionEnd: Schema.Struct<{
+    readonly summary: Schema.optionalKey<Schema.String>;
+}>;
+export declare const SessionList: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly workspaceId: Schema.String;
+        readonly projectId: Schema.optionalKey<Schema.String>;
+        readonly taskId: Schema.String;
+        readonly actorType: Schema.Union<readonly [Schema.Literal<"human">, Schema.Literal<"delegated_agent">, Schema.Literal<"agent">]>;
+        readonly actorId: Schema.String;
+        readonly actorName: Schema.optionalKey<Schema.String>;
+        readonly delegatedByUserId: Schema.optionalKey<Schema.String>;
+        readonly agentName: Schema.optionalKey<Schema.String>;
+        readonly agentIdentityId: Schema.optionalKey<Schema.String>;
+        readonly runtimeMetadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+        readonly modelMetadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+        readonly status: Schema.Union<readonly [Schema.Literal<"active">, Schema.Literal<"ended">]>;
+        readonly summary: Schema.optionalKey<Schema.String>;
+        readonly startedAt: Schema.String;
+        readonly endedAt: Schema.optionalKey<Schema.String>;
+        readonly createdAt: Schema.String;
+        readonly updatedAt: Schema.String;
+    }>>;
+}>;
+export declare const SessionUpdate: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly sessionId: Schema.String;
+    readonly taskId: Schema.String;
+    readonly kind: Schema.Union<readonly [Schema.Literal<"note">, Schema.Literal<"question">, Schema.Literal<"answer">, Schema.Literal<"decision">, Schema.Literal<"blocker">, Schema.Literal<"finding">, Schema.Literal<"handoff">, Schema.Literal<"test_result">, Schema.Literal<"file_reference">, Schema.Literal<"status_change">, Schema.Literal<"assignment_change">, Schema.Literal<"link">]>;
+    readonly content: Schema.String;
+    readonly metadata: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly createdAt: Schema.String;
+}>;
+export declare const SessionUpdateList: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly sessionId: Schema.String;
+        readonly taskId: Schema.String;
+        readonly kind: Schema.Union<readonly [Schema.Literal<"note">, Schema.Literal<"question">, Schema.Literal<"answer">, Schema.Literal<"decision">, Schema.Literal<"blocker">, Schema.Literal<"finding">, Schema.Literal<"handoff">, Schema.Literal<"test_result">, Schema.Literal<"file_reference">, Schema.Literal<"status_change">, Schema.Literal<"assignment_change">, Schema.Literal<"link">]>;
+        readonly content: Schema.String;
+        readonly metadata: Schema.$Record<Schema.String, Schema.Unknown>;
+        readonly createdAt: Schema.String;
+    }>>;
+}>;
+export declare const SessionUpdateCreate: Schema.Struct<{
+    readonly kind: Schema.Union<readonly [Schema.Literal<"note">, Schema.Literal<"question">, Schema.Literal<"answer">, Schema.Literal<"decision">, Schema.Literal<"blocker">, Schema.Literal<"finding">, Schema.Literal<"handoff">, Schema.Literal<"test_result">, Schema.Literal<"file_reference">, Schema.Literal<"status_change">, Schema.Literal<"assignment_change">, Schema.Literal<"link">]>;
+    readonly content: Schema.String;
+    readonly metadata: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+}>;
+export type SessionStatus = (typeof SessionStatus)['Type'];
+export type SessionUpdateKind = (typeof SessionUpdateKind)['Type'];
+export type Session = (typeof Session)['Type'];
+export type SessionCreate = (typeof SessionCreate)['Type'];
+export type SessionEnd = (typeof SessionEnd)['Type'];
+export type SessionList = (typeof SessionList)['Type'];
+export type SessionUpdate = (typeof SessionUpdate)['Type'];
+export type SessionUpdateList = (typeof SessionUpdateList)['Type'];
+export type SessionUpdateCreate = (typeof SessionUpdateCreate)['Type'];

package/types/packages/core/src/step-brief.d.ts

@@ -0,0 +1,50 @@
+import type { JsonObject } from './runtime-type';
+/** Validates an Output against its JSON Schema; the message is what the agent sees for its one repair. */
+export declare function validateAgentOutput(schema: JsonObject, output: JsonObject): {
+    readonly ok: true;
+} | {
+    readonly ok: false;
+    readonly message: string;
+};
+/** The first message an agent receives. */
+export declare function renderStepBriefPrompt(input: {
+    readonly instruction: string;
+    readonly contextPackMarkdown?: string;
+    readonly outputSchema: JsonObject;
+}): string;
+type ContextArtifact = {
+    readonly title: string;
+    readonly kind: string;
+    readonly text: string;
+};
+/**
+ * A program agent Step's ContextPack: its Task's context, this Run's artifacts, related artifacts from earlier Runs,
+ * and what earlier attempts of the Step recorded; then the Run's Intent and steering. Undefined when there is nothing to say.
+ */
+export declare function programStepContext(input: {
+    readonly taskContext?: string;
+    /** The Project's Kits, for a Run with no Task whose ContextPack would carry them. */
+    readonly kits?: string;
+    readonly runArtifacts: readonly ContextArtifact[];
+    readonly earlierArtifacts: readonly ContextArtifact[];
+    readonly handoff: readonly {
+        readonly attempt: number;
+        readonly kind: string;
+        readonly content: string;
+    }[];
+    /** The Run's current Intent, as Oversight renders it. */
+    readonly intent?: string;
+    readonly steering?: readonly string[];
+}): string | undefined;
+/** The program's prompt, and how the agent leaves a trail a retry on another Runner can follow. */
+export declare const programStepInstruction: (prompt: string) => string;
+type StepCredentialLease = {
+    readonly stepAttemptId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+};
+/** The agent's credential for StepAttempt-scoped Kitman MCP tools; it is valid only for the lease it was minted for. */
+export declare function mintStepCredential(secret: string, lease: StepCredentialLease): string;
+export declare function stepCredentialAttemptId(credential: string): string | undefined;
+export declare function stepCredentialMatches(secret: string, credential: string, lease: StepCredentialLease): boolean;
+export {};