@danypops/papyrus 0.44.10 → 0.44.12

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danypops/papyrus",
-  "version": "0.44.10",
+  "version": "0.44.12",
   "description": "Daemon-backed graph artifacts, evidence-bearing tasks, rules, skills, and native TUI workflows for Pi",
   "type": "module",
   "keywords": ["pi-package"],

package/src/artifact/artifact.ts

@@ -20,6 +20,29 @@ export interface Artifact {
 	edges?: ArtifactEdge[];
 }
 
+/**
+ * A list operation's default projection: everything needed to identify, browse, and pick
+ * one artifact out of many, without its body/extra -- the same fields show()'s own full
+ * Artifact carries minus the two that make listing dozens of rows as expensive as showing
+ * each one individually (a Playbook's full runbook body, a Rule's condition/action text).
+ */
+export interface ArtifactSummary {
+	id: string;
+	kind: string;
+	title: string;
+	status: string;
+	subtype: string;
+	labels: string[];
+	created_at: string;
+	updated_at: string;
+	alias: string;
+}
+
+export function summarizeArtifact(artifact: Artifact): ArtifactSummary {
+	const { id, kind, title, status, subtype, labels, created_at, updated_at, alias } = artifact;
+	return { id, kind, title, status, subtype, labels, created_at, updated_at, alias };
+}
+
 export interface CreateArtifactInput {
 	kind?: string;
 	title?: string;

package/src/constants.ts

@@ -16,6 +16,17 @@ export const WAL_CHECKPOINT_INTERVAL_MS = 60_000;
 export const DB_OPTIMIZE_INTERVAL_MS = 24 * 60 * 60_000;
 export const GATE_COMMAND_TIMEOUT_MS = 30_000;
 export const GATE_TEST_TIMEOUT_MS = 60_000;
+/**
+ * Ceiling a Gate's own explicit `timeoutMs` (domain/gate.ts) may request, overriding
+ * GATE_COMMAND_TIMEOUT_MS/GATE_TEST_TIMEOUT_MS for that one gate -- e.g. a task whose gate is a
+ * full monorepo test run that legitimately takes longer than either type default. Real, confirmed
+ * bug this exists for: a caller had no way to declare a longer-than-default gate timeout at all --
+ * `tasks.set_gates` silently accepted and dropped an experimental `timeoutMs` field before this.
+ * handlers/tasks.ts's GATE_OPERATION_LIMITS derives its own outer Vehicle transport deadline from
+ * this same constant, so the outer deadline can never fire strictly before a single gate honoring
+ * this ceiling has had a chance to.
+ */
+export const GATE_TIMEOUT_MAX_MS = 300_000;
 export const GATE_OUTPUT_LIMIT = 200;
 export const GATE_MAX_BUFFER_BYTES = 1_048_576;
 export const GATE_FILE_MAX_BYTES = 1_048_576;

package/src/domain/gate.ts

@@ -1,3 +1,5 @@
+import { GATE_TIMEOUT_MAX_MS } from "../constants.ts";
+
 export const GATE_TYPES = ["file-exists", "command", "contains", "test"] as const;
 export type GateType = (typeof GATE_TYPES)[number];
 
@@ -5,6 +7,8 @@ export interface Gate {
 	type: GateType;
 	target: string;
 	expect?: string;
+	/** Overrides GATE_COMMAND_TIMEOUT_MS/GATE_TEST_TIMEOUT_MS for this one "command"/"test" gate, bounded by GATE_TIMEOUT_MAX_MS (see its own doc comment). */
+	timeoutMs?: number;
 }
 
 function isRecord(value: unknown): value is Record<string, unknown> {
@@ -29,10 +33,17 @@ export function validateGates(value: unknown): Gate[] {
 		if (entry.expect !== undefined && typeof entry.expect !== "string") {
 			throw new Error(`gate at index ${index} expect must be a string`);
 		}
+		if (
+			entry.timeoutMs !== undefined &&
+			(!Number.isInteger(entry.timeoutMs) || (entry.timeoutMs as number) < 1_000 || (entry.timeoutMs as number) > GATE_TIMEOUT_MAX_MS)
+		) {
+			throw new Error(`gate at index ${index} timeoutMs must be an integer between 1000 and ${GATE_TIMEOUT_MAX_MS}`);
+		}
 		return {
 			type: entry.type as GateType,
 			target: entry.target,
 			...(typeof entry.expect === "string" ? { expect: entry.expect } : {}),
+			...(typeof entry.timeoutMs === "number" ? { timeoutMs: entry.timeoutMs } : {}),
 		};
 	});
 }

