@danypops/tickets 0.12.0 → 0.14.0

package/src/rpc/server.ts

@@ -11,11 +11,19 @@ import type { VehicleRegistry } from "@danypops/vehicle-server";
 import { createVehicleHttpApp } from "@danypops/vehicle-server/http";
 import type { Logger } from "@danypops/vehicle-server/logging";
 import { errorResponse, healthResponse, jsonResponse, readyResponse, requireBearerToken } from "@danypops/vehicle-server/rpc-http";
+import {
+  isSessionRegistered,
+  registerSessionIdentity,
+  releaseSessionIdentity,
+  verifySessionSecret,
+} from "@danypops/vehicle-server/session-identity";
 import { parseRef } from "../issue/issue.js";
 import type { TicketService } from "../issue/service.js";
 import { FocusError, type FocusStore } from "../sqlite/focus.js";
 import type { Ledger } from "../sqlite/ledger.js";
 import { SavedQueryNotFoundError, type SavedQueryStore } from "../sqlite/saved-queries.js";
+import { SessionAuthError, type SqliteSessionIdentityStore } from "../sqlite/session-identity.js";
+import type { WatchStore } from "../sqlite/watches.js";
 import type { StagePayload, StageStore } from "../stage/store.js";
 import { statusForKnownTicketError } from "./error-status.js";
 import { type StagePushResult, TICKET_OPERATIONS, type TicketOperation, type TicketOpInputs, type TicketOpOutputs } from "./ops.js";
