@kitman-sh/sdk 0.10.82 → 0.10.84

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

@@ -0,0 +1,250 @@
+import * as Schema from 'effect/Schema';
+import type { WorkspaceNotificationPreferences } from './workspace';
+export declare const NotificationKinds: readonly ['question_waiting', 'run_failed', 'review_ready', 'no_runner', 'proposal_waiting', 'approval_waiting', 'assigned', 'mentioned', 'commented', 'state_changed', 'run_finished', 'drift_unresolved', 'run_progress', 'change_request_update', 'start_blocked', 'update_drafted', 'runner_problem'];
+export type NotificationKind = (typeof NotificationKinds)[number];
+/** The facts a Notification's fixed templates render; never Outputs, transcripts, source or secrets. */
+export declare const NotificationPayload: Schema.Struct<{
+    readonly taskKey: Schema.optionalKey<Schema.String>;
+    readonly taskTitle: Schema.optionalKey<Schema.String>;
+    readonly loopTitle: Schema.optionalKey<Schema.String>;
+    readonly proposalTitle: Schema.optionalKey<Schema.String>;
+    /** The Code Mode operation a hosted MCP approval waits on. */
+    readonly toolName: Schema.optionalKey<Schema.String>;
+    readonly workspaceName: Schema.optionalKey<Schema.String>;
+    /** The Question's name, the Run's status, or the drifted constraint. */
+    readonly cause: Schema.optionalKey<Schema.String>;
+    /** The state a Task moved to. */
+    readonly state: Schema.optionalKey<Schema.String>;
+    readonly changeRequestUrl: Schema.optionalKey<Schema.String>;
+    /** What a Run needs that Kitman could not choose, such as its Loop or repository. */
+    readonly missing: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    /** The ChangeRequests a person can choose between for a missing `changeRequestId`, as links. */
+    readonly choices: Schema.optionalKey<Schema.$Array<Schema.String>>;
+    readonly projectId: Schema.optionalKey<Schema.String>;
+    readonly projectName: Schema.optionalKey<Schema.String>;
+    /** What a drafted Project Update was written from, since the Update before it. */
+    readonly writtenFrom: Schema.optionalKey<Schema.Struct<{
+        readonly runs: Schema.Int;
+        readonly taskChanges: Schema.Int;
+        readonly since: Schema.optionalKey<Schema.String>;
+    }>>;
+    readonly runnerName: Schema.optionalKey<Schema.String>;
+    /** A Runner Problem and the one command or action that fixes it. */
+    readonly problem: Schema.optionalKey<Schema.String>;
+    readonly fix: Schema.optionalKey<Schema.String>;
+}>;
+export type NotificationPayload = (typeof NotificationPayload)['Type'];
+export declare const NotificationSubject: Schema.Struct<{
+    readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">, Schema.Literal<"memory">, Schema.Literal<"mcp_approval">, Schema.Literal<"project_update">, Schema.Literal<"runner">]>;
+    readonly id: Schema.String;
+}>;
+export declare const Notification: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly workspaceId: Schema.String;
+    readonly recipientUserId: Schema.String;
+    readonly kind: Schema.Literals<readonly ["question_waiting", "run_failed", "review_ready", "no_runner", "proposal_waiting", "approval_waiting", "assigned", "mentioned", "commented", "state_changed", "run_finished", "drift_unresolved", "run_progress", "change_request_update", "start_blocked", "update_drafted", "runner_problem"]>;
+    readonly subject: Schema.Struct<{
+        readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">, Schema.Literal<"memory">, Schema.Literal<"mcp_approval">, Schema.Literal<"project_update">, Schema.Literal<"runner">]>;
+        readonly id: Schema.String;
+    }>;
+    /** Empty when Kitman acted. */
+    readonly actorId: Schema.optionalKey<Schema.String>;
+    readonly actorName: Schema.optionalKey<Schema.String>;
+    readonly payload: Schema.Struct<{
+        readonly taskKey: Schema.optionalKey<Schema.String>;
+        readonly taskTitle: Schema.optionalKey<Schema.String>;
+        readonly loopTitle: Schema.optionalKey<Schema.String>;
+        readonly proposalTitle: Schema.optionalKey<Schema.String>;
+        /** The Code Mode operation a hosted MCP approval waits on. */
+        readonly toolName: Schema.optionalKey<Schema.String>;
+        readonly workspaceName: Schema.optionalKey<Schema.String>;
+        /** The Question's name, the Run's status, or the drifted constraint. */
+        readonly cause: Schema.optionalKey<Schema.String>;
+        /** The state a Task moved to. */
+        readonly state: Schema.optionalKey<Schema.String>;
+        readonly changeRequestUrl: Schema.optionalKey<Schema.String>;
+        /** What a Run needs that Kitman could not choose, such as its Loop or repository. */
+        readonly missing: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        /** The ChangeRequests a person can choose between for a missing `changeRequestId`, as links. */
+        readonly choices: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        readonly projectId: Schema.optionalKey<Schema.String>;
+        readonly projectName: Schema.optionalKey<Schema.String>;
+        /** What a drafted Project Update was written from, since the Update before it. */
+        readonly writtenFrom: Schema.optionalKey<Schema.Struct<{
+            readonly runs: Schema.Int;
+            readonly taskChanges: Schema.Int;
+            readonly since: Schema.optionalKey<Schema.String>;
+        }>>;
+        readonly runnerName: Schema.optionalKey<Schema.String>;
+        /** A Runner Problem and the one command or action that fixes it. */
+        readonly problem: Schema.optionalKey<Schema.String>;
+        readonly fix: Schema.optionalKey<Schema.String>;
+    }>;
+    readonly title: Schema.String;
+    readonly body: Schema.String;
+    readonly link: Schema.String;
+    readonly createdAt: Schema.String;
+    readonly readAt: Schema.optionalKey<Schema.String>;
+}>;
+export type Notification = (typeof Notification)['Type'];
+export declare const InboxActions: readonly ['answer', 'review', 'decide', 'retry', 'runner_offline', 'start'];
+export declare const InboxFilters: readonly ['inbox', 'unread', 'snoozed', 'done'];
+export type InboxFilter = (typeof InboxFilters)[number];
+/** One subject's Notifications for its recipient, newest first; the item a person works in their Inbox. */
+export declare const InboxItem: Schema.Struct<{
+    readonly subject: Schema.Struct<{
+        readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">, Schema.Literal<"memory">, Schema.Literal<"mcp_approval">, Schema.Literal<"project_update">, Schema.Literal<"runner">]>;
+        readonly id: Schema.String;
+    }>;
+    /** What the item asks of its recipient, until it is done. */
+    readonly action: Schema.optionalKey<Schema.Literals<readonly ["answer", "review", "decide", "retry", "runner_offline", "start"]>>;
+    readonly unread: Schema.Int;
+    readonly latestAt: Schema.String;
+    readonly doneAt: Schema.optionalKey<Schema.String>;
+    readonly snoozedUntil: Schema.optionalKey<Schema.String>;
+    readonly notifications: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly workspaceId: Schema.String;
+        readonly recipientUserId: Schema.String;
+        readonly kind: Schema.Literals<readonly ["question_waiting", "run_failed", "review_ready", "no_runner", "proposal_waiting", "approval_waiting", "assigned", "mentioned", "commented", "state_changed", "run_finished", "drift_unresolved", "run_progress", "change_request_update", "start_blocked", "update_drafted", "runner_problem"]>;
+        readonly subject: Schema.Struct<{
+            readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">, Schema.Literal<"memory">, Schema.Literal<"mcp_approval">, Schema.Literal<"project_update">, Schema.Literal<"runner">]>;
+            readonly id: Schema.String;
+        }>;
+        /** Empty when Kitman acted. */
+        readonly actorId: Schema.optionalKey<Schema.String>;
+        readonly actorName: Schema.optionalKey<Schema.String>;
+        readonly payload: Schema.Struct<{
+            readonly taskKey: Schema.optionalKey<Schema.String>;
+            readonly taskTitle: Schema.optionalKey<Schema.String>;
+            readonly loopTitle: Schema.optionalKey<Schema.String>;
+            readonly proposalTitle: Schema.optionalKey<Schema.String>;
+            /** The Code Mode operation a hosted MCP approval waits on. */
+            readonly toolName: Schema.optionalKey<Schema.String>;
+            readonly workspaceName: Schema.optionalKey<Schema.String>;
+            /** The Question's name, the Run's status, or the drifted constraint. */
+            readonly cause: Schema.optionalKey<Schema.String>;
+            /** The state a Task moved to. */
+            readonly state: Schema.optionalKey<Schema.String>;
+            readonly changeRequestUrl: Schema.optionalKey<Schema.String>;
+            /** What a Run needs that Kitman could not choose, such as its Loop or repository. */
+            readonly missing: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            /** The ChangeRequests a person can choose between for a missing `changeRequestId`, as links. */
+            readonly choices: Schema.optionalKey<Schema.$Array<Schema.String>>;
+            readonly projectId: Schema.optionalKey<Schema.String>;
+            readonly projectName: Schema.optionalKey<Schema.String>;
+            /** What a drafted Project Update was written from, since the Update before it. */
+            readonly writtenFrom: Schema.optionalKey<Schema.Struct<{
+                readonly runs: Schema.Int;
+                readonly taskChanges: Schema.Int;
+                readonly since: Schema.optionalKey<Schema.String>;
+            }>>;
+            readonly runnerName: Schema.optionalKey<Schema.String>;
+            /** A Runner Problem and the one command or action that fixes it. */
+            readonly problem: Schema.optionalKey<Schema.String>;
+            readonly fix: Schema.optionalKey<Schema.String>;
+        }>;
+        readonly title: Schema.String;
+        readonly body: Schema.String;
+        readonly link: Schema.String;
+        readonly createdAt: Schema.String;
+        readonly readAt: Schema.optionalKey<Schema.String>;
+    }>>;
+}>;
+export type InboxItem = (typeof InboxItem)['Type'];
+export declare const InboxList: Schema.Struct<{
+    readonly items: Schema.$Array<Schema.Struct<{
+        readonly subject: Schema.Struct<{
+            readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">, Schema.Literal<"memory">, Schema.Literal<"mcp_approval">, Schema.Literal<"project_update">, Schema.Literal<"runner">]>;
+            readonly id: Schema.String;
+        }>;
+        /** What the item asks of its recipient, until it is done. */
+        readonly action: Schema.optionalKey<Schema.Literals<readonly ["answer", "review", "decide", "retry", "runner_offline", "start"]>>;
+        readonly unread: Schema.Int;
+        readonly latestAt: Schema.String;
+        readonly doneAt: Schema.optionalKey<Schema.String>;
+        readonly snoozedUntil: Schema.optionalKey<Schema.String>;
+        readonly notifications: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly workspaceId: Schema.String;
+            readonly recipientUserId: Schema.String;
+            readonly kind: Schema.Literals<readonly ["question_waiting", "run_failed", "review_ready", "no_runner", "proposal_waiting", "approval_waiting", "assigned", "mentioned", "commented", "state_changed", "run_finished", "drift_unresolved", "run_progress", "change_request_update", "start_blocked", "update_drafted", "runner_problem"]>;
+            readonly subject: Schema.Struct<{
+                readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">, Schema.Literal<"memory">, Schema.Literal<"mcp_approval">, Schema.Literal<"project_update">, Schema.Literal<"runner">]>;
+                readonly id: Schema.String;
+            }>;
+            /** Empty when Kitman acted. */
+            readonly actorId: Schema.optionalKey<Schema.String>;
+            readonly actorName: Schema.optionalKey<Schema.String>;
+            readonly payload: Schema.Struct<{
+                readonly taskKey: Schema.optionalKey<Schema.String>;
+                readonly taskTitle: Schema.optionalKey<Schema.String>;
+                readonly loopTitle: Schema.optionalKey<Schema.String>;
+                readonly proposalTitle: Schema.optionalKey<Schema.String>;
+                /** The Code Mode operation a hosted MCP approval waits on. */
+                readonly toolName: Schema.optionalKey<Schema.String>;
+                readonly workspaceName: Schema.optionalKey<Schema.String>;
+                /** The Question's name, the Run's status, or the drifted constraint. */
+                readonly cause: Schema.optionalKey<Schema.String>;
+                /** The state a Task moved to. */
+                readonly state: Schema.optionalKey<Schema.String>;
+                readonly changeRequestUrl: Schema.optionalKey<Schema.String>;
+                /** What a Run needs that Kitman could not choose, such as its Loop or repository. */
+                readonly missing: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                /** The ChangeRequests a person can choose between for a missing `changeRequestId`, as links. */
+                readonly choices: Schema.optionalKey<Schema.$Array<Schema.String>>;
+                readonly projectId: Schema.optionalKey<Schema.String>;
+                readonly projectName: Schema.optionalKey<Schema.String>;
+                /** What a drafted Project Update was written from, since the Update before it. */
+                readonly writtenFrom: Schema.optionalKey<Schema.Struct<{
+                    readonly runs: Schema.Int;
+                    readonly taskChanges: Schema.Int;
+                    readonly since: Schema.optionalKey<Schema.String>;
+                }>>;
+                readonly runnerName: Schema.optionalKey<Schema.String>;
+                /** A Runner Problem and the one command or action that fixes it. */
+                readonly problem: Schema.optionalKey<Schema.String>;
+                readonly fix: Schema.optionalKey<Schema.String>;
+            }>;
+            readonly title: Schema.String;
+            readonly body: Schema.String;
+            readonly link: Schema.String;
+            readonly createdAt: Schema.String;
+            readonly readAt: Schema.optionalKey<Schema.String>;
+        }>>;
+    }>>;
+}>;
+export type InboxList = (typeof InboxList)['Type'];
+/** How many items the Inbox shows, and how many of them have something unread. */
+export declare const InboxCounts: Schema.Struct<{
+    readonly items: Schema.Int;
+    readonly unread: Schema.Int;
+}>;
+export type InboxCounts = (typeof InboxCounts)['Type'];
+export declare const InboxSubjects: Schema.Struct<{
+    readonly subjects: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">, Schema.Literal<"memory">, Schema.Literal<"mcp_approval">, Schema.Literal<"project_update">, Schema.Literal<"runner">]>;
+        readonly id: Schema.String;
+    }>>;
+}>;
+export type InboxSubjects = (typeof InboxSubjects)['Type'];
+export declare const InboxSnooze: Schema.Struct<{
+    readonly subjects: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">, Schema.Literal<"memory">, Schema.Literal<"mcp_approval">, Schema.Literal<"project_update">, Schema.Literal<"runner">]>;
+        readonly id: Schema.String;
+    }>>;
+    readonly until: Schema.String;
+}>;
+export type InboxSnooze = (typeof InboxSnooze)['Type'];
+export declare const InboxUnsubscribe: Schema.Struct<{
+    readonly taskIds: Schema.$Array<Schema.String>;
+}>;
+export type InboxUnsubscribe = (typeof InboxUnsubscribe)['Type'];
+export declare const notificationPreferenceOf: (kind: NotificationKind) => keyof WorkspaceNotificationPreferences;
+export type RenderedNotification = Pick<Notification, 'title' | 'body' | 'link'>;
+export declare const renderNotification: (notification: {
+    readonly kind: NotificationKind;
+    readonly subject: (typeof NotificationSubject)['Type'];
+    readonly payload: NotificationPayload;
+}) => RenderedNotification;
+export declare const writtenFromText: (from: NotificationPayload['writtenFrom']) => string;

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