package/src/handlers/docs.ts

@@ -9,7 +9,7 @@ import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
 import { listDocuments } from "../domain-services.ts";
 import { docsOperations } from "../modules/docs.ts";
-import { createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
+import { booleanProp, createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "docs";
 
@@ -66,9 +66,9 @@ export function registerDocsVehicleOperations(
 
 	define(
 		"list",
-		"Lists Docs matching an optional status/text filter, scoped to project_root when given.",
+		"Lists Docs matching an optional status/text filter, scoped to project_root when given. Returns a lean summary (no body) by default -- pass full: true for the complete artifact.",
 		"read",
-		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, full: booleanProp },
 		[],
 		(input) => input,
 	);

package/src/handlers/playbooks.ts

@@ -29,6 +29,7 @@ import type { TaskEventStore } from "../stores/task-event-store.ts";
 import type { TaskScopeStore } from "../stores/task-scope-store.ts";
 import type { Tasks } from "../task/task-service.ts";
 import {
+	booleanProp,
 	buildWorkflowRunContent,
 	classifyPlaybookComposition,
 	classifySessionAuthorization,
@@ -107,9 +108,9 @@ export function registerPlaybooksVehicleOperations(registry: VehicleRegistry, de
 
 	define(
 		"list",
-		"Lists Playbooks matching an optional status/text filter, scoped to project_root when given.",
+		"Lists Playbooks matching an optional status/text filter, scoped to project_root when given. Returns a lean summary (no body/steps) by default -- pass full: true for the complete artifact.",
 		"read",
-		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, full: booleanProp },
 		[],
 		(input) => input,
 	);

package/src/handlers/rules.ts

@@ -9,7 +9,7 @@ import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import { listRules } from "../domain-services.ts";
 import { rulesOperations } from "../modules/rules.ts";
-import { createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
+import { booleanProp, createOperationDefiner, numberProp, resolveArtifactIdWidened, stringProp, validationError } from "./shared.ts";
 
 const OWNER = "rules";
 
@@ -70,9 +70,9 @@ export function registerRulesVehicleOperations(registry: VehicleRegistry, artifa
 
 	define(
 		"list",
-		"Lists Rules matching an optional status/text filter, scoped to project_root when given.",
+		"Lists Rules matching an optional status/text filter, scoped to project_root when given. Returns a lean summary (no condition/action/body) by default -- pass full: true for the complete artifact.",
 		"read",
-		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp },
+		{ status: stringProp, text: stringProp, limit: numberProp, project_root: stringProp, full: booleanProp },
 		[],
 		(input) => input,
 	);

package/src/handlers/shared.ts

@@ -9,6 +9,7 @@ import {
 	defineVehicleSchema,
 	type VehicleContentBlock,
 	VehicleError,
+	type VehicleLimits,
 	type VehicleOperationContext,
 	type VehicleSchemaCodec,
 } from "@danypops/vehicle-core";
@@ -57,6 +58,7 @@ export const passthroughOutput: VehicleSchemaCodec<unknown> = defineVehicleSchem
 
 export const stringProp = { type: "string" } as const;
 export const numberProp = { type: "number" } as const;
+export const booleanProp = { type: "boolean" } as const;
 
 /**
  * A plain `throw new Error(...)` inside any resolve()/execute() step here is caught by
@@ -243,6 +245,14 @@ export type DefineOperation = (
 	required: readonly string[],
 	resolve: (input: Record<string, unknown>) => Record<string, unknown>,
 	execute?: (input: Record<string, unknown>, context: VehicleOperationContext<Record<string, unknown>>) => unknown,
+	/**
+	 * Overrides this one operation's own Vehicle transport limits, distinct from every other
+	 * operation this same createOperationDefiner call produces. For an operation that shells out
+	 * to and waits on a real external command (e.g. tasks.run_gates/tasks.complete) rather than an
+	 * instant CRUD read/write -- see handlers/tasks.ts's GATE_OPERATION_LIMITS for the motivating
+	 * case. Omit to keep the definer's own default limits, unchanged for every other action.
+	 */
+	limits?: VehicleLimits,
 ) => void;
 
 const STANDARD_OPERATION_LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
@@ -261,7 +271,7 @@ export function createOperationDefiner(
 	permissions: readonly [string, string],
 	defaultCall: (name: string, input: Record<string, unknown>) => unknown,
 ): DefineOperation {
-	return (action, description, effect, properties, required, resolve, execute) => {
+	return (action, description, effect, properties, required, resolve, execute, limits) => {
 		const operation = defineVehicleOperation({
 			name: `${domain}.${action}`,
 			version: 1,
@@ -271,7 +281,7 @@ export function createOperationDefiner(
 			permissions: [...permissions],
 			effect,
 			idempotency: { mode: effect === "read" ? "safe" : "unsafe" },
-			limits: STANDARD_OPERATION_LIMITS,
+			limits: limits ?? STANDARD_OPERATION_LIMITS,
 		});
 		registry.register(
 			owner,

package/src/handlers/tasks.ts

@@ -19,8 +19,10 @@
  *
  * remove/remove_subtree/restore are not duplicated here -- see ./artifact-trash-vehicle.ts.
  */
+import type { VehicleLimits } from "@danypops/vehicle-core";
 import type { VehicleRegistry } from "@danypops/vehicle-server";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
+import { GATE_TIMEOUT_MAX_MS } from "../constants.ts";
 import type { TaskViewMode } from "../domain/task-scope.ts";
 import { tasksOperations } from "../modules/tasks.ts";
 import type { SessionIdentity } from "../session-identity/session-identity-service.ts";
@@ -40,7 +42,31 @@ import {
 } from "./shared.ts";
 
 const OWNER = "tasks";
-const LIMITS = { defaultTimeoutMs: 5_000, maxTimeoutMs: 30_000, maxRequestBytes: 65_536, maxResponseBytes: 262_144 };
+
+/**
+ * tasks.run_gates/tasks.complete's own Vehicle transport limits, distinct from every other
+ * tasks.* CRUD action's shared STANDARD_OPERATION_LIMITS (createOperationDefiner's own default,
+ * 5s). Those two operations shell out to and wait on a real, caller-configured external command
+ * (domain/gate.ts's Gate.timeoutMs) -- the shared 5s CRUD default was an accidental inheritance,
+ * not a deliberate choice, and aborted the RPC call for any gate command that took longer than a
+ * few seconds, even a genuinely successful one (confirmed live, twice, with hard numbers: a real
+ * ~13s gate failed deterministically every time; a ~28s gate flapped around a separate, unrelated
+ * 30s inner per-gate-type default).
+ *
+ * defaultTimeoutMs is derived from GATE_TIMEOUT_MAX_MS (the longest a single gate's own explicit
+ * timeoutMs may request) plus a buffer for process-spawn/RPC/serialization overhead, so the outer
+ * transport deadline can never fire strictly before a single gate honoring that ceiling has had a
+ * chance to. A task with SEVERAL gates each near that ceiling can still exceed this default in
+ * aggregate (gates run sequentially -- see ops.ts's runGatesAsync); there is no aggregate
+ * task-level gate-time budget yet. maxTimeoutMs gives a caller who knows its gates are
+ * collectively slower room to explicitly request a longer deadline.
+ */
+const GATE_OPERATION_LIMITS: VehicleLimits = {
+	defaultTimeoutMs: GATE_TIMEOUT_MAX_MS + 60_000,
+	maxTimeoutMs: GATE_TIMEOUT_MAX_MS * 4,
+	maxRequestBytes: 65_536,
+	maxResponseBytes: 262_144,
+};
 
 const objectProp = { type: "object" } as unknown as { type: string };
 const arrayProp = { type: "array" } as unknown as { type: string };
@@ -456,6 +482,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 			const labels = labelsById(artifacts, dependencyIds);
 			return { ...result, content: [{ type: "text" as const, text: completionContentText(labels, result) }] };
 		},
+		GATE_OPERATION_LIMITS,
 	);
 
 	define(
@@ -484,6 +511,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 				"No gates configured.";
 			return { gates, content: [{ type: "text" as const, text }] };
 		},
+		GATE_OPERATION_LIMITS,
 	);
 
 	define(
@@ -496,7 +524,7 @@ export function registerTasksVehicleOperations(registry: VehicleRegistry, deps:
 	);
 	define(
 		"set_gates",
-		"Replaces a Task's gate commands in full.",
+		"Replaces a Task's gate commands in full. Each gate is {type, target, expect?, timeoutMs?} -- timeoutMs overrides the default per-type command timeout (30s)/test timeout (60s) for a legitimately slower gate, up to a bounded ceiling.",
 		"local-write",
 		{ id: stringProp, name: stringProp, gates: arrayProp, project_root: stringProp },
 		["gates"],

package/src/modules/docs.ts

@@ -7,6 +7,7 @@
  * ArtifactStore-based with no other module's concrete class dependency.
  */
 
+import { summarizeArtifact } from "../artifact/artifact.ts";
 import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import type { AuthorityRegistry } from "../authority-registry.ts";
@@ -21,7 +22,7 @@ import {
 	updateDocument,
 } from "../domain-services.ts";
 import type { OperationDefinition } from "../module-registry.ts";
-import { type OperationInput, optionalNumber, optionalString, string } from "./operation-input.ts";
+import { type OperationInput, optionalBoolean, optionalNumber, optionalString, string } from "./operation-input.ts";
 
 const MODULE_ID = "docs";
 
@@ -76,7 +77,10 @@ export function docsOperations(artifacts: ArtifactStore, scopes: ArtifactScopeSt
 				eventContext(input),
 			),
 		),
-		define("docs.list", (input: OperationInput) => listDocuments(artifacts, scopes, artifactFilter(input))),
+		define("docs.list", (input: OperationInput) => {
+			const docs = listDocuments(artifacts, scopes, artifactFilter(input));
+			return optionalBoolean(input, "full") === true ? docs : docs.map(summarizeArtifact);
+		}),
 		define("docs.show", (input: OperationInput) => showDocument(artifacts, string(input, "id"))),
 		define("docs.activate", (input: OperationInput) =>
 			transitionDocument(artifacts, string(input, "id"), "activate", authority, eventContext(input)),

package/src/modules/operation-input.ts

@@ -33,3 +33,10 @@ export function optionalNumber(input: OperationInput, key: string): number | und
 	if (typeof value !== "number" || !Number.isFinite(value)) throw new Error(`${key} must be a number`);
 	return value;
 }
+
+export function optionalBoolean(input: OperationInput, key: string): boolean | undefined {
+	const value = input[key];
+	if (value === undefined) return undefined;
+	if (typeof value !== "boolean") throw new Error(`${key} must be a boolean`);
+	return value;
+}

package/src/modules/playbooks.ts

@@ -10,6 +10,7 @@
  * playbook/playbook-definition.ts for the full rationale.
  */
 
+import { summarizeArtifact } from "../artifact/artifact.ts";
 import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import {
@@ -31,7 +32,7 @@ import type { SessionIdentity } from "../session-identity/session-identity-servi
 import type { TaskEventStore } from "../stores/task-event-store.ts";
 import type { TaskScopeStore } from "../stores/task-scope-store.ts";
 import type { Tasks } from "../task/task-service.ts";
-import { type OperationInput, optionalNumber, optionalString, string } from "./operation-input.ts";
+import { type OperationInput, optionalBoolean, optionalNumber, optionalString, string } from "./operation-input.ts";
 
 const MODULE_ID = "playbooks";
 
@@ -114,7 +115,10 @@ export function playbooksOperations({
 				eventContext(input),
 			),
 		),
-		define("playbooks.list", (input: OperationInput) => listPlaybooks(artifacts, artifactScopes, artifactFilter(input))),
+		define("playbooks.list", (input: OperationInput) => {
+			const playbooks = listPlaybooks(artifacts, artifactScopes, artifactFilter(input));
+			return optionalBoolean(input, "full") === true ? playbooks : playbooks.map(summarizeArtifact);
+		}),
 		define("playbooks.show", (input: OperationInput) => showPlaybook(artifacts, string(input, "id"))),
 		define("playbooks.preview", (input: OperationInput) =>
 			playbookInvocation(artifacts, string(input, "id"), input.arguments as Record<string, unknown> | undefined),

package/src/modules/rules.ts

@@ -11,6 +11,7 @@
  * registry" convention.
  */
 
+import { summarizeArtifact } from "../artifact/artifact.ts";
 import type { ArtifactScopeStore } from "../artifact/artifact-scope-store.ts";
 import type { ArtifactStore } from "../artifact/artifact-store.ts";
 import {
@@ -24,7 +25,7 @@ import {
 	updateRule,
 } from "../domain-services.ts";
 import type { OperationDefinition } from "../module-registry.ts";
-import { type OperationInput, optionalNumber, optionalString, string } from "./operation-input.ts";
+import { type OperationInput, optionalBoolean, optionalNumber, optionalString, string } from "./operation-input.ts";
 
 const MODULE_ID = "rules";
 
@@ -79,7 +80,10 @@ export function rulesOperations(artifacts: ArtifactStore, scopes: ArtifactScopeS
 				eventContext(input),
 			),
 		),
-		define("rules.list", (input: OperationInput) => listRules(artifacts, scopes, artifactFilter(input))),
+		define("rules.list", (input: OperationInput) => {
+			const rules = listRules(artifacts, scopes, artifactFilter(input));
+			return optionalBoolean(input, "full") === true ? rules : rules.map(summarizeArtifact);
+		}),
 		define("rules.show", (input: OperationInput) => showRule(artifacts, string(input, "id"))),
 		define("rules.preview", (input: OperationInput) => previewRule(artifacts, string(input, "id"))),
 		define("rules.enable", (input: OperationInput) => transitionRule(artifacts, string(input, "id"), "enable", eventContext(input))),

package/src/ops.ts

@@ -601,8 +601,9 @@ function readBoundedGateFile(path: string): string {
 /** Shared by the sync and async process-gate runners so "test" is never a second, independently
  * maintained copy of "command"'s own command-template/timeout selection. */
 function processGateCommand(gate: Gate): { command: string; timeout: number } {
-	if (gate.type === "test") return { command: `npx vitest run ${gate.target} --reporter=dot`, timeout: GATE_TEST_TIMEOUT_MS };
-	return { command: gate.target, timeout: GATE_COMMAND_TIMEOUT_MS };
+	if (gate.type === "test")
+		return { command: `npx vitest run ${gate.target} --reporter=dot`, timeout: gate.timeoutMs ?? GATE_TEST_TIMEOUT_MS };
+	return { command: gate.target, timeout: gate.timeoutMs ?? GATE_COMMAND_TIMEOUT_MS };
 }
 
 /**