clinkx 0.3.0 → 1.1.0

package/dist/progress-report/schema.js

@@ -0,0 +1,119 @@
+import { z } from "zod";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { AgentStatusSchema, BlockerEntrySchema, BoundedIdSchema, BoundedMessageSchema, BoundedTitleSchema, FileChangeEntrySchema, LogKindSchema, NonnegativeSafeIntegerSchema, ProgressReportSessionIdSchema, ProjectFolderPathSchema, SessionStatusSchema, TaskSectionSchema, } from "../../clinkx-workflows/dist/dashboard/progress-report-contract.js";
+/**
+ * Tool-input schemas for the native progress-report tools.
+ *
+ * This is deliberately NOT `src/schema.ts` — that file is the frozen v1
+ * `clink` input contract. Per-tool schema modules are the established shape
+ * (`src/context-builder/schema.ts`). Every document-shaped field here reuses the
+ * dashboard's own producer contract, so the writer cannot drift from the reader.
+ *
+ * Server-owned fields are absent by construction: `session.id`, `started_at`,
+ * every `updated_at` / `t` / `last_run`, and `schema_version` are stamped by the
+ * store, never accepted from a caller.
+ */
+const RequestIdSchema = z
+    .string()
+    .min(1)
+    .max(128)
+    .describe("Idempotency key for this call. Replaying the same request_id with identical content returns the original receipt and writes nothing; reusing it with different content is rejected. Use a fresh key (a UUID) per intended write. On progress_report_start the session id is DERIVED from this key, so it must be unique per report, and the returned receipt describes the original call — check replayed:true and call progress_report_get if you need the report's current revision.");
+// Agents are upserted by name; updated_at is stamped server-side.
+const AgentInputSchema = z
+    .object({
+    name: BoundedIdSchema,
+    role: BoundedIdSchema,
+    status: AgentStatusSchema,
+    activity: BoundedMessageSchema,
+})
+    .strict();
+const LogAppendSchema = z
+    .object({ agent: BoundedIdSchema, kind: LogKindSchema, msg: BoundedMessageSchema })
+    .strict();
+const DecisionAppendSchema = z
+    .object({ by: BoundedIdSchema, msg: BoundedMessageSchema })
+    .strict();
+const TestsSetSchema = z
+    .object({
+    passed: NonnegativeSafeIntegerSchema,
+    failed: NonnegativeSafeIntegerSchema,
+    skipped: NonnegativeSafeIntegerSchema,
+    failing: z.array(BoundedMessageSchema).max(100),
+})
+    .strict();
+export const ProgressReportStartInputSchema = z
+    .object({
+    request_id: RequestIdSchema,
+    project_folder: ProjectFolderPathSchema.describe("Absolute path of the workspace this session is working in. progress_report_list matches candidates by it."),
+    title: BoundedTitleSchema,
+    goal: BoundedTitleSchema,
+    opened_by: BoundedIdSchema.describe("Agent name credited with the opening log entry. Use a lowercase slug that matches an agents[].name."),
+    agents: z.array(AgentInputSchema).max(50).optional(),
+    tasks: z.array(TaskSectionSchema).max(200).optional(),
+})
+    .strict();
+export const ProgressReportChangesSchema = z
+    .object({
+    session: z
+        .object({
+        title: BoundedTitleSchema.optional(),
+        goal: BoundedTitleSchema.optional(),
+        status: SessionStatusSchema.optional(),
+    })
+        .strict()
+        .optional(),
+    agents_upsert: z.array(AgentInputSchema).max(50).optional(),
+    tasks_upsert: z.array(TaskSectionSchema).max(200).optional(),
+    log_append: z.array(LogAppendSchema).max(50).optional(),
+    files_upsert: z.array(FileChangeEntrySchema).max(500).optional(),
+    tests_set: TestsSetSchema.optional(),
+    blockers_set: z.array(BlockerEntrySchema).max(50).optional(),
+    decisions_append: z.array(DecisionAppendSchema).max(20).optional(),
+})
+    .strict()
+    // NOTE: `.refine` produces a ZodEffects, which zodToJsonSchema DROPS. The
+    // advertised JSON Schema therefore still admits `changes: {}`; enforcement is
+    // server-side only, in the safeParse that every tool call goes through. Do not
+    // assume a client's schema validation has already rejected an empty patch.
+    .refine((value) => Object.values(value).some((v) => v !== undefined), {
+    message: "changes must carry at least one of session, agents_upsert, tasks_upsert, log_append, files_upsert, tests_set, blockers_set, decisions_append",
+});
+export const ProgressReportUpdateInputSchema = z
+    .object({
+    report_id: ProgressReportSessionIdSchema.describe("The session id returned by progress_report_start or progress_report_list."),
+    request_id: RequestIdSchema,
+    expected_revision: z
+        .number()
+        .int()
+        .min(1)
+        .describe("The revision this update is based on, from the last receipt or progress_report_get. A mismatch is rejected as revision_conflict rather than silently overwriting a concurrent write."),
+    changes: ProgressReportChangesSchema,
+    reopen: z
+        .boolean()
+        .optional()
+        .describe("Required to write to a report already closed as done or failed. Setting session.status to running also reopens it."),
+})
+    .strict();
+export const ProgressReportGetInputSchema = z
+    .object({ report_id: ProgressReportSessionIdSchema })
+    .strict();
+export const ProgressReportListInputSchema = z
+    .object({
+    project_folder: ProjectFolderPathSchema.optional().describe("Restrict to reports opened for this workspace. Omit to list every report."),
+    limit: z.number().int().min(1).max(50).default(5),
+})
+    .strict();
+const JSON_SCHEMA_OPTIONS = { $refStrategy: "none" };
+export function progressReportStartJsonSchema() {
+    return zodToJsonSchema(ProgressReportStartInputSchema, JSON_SCHEMA_OPTIONS);
+}
+export function progressReportUpdateJsonSchema() {
+    return zodToJsonSchema(ProgressReportUpdateInputSchema, JSON_SCHEMA_OPTIONS);
+}
+export function progressReportGetJsonSchema() {
+    return zodToJsonSchema(ProgressReportGetInputSchema, JSON_SCHEMA_OPTIONS);
+}
+export function progressReportListJsonSchema() {
+    return zodToJsonSchema(ProgressReportListInputSchema, JSON_SCHEMA_OPTIONS);
+}
+//# sourceMappingURL=schema.js.map