@@ -0,0 +1,175 @@
+import * as Config from 'effect/Config';
+import * as Context from 'effect/Context';
+import * as Layer from 'effect/Layer';
+import * as Metric from 'effect/Metric';
+import * as Tracer from 'effect/Tracer';
+import type { JsonValue } from './runtime-type';
+/**
+ * Shared telemetry contract for the control plane and customer-managed runners.
+ *
+ * `Telemetry` is the bounded, redacting front of Effect's own observability: metrics live in an Effect metric
+ * registry and render through `PrometheusMetrics`, spans come from the Effect `Tracer`, and logs go to the Effect
+ * loggers. A process exports all three over OTLP through {@link layerProcessTelemetryExport}.
+ */
+export declare const TraceparentHeader: 'traceparent';
+export declare const RequestIdHeader: 'x-request-id';
+/**
+ * Only route families registered here may become HTTP metric labels. Unknown
+ * paths intentionally collapse to `/unknown`; path-derived values never reach
+ * the metrics registry.
+ */
+export declare const TrustedRoutePrefixes: readonly string[];
+export type TraceContext = {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly traceFlags: string;
+    readonly traceState?: string;
+};
+type SpanStatus = 'unset' | 'ok' | 'error';
+type TelemetryAttributeValue = string | number | boolean;
+type TelemetryAttributes = Readonly<{
+    readonly [key: string]: JsonValue;
+}>;
+type TelemetryLabelInput = Readonly<{
+    readonly [key: string]: JsonValue;
+}>;
+type SpanRecord = {
+    readonly traceId: string;
+    readonly spanId: string;
+    readonly parentSpanId?: string;
+    readonly name: string;
+    readonly serviceName: string;
+    readonly startTimeUnixMs: number;
+    readonly endTimeUnixMs: number;
+    readonly status: SpanStatus;
+    readonly attributes: Readonly<Record<string, TelemetryAttributeValue>>;
+    readonly events: readonly SpanEvent[];
+};
+type SpanEvent = {
+    readonly name: string;
+    readonly timeUnixMs: number;
+    readonly attributes: Readonly<Record<string, TelemetryAttributeValue>>;
+};
+type MetricType = 'counter' | 'gauge' | 'histogram';
+type MetricDefinition = {
+    readonly name: string;
+    readonly help: string;
+    readonly type: MetricType;
+    readonly labelNames: readonly string[];
+    readonly maxSeries?: number;
+    readonly buckets?: readonly number[];
+};
+type MetricSeriesSnapshot = {
+    readonly name: string;
+    readonly type: MetricType;
+    readonly labels: Readonly<Record<string, string>>;
+    readonly value?: number;
+    readonly count?: number;
+    readonly sum?: number;
+    readonly buckets?: Readonly<Record<string, number>>;
+};
+type TelemetrySnapshot = {
+    readonly serviceName: string;
+    readonly spans: readonly SpanRecord[];
+    readonly metrics: {
+        readonly series: readonly MetricSeriesSnapshot[];
+        readonly seriesCount: number;
+    };
+};
+export declare const MetricDefinitions: readonly MetricDefinition[];
+export declare function parseTraceparent(value: string | undefined | null): TraceContext | undefined;
+export declare function formatTraceparent(context: TraceContext): string;
+export declare function injectTraceContext(headers: Headers | Record<string, string>, context: TraceContext, requestId?: string): void;
+export declare function normalizeRequestId(value: string | undefined | null): string;
+export declare function statusClass(status: number): `${1 | 2 | 3 | 4 | 5}xx` | 'unknown';
+export declare function templateRoute(pathname: string): string;
+export declare function safeOperation(value: string, fallback?: string): string;
+/** Attach the span created at an HTTP boundary for downstream application seams. */
+export declare function attachRequestTraceContext<RequestObject extends object>(request: RequestObject, context: TraceContext): void;
+export declare function requestTraceContext<RequestObject extends object>(request: RequestObject): TraceContext | undefined;
+/** An Effect `Tracer` span behind the same attribute, event and redaction bounds as every other signal. */
+export declare class TelemetrySpan {
+    private readonly telemetry;
+    readonly name: string;
+    readonly span: Tracer.Span;
+    readonly parentSpanId: string | undefined;
+    readonly startTimeUnixMs: number;
+    private readonly order;
+    readonly context: TraceContext;
+    private readonly attributes;
+    private readonly events;
+    private ended;
+    private status;
+    private errorType;
+    constructor(telemetry: Telemetry, name: string, span: Tracer.Span, parentSpanId: string | undefined, traceFlags: string, startTimeUnixMs: number, order: number, attributes: TelemetryAttributes);
+    setAttribute<ValueType>(key: string, value: ValueType): this;
+    setAttributes(attributes: TelemetryAttributes): this;
+    addEvent(name: string, attributes?: TelemetryAttributes): this;
+    recordException<ErrorType>(error: ErrorType): this;
+    end(status?: SpanStatus): void;
+}
+/** The process's Effect services that receive spans and logs: an OTLP tracer and loggers, or JSON log lines. */
+type TelemetryExport = Context.Context<never>;
+export declare class Telemetry {
+    readonly serviceName: string;
+    readonly metricRegistry: Metric.MetricRegistry;
+    private readonly metricServices;
+    /** The latest finished spans with their start order, written round the ring. */
+    private readonly spans;
+    private finishedSpans;
+    private readonly series;
+    private readonly maxSpans;
+    private readonly maxSeries;
+    private readonly reservedSeriesLimit;
+    private reservedSeries;
+    private readonly clock;
+    private exportServices;
+    private recordSpans;
+    private recordMetrics;
+    private recordLogs;
+    private propagateTrace;
+    private nextSpanOrder;
+    private recordingOverflow;
+    constructor(input: {
+        readonly serviceName: string;
+        readonly clock?: () => number;
+        readonly maxSpans?: number;
+        readonly maxMetricSeries?: number;
+        readonly metricRegistry?: Metric.MetricRegistry;
+    });
+    setExport(services: TelemetryExport | undefined): void;
+    /** Disable span retention/export while keeping trace context propagation and RED metrics available. */
+    setSpanRecordingEnabled(enabled: boolean): void;
+    setMetricsEnabled(enabled: boolean): void;
+    setLogRecordingEnabled(enabled: boolean): void;
+    setTracePropagationEnabled(enabled: boolean): void;
+    isTracePropagationEnabled(): boolean;
+    now(): number;
+    startSpan(name: string, options?: {
+        readonly parent?: TraceContext | string | null;
+        readonly attributes?: TelemetryAttributes;
+    }): TelemetrySpan;
+    counter(name: string, labels?: TelemetryLabelInput, value?: number): void;
+    gauge(name: string, value: number, labels?: TelemetryLabelInput): void;
+    histogram(name: string, value: number, labels?: TelemetryLabelInput): void;
+    log(event: string, fields?: TelemetryAttributes, span?: TelemetrySpan): void;
+    overflow(signal: string, reason: string): void;
+    prometheus(): string;
+    snapshot(): TelemetrySnapshot;
+    finishSpan(span: SpanRecord, order: number): void;
+    private record;
+    /** Admits a new label set while the series bounds hold, keeping room for the non-HTTP metrics. */
+    private admitSeries;
+}
+export declare function registerProcessTelemetry(telemetry: Telemetry): Telemetry;
+/** Returns one bounded recorder per service process for library seams. */
+export declare function getProcessTelemetry(serviceName: string): Telemetry;
+/** Prometheus exposition of every registered service, each metric family once. */
+export declare function processTelemetryPrometheus(): string;
+/**
+ * Exports the process's telemetry while the layer is alive, and provides the same tracer and loggers to the effects
+ * it is provided to. With `OTEL_EXPORTER_OTLP_ENDPOINT` set, spans, logs and the process metric registry go to that
+ * OTLP/HTTP collector; otherwise logs are written to stdout as JSON lines and spans stay in process.
+ */
+export declare const layerProcessTelemetryExport: (serviceName: string) => Layer.Layer<never, Config.ConfigError>;
+export {};

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

