clinkx 0.3.0 → 1.0.0

package/clinkx-workflows/dist/dashboard/activity-contract.js

@@ -0,0 +1,105 @@
+import { z } from "zod";
+export const ACTIVITY_STATE_FILENAME = "state.json";
+export const ACTIVITY_RESULT_FILENAME = "result.txt";
+export const DEFAULT_MAX_ACTIVITY_RESULT_BYTES = 64 * 1_024;
+export const MAX_ACTIVITY_STATE_BYTES = 16 * 1_024;
+export const DEFAULT_MAX_ACTIVITY_ENTRIES = 1_000;
+export const DEFAULT_MAX_ACTIVITY_TOTAL_BYTES = 128 * 1_024 * 1_024;
+export const DEFAULT_ACTIVITY_MAX_AGE_MS = 24 * 60 * 60 * 1_000;
+export const DEFAULT_ACTIVITY_HEARTBEAT_INTERVAL_MS = 30_000;
+export const ActivityIdSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .regex(/^[A-Za-z0-9_-]+$/);
+const ActivityTimestampSchema = z.string().datetime({ offset: true });
+export const ActivityKindSchema = z.enum(["clink", "clink_agent_run"]);
+export const ActivityPhaseSchema = z.enum([
+    "resolving",
+    "running",
+    "parsing",
+    "terminal",
+]);
+export const ActivityTerminalStatusSchema = z.enum([
+    "succeeded",
+    "failed",
+    "cancelled",
+]);
+export const ActivityOutcomeKindSchema = z.enum([
+    "success",
+    "error",
+    "cancelled",
+]);
+export const ActivityResultReferenceSchema = z.object({
+    path: z.literal(ACTIVITY_RESULT_FILENAME),
+    bytes: z.number().int().min(0).max(DEFAULT_MAX_ACTIVITY_RESULT_BYTES),
+    sha256: z.string().length(64).regex(/^[0-9a-f]+$/),
+    truncated: z.boolean(),
+}).strict();
+export const ActivityStateV1Schema = z.object({
+    schemaVersion: z.literal("clinkx-dashboard-activity-v1"),
+    activityId: ActivityIdSchema,
+    kind: ActivityKindSchema,
+    phase: ActivityPhaseSchema,
+    status: z.enum(["running", "succeeded", "failed", "cancelled"]),
+    adapter: z.string().min(1).max(128),
+    role: z.string().min(1).max(128),
+    startedAt: ActivityTimestampSchema,
+    stateUpdatedAt: ActivityTimestampSchema,
+    leaseUpdatedAt: ActivityTimestampSchema.optional(),
+    completedAt: ActivityTimestampSchema.optional(),
+    outcome: z.object({
+        kind: ActivityOutcomeKindSchema,
+    }).strict().optional(),
+    result: ActivityResultReferenceSchema.optional(),
+    /**
+     * Project folder(s) the activity ran against, recorded by the producer.
+     * Optional so existing on-disk state.json files keep validating; the
+     * dashboard reader caps and defends the array defensively on projection.
+     */
+    projectFolders: z.array(z.string()).optional(),
+}).strict().superRefine((state, context) => {
+    const terminal = state.phase === "terminal";
+    if (terminal !== (state.status !== "running")) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "terminal phase and status must agree",
+            path: ["status"],
+        });
+    }
+    if (terminal !== (state.completedAt !== undefined &&
+        state.outcome !== undefined)) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "terminal records require completion metadata",
+            path: ["completedAt"],
+        });
+    }
+    if (state.kind === "clink_agent_run" &&
+        state.result !== undefined) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "agent-run activities are metadata-only",
+            path: ["result"],
+        });
+    }
+    if (state.kind === "clink_agent_run" &&
+        state.phase === "parsing") {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "agent-run activities have no parsing phase",
+            path: ["phase"],
+        });
+    }
+    if (terminal &&
+        ((state.status === "succeeded" && state.outcome?.kind !== "success") ||
+            (state.status === "failed" && state.outcome?.kind !== "error") ||
+            (state.status === "cancelled" && state.outcome?.kind !== "cancelled"))) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "terminal status and outcome must agree",
+            path: ["outcome"],
+        });
+    }
+});
+//# sourceMappingURL=activity-contract.js.map

package/clinkx-workflows/dist/dashboard/activity-contract.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-contract.js","sourceRoot":"","sources":["../../src/dashboard/activity-contract.ts"],"names":[],"mappings":"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"}

package/clinkx-workflows/dist/dashboard/activity-lease.d.ts