@@ -25,6 +33,7 @@ export interface TicketsAppDeps {
   ledger: Ledger;
   focusStore: FocusStore;
   queries: SavedQueryStore;
+  sessionIdentity: SqliteSessionIdentityStore;
   token: string;
   version: string;
   logger?: Logger;
@@ -45,6 +54,20 @@ export interface TicketsAppDeps {
    */
   vehicleRegistry: VehicleRegistry;
   stageStore: StageStore;
+  watches: WatchStore;
+}
+
+/**
+ * The subset of a Vehicle call's own identity a handful of handlers read for a sensible default --
+ * see issue.subscribe/query.subscribe below, which default subscriberId/projectRoot from these
+ * when the caller doesn't pass them explicitly, mirroring @danypops/pipes' own ci.subscribe.
+ * Always undefined-safe: absent entirely for the raw HTTP /api/v1/ops dispatch (which has no Pi
+ * session behind it), present when the call came through agent-tools/tickets-vehicle.ts's
+ * Vehicle registration (see its own VehicleOperationContext.callerSessionId/callerProjectRoot).
+ */
+export interface HandlerCallContext {
+  callerSessionId?: string;
+  callerProjectRoot?: string;
 }
 
 // Narrower than TicketsAppDeps on purpose: no real handler reads
@@ -53,6 +76,7 @@ export interface TicketsAppDeps {
 export type Handler<Op extends TicketOperation> = (
   deps: Omit<TicketsAppDeps, "vehicleRegistry">,
   input: TicketOpInputs[Op],
+  callContext?: HandlerCallContext,
 ) => Promise<TicketOpOutputs[Op]>;
 
 /**
@@ -61,6 +85,28 @@ export type Handler<Op extends TicketOperation> = (
  * VehicleRegistry projection -- never reimplemented a second time for the
  * newer surface.
  */
+/**
+ * Resolves which Focus scope a focus.* call actually targets, and enforces the one place a
+ * caller-supplied session id is behavior-affecting in this daemon (see sqlite/session-identity.ts's
+ * own doc comment): an EXPLICIT input.sessionId must present the matching sessionSecret if that
+ * session id is registered; an unregistered one (or the implicit callContext.callerSessionId
+ * default -- never model-settable, since it's not part of any operation's declared input schema)
+ * passes through unarmored. input.sessionId always wins over callContext.callerSessionId, the
+ * same precedence issue.subscribe/query.subscribe already established for subscriberId.
+ */
+function resolveFocusScope(
+  deps: Pick<TicketsAppDeps, "sessionIdentity">,
+  input: { sessionId?: string; sessionSecret?: string },
+  callContext: HandlerCallContext | undefined,
+): string | undefined {
+  const explicit = input.sessionId;
+  if (explicit === undefined) return callContext?.callerSessionId;
+  if (isSessionRegistered(deps.sessionIdentity, explicit) && !verifySessionSecret(deps.sessionIdentity, explicit, input.sessionSecret)) {
+    throw new SessionAuthError(`session "${explicit}" is registered but the given secret does not match`);
+  }
+  return explicit;
+}
+
 export const TICKET_OP_HANDLERS: { [Op in TicketOperation]: Handler<Op> } = {
   "backends.list": async (deps) => ({ backends: deps.service.backendCapabilities() }),
   "issue.list": async (deps, input) => ({ issues: await deps.service.list(input.backend, input.filter) }),
@@ -76,7 +122,8 @@ export const TICKET_OP_HANDLERS: { [Op in TicketOperation]: Handler<Op> } = {
   "issue.merge": async (deps, input) => ({ issue: await deps.service.merge(input.ref, input.method) }),
   "ledger.search": async (deps, input) => ({ issues: deps.ledger.search(input.query, input.limit, input.backend) }),
   "ledger.stats": async (deps) => ({ backends: deps.ledger.stats() }),
-  "focus.set": async (deps, input) => {
+  "focus.set": async (deps, input, callContext) => {
+    const scope = resolveFocusScope(deps, input, callContext);
     // Ledger-first: focusing a ticket already pooled locally needs no live
     // backend call. Otherwise fall back to a live get (also validates the
     // ref actually exists) and opportunistically warm the ledger with it,
@@ -86,12 +133,25 @@ export const TICKET_OP_HANDLERS: { [Op in TicketOperation]: Handler<Op> } = {
     const issue = cached ?? (await deps.service.get(input.ref));
     if (!cached) deps.ledger.upsert(parseRef(input.ref).backend, issue);
     if (!issue.url) throw new FocusError(`issue "${input.ref}" has no URL from its backend; cannot focus without a full link`);
-    return { focus: deps.focusStore.set(input.ref, issue.title, issue.url) };
+    return { focus: deps.focusStore.set(input.ref, issue.title, issue.url, scope) };
+  },
+  "focus.get": async (deps, input, callContext) => ({
+    focus: deps.focusStore.get(resolveFocusScope(deps, input, callContext)) ?? null,
+  }),
+  "focus.pause": async (deps, input, callContext) => ({
+    focus: deps.focusStore.pause(input.reason, resolveFocusScope(deps, input, callContext)),
+  }),
+  "focus.unpause": async (deps, input, callContext) => ({
+    focus: deps.focusStore.unpause(resolveFocusScope(deps, input, callContext)),
+  }),
+  "focus.clear": async (deps, input, callContext) => ({
+    cleared: deps.focusStore.clear(resolveFocusScope(deps, input, callContext)),
+  }),
+  "session.register": async (deps, input) => registerSessionIdentity(deps.sessionIdentity, input.sessionId),
+  "session.release": async (deps, input) => {
+    releaseSessionIdentity(deps.sessionIdentity, input.sessionId, input.sessionSecret);
+    return { released: true };
   },
-  "focus.get": async (deps) => ({ focus: deps.focusStore.get() ?? null }),
-  "focus.pause": async (deps, input) => ({ focus: deps.focusStore.pause(input.reason) }),
-  "focus.unpause": async (deps) => ({ focus: deps.focusStore.unpause() }),
-  "focus.clear": async (deps) => ({ cleared: deps.focusStore.clear() }),
   "discover.fields": async (deps, input) => ({ mappings: await deps.service.discoverFields(input.backend) }),
   "discover.statuses": async (deps, input) => ({ mappings: await deps.service.discoverStatuses(input.backend) }),
   "discover.template": async (deps, input) => ({
@@ -109,6 +169,37 @@ export const TICKET_OP_HANDLERS: { [Op in TicketOperation]: Handler<Op> } = {
     if (!saved) throw new SavedQueryNotFoundError(input.name);
     return { issues: await deps.service.runQuery(saved.backend, saved.query, input.limit) };
   },
+  "issue.subscribe": async (deps, input, callContext) => {
+    const subscriberId = input.subscriberId ?? callContext?.callerSessionId ?? "";
+    const projectRoot = input.projectRoot ?? callContext?.callerProjectRoot;
+    deps.watches.subscribeIssue(input.ref, { subscriberId, scheduleMs: input.scheduleMs, projectRoot });
+    return { subscribed: true };
+  },
+  "issue.unsubscribe": async (deps, input, callContext) => {
+    deps.watches.unsubscribeIssue(input.ref, input.subscriberId ?? callContext?.callerSessionId ?? "");
+    return { unsubscribed: true };
+  },
+  "issue.subscribed": async (deps, input, callContext) => ({
+    watches: deps.watches.issueSubscriptionsFor(input.subscriberId ?? callContext?.callerSessionId ?? ""),
+  }),
+  "query.subscribe": async (deps, input, callContext) => {
+    const subscriberId = input.subscriberId ?? callContext?.callerSessionId ?? "";
+    const projectRoot = input.projectRoot ?? callContext?.callerProjectRoot;
+    deps.watches.subscribeQuery(input.name, { subscriberId, scheduleMs: input.scheduleMs, projectRoot });
+    return { subscribed: true };
+  },
+  "query.unsubscribe": async (deps, input, callContext) => {
+    deps.watches.unsubscribeQuery(input.name, input.subscriberId ?? callContext?.callerSessionId ?? "");
+    return { unsubscribed: true };
+  },
+  "query.subscribed": async (deps, input, callContext) => ({
+    watches: deps.watches.queryWatchSubscriptionsFor(input.subscriberId ?? callContext?.callerSessionId ?? ""),
+  }),
+  "watch.events": async (deps, input, callContext) => {
+    const subscriberId = input.subscriberId ?? callContext?.callerSessionId ?? "";
+    const events = deps.watches.eventsSince(subscriberId, input.sinceId ?? 0, input.limit);
+    return { events, lastId: events.at(-1)?.id ?? input.sinceId ?? 0 };
+  },
   "stage.add": async (deps, input) => ({ item: deps.stageStore.add(input.payload) }),
   "stage.list": async (deps) => ({ items: deps.stageStore.list() }),
   "stage.show": async (deps, input) => ({ item: deps.stageStore.show(input.id) }),

package/src/sqlite/focus.ts

@@ -1,12 +1,17 @@
 /**
- * Focus — the single ticket currently being worked on, independent of any
- * one CLI invocation or tool call. Unlike the Ledger (a cache of every issue
- * the daemon has ever seen), Focus is a pointer: one ref, its resolved title
+ * Focus — the ticket currently being worked on, independent of any one CLI
+ * invocation or tool call. Unlike the Ledger (a cache of every issue the
+ * daemon has ever seen), Focus is a pointer: one ref, its resolved title
  * and full web URL, and whether work on it is active or paused. Persisted
- * so it survives daemon restarts. A singleton by design — there is never
- * more than one ticket in focus at a time, so setting focus always replaces
- * whatever was there, the same way switching your attention to a different
- * ticket in real life replaces what you were just looking at.
+ * so it survives daemon restarts.
+ *
+ * One Focus per *scope*, not a single global singleton -- mirrors Papyrus's
+ * own Task Focus (stores/task-focus-store.ts / stores/sqlite-task-focus-store.ts)
+ * one domain over: a scope defaults to "global" for a caller that doesn't
+ * supply one (the bare CLI, legacy behavior, exactly today's pre-scoping
+ * shape), but is normally the requesting Pi session's own id, so two
+ * concurrent agents/terminals each get their own Focus instead of
+ * clobbering a shared one.
  */
 import type { Database } from "bun:sqlite";
 import type { Migration } from "@danypops/vehicle-server/storage";
@@ -28,6 +33,28 @@ export const FOCUS_MIGRATIONS: Migration[] = [
       `);
     },
   },
+  {
+    // Re-keys ticket_focus from a hardcoded id=1 singleton to one row per scope. Focus is a
+    // pointer, not historical data -- dropping and recreating (rather than an in-place
+    // ALTER TABLE + backfill) is a deliberate, acceptable loss of whatever was focused before
+    // this migration runs, the same way Papyrus's own equivalent migration didn't attempt to
+    // carry a pre-scoping global focus forward into some arbitrary scope.
+    version: 5,
+    up: (db) => {
+      db.exec("DROP TABLE IF EXISTS ticket_focus;");
+      db.exec(`
+        CREATE TABLE ticket_focus (
+          scope TEXT PRIMARY KEY,
+          ref TEXT NOT NULL,
+          title TEXT NOT NULL,
+          url TEXT NOT NULL,
+          status TEXT NOT NULL,
+          pause_reason TEXT,
+          updated_at TEXT NOT NULL
+        );
+      `);
+    },
+  },
 ];
 
 export type FocusStatus = "active" | "paused";
@@ -49,7 +76,24 @@ export class FocusError extends Error {
   }
 }
 
+export const FOCUS_DEFAULT_SCOPE = "global";
+export const FOCUS_SCOPE_MAX_LENGTH = 128;
+/** Bounds distinct concurrent focus scopes (sessions); the least-recently-updated scope is evicted beyond this, mirroring Papyrus's TASK_FOCUS_MAX_SCOPES. */
+export const FOCUS_MAX_SCOPES = 200;
+/** A scope untouched this long is eligible for time-based reaping (see FocusStore.reapStale), independent of FOCUS_MAX_SCOPES's own eviction. 30 days, matching Papyrus's TASK_FOCUS_STALE_AFTER_MS convention. */
+export const FOCUS_STALE_AFTER_MS = 30 * 24 * 60 * 60 * 1000;
+
+/** An absent/empty scope defaults to "global" -- the bare CLI / legacy single-focus behavior; a real scope (normally a Pi session id) passes through unchanged. */
+export function normalizeFocusScope(scope: string | undefined): string {
+  const value = scope && scope.length > 0 ? scope : FOCUS_DEFAULT_SCOPE;
+  if (value.length > FOCUS_SCOPE_MAX_LENGTH) {
+    throw new FocusError(`focus scope must be at most ${FOCUS_SCOPE_MAX_LENGTH} characters`);
+  }
+  return value;
+}
+
 interface FocusRow {
+  scope: string;
   ref: string;
   title: string;
   url: string;
@@ -72,55 +116,72 @@ function rowToState(row: FocusRow): TicketFocusState {
 export class FocusStore {
   constructor(private readonly db: Database) {}
 
-  get(): TicketFocusState | undefined {
+  get(scope?: string): TicketFocusState | undefined {
     const row = this.db
-      .query("SELECT ref, title, url, status, pause_reason, updated_at FROM ticket_focus WHERE id = 1")
-      .get() as FocusRow | null;
+      .query("SELECT scope, ref, title, url, status, pause_reason, updated_at FROM ticket_focus WHERE scope = $scope")
+      .get({ $scope: normalizeFocusScope(scope) }) as FocusRow | null;
     return row ? rowToState(row) : undefined;
   }
 
   /** Always lands "active" and drops any prior pause reason: switching focus onto a different ticket is not the same as resuming a pause on the old one. */
-  set(ref: string, title: string, url: string): TicketFocusState {
+  set(ref: string, title: string, url: string, scope?: string): TicketFocusState {
+    const key = normalizeFocusScope(scope);
     const updatedAt = new Date().toISOString();
+    this.evictOldestBeyondCap(key);
     this.db
       .query(
-        `INSERT INTO ticket_focus (id, ref, title, url, status, pause_reason, updated_at)
-         VALUES (1, $ref, $title, $url, 'active', NULL, $updatedAt)
-         ON CONFLICT(id) DO UPDATE SET
+        `INSERT INTO ticket_focus (scope, ref, title, url, status, pause_reason, updated_at)
+         VALUES ($scope, $ref, $title, $url, 'active', NULL, $updatedAt)
+         ON CONFLICT(scope) DO UPDATE SET
            ref = excluded.ref, title = excluded.title, url = excluded.url,
            status = 'active', pause_reason = NULL, updated_at = excluded.updated_at`,
       )
-      .run({ $ref: ref, $title: title, $url: url, $updatedAt: updatedAt });
+      .run({ $scope: key, $ref: ref, $title: title, $url: url, $updatedAt: updatedAt });
     return { ref, title, url, status: "active", updatedAt };
   }
 
-  pause(reason?: string): TicketFocusState {
-    const current = this.get();
+  pause(reason?: string, scope?: string): TicketFocusState {
+    const current = this.get(scope);
     if (!current) throw new FocusError("no ticket is currently focused");
     if (current.status === "paused") throw new FocusError(`focus on "${current.ref}" is already paused`);
-    return this.transition("paused", reason);
+    return this.transition("paused", reason, scope);
   }
 
-  unpause(): TicketFocusState {
-    const current = this.get();
+  unpause(scope?: string): TicketFocusState {
+    const current = this.get(scope);
     if (!current) throw new FocusError("no ticket is currently focused");
     if (current.status === "active") throw new FocusError(`focus on "${current.ref}" is already active`);
-    return this.transition("active", undefined);
+    return this.transition("active", undefined, scope);
   }
 
-  /** Returns whether a focus existed to clear (idempotent either way). */
-  clear(): boolean {
-    const existed = this.get() !== undefined;
-    this.db.exec("DELETE FROM ticket_focus WHERE id = 1");
+  /** Returns whether a focus existed in this scope to clear (idempotent either way). */
+  clear(scope?: string): boolean {
+    const existed = this.get(scope) !== undefined;
+    this.db.query("DELETE FROM ticket_focus WHERE scope = $scope").run({ $scope: normalizeFocusScope(scope) });
     return existed;
   }
 
-  private transition(status: FocusStatus, reason: string | undefined): TicketFocusState {
+  /** Deletes every scope's row whose updatedAt is strictly before olderThanIso (see FOCUS_STALE_AFTER_MS). Returns how many rows were removed. */
+  reapStale(olderThanIso: string): number {
+    return this.db.query("DELETE FROM ticket_focus WHERE updated_at < $cutoff").run({ $cutoff: olderThanIso }).changes;
+  }
+
+  private transition(status: FocusStatus, reason: string | undefined, scope: string | undefined): TicketFocusState {
+    const key = normalizeFocusScope(scope);
     const updatedAt = new Date().toISOString();
     this.db
-      .query("UPDATE ticket_focus SET status = $status, pause_reason = $reason, updated_at = $updatedAt WHERE id = 1")
-      .run({ $status: status, $reason: reason ?? null, $updatedAt: updatedAt });
-    // Non-null: transition() is only ever called right after get() confirmed a row exists.
-    return this.get()!;
+      .query("UPDATE ticket_focus SET status = $status, pause_reason = $reason, updated_at = $updatedAt WHERE scope = $scope")
+      .run({ $scope: key, $status: status, $reason: reason ?? null, $updatedAt: updatedAt });
+    // Non-null: transition() is only ever called right after get() confirmed a row exists for this scope.
+    return this.get(key)!;
+  }
+
+  /** Evicts the least-recently-updated scope once a brand-new scope would push the total beyond FOCUS_MAX_SCOPES. A no-op for a scope that already has a row (set() on an existing scope never counts as growth). */
+  private evictOldestBeyondCap(key: string): void {
+    const exists = this.db.query("SELECT 1 FROM ticket_focus WHERE scope = $scope").get({ $scope: key });
+    if (exists) return;
+    const count = (this.db.query("SELECT COUNT(*) AS count FROM ticket_focus").get() as { count: number }).count;
+    if (count < FOCUS_MAX_SCOPES) return;
+    this.db.exec("DELETE FROM ticket_focus WHERE scope = (SELECT scope FROM ticket_focus ORDER BY updated_at ASC LIMIT 1)");
   }
 }

package/src/sqlite/session-identity.ts

@@ -0,0 +1,94 @@
+/**
+ * Sqlite-backed SessionIdentityStore adapter for @danypops/vehicle-server's own
+ * generic session-identity primitive (secret generation/hashing/constant-time
+ * verify) -- this file only wires that primitive to sqlite, the same split
+ * Papyrus's own stores/sqlite-session-identity-store.ts makes.
+ *
+ * Hardens the one place a caller-supplied session id becomes BEHAVIOR-affecting
+ * in this daemon: focus.set/pause/unpause/clear, once a caller passes an EXPLICIT
+ * sessionId (see rpc/server.ts's own TICKET_OP_HANDLERS) -- this daemon, like
+ * Papyrus's, authenticates every client with one shared bearer token, so a bare
+ * session id alone is not a credential once it can redirect/pause/clear someone
+ * else's live Focus. Opt-in armor: a session id that was never registered
+ * (the implicit callContext.callerSessionId default from a real Vehicle tool
+ * call, or a bare CLI caller) passes through unarmored, exactly as today.
+ */
+import type { Database } from "bun:sqlite";
+import type { SessionIdentityRecord, SessionIdentityStore } from "@danypops/vehicle-server/session-identity";
+import type { Migration } from "@danypops/vehicle-server/storage";
+
+/** An explicit sessionId claim (see rpc/server.ts's resolveFocusScope) against a REGISTERED session id, with a missing or wrong sessionSecret. Maps to HTTP 401, not 400 -- this is an authorization failure, not a validation one. */
+export class SessionAuthError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "SessionAuthError";
+  }
+}
+
+export const SESSION_IDENTITY_MIGRATIONS: Migration[] = [
+  {
+    version: 6,
+    up: (db) => {
+      db.exec(`
+        CREATE TABLE session_identities (
+          session_id TEXT PRIMARY KEY,
+          secret_hash TEXT NOT NULL,
+          registered_at TEXT NOT NULL,
+          last_seen_at TEXT NOT NULL
+        );
+      `);
+    },
+  },
+];
+
+interface SessionIdentityRow {
+  session_id: string;
+  secret_hash: string;
+  registered_at: string;
+  last_seen_at: string;
+}
+
+function rowToRecord(row: SessionIdentityRow): SessionIdentityRecord {
+  return { sessionId: row.session_id, secretHash: row.secret_hash, registeredAt: row.registered_at, lastSeenAt: row.last_seen_at };
+}
+
+export class SqliteSessionIdentityStore implements SessionIdentityStore {
+  constructor(private readonly db: Database) {}
+
+  find(sessionId: string): SessionIdentityRecord | undefined {
+    const row = this.db
+      .query("SELECT session_id, secret_hash, registered_at, last_seen_at FROM session_identities WHERE session_id = $sessionId")
+      .get({ $sessionId: sessionId }) as SessionIdentityRow | null;
+    return row ? rowToRecord(row) : undefined;
+  }
+
+  upsert(record: SessionIdentityRecord): void {
+    this.db
+      .query(
+        `INSERT INTO session_identities (session_id, secret_hash, registered_at, last_seen_at)
+         VALUES ($sessionId, $secretHash, $registeredAt, $lastSeenAt)
+         ON CONFLICT(session_id) DO UPDATE SET
+           secret_hash = excluded.secret_hash, registered_at = excluded.registered_at, last_seen_at = excluded.last_seen_at`,
+      )
+      .run({
+        $sessionId: record.sessionId,
+        $secretHash: record.secretHash,
+        $registeredAt: record.registeredAt,
+        $lastSeenAt: record.lastSeenAt,
+      });
+  }
+
+  remove(sessionId: string): void {
+    this.db.query("DELETE FROM session_identities WHERE session_id = $sessionId").run({ $sessionId: sessionId });
+  }
+
+  touch(sessionId: string, lastSeenAt: string): void {
+    this.db
+      .query("UPDATE session_identities SET last_seen_at = $lastSeenAt WHERE session_id = $sessionId")
+      .run({ $sessionId: sessionId, $lastSeenAt: lastSeenAt });
+  }
+
+  count(): number {
+    return (this.db.query("SELECT COUNT(*) AS count FROM session_identities").get() as { count: number }).count;
+  }
+}