@@ -0,0 +1,15 @@
+import * as Schema from 'effect/Schema';
+/** What can move between the Workspace and one of its Teams. */
+export declare const OwnedKind: Schema.Literals<readonly ["repository", "memory", "decision", "secret"]>;
+/** The new owner: a Team, or the Workspace when `team` is null. */
+export declare const OwnerChange: Schema.Struct<{
+    readonly team: Schema.Union<readonly [Schema.String, Schema.Null]>;
+}>;
+export declare const OwnerMoved: Schema.Struct<{
+    readonly kind: Schema.Literals<readonly ["repository", "memory", "decision", "secret"]>;
+    readonly id: Schema.String;
+    readonly team: Schema.Union<readonly [Schema.String, Schema.Null]>;
+}>;
+export type OwnedKind = (typeof OwnedKind)['Type'];
+export type OwnerChange = (typeof OwnerChange)['Type'];
+export type OwnerMoved = (typeof OwnerMoved)['Type'];

package/types/packages/core/src/personal-development-profile.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A deliberately frozen, non-administrative capability set for a human's
+ * foreground development runner. New capabilities require a new profile.
+ */
+export declare const PersonalDevelopmentProfileName: 'personal_development_v1';
+export declare const PersonalDevelopmentProfileCapabilityNames: readonly ["kitman_resolve_team_context", "kitman_list_accessible_teams", "kitman_get_task", "kitman_search_tasks", "kitman_list_task_dependencies", "kitman_list_repo_bindings", "kitman_list_task_members", "kitman_list_task_thread_entries", "kitman_list_task_sessions", "kitman_get_session", "kitman_list_session_updates", "kitman_get_context_pack_snapshot", "kitman_get_latest_context_pack", "kitman_get_context_pack_retrieval_ref", "kitman_get_context_pack", "kitman_record_context_relevance_feedback", "kitman_get_task_execution_record", "kitman_list_memories", "kitman_get_memory", "kitman_record_session_update", "kitman_record_task_thread_entry", "kitman_post_task_question", "kitman_record_decision", "kitman_record_blocker", "kitman_link_task_artifact", "kitman_create_task_asset_upload", "kitman_complete_task_asset_upload", "kitman_get_task_asset_download_url", "kitman_generate_handoff"];
+export declare const PersonalDevelopmentProfile: {
+    readonly name: "personal_development_v1";
+    readonly capabilityNames: readonly ["kitman_resolve_team_context", "kitman_list_accessible_teams", "kitman_get_task", "kitman_search_tasks", "kitman_list_task_dependencies", "kitman_list_repo_bindings", "kitman_list_task_members", "kitman_list_task_thread_entries", "kitman_list_task_sessions", "kitman_get_session", "kitman_list_session_updates", "kitman_get_context_pack_snapshot", "kitman_get_latest_context_pack", "kitman_get_context_pack_retrieval_ref", "kitman_get_context_pack", "kitman_record_context_relevance_feedback", "kitman_get_task_execution_record", "kitman_list_memories", "kitman_get_memory", "kitman_record_session_update", "kitman_record_task_thread_entry", "kitman_post_task_question", "kitman_record_decision", "kitman_record_blocker", "kitman_link_task_artifact", "kitman_create_task_asset_upload", "kitman_complete_task_asset_upload", "kitman_get_task_asset_download_url", "kitman_generate_handoff"];
+};
+export type PersonalDevelopmentProfileName = typeof PersonalDevelopmentProfileName;

