@danypops/papyrus 0.35.0 → 0.35.2

package/package.json

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

package/src/client.ts

@@ -57,3 +57,24 @@ export async function connectPapyrusClient(dir: string = daemonStateDir()): Prom
 		throw new Error("Papyrus daemon state is stale or unreachable; restart papyrus.service");
 	}
 }
+
+export interface PushChannelTarget {
+	/** ws:// URL for the daemon's push-invalidation channel (see push-channel.ts in daemon-kit). */
+	url: string;
+	token: string;
+}
+
+/**
+ * Narrow surface for a push-channel consumer -- exposes only what's needed to open
+ * the WebSocket (url derived from the same handle connectPapyrusClient reads, token),
+ * not daemon-state.ts's whole internal handle shape. Returns undefined rather than
+ * throwing when the daemon has never started (no token/port on disk yet); a caller
+ * wiring this into a UI widget already tolerates "daemon not running" for its own
+ * fetch-based refresh and should treat push-channel absence the same way -- fall
+ * back to polling rather than surfacing an error.
+ */
+export function resolvePushChannelTarget(dir: string = daemonStateDir()): PushChannelTarget | undefined {
+	const handle = readDaemonHandle(dir);
+	if (!handle) return undefined;
+	return { url: `${handle.baseUrl.replace(/^http/, "ws")}/push`, token: handle.token };
+}

package/src/daemon.ts

@@ -1,18 +1,47 @@
+import { PushChannel } from "@danypops/daemon-kit/push-channel";
 import { DAEMON_HOST, DB_OPTIMIZE_INTERVAL_MS, WAL_CHECKPOINT_INTERVAL_MS, dbPath } from "./constants.ts";
 import { clearDaemonPort, daemonStateDir, loadOrCreateToken, writeDaemonPort } from "./daemon-state.ts";
 import { createApp, createPapyrusService } from "./service.ts";
 import { logEvent } from "./log.ts";
 