@@ -0,0 +1,25 @@
+/** Same floor as `run.lock` heartbeat staleness (`max(60s, interval × 6)`). */
+export declare const ACTIVITY_LEASE_STALE_FLOOR_MS = 60000;
+export declare const ACTIVITY_LEASE_STALE_MULTIPLIER = 6;
+export declare const ACTIVITY_LEASE_STALE_AFTER_MS: number;
+export type ActivityLeaseObservation = "live" | "orphaned" | "unknown";
+/**
+ * Read-time lease overlay. Never persist the result.
+ *
+ * Running + fresh `leaseUpdatedAt` (age ≤ 180s, including a producer clock
+ * slightly ahead) → `live`. Running + stale lease → `orphaned`. Missing or
+ * unparseable lease → `unknown` (never death). Terminal rows ignore any leftover
+ * lease and always return `unknown`.
+ */
+export declare function classifyActivityLease(input: Readonly<{
+    status: "running" | "succeeded" | "failed" | "cancelled";
+    leaseUpdatedAt: string | undefined;
+    nowMs: number;
+}>): Readonly<{
+    orphaned: boolean;
+    leaseObservation: ActivityLeaseObservation;
+}>;
+export declare function isActivityLivePin(row: Readonly<{
+    status: string;
+    leaseObservation: ActivityLeaseObservation;
+}>): boolean;

package/clinkx-workflows/dist/dashboard/activity-lease.js

@@ -0,0 +1,34 @@
+import { DEFAULT_ACTIVITY_HEARTBEAT_INTERVAL_MS } from "./activity-contract.js";
+/** Same floor as `run.lock` heartbeat staleness (`max(60s, interval × 6)`). */
+export const ACTIVITY_LEASE_STALE_FLOOR_MS = 60_000;
+export const ACTIVITY_LEASE_STALE_MULTIPLIER = 6;
+export const ACTIVITY_LEASE_STALE_AFTER_MS = Math.max(ACTIVITY_LEASE_STALE_FLOOR_MS, DEFAULT_ACTIVITY_HEARTBEAT_INTERVAL_MS * ACTIVITY_LEASE_STALE_MULTIPLIER);
+/**
+ * Read-time lease overlay. Never persist the result.
+ *
+ * Running + fresh `leaseUpdatedAt` (age ≤ 180s, including a producer clock
+ * slightly ahead) → `live`. Running + stale lease → `orphaned`. Missing or
+ * unparseable lease → `unknown` (never death). Terminal rows ignore any leftover
+ * lease and always return `unknown`.
+ */
+export function classifyActivityLease(input) {
+    if (input.status !== "running") {
+        return { orphaned: false, leaseObservation: "unknown" };
+    }
+    if (input.leaseUpdatedAt === undefined) {
+        return { orphaned: false, leaseObservation: "unknown" };
+    }
+    const leaseMs = Date.parse(input.leaseUpdatedAt);
+    if (!Number.isFinite(leaseMs)) {
+        return { orphaned: false, leaseObservation: "unknown" };
+    }
+    const ageMs = input.nowMs - leaseMs;
+    if (ageMs <= ACTIVITY_LEASE_STALE_AFTER_MS) {
+        return { orphaned: false, leaseObservation: "live" };
+    }
+    return { orphaned: true, leaseObservation: "orphaned" };
+}
+export function isActivityLivePin(row) {
+    return row.status === "running" && row.leaseObservation === "live";
+}
+//# sourceMappingURL=activity-lease.js.map

package/clinkx-workflows/dist/dashboard/activity-lease.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"activity-lease.js","sourceRoot":"","sources":["../../src/dashboard/activity-lease.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sCAAsC,EAAE,MAAM,wBAAwB,CAAC;AAEhF,+EAA+E;AAC/E,MAAM,CAAC,MAAM,6BAA6B,GAAG,MAAM,CAAC;AACpD,MAAM,CAAC,MAAM,+BAA+B,GAAG,CAAC,CAAC;AAEjD,MAAM,CAAC,MAAM,6BAA6B,GAAG,IAAI,CAAC,GAAG,CACnD,6BAA6B,EAC7B,sCAAsC,GAAG,+BAA+B,CACzE,CAAC;AAIF;;;;;;;GAOG;AACH,MAAM,UAAU,qBAAqB,CAAC,KAIpC;IAIA,IAAI,KAAK,CAAC,MAAM,KAAK,SAAS,EAAE,CAAC;QAC/B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,CAAC;IAC1D,CAAC;IACD,IAAI,KAAK,CAAC,cAAc,KAAK,SAAS,EAAE,CAAC;QACvC,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,CAAC;IAC1D,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;IACjD,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9B,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,SAAS,EAAE,CAAC;IAC1D,CAAC;IACD,MAAM,KAAK,GAAG,KAAK,CAAC,KAAK,GAAG,OAAO,CAAC;IACpC,IAAI,KAAK,IAAI,6BAA6B,EAAE,CAAC;QAC3C,OAAO,EAAE,QAAQ,EAAE,KAAK,EAAE,gBAAgB,EAAE,MAAM,EAAE,CAAC;IACvD,CAAC;IACD,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,gBAAgB,EAAE,UAAU,EAAE,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,GAGhC;IACA,OAAO,GAAG,CAAC,MAAM,KAAK,SAAS,IAAI,GAAG,CAAC,gBAAgB,KAAK,MAAM,CAAC;AACrE,CAAC"}