package/types/packages/core/src/platform-release.d.ts

@@ -0,0 +1,60 @@
+import { type RunnerArtifactManifest, type RunnerArchitecture, type RunnerOciIndex } from './runner-trust';
+declare const PlatformComponents: readonly ['api', 'web', 'worker', 'mcp', 'runner'];
+type PlatformComponent = (typeof PlatformComponents)[number];
+export type PlatformReleaseArtifactInput = {
+    readonly component: PlatformComponent;
+    readonly architecture: RunnerArchitecture;
+    readonly imageDigest: string;
+    readonly imageSize: number;
+    readonly sbomDigest: string;
+    readonly provenanceDigest: string;
+    readonly runnerPackageDigest?: string;
+    readonly runnerPackageSize?: number;
+};
+type PlatformReleaseArtifact = PlatformReleaseArtifactInput & {
+    readonly image: RunnerArtifactManifest;
+    readonly runnerPackage?: RunnerArtifactManifest;
+};
+type PlatformNativeSmokeEvidence = {
+    readonly architecture: RunnerArchitecture;
+    readonly status: 'verified' | 'not_run';
+    readonly executionMode: 'native' | 'emulated' | 'not_run';
+    readonly runnerId?: string;
+    readonly note: string;
+};
+export type PlatformReleaseManifest = {
+    readonly contractVersion: 'platform-release.v1';
+    readonly version: string;
+    readonly sourceCommit: string;
+    readonly lockfileDigest: string;
+    readonly baseImage: string;
+    readonly profileDigest: string;
+    readonly certificationDigest: string;
+    readonly components: Readonly<Record<PlatformComponent, {
+        readonly imageIndex: RunnerOciIndex;
+    }>>;
+    readonly artifacts: readonly PlatformReleaseArtifact[];
+    readonly nativeSmoke: readonly PlatformNativeSmokeEvidence[];
+    readonly signing: {
+        readonly required: true;
+        readonly configured: boolean;
+        readonly note: string;
+    };
+    readonly manifestDigest: string;
+};
+type CreatePlatformReleaseManifestInput = {
+    readonly version: string;
+    readonly sourceCommit: string;
+    readonly lockfileDigest: string;
+    readonly baseImage: string;
+    readonly profileDigest: string;
+    readonly certificationDigest: string;
+    readonly artifacts: readonly PlatformReleaseArtifactInput[];
+    readonly nativeSmoke?: readonly PlatformNativeSmokeEvidence[];
+    readonly signingConfigured?: boolean;
+    readonly signedAt?: Date | string;
+    readonly expiresAt?: Date | string;
+};
+export declare function createPlatformReleaseManifest(input: CreatePlatformReleaseManifestInput): PlatformReleaseManifest;
+export declare function verifyPlatformReleaseManifest(manifest: PlatformReleaseManifest): boolean;
+export {};

