@kitman-sh/sdk 0.7.2 → 0.7.3

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

@@ -0,0 +1,181 @@
+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', 'assigned', 'mentioned', 'commented', 'state_changed', 'run_finished', 'drift_unresolved', 'run_progress', 'change_request_update', 'start_blocked'];
+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 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>>;
+}>;
+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">]>;
+    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", "assigned", "mentioned", "commented", "state_changed", "run_finished", "drift_unresolved", "run_progress", "change_request_update", "start_blocked"]>;
+    readonly subject: Schema.Struct<{
+        readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">]>;
+        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 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>>;
+    }>;
+    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">]>;
+        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", "assigned", "mentioned", "commented", "state_changed", "run_finished", "drift_unresolved", "run_progress", "change_request_update", "start_blocked"]>;
+        readonly subject: Schema.Struct<{
+            readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">]>;
+            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 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>>;
+        }>;
+        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">]>;
+            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", "assigned", "mentioned", "commented", "state_changed", "run_finished", "drift_unresolved", "run_progress", "change_request_update", "start_blocked"]>;
+            readonly subject: Schema.Struct<{
+                readonly kind: Schema.Union<readonly [Schema.Literal<"task">, Schema.Literal<"run">, Schema.Literal<"proposal">]>;
+                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 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>>;
+            }>;
+            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">]>;
+        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">]>;
+        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;

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 {};