package/dist/progress-report/schema.js.map

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

package/dist/progress-report/store.d.ts

@@ -0,0 +1,66 @@
+import { type ProgressReportDocument } from "../../clinkx-workflows/dist/dashboard/progress-report-contract.js";
+import type { ProgressReportChanges, ProgressReportStartInput } from "./schema.js";
+export declare const REPORTS_SUBDIR = "progress-reports";
+export declare const REPORT_FILENAME = "report-data.json";
+export declare const CONTROL_FILENAME = ".control.json";
+/** Mirrors the dashboard reader's own per-file cap (progress-report-reader.ts). */
+export declare const MAX_REPORT_FILE_BYTES: number;
+/** Bound directory enumeration the same way the reader does. */
+export declare const SCAN_CAP = 10000;
+/**
+ * How many directories are actually READ per listing. Enumeration is stat-only;
+ * only the newest this many are opened, exactly as the dashboard reader does.
+ */
+export declare const MAX_LIST_CANDIDATES = 200;
+/** Aggregate read budget for one listing, matching the reader's own budget. */
+export declare const MAX_LIST_SCAN_BYTES: number;
+/** How many bounded request_id receipts to retain per session. */
+export declare const RECEIPT_RETENTION = 32;
+export interface ProgressReportReceipt {
+    readonly session_id: string;
+    readonly revision: number;
+    readonly path: string;
+    readonly status: string;
+    readonly updated_at: string;
+    readonly replayed: boolean;
+}
+export declare function reportsRoot(env?: NodeJS.ProcessEnv): string;
+export declare function startReport(input: ProgressReportStartInput, env?: NodeJS.ProcessEnv): Promise<ProgressReportReceipt>;
+export declare function updateReport(args: {
+    readonly report_id: string;
+    readonly request_id: string;
+    readonly expected_revision: number;
+    readonly changes: ProgressReportChanges;
+    readonly reopen?: boolean | undefined;
+}, env?: NodeJS.ProcessEnv): Promise<ProgressReportReceipt>;
+export declare function getReport(reportId: string, env?: NodeJS.ProcessEnv): Promise<{
+    document: ProgressReportDocument;
+    revision: number;
+    path: string;
+}>;
+export interface ProgressReportCandidate {
+    readonly id: string;
+    readonly path: string;
+    readonly title: string;
+    readonly goal: string;
+    readonly status: string;
+    readonly revision: number;
+    readonly updated_at: string;
+    readonly agents: readonly string[];
+    readonly tasks: readonly string[];
+}
+export interface ProgressReportListing {
+    readonly candidates: readonly ProgressReportCandidate[];
+    /** True when the listing could not consider every report on disk. */
+    readonly truncated: boolean;
+}
+export declare function listReports(options: {
+    readonly project_folder?: string;
+    readonly limit: number;
+}, env?: NodeJS.ProcessEnv): Promise<ProgressReportListing>;
+/**
+ * Apply one bounded patch. Every server-owned field (timestamps, ids) is
+ * stamped here rather than trusted from the caller, so a caller cannot publish
+ * a guessed clock or rewrite an identity.
+ */
+export declare function applyChanges(current: ProgressReportDocument, changes: ProgressReportChanges, reopen: boolean): ProgressReportDocument;