package/types/packages/core/src/program-credential.d.ts

@@ -0,0 +1,10 @@
+type ProgramCredentialLease = {
+    readonly workUnitId: string;
+    readonly leaseId: string;
+    readonly fencingToken: string;
+};
+/** A program process's credential for the Runner RPC; it is valid only for the orchestration lease it was minted for. */
+export declare function mintProgramCredential(secret: string, lease: ProgramCredentialLease): string;
+export declare function programCredentialWorkUnitId(credential: string): string | undefined;
+export declare function programCredentialMatches(secret: string, credential: string, lease: ProgramCredentialLease): boolean;
+export {};

package/types/packages/core/src/provider-safe-text.d.ts

@@ -0,0 +1,2 @@
+export declare const UnsafeProviderContentPattern: string;
+export declare const SafeProviderMetadataPattern: string;

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

@@ -0,0 +1,68 @@
+import * as Schema from 'effect/Schema';
+import type { NotificationKind } from './notification';
+/** What a device can be pushed about; a Question is on by default, the others are opt-in. */
+export declare const PushEvents: readonly ['question_asked', 'run_failed', 'run_done'];
+export type PushEvent = (typeof PushEvents)[number];
+export declare const defaultPushEvents: readonly PushEvent[];
+export declare const pushEventOf: (kind: NotificationKind) => PushEvent | undefined;
+/** A browser's PushSubscription as `toJSON()` gives it, with what the person chose for that device. */
+export declare const PushDeviceInput: Schema.Struct<{
+    readonly endpoint: Schema.String;
+    readonly keys: Schema.Struct<{
+        readonly p256dh: Schema.String;
+        readonly auth: Schema.String;
+    }>;
+    /** How the person tells their devices apart, such as the browser and platform. */
+    readonly label: Schema.optionalKey<Schema.String>;
+    readonly events: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["question_asked", "run_failed", "run_done"]>>>;
+}>;
+export type PushDeviceInput = (typeof PushDeviceInput)['Type'];
+export declare const PushDeviceChange: Schema.Struct<{
+    readonly enabled: Schema.optionalKey<Schema.Boolean>;
+    readonly events: Schema.optionalKey<Schema.$Array<Schema.Literals<readonly ["question_asked", "run_failed", "run_done"]>>>;
+}>;
+export type PushDeviceChange = (typeof PushDeviceChange)['Type'];
+/** One of a person's devices; its endpoint and keys stay on the server. */
+export declare const PushDevice: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly label: Schema.String;
+    readonly enabled: Schema.Boolean;
+    readonly events: Schema.$Array<Schema.Literals<readonly ["question_asked", "run_failed", "run_done"]>>;
+    /** Lets a browser find its own device among the person's. */
+    readonly endpointHash: Schema.String;
+    readonly createdAt: Schema.String;
+    readonly lastPushedAt: Schema.optionalKey<Schema.String>;
+}>;
+export type PushDevice = (typeof PushDevice)['Type'];
+export declare const PushSettings: Schema.Struct<{
+    /** The VAPID public key a browser subscribes with; absent when this Kitman cannot send pushes. */
+    readonly publicKey: Schema.optionalKey<Schema.String>;
+    readonly devices: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly label: Schema.String;
+        readonly enabled: Schema.Boolean;
+        readonly events: Schema.$Array<Schema.Literals<readonly ["question_asked", "run_failed", "run_done"]>>;
+        /** Lets a browser find its own device among the person's. */
+        readonly endpointHash: Schema.String;
+        readonly createdAt: Schema.String;
+        readonly lastPushedAt: Schema.optionalKey<Schema.String>;
+    }>>;
+}>;
+export type PushSettings = (typeof PushSettings)['Type'];
+/** What a push carries to the service worker: a short summary and a link, never source, Outputs or secrets. */
+export type PushMessage = {
+    readonly title: string;
+    readonly body: string;
+    /** Same tag, same notification: a later push about the Run replaces the earlier one on the device. */
+    readonly tag: string;
+    /** The page that tapping opens, relative to the web app. */
+    readonly url: string;
+    /** Replaces the device's notification without alerting again: one within the minute already did. */
+    readonly quiet?: true;
+    /** Offered as "Accept recommendation" where the platform shows notification actions. */
+    readonly accept?: {
+        readonly runId: string;
+        readonly questionId: string;
+        readonly value: string;
+    };
+};

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