+/**
+ * Operations that never change what a Task-graph reader (the pi-papyrus widget's
+ * push subscriber) would see -- excluded from the "tasks" publish so a read call
+ * doesn't trigger a pointless extra refresh. Defaults to publishing for anything
+ * not in this set, including future operations -- a missed push (stale widget for
+ * up to one poll interval, the existing fallback) is a far smaller cost than a
+ * silently-uncovered new mutation.
+ */
+const TASK_READ_ONLY_OPERATIONS = new Set([
+	"tasks.active", "tasks.context", "tasks.event_feed", "tasks.focused",
+	"tasks.graph", "tasks.history", "tasks.list", "tasks.plan", "tasks.scope", "tasks.show",
+]);
+
 /** Start the supervised, long-running Papyrus service. */
 export function serveMain(): void {
 	const stateDir = daemonStateDir();
 	const token = loadOrCreateToken(stateDir);
 	const service = createPapyrusService(dbPath());
-	const app = createApp({ service, token });
+	const pushChannel = new PushChannel({ token });
+	const app = createApp({
+		service,
+		token,
+		onOperationExecuted: (operation) => {
+			if (operation.startsWith("tasks.") && !TASK_READ_ONLY_OPERATIONS.has(operation)) {
+				pushChannel.publish("tasks", { operation });
+			}
+		},
+	});
 	const server = Bun.serve({
 		hostname: DAEMON_HOST,
 		port: 0,
-		fetch: (request) => app.fetch(request),
+		fetch: (request, bunServer) => {
+			if (new URL(request.url).pathname === "/push") return pushChannel.upgrade(request, bunServer) ?? undefined;
+			return app.fetch(request);
+		},
+		// A no-op fallback when pushChannel never calls server.upgrade() is safe: Bun only
+		// invokes these handlers for a connection that actually upgraded.
+		websocket: pushChannel.websocketHandlers(),
 	});
 	if (!server.port) {
 		service.close();

package/src/discussion-service.ts

@@ -192,7 +192,10 @@ export class Discussions {
 
 	show(discussionId: string): DiscussionAndRounds {
 		const discussion = requireDiscussion(this.artifacts.get(discussionId), discussionId);
-		return { discussion, rounds: this.rounds.list({ discussionId }) };
+		// DISCUSSION_MAX_ROUNDS is the hard cap enforced at reply() time, so fetching exactly that
+		// many always returns the complete transcript -- never the round store's own smaller
+		// default page size, which would silently drop the tail of a long deliberation.
+		return { discussion, rounds: this.rounds.list({ discussionId, limit: DISCUSSION_MAX_ROUNDS }) };
 	}
 
 	listRounds(discussionId: string, afterRound?: number, limit?: number): DiscussionRound[] {

package/src/index.ts

@@ -19,7 +19,7 @@ export type { TaskViewSelection } from "./domain/task-scope.ts";
 export type { ArtifactStore } from "./ports/artifact-store.ts";
 export type { GraphRenderer } from "./ports/graph-renderer.ts";
 
-export { connectPapyrusClient, type PapyrusClient } from "./client.ts";
+export { connectPapyrusClient, resolvePushChannelTarget, type PapyrusClient, type PushChannelTarget } from "./client.ts";
 export type { DiscussionAndRounds } from "./discussion-service.ts";
 export { NOTE_DISPOSITIONS } from "./note-service.ts";
 export type { OperationName, SchemaState } from "./service.ts";

package/src/modules/discuss.ts

@@ -12,10 +12,15 @@ type OperationInput = Record<string, unknown>;
 
 function string(input: OperationInput, key: string): string {
 	const value = input[key];
-	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required`);
+	if (typeof value !== "string" || value.length === 0) throw new Error(`${key} is required${REQUIRED_FIELD_HINTS[key] ? ` (${REQUIRED_FIELD_HINTS[key]})` : ""}`);
 	return value;
 }
 
+/** Fields whose name alone doesn't say what a valid value looks like -- everything else (title, content, id, settlement) is self-explanatory. */
+const REQUIRED_FIELD_HINTS: Record<string, string> = {
+	actor: 'a display name for who is posting, e.g. "alice" or "agent"',
+};
+
 function optionalString(input: OperationInput, key: string): string | undefined {
 	const value = input[key];
 	if (value === undefined) return undefined;

package/src/service.ts

@@ -534,7 +534,17 @@ async function readOperationBody(request: Request): Promise<{ op?: unknown; inpu
 	return JSON.parse(new TextDecoder().decode(bytes)) as { op?: unknown; input?: unknown };
 }
 
-export function createApp(deps: { service: PapyrusService; token: string }): { fetch(request: Request): Promise<Response> } {
+export function createApp(deps: {
+	service: PapyrusService;
+	token: string;
+	/**
+	 * Fired after an operation executes successfully -- decoupled from any specific
+	 * consumer (push-invalidation, audit logging, metrics) so this HTTP layer stays
+	 * agnostic of what a caller does with the notification. The composition root
+	 * (daemon.ts) wires this to a PushChannel; tests and other embedders can ignore it.
+	 */
+	onOperationExecuted?: (operation: string, input: OperationInput) => void;
+}): { fetch(request: Request): Promise<Response> } {
 	return {
 		async fetch(request: Request): Promise<Response> {
 			if (request.headers.get("authorization") !== `Bearer ${deps.token}`) {
@@ -555,7 +565,9 @@ export function createApp(deps: { service: PapyrusService; token: string }): { f
 					if (typeof input !== "object" || input === null || Array.isArray(input)) {
 						return json({ error: "input must be an object" }, { status: 400 });
 					}
-					return json({ result: await deps.service.execute(body.op, input as OperationInput) });
+					const result = await deps.service.execute(body.op, input as OperationInput);
+					deps.onOperationExecuted?.(body.op, input as OperationInput);
+					return json({ result });
 				} catch (error) {
 					const status = error instanceof PayloadTooLargeError ? 413 : error instanceof UnknownOperationError ? 404 : error instanceof InvalidSessionSecretError ? 403 : 400;
 					return json({ error: error instanceof Error ? error.message : String(error) }, { status });