package/clinkx-workflows/dist/dashboard/activity-reader.d.ts

@@ -0,0 +1,86 @@
+import { readContainedRelativeFile } from "../contained-file.js";
+import { type ActivityStateV1 } from "./activity-contract.js";
+import { type ActivityLeaseObservation } from "./activity-lease.js";
+export interface DashboardActivityIdentity {
+    readonly activityId: string;
+    readonly activityGeneration: string;
+    readonly stateRevision: string;
+}
+export interface DashboardActivityListItem extends DashboardActivityIdentity {
+    readonly kind: ActivityStateV1["kind"];
+    readonly phase: ActivityStateV1["phase"];
+    readonly status: ActivityStateV1["status"];
+    readonly adapter: string;
+    readonly role: string;
+    readonly startedAt: string;
+    readonly stateUpdatedAt: string;
+    readonly completedAt?: string;
+    readonly hasResult: boolean;
+    /**
+     * Project folder(s) the activity ran against, from the persisted
+     * `projectFolders` field. Empty when none were recorded.
+     */
+    readonly projectFolders: readonly string[];
+    readonly orphaned: boolean;
+    readonly leaseObservation: ActivityLeaseObservation;
+}
+export interface DashboardActivityDetail extends DashboardActivityListItem {
+    readonly outcome?: ActivityStateV1["outcome"];
+    readonly resultTruncated?: boolean;
+}
+export interface DashboardActivityListResponse {
+    readonly activities: readonly DashboardActivityListItem[];
+    readonly nextBefore?: string;
+    readonly serverNow: string;
+}
+export type DashboardActivityDetailResult = Readonly<{
+    kind: "available";
+    detail: DashboardActivityDetail;
+}> | Readonly<{
+    kind: "activity_generation_changed";
+}> | Readonly<{
+    kind: "activity_state_changed";
+}> | Readonly<{
+    kind: "unavailable";
+}>;
+export type DashboardActivityRawResult = Readonly<{
+    kind: "available";
+    content: string;
+    mediaType: "text/plain; charset=utf-8";
+    activityGeneration: string;
+    stateRevision: string;
+}> | Readonly<{
+    kind: "activity_generation_changed";
+}> | Readonly<{
+    kind: "activity_state_changed";
+}> | Readonly<{
+    kind: "unavailable";
+    reason: "not_persisted" | "invalid" | "too_large";
+}>;
+export type DashboardCurrentActivityResolution = Readonly<{
+    kind: "resolved";
+    activityId: string;
+    activityGeneration: string;
+}> | Readonly<{
+    kind: "missing";
+}>;
+export interface DashboardActivityReader {
+    readonly list: (activitiesRoot: string, query?: Readonly<{
+        limit?: number;
+        before?: string;
+    }>) => Promise<DashboardActivityListResponse>;
+    readonly readDetail: (activitiesRoot: string, activityId: string, activityGeneration: string) => Promise<DashboardActivityDetailResult>;
+    /** Resolve the current activity-directory incarnation without list pagination. */
+    readonly resolveCurrent: (activitiesRoot: string, activityId: string) => Promise<DashboardCurrentActivityResolution>;
+    readonly readResult: (request: Readonly<{
+        activitiesRoot: string;
+        activityId: string;
+        activityGeneration: string;
+    }>) => Promise<DashboardActivityRawResult>;
+}
+type ActivityStateFileReader = typeof readContainedRelativeFile;
+export declare function createDashboardActivityReader(options?: Readonly<{
+    now?: (() => Date) | undefined;
+    readStateFile?: ActivityStateFileReader | undefined;
+}>): DashboardActivityReader;
+export {};