@@ -0,0 +1,22 @@
+import type { Run, RunDisplay, RunDisplayState, RunShow, RunWaiting } from './loop';
+export type RunDisplayInput = Pick<RunShow, 'run' | 'steps' | 'questions' | 'children' | 'waiting'> & {
+    /** A Runner has leased one of the Run's orchestration Work Units. */
+    readonly claimed: boolean;
+    /** An eligible Runner is online for the Run's Team, or for no Team. */
+    readonly runnerOnline: boolean;
+    /** The `verify` Steps whose verification failed. */
+    readonly failedChecks: readonly string[];
+};
+export declare const runDisplayLabels: Record<RunDisplayState, string>;
+/** A resource the Run waits its turn for, and who holds it. */
+export declare const turnWords: (entry: Extract<RunWaiting, {
+    readonly kind: 'claim';
+}>) => string;
+/** What a Run's output says it left open: any Loop's `unsettled` list. `displayFacts` in run-list.ts reads the same. */
+export declare const reportedUnsettled: (output: Run['output']) => readonly string[] | undefined;
+/** What a Run and the Child Runs below it report left open. */
+export declare const unsettledItems: ({ run, children }: Pick<RunDisplayInput, 'run' | 'children'>) => string[];
+/** A display summary for a list row: one line, cut short. */
+export declare const listedSummary: (summary: string) => string;
+/** The one display state every surface shows for a Run (ADR-0072). */
+export declare const runDisplay: (input: RunDisplayInput) => RunDisplay;