@teamscala/service-boot 0.23.308 → 0.23.310

package/package.json

@@ -6,7 +6,7 @@
   },
   "name": "@teamscala/service-boot",
   "type": "module",
-  "version": "0.23.308",
+  "version": "0.23.310",
   "sideEffects": false,
   "files": [
     "src"

package/src/fn-routers/task-sync-assign.d.ts

@@ -55,6 +55,7 @@
  */
 import * as v from "valibot";
 import type { Prisma, WorkItem } from "./task-sync-router.ts";
+import { type Context } from "./auth-router.ts";
 /**
  * The assignment input. `name` + `description` are REQUIRED TOGETHER at the
  * signature: oRPC parses this schema before the handler runs, so a call missing
@@ -194,3 +195,46 @@ export interface AssignmentResult {
     task: WorkItem;
     emitted: boolean;
 }
+/**
+ * createBriefTask ORPC input. The MINT entry point a spawner calls to turn a
+ * raw brief into the task row a lane self-briefs from. `name` is the lane's work
+ * label (the spawner's windowName); `description` is the brief, stored as the
+ * task's FIRST COMMENT — never on the task row itself, so "the brief" has
+ * exactly one home (`task-sync-brief.ts` readLatestTaskComment, newest-first).
+ * Mirrors `assignTaskInput` minus the spawn-shaping fields (slug/windowName/
+ * idempotencyKey), which belong on the spawn emission, not the mint.
+ */
+export declare const createBriefTaskInput: v.ObjectSchema<{
+    readonly name: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "name is required — the lane's work label">]>;
+    readonly description: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.MinLengthAction<string, 1, "description is required — it is the brief (first comment)">]>;
+    readonly parent_id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+    readonly organisation_id: v.OptionalSchema<v.StringSchema<undefined>, undefined>;
+}, undefined>;
+/**
+ * createBriefTask ORPC handler. `spawn_agent_tab` calls this when it receives
+ * an `initialPrompt` with no `workItemId`: the prompt becomes the task's first
+ * comment, the returned `work_item_id` rides the spawn payload as `workItemId`,
+ * and the lane PULLS the brief at boot (`readAssignedBrief`) — no keystroke, no
+ * channel send, no positional argument. That deletes the keystroke-brief
+ * failure class by construction (`buildAssignmentSpawnPayload` already carries
+ * `workItemId` and never `initialPrompt`).
+ *
+ * Wraps the pure `createTaskWithBriefComment` (atomic task + first comment). The
+ * task is `kind:"task"`, `status:"active"`, `assignee_type:"agent"`, with NO
+ * `kind_data.lane.session`: the CLI mints the session at spawn and SessionStart
+ * ADOPTS this task by id (`adoptAssignmentTask`), which binds the brief to the
+ * lane. Returns only the `work_item_id` — the single fact the spawner needs to
+ * carry the brief without writing it into the spawn payload. Same transport as
+ * `readAssignedBrief`: page-gate-exempt (fn.taskSync), localhost super-admin.
+ */
+export declare const createBriefTaskHandler: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+    headers: Headers;
+    resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+    prisma: any;
+    user: import("./auth-router.ts").User;
+    orgId: string | null | undefined;
+}>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+    work_item_id: string;
+}, {
+    work_item_id: string;
+}>, Record<never, never>, Record<never, never>>;

package/src/fn-routers/task-sync-assign.test.ts

@@ -13,6 +13,7 @@ import { describe, it, expect } from "bun:test";
 import * as v from "valibot";
 import {
 	assignTaskInput,
+	createBriefTaskInput,
 	createTaskWithBriefComment,
 	adoptAssignmentTask,
 	bindTaskToKnownSession,
@@ -90,6 +91,37 @@ describe("assignTaskInput (incomplete task is unconstructible)", () => {
 	});
 });
 
+describe("createBriefTaskInput (the spawner's mint entry — incomplete task is unconstructible)", () => {
+	// The mint a raw initialPrompt hits: spawn_agent_tab calls createBriefTask,
+	// which validates against this schema BEFORE the handler runs. An incomplete
+	// mint (no brief) is rejected at the signature, never caught after the fact —
+	// the same gate assignTaskInput sets, on the entry point spawn_agent_tab owns.
+	it("accepts name + description together", () => {
+		const out = v.safeParse(createBriefTaskInput, {
+			name: "Spawn mints row",
+			description: "the brief text",
+		});
+		expect(out.success).toBe(true);
+	});
+
+	it("rejects a missing description — no brief, no minted task", () => {
+		expect(v.safeParse(createBriefTaskInput, { name: "X" }).success).toBe(false);
+	});
+
+	it("rejects a missing name", () => {
+		expect(v.safeParse(createBriefTaskInput, { description: "d" }).success).toBe(false);
+	});
+
+	it("rejects an empty-string description (not just absent)", () => {
+		expect(v.safeParse(createBriefTaskInput, { name: "X", description: "" }).success).toBe(false);
+	});
+
+	it("treats parent_id/organisation_id as optional (exploratory lane)", () => {
+		const out = v.safeParse(createBriefTaskInput, { name: "Explore", description: "d" });
+		expect(out.success).toBe(true);
+	});
+});
+
 describe("createTaskWithBriefComment (atomic task + first comment = brief)", () => {
 	it("creates the task active with kind_data carrying NO session, and writes the description as the first comment in the SAME transaction", async () => {
 		const { prisma, calls } = fakePrisma();

package/src/fn-routers/task-sync-assign.ts

@@ -57,6 +57,7 @@
 import { getPlatformOrgId } from "@teamscala/db/registry/platform";
 import * as v from "valibot";
 import type { Prisma, WorkItem } from "./task-sync-router.ts";
+import { authed, type Context } from "./auth-router.ts";
 
 /**
  * The assignment input. `name` + `description` are REQUIRED TOGETHER at the
@@ -288,3 +289,57 @@ export interface AssignmentResult {
 	task: WorkItem;
 	emitted: boolean;
 }
+
+/**
+ * createBriefTask ORPC input. The MINT entry point a spawner calls to turn a
+ * raw brief into the task row a lane self-briefs from. `name` is the lane's work
+ * label (the spawner's windowName); `description` is the brief, stored as the
+ * task's FIRST COMMENT — never on the task row itself, so "the brief" has
+ * exactly one home (`task-sync-brief.ts` readLatestTaskComment, newest-first).
+ * Mirrors `assignTaskInput` minus the spawn-shaping fields (slug/windowName/
+ * idempotencyKey), which belong on the spawn emission, not the mint.
+ */
+export const createBriefTaskInput = v.object({
+	name: v.pipe(v.string(), v.minLength(1, "name is required — the lane's work label")),
+	description: v.pipe(
+		v.string(),
+		v.minLength(1, "description is required — it is the brief (first comment)"),
+	),
+	parent_id: v.optional(v.string()),
+	organisation_id: v.optional(v.string()),
+});
+
+/**
+ * createBriefTask ORPC handler. `spawn_agent_tab` calls this when it receives
+ * an `initialPrompt` with no `workItemId`: the prompt becomes the task's first
+ * comment, the returned `work_item_id` rides the spawn payload as `workItemId`,
+ * and the lane PULLS the brief at boot (`readAssignedBrief`) — no keystroke, no
+ * channel send, no positional argument. That deletes the keystroke-brief
+ * failure class by construction (`buildAssignmentSpawnPayload` already carries
+ * `workItemId` and never `initialPrompt`).
+ *
+ * Wraps the pure `createTaskWithBriefComment` (atomic task + first comment). The
+ * task is `kind:"task"`, `status:"active"`, `assignee_type:"agent"`, with NO
+ * `kind_data.lane.session`: the CLI mints the session at spawn and SessionStart
+ * ADOPTS this task by id (`adoptAssignmentTask`), which binds the brief to the
+ * lane. Returns only the `work_item_id` — the single fact the spawner needs to
+ * carry the brief without writing it into the spawn payload. Same transport as
+ * `readAssignedBrief`: page-gate-exempt (fn.taskSync), localhost super-admin.
+ */
+export const createBriefTaskHandler = authed.handler(async ({ input, context }) => {
+	const ctx = context as Context;
+	const prisma = ctx.prisma as Prisma;
+	const data = input as v.InferOutput<typeof createBriefTaskInput>;
+	const userId = (ctx.user as { id: string }).id;
+	const task = await createTaskWithBriefComment(
+		prisma,
+		{
+			name: data.name,
+			description: data.description,
+			parent_id: data.parent_id,
+			organisation_id: resolveAssignOrg(data.organisation_id),
+		},
+		userId,
+	);
+	return { work_item_id: task.id };
+});

package/src/fn-routers/task-sync-router.d.ts

@@ -319,6 +319,18 @@ export declare const taskSyncRouter: {
         brief: string | null;
         comment_created_at: string | null;
     }>, Record<never, never>, Record<never, never>>;
+    /** SPAWNER→DB brief mint: `spawn_agent_tab` turns an initialPrompt into the task row (brief = first comment) the lane self-briefs from; returns the work_item_id that rides the spawn payload. Handler in task-sync-assign.ts. */
+    createBriefTask: import("@orpc/server").DecoratedProcedure<import("@orpc/server").MergedInitialContext<Context & Record<never, never>, Context, Context>, import("@orpc/server").MergedCurrentContext<Context, {
+        headers: Headers;
+        resolveUser?: (headers: Headers, prisma: any) => Promise<import("./auth-router.ts").User | null>;
+        prisma: any;
+        user: import("./auth-router.ts").User;
+        orgId: string | null | undefined;
+    }>, import("@orpc/contract").Schema<unknown, unknown>, import("@orpc/contract").Schema<{
+        work_item_id: string;
+    }, {
+        work_item_id: string;
+    }>, Record<never, never>, Record<never, never>>;
     /**
      * DB→AGENT realtime leg (explicit dispatch path). Record an out-of-band
      * change to a subtask's status (operator toggles it in the projects UI,

package/src/fn-routers/task-sync-router.ts

@@ -42,7 +42,7 @@ import { authed, type Context } from "./auth-router.ts";
 import { notifyLaneOfTaskChange } from "./task-sync-dispatch.ts";
 import { resolveLaneTask, resolveLaneWorkName } from "./task-sync-lane.ts";
 import { readAssignedBriefHandler } from "./task-sync-brief.ts";
-import { adoptAssignmentTask } from "./task-sync-assign.ts";
+import { adoptAssignmentTask, createBriefTaskHandler } from "./task-sync-assign.ts";
 import * as v from "valibot";
 import {
 	STATUS_TO_WORK_ITEM,
@@ -949,6 +949,9 @@ export const taskSyncRouter = {
 	 */
 	readAssignedBrief: readAssignedBriefHandler,
 
+	/** SPAWNER→DB brief mint: `spawn_agent_tab` turns an initialPrompt into the task row (brief = first comment) the lane self-briefs from; returns the work_item_id that rides the spawn payload. Handler in task-sync-assign.ts. */
+	createBriefTask: createBriefTaskHandler,
+
 	/**
 	 * DB→AGENT realtime leg (explicit dispatch path). Record an out-of-band
 	 * change to a subtask's status (operator toggles it in the projects UI,

package/src/pg-boss-mount.ts

@@ -204,8 +204,15 @@ export async function mountPgBoss(
 			// underlying SQL is ON CONFLICT DO NOTHING, so calling it on every
 			// boot is a safe idempotent assert, never a duplicate-creation error.
 			await boss.createQueue(queueName);
-			await boss.work(queueName, async (job) => {
-				return await resolveHandler(config.handler_slug, config, job?.data);
+			await boss.work(queueName, async (jobs) => {
+				let result: unknown;
+				for (const job of jobs) {
+					result = await resolveHandler(config.handler_slug, config, job.data);
+				}
+				// pg-boss stores the work handler return as job output when
+				// exactly one job was processed (manager.js complete()). For
+				// batch/scheduled jobs the return is not stored.
+				return jobs.length === 1 ? result : undefined;
 			});
 
 			if (config.cron) {