@mastra/factory 0.24.0-alpha.1 → 0.24.0-alpha.10

package/dist/tools/work-item-tools.js

@@ -0,0 +1,342 @@
+import { boardForWorkItem } from "../boards/semantics.js";
+import "../boards/index.js";
+import { WorkItemRelationError } from "../storage/domains/work-items/base.js";
+import { requirePerson } from "./scope.js";
+import { findWorkItem, truncate, workItemNotFound, workItemNumber, workItemRefSchema, workItemStage } from "./read-tools.js";
+import { transitionBodySchema } from "../routes/contracts.js";
+import { resolveWorkItemRepository } from "../session/work-item-repository.js";
+import { createFactoryWorkItem } from "../work-items/create-work-item.js";
+import { dismissFactoryDecision, resolveFactoryProposal, retryFactoryDecision } from "../work-items/decision-actions.js";
+import { randomUUID } from "crypto";
+import { z } from "zod";
+import { createTool } from "@mastra/core/tools";
+//#region src/tools/work-item-tools.ts
+/**
+* Factory tools that change work items: file one, move it, settle its
+* decisions, and follow it. They act as the session's person (a human actor),
+* through the same code the board's routes use.
+*/
+const repositorySchema = z.string().trim().min(3).max(200).regex(/^[^/\s]+\/[^/\s]+$/, "Use the owner/name form, e.g. \"mastra-ai/mastra\".").describe("A repository linked to this Factory, as owner/name.");
+const decisionId = z.string().trim().uuid().describe("Decision id, from factory_list_attention or inspect.");
+function briefItem(item) {
+	return {
+		id: item.id,
+		number: workItemNumber(item),
+		title: truncate(item.title, 600),
+		stage: workItemStage(item)
+	};
+}
+function settled(result) {
+	if (!result.ok) throw new Error(result.message);
+	const { decision } = result;
+	return {
+		decisionId: decision.id,
+		status: decision.status,
+		workItemId: decision.workItemId
+	};
+}
+/** The work-item write and subscription tools for one user session's turn. */
+function createFactoryWorkItemTools(scope, deps) {
+	const project = {
+		orgId: scope.orgId,
+		factoryProjectId: scope.factoryProjectId
+	};
+	const audit = async (input) => {
+		await deps.auditRecorder.record({
+			orgId: scope.orgId,
+			actorId: scope.interactive ? scope.userId : `agent:session:${scope.sessionId}`,
+			actorType: scope.interactive ? "human" : "agent",
+			...scope.actorProfile ? { actorProfile: scope.actorProfile } : {},
+			...input
+		});
+	};
+	const requireItem = async (ref) => {
+		const item = await findWorkItem(deps.workItems, scope, ref);
+		if (!item) throw workItemNotFound(ref);
+		return item;
+	};
+	/**
+	* Check `slug` is a repository linked to this Factory and that a card with
+	* `metadata` would run in it (a card synced from an issue follows the
+	* issue's repository, which a slug can't override).
+	*/
+	const requireRepository = async (slug, metadata = null) => {
+		const sourceControl = await deps.sessions.getSourceControlBySessionId(scope.sessionId);
+		if (!sourceControl) throw new Error("This session has no source-control provider to look repositories up in.");
+		const resolve = (repository) => resolveWorkItemRepository({
+			sourceControl,
+			...project,
+			item: { metadata: repository ? {
+				...metadata,
+				repository
+			} : metadata }
+		});
+		const resolution = await resolve(slug);
+		if (resolution.status === "resolved" && resolution.slug === slug) return;
+		if (resolution.status === "resolved") throw new Error(`This card runs in ${resolution.slug}, which comes from its linked issue and can't be changed.`);
+		const linked = await resolve();
+		const candidates = linked.status === "ambiguous" ? linked.candidates : linked.status === "resolved" ? [linked.slug] : [];
+		throw new Error(candidates.length > 0 ? `${slug} is not linked to this Factory. Linked repositories: ${candidates.join(", ")}.` : `${slug} is not linked to this Factory, and it has no linked repositories.`);
+	};
+	const follow = (item, reason) => deps.workItems.subscribeToWorkItem({
+		...project,
+		workItemId: item.id,
+		sessionId: scope.sessionId,
+		threadId: scope.threadId,
+		resourceId: scope.resourceId,
+		userId: scope.userId,
+		reason
+	});
+	return {
+		factory_create_work_item: createTool({
+			id: "factory_create_work_item",
+			description: "File a new work item on this Factory's Work board for the person you are working with. It lands in the board's first phase, exactly like pressing New card, and this session follows it. Check factory_list_work_items for an existing item first. Name the repository when the Factory links more than one; runs refuse to start on a card that doesn't say which.",
+			inputSchema: z.object({
+				title: z.string().trim().min(1).max(512).describe("Short title, as it should read on the card."),
+				brief: z.string().trim().min(1).max(8e3).describe("What needs doing and why; posted as the first comment on the card."),
+				repository: repositorySchema.optional()
+			}).strict(),
+			execute: async ({ title, brief, repository }) => {
+				if (repository) await requireRepository(repository);
+				const created = await createFactoryWorkItem({
+					workItems: deps.workItems,
+					boards: deps.boards,
+					transitionService: deps.transitionService,
+					audit,
+					...project,
+					userId: scope.userId,
+					...scope.actorProfile ? { origin: { actorProfile: scope.actorProfile } } : {},
+					input: {
+						title,
+						...repository ? { metadata: { repository } } : {}
+					}
+				});
+				if (created.status === "refused") throw new Error(created.message);
+				if (created.status === "rejected") throw new Error(`The board refused the new item: ${created.reason}`);
+				const { item } = created;
+				const warnings = [];
+				try {
+					const comment = await deps.feed.createComment({
+						orgId: scope.orgId,
+						workItemId: item.id,
+						author: {
+							kind: "user",
+							id: scope.userId
+						},
+						body: brief
+					});
+					if (comment.status !== "created") warnings.push(`The brief was not posted (${comment.status === "invalid" ? comment.message : comment.status}).`);
+				} catch (error) {
+					warnings.push(`The brief was not posted: ${error instanceof Error ? error.message : String(error)}`);
+				}
+				try {
+					await follow(item, "created");
+				} catch (error) {
+					warnings.push(`This session does not follow it yet: ${error instanceof Error ? error.message : String(error)}`);
+				}
+				return warnings.length ? {
+					...briefItem(item),
+					warnings
+				} : briefItem(item);
+			}
+		}),
+		factory_transition_work_item: createTool({
+			id: "factory_transition_work_item",
+			description: "Move a work item to another stage of its board, as the person you are working with. The board's rules decide whether the move is allowed and what it starts.",
+			inputSchema: z.object({
+				workItem: workItemRefSchema,
+				stage: z.string().trim().min(1).max(64).describe("Destination stage, e.g. \"planning\" or \"done\".")
+			}).strict(),
+			execute: async ({ workItem, stage }) => {
+				if (!deps.transitionService) throw new Error("Factory stage transitions are not available right now.");
+				const item = await requireItem(workItem);
+				const parsed = transitionBodySchema.safeParse({
+					board: boardForWorkItem(item),
+					stage,
+					expectedRevision: item.revision,
+					requestId: randomUUID(),
+					cause: "factory_tools"
+				});
+				if (!parsed.success) throw new Error(`"${stage}" is not a valid stage name.`);
+				const result = await deps.transitionService.transition({
+					...parsed.data,
+					...project,
+					workItemId: item.id,
+					...scope.interactive ? {
+						actor: {
+							type: "human",
+							id: scope.userId
+						},
+						...scope.actorProfile ? { actorProfile: scope.actorProfile } : {},
+						ingress: {
+							...parsed.data.ingress,
+							identity: `human:${scope.userId}:${parsed.data.ingress.identity}`
+						}
+					} : {
+						actor: {
+							type: "agent",
+							bindingId: `session:${scope.sessionId}`,
+							role: "session"
+						},
+						ingress: {
+							type: "agent",
+							identity: `session:${scope.sessionId}:${parsed.data.ingress.identity}`
+						}
+					}
+				});
+				if (result.status === "rejected") throw new Error(`The move was refused (${result.code}): ${result.reason}`);
+				return {
+					workItemId: item.id,
+					stage: result.stage,
+					revision: result.revision
+				};
+			}
+		}),
+		factory_update_work_item: createTool({
+			id: "factory_update_work_item",
+			description: "Edit a work item's fields as the person you are working with: its title, the repository its runs use, its parent item, or pre-approving its plans. Move stages with factory_transition_work_item and start roles with factory_start_session; post to the card's feed for anything else.",
+			inputSchema: z.object({
+				workItem: workItemRefSchema,
+				title: z.string().trim().min(1).max(500).optional().describe("New card title."),
+				repository: repositorySchema.optional(),
+				parentWorkItem: workItemRefSchema.nullable().optional().describe("Parent work item (id or #number), or null to detach it from its parent."),
+				plansPreapproved: z.literal(true).optional().describe("Pre-approve the item's plans, so its runs no longer stop for plan approval. Can't be undone here.")
+			}).strict().refine((input) => Object.keys(input).some((key) => key !== "workItem"), "Pass at least one field to change."),
+			execute: async ({ workItem, title, repository, parentWorkItem, plansPreapproved }) => {
+				if (plansPreapproved) requirePerson(scope, "pre-approve plans");
+				const item = await requireItem(workItem);
+				if (repository) await requireRepository(repository, item.metadata);
+				let parentWorkItemId;
+				if (parentWorkItem === null) parentWorkItemId = null;
+				else if (parentWorkItem !== void 0) parentWorkItemId = (await requireItem(parentWorkItem)).id;
+				const patch = {
+					...title !== void 0 ? { title } : {},
+					...repository ? { metadata: { repository } } : {},
+					...parentWorkItemId !== void 0 ? { parentWorkItemId } : {},
+					...plansPreapproved ? { plansPreapproved } : {}
+				};
+				let updated;
+				try {
+					updated = await deps.workItems.update({
+						orgId: scope.orgId,
+						id: item.id,
+						userId: scope.userId,
+						patch
+					});
+				} catch (error) {
+					if (error instanceof WorkItemRelationError) throw new Error(`The parent was refused: ${error.message}`);
+					throw error;
+				}
+				if (!updated) throw workItemNotFound(workItem);
+				const fields = [
+					...title !== void 0 ? ["title"] : [],
+					...repository ? ["metadata"] : [],
+					...parentWorkItemId !== void 0 ? ["parentWorkItemId"] : [],
+					...plansPreapproved ? ["plansPreapproved"] : []
+				];
+				await audit({
+					action: "factory.work_item.updated",
+					factoryProjectId: scope.factoryProjectId,
+					targets: [{
+						type: "work_item",
+						id: updated.item.id,
+						name: updated.item.title
+					}],
+					metadata: {
+						fields,
+						cause: "factory_tools"
+					}
+				});
+				const metadata = updated.item.metadata ?? {};
+				return {
+					workItem: briefItem(updated.item),
+					updated: fields.map((field) => field === "metadata" ? "repository" : field),
+					repository: typeof metadata.repository === "string" ? metadata.repository : null,
+					parentWorkItemId: updated.item.parentWorkItemId,
+					plansPreapproved: updated.item.plansPreapprovedAt !== null
+				};
+			}
+		}),
+		factory_retry_decision: createTool({
+			id: "factory_retry_decision",
+			description: "Retry one failed Factory run once its cause is fixed. Refused when the failure cannot be fixed by retrying or the item has moved on.",
+			inputSchema: z.object({ decisionId }).strict(),
+			execute: async ({ decisionId }) => settled(await retryFactoryDecision({
+				workItems: deps.workItems,
+				boards: deps.boards,
+				...project,
+				decisionId
+			}))
+		}),
+		factory_dismiss_decision: createTool({
+			id: "factory_dismiss_decision",
+			description: "Dismiss one proposed Factory run that is no longer wanted.",
+			inputSchema: z.object({ decisionId }).strict(),
+			execute: async ({ decisionId }) => {
+				requirePerson(scope, "dismiss a proposed run");
+				return settled(await dismissFactoryDecision({
+					workItems: deps.workItems,
+					audit,
+					...project,
+					userId: scope.userId,
+					decisionId
+				}));
+			}
+		}),
+		factory_resolve_proposal: createTool({
+			id: "factory_resolve_proposal",
+			description: "Approve or dismiss one proposed Factory run. Approving starts the run and lets the item's later runs start without asking.",
+			inputSchema: z.object({
+				decisionId,
+				action: z.enum(["approve", "dismiss"])
+			}).strict(),
+			execute: async ({ decisionId, action }) => {
+				requirePerson(scope, "approve or dismiss a proposed run");
+				return settled(await resolveFactoryProposal({
+					workItems: deps.workItems,
+					audit,
+					...project,
+					userId: scope.userId,
+					decisionId,
+					action
+				}));
+			}
+		}),
+		factory_subscribe_work_item: createTool({
+			id: "factory_subscribe_work_item",
+			description: "Follow a work item from this session, so you hear about its progress and its sessions report to you. Items you file or start are followed already.",
+			inputSchema: z.object({ workItem: workItemRefSchema }).strict(),
+			execute: async ({ workItem }) => {
+				const item = await requireItem(workItem);
+				const subscription = await follow(item, "subscribed");
+				return {
+					workItem: briefItem(item),
+					subscribed: true,
+					reason: subscription.reason
+				};
+			}
+		}),
+		factory_unsubscribe_work_item: createTool({
+			id: "factory_unsubscribe_work_item",
+			description: "Stop following a work item from this session.",
+			inputSchema: z.object({ workItem: workItemRefSchema }).strict(),
+			execute: async ({ workItem }) => {
+				const item = await requireItem(workItem);
+				const removed = await deps.workItems.unsubscribeFromWorkItem({
+					orgId: scope.orgId,
+					workItemId: item.id,
+					sessionId: scope.sessionId
+				});
+				return {
+					workItem: briefItem(item),
+					subscribed: false,
+					wasSubscribed: removed
+				};
+			}
+		})
+	};
+}
+//#endregion
+export { createFactoryWorkItemTools };
+
+//# sourceMappingURL=work-item-tools.js.map

package/dist/tools/work-item-tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-item-tools.js","names":[],"sources":["../../src/tools/work-item-tools.ts"],"sourcesContent":["/**\n * Factory tools that change work items: file one, move it, settle its\n * decisions, and follow it. They act as the session's person (a human actor),\n * through the same code the board's routes use.\n */\n\nimport { randomUUID } from 'node:crypto';\nimport { createTool } from '@mastra/core/tools';\nimport { z } from 'zod';\n\nimport { boardForWorkItem } from '../boards/index.js';\nimport type { BoardRegistry } from '../boards/index.js';\nimport type { IntegrationTools } from '../integrations/base.js';\nimport { transitionBodySchema } from '../routes/contracts.js';\nimport type { FactoryTransitionService } from '../rules/transition-service.js';\nimport type { SourceControlSessionLookup } from '../session/factory-session.js';\nimport { resolveWorkItemRepository } from '../session/work-item-repository.js';\nimport type { AuditRecorder } from '../storage/domains/audit/domain.js';\nimport type { CommentsDomain } from '../storage/domains/comments/domain.js';\nimport { WorkItemRelationError } from '../storage/domains/work-items/base.js';\nimport type { UpdateWorkItemInput, WorkItemRow, WorkItemsStorage } from '../storage/domains/work-items/base.js';\nimport { createFactoryWorkItem } from '../work-items/create-work-item.js';\nimport type { FactoryAuditEmit } from '../work-items/create-work-item.js';\nimport {\n  dismissFactoryDecision,\n  resolveFactoryProposal,\n  retryFactoryDecision,\n} from '../work-items/decision-actions.js';\nimport type { FactoryDecisionActionResult } from '../work-items/decision-actions.js';\nimport {\n  MAX_TEXT,\n  findWorkItem,\n  workItemRefSchema,\n  truncate,\n  workItemNotFound,\n  workItemNumber,\n  workItemStage,\n} from './read-tools.js';\nimport { requirePerson } from './scope.js';\nimport type { FactoryToolScope } from './scope.js';\n\nexport interface FactoryWorkItemToolDependencies {\n  workItems: WorkItemsStorage;\n  boards: BoardRegistry;\n  /** Governed stage moves; filing and moving items refuse while it is unavailable. */\n  transitionService: Pick<FactoryTransitionService, 'transition'> | undefined;\n  /** Writes audit rows with an explicit actor; tool calls have no HTTP request to read one from. */\n  auditRecorder: AuditRecorder;\n  /** The feed's front door: validates, touches open boards and mirrors to linked channels. */\n  feed: Pick<CommentsDomain, 'createComment'>;\n  /** Finds the caller session's source-control provider, whose linked repositories a card can name. */\n  sessions: Pick<SourceControlSessionLookup, 'getSourceControlBySessionId'>;\n}\n\nconst repositorySchema = z\n  .string()\n  .trim()\n  .min(3)\n  .max(200)\n  .regex(/^[^/\\s]+\\/[^/\\s]+$/, 'Use the owner/name form, e.g. \"mastra-ai/mastra\".')\n  .describe('A repository linked to this Factory, as owner/name.');\n\nconst decisionId = z.string().trim().uuid().describe('Decision id, from factory_list_attention or inspect.');\n\nfunction briefItem(item: WorkItemRow) {\n  return {\n    id: item.id,\n    number: workItemNumber(item),\n    title: truncate(item.title, MAX_TEXT),\n    stage: workItemStage(item),\n  };\n}\n\nfunction settled(result: FactoryDecisionActionResult) {\n  if (!result.ok) throw new Error(result.message);\n  const { decision } = result;\n  return { decisionId: decision.id, status: decision.status, workItemId: decision.workItemId };\n}\n\n/** The work-item write and subscription tools for one user session's turn. */\nexport function createFactoryWorkItemTools(\n  scope: FactoryToolScope,\n  deps: FactoryWorkItemToolDependencies,\n): IntegrationTools {\n  const project = { orgId: scope.orgId, factoryProjectId: scope.factoryProjectId };\n  const audit: FactoryAuditEmit = async input => {\n    await deps.auditRecorder.record({\n      orgId: scope.orgId,\n      // Turns nobody signed in started are recorded as this session's agent, as their moves are.\n      actorId: scope.interactive ? scope.userId : `agent:session:${scope.sessionId}`,\n      actorType: scope.interactive ? 'human' : 'agent',\n      ...(scope.actorProfile ? { actorProfile: scope.actorProfile } : {}),\n      ...input,\n    });\n  };\n  const requireItem = async (ref: string) => {\n    const item = await findWorkItem(deps.workItems, scope, ref);\n    if (!item) throw workItemNotFound(ref);\n    return item;\n  };\n  /**\n   * Check `slug` is a repository linked to this Factory and that a card with\n   * `metadata` would run in it (a card synced from an issue follows the\n   * issue's repository, which a slug can't override).\n   */\n  const requireRepository = async (slug: string, metadata: Record<string, unknown> | null = null) => {\n    const sourceControl = await deps.sessions.getSourceControlBySessionId(scope.sessionId);\n    if (!sourceControl) throw new Error('This session has no source-control provider to look repositories up in.');\n    const resolve = (repository?: string) =>\n      resolveWorkItemRepository({\n        sourceControl,\n        ...project,\n        item: { metadata: repository ? { ...metadata, repository } : metadata },\n      });\n    const resolution = await resolve(slug);\n    if (resolution.status === 'resolved' && resolution.slug === slug) return;\n    if (resolution.status === 'resolved') {\n      throw new Error(`This card runs in ${resolution.slug}, which comes from its linked issue and can't be changed.`);\n    }\n    const linked = await resolve();\n    const candidates =\n      linked.status === 'ambiguous' ? linked.candidates : linked.status === 'resolved' ? [linked.slug] : [];\n    throw new Error(\n      candidates.length > 0\n        ? `${slug} is not linked to this Factory. Linked repositories: ${candidates.join(', ')}.`\n        : `${slug} is not linked to this Factory, and it has no linked repositories.`,\n    );\n  };\n  const follow = (item: WorkItemRow, reason: 'created' | 'subscribed') =>\n    deps.workItems.subscribeToWorkItem({\n      ...project,\n      workItemId: item.id,\n      sessionId: scope.sessionId,\n      threadId: scope.threadId,\n      resourceId: scope.resourceId,\n      userId: scope.userId,\n      reason,\n    });\n\n  return {\n    factory_create_work_item: createTool({\n      id: 'factory_create_work_item',\n      description:\n        \"File a new work item on this Factory's Work board for the person you are working with. It lands in the board's first phase, exactly like pressing New card, and this session follows it. Check factory_list_work_items for an existing item first. Name the repository when the Factory links more than one; runs refuse to start on a card that doesn't say which.\",\n      inputSchema: z\n        .object({\n          title: z.string().trim().min(1).max(512).describe('Short title, as it should read on the card.'),\n          brief: z\n            .string()\n            .trim()\n            .min(1)\n            .max(8000)\n            .describe('What needs doing and why; posted as the first comment on the card.'),\n          repository: repositorySchema.optional(),\n        })\n        .strict(),\n      execute: async ({ title, brief, repository }) => {\n        if (repository) await requireRepository(repository);\n        const created = await createFactoryWorkItem({\n          workItems: deps.workItems,\n          boards: deps.boards,\n          transitionService: deps.transitionService,\n          audit,\n          ...project,\n          userId: scope.userId,\n          ...(scope.actorProfile ? { origin: { actorProfile: scope.actorProfile } } : {}),\n          input: { title, ...(repository ? { metadata: { repository } } : {}) },\n        });\n        if (created.status === 'refused') throw new Error(created.message);\n        if (created.status === 'rejected') throw new Error(`The board refused the new item: ${created.reason}`);\n        const { item } = created;\n        // The card exists from here on: report follow-up failures alongside it\n        // rather than failing the call, so the agent doesn't file it twice.\n        const warnings: string[] = [];\n        try {\n          const comment = await deps.feed.createComment({\n            orgId: scope.orgId,\n            workItemId: item.id,\n            author: { kind: 'user', id: scope.userId },\n            body: brief,\n          });\n          if (comment.status !== 'created') {\n            warnings.push(\n              `The brief was not posted (${comment.status === 'invalid' ? comment.message : comment.status}).`,\n            );\n          }\n        } catch (error) {\n          warnings.push(`The brief was not posted: ${error instanceof Error ? error.message : String(error)}`);\n        }\n        try {\n          await follow(item, 'created');\n        } catch (error) {\n          warnings.push(\n            `This session does not follow it yet: ${error instanceof Error ? error.message : String(error)}`,\n          );\n        }\n        return warnings.length ? { ...briefItem(item), warnings } : briefItem(item);\n      },\n    }),\n\n    factory_transition_work_item: createTool({\n      id: 'factory_transition_work_item',\n      description:\n        \"Move a work item to another stage of its board, as the person you are working with. The board's rules decide whether the move is allowed and what it starts.\",\n      inputSchema: z\n        .object({\n          workItem: workItemRefSchema,\n          stage: z.string().trim().min(1).max(64).describe('Destination stage, e.g. \"planning\" or \"done\".'),\n        })\n        .strict(),\n      execute: async ({ workItem, stage }) => {\n        if (!deps.transitionService) throw new Error('Factory stage transitions are not available right now.');\n        const item = await requireItem(workItem);\n        const parsed = transitionBodySchema.safeParse({\n          board: boardForWorkItem(item),\n          stage,\n          expectedRevision: item.revision,\n          requestId: randomUUID(),\n          cause: 'factory_tools',\n        });\n        if (!parsed.success) throw new Error(`\"${stage}\" is not a valid stage name.`);\n        const result = await deps.transitionService.transition({\n          ...parsed.data,\n          ...project,\n          workItemId: item.id,\n          ...(scope.interactive\n            ? {\n                actor: { type: 'human' as const, id: scope.userId },\n                ...(scope.actorProfile ? { actorProfile: scope.actorProfile } : {}),\n                ingress: { ...parsed.data.ingress, identity: `human:${scope.userId}:${parsed.data.ingress.identity}` },\n              }\n            : {\n                // Nobody signed in started this turn: move as this session's agent, so the\n                // plan gate and the agent's done gates apply and the move arms no runs.\n                actor: { type: 'agent' as const, bindingId: `session:${scope.sessionId}`, role: 'session' },\n                ingress: {\n                  type: 'agent' as const,\n                  identity: `session:${scope.sessionId}:${parsed.data.ingress.identity}`,\n                },\n              }),\n        });\n        if (result.status === 'rejected') throw new Error(`The move was refused (${result.code}): ${result.reason}`);\n        return { workItemId: item.id, stage: result.stage, revision: result.revision };\n      },\n    }),\n\n    factory_update_work_item: createTool({\n      id: 'factory_update_work_item',\n      description:\n        \"Edit a work item's fields as the person you are working with: its title, the repository its runs use, its parent item, or pre-approving its plans. Move stages with factory_transition_work_item and start roles with factory_start_session; post to the card's feed for anything else.\",\n      inputSchema: z\n        .object({\n          workItem: workItemRefSchema,\n          title: z.string().trim().min(1).max(500).optional().describe('New card title.'),\n          repository: repositorySchema.optional(),\n          parentWorkItem: workItemRefSchema\n            .nullable()\n            .optional()\n            .describe('Parent work item (id or #number), or null to detach it from its parent.'),\n          plansPreapproved: z\n            .literal(true)\n            .optional()\n            .describe(\n              \"Pre-approve the item's plans, so its runs no longer stop for plan approval. Can't be undone here.\",\n            ),\n        })\n        .strict()\n        .refine(input => Object.keys(input).some(key => key !== 'workItem'), 'Pass at least one field to change.'),\n      execute: async ({ workItem, title, repository, parentWorkItem, plansPreapproved }) => {\n        // Pre-approval drops the plan-approval gate for good, so it is the person's call.\n        if (plansPreapproved) requirePerson(scope, 'pre-approve plans');\n        const item = await requireItem(workItem);\n        if (repository) await requireRepository(repository, item.metadata);\n        let parentWorkItemId: string | null | undefined;\n        if (parentWorkItem === null) parentWorkItemId = null;\n        else if (parentWorkItem !== undefined) parentWorkItemId = (await requireItem(parentWorkItem)).id;\n        const patch: UpdateWorkItemInput = {\n          ...(title !== undefined ? { title } : {}),\n          ...(repository ? { metadata: { repository } } : {}),\n          ...(parentWorkItemId !== undefined ? { parentWorkItemId } : {}),\n          ...(plansPreapproved ? { plansPreapproved } : {}),\n        };\n        let updated: Awaited<ReturnType<WorkItemsStorage['update']>>;\n        try {\n          updated = await deps.workItems.update({ orgId: scope.orgId, id: item.id, userId: scope.userId, patch });\n        } catch (error) {\n          if (error instanceof WorkItemRelationError) throw new Error(`The parent was refused: ${error.message}`);\n          throw error;\n        }\n        if (!updated) throw workItemNotFound(workItem);\n        const fields = [\n          ...(title !== undefined ? ['title'] : []),\n          ...(repository ? ['metadata'] : []),\n          ...(parentWorkItemId !== undefined ? ['parentWorkItemId'] : []),\n          ...(plansPreapproved ? ['plansPreapproved'] : []),\n        ];\n        await audit({\n          action: 'factory.work_item.updated',\n          factoryProjectId: scope.factoryProjectId,\n          targets: [{ type: 'work_item', id: updated.item.id, name: updated.item.title }],\n          metadata: { fields, cause: 'factory_tools' },\n        });\n        const metadata = updated.item.metadata ?? {};\n        return {\n          workItem: briefItem(updated.item),\n          updated: fields.map(field => (field === 'metadata' ? 'repository' : field)),\n          repository: typeof metadata.repository === 'string' ? metadata.repository : null,\n          parentWorkItemId: updated.item.parentWorkItemId,\n          plansPreapproved: updated.item.plansPreapprovedAt !== null,\n        };\n      },\n    }),\n\n    factory_retry_decision: createTool({\n      id: 'factory_retry_decision',\n      description:\n        'Retry one failed Factory run once its cause is fixed. Refused when the failure cannot be fixed by retrying or the item has moved on.',\n      inputSchema: z.object({ decisionId }).strict(),\n      execute: async ({ decisionId }) =>\n        settled(await retryFactoryDecision({ workItems: deps.workItems, boards: deps.boards, ...project, decisionId })),\n    }),\n\n    factory_dismiss_decision: createTool({\n      id: 'factory_dismiss_decision',\n      description: 'Dismiss one proposed Factory run that is no longer wanted.',\n      inputSchema: z.object({ decisionId }).strict(),\n      execute: async ({ decisionId }) => {\n        requirePerson(scope, 'dismiss a proposed run');\n        return settled(\n          await dismissFactoryDecision({\n            workItems: deps.workItems,\n            audit,\n            ...project,\n            userId: scope.userId,\n            decisionId,\n          }),\n        );\n      },\n    }),\n\n    factory_resolve_proposal: createTool({\n      id: 'factory_resolve_proposal',\n      description:\n        \"Approve or dismiss one proposed Factory run. Approving starts the run and lets the item's later runs start without asking.\",\n      inputSchema: z.object({ decisionId, action: z.enum(['approve', 'dismiss']) }).strict(),\n      execute: async ({ decisionId, action }) => {\n        requirePerson(scope, 'approve or dismiss a proposed run');\n        return settled(\n          await resolveFactoryProposal({\n            workItems: deps.workItems,\n            audit,\n            ...project,\n            userId: scope.userId,\n            decisionId,\n            action,\n          }),\n        );\n      },\n    }),\n\n    factory_subscribe_work_item: createTool({\n      id: 'factory_subscribe_work_item',\n      description:\n        'Follow a work item from this session, so you hear about its progress and its sessions report to you. Items you file or start are followed already.',\n      inputSchema: z.object({ workItem: workItemRefSchema }).strict(),\n      execute: async ({ workItem }) => {\n        const item = await requireItem(workItem);\n        const subscription = await follow(item, 'subscribed');\n        return { workItem: briefItem(item), subscribed: true, reason: subscription.reason };\n      },\n    }),\n\n    factory_unsubscribe_work_item: createTool({\n      id: 'factory_unsubscribe_work_item',\n      description: 'Stop following a work item from this session.',\n      inputSchema: z.object({ workItem: workItemRefSchema }).strict(),\n      execute: async ({ workItem }) => {\n        const item = await requireItem(workItem);\n        const removed = await deps.workItems.unsubscribeFromWorkItem({\n          orgId: scope.orgId,\n          workItemId: item.id,\n          sessionId: scope.sessionId,\n        });\n        return { workItem: briefItem(item), subscribed: false, wasSubscribed: removed };\n      },\n    }),\n  };\n}\n"],"mappings":"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"}

package/dist/work-items/create-work-item.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Filing a work item, shared by the board's create route and the Factory tools
+ * so a card filed from a session goes through exactly what "New card" does.
+ */
+import type { BoardRegistry } from '../boards/index.js';
+import type { FactoryTransitionRequest, FactoryTransitionService } from '../rules/transition-service.js';
+import type { EmitAuditInput } from '../storage/domains/audit/domain.js';
+import type { CreateWorkItemInput, WorkItemRow, WorkItemsStorage } from '../storage/domains/work-items/base.js';
+/** Records one audit event for the caller; routes bind it to the request, tools to the session's person. */
+export type FactoryAuditEmit = (input: EmitAuditInput) => Promise<void>;
+type TransitionResult = Awaited<ReturnType<FactoryTransitionService['transition']>>;
+export type CreateFactoryWorkItemResult = 
+/** A new card, entered into its board's first phase and audited. */
+{
+    status: 'created';
+    item: WorkItemRow;
+}
+/** The source key matched an existing card, which was updated instead (the caller audits the patch). */
+ | {
+    status: 'reused';
+    item: WorkItemRow;
+} | {
+    status: 'refused';
+    code: 'invalid_board' | 'governed_transition_required' | 'factory_transitions_unavailable';
+    message: string;
+}
+/** The first phase's entry rules refused the card; it was removed again. */
+ | {
+    status: 'rejected';
+    code: Extract<TransitionResult, {
+        status: 'rejected';
+    }>['code'];
+    reason: string;
+};
+export interface CreateFactoryWorkItemArgs {
+    workItems: WorkItemsStorage;
+    boards: BoardRegistry;
+    transitionService: Pick<FactoryTransitionService, 'transition'> | undefined;
+    audit: FactoryAuditEmit;
+    orgId: string;
+    /** Who files the card; becomes its `created_by` and the human actor of its first phase entry. */
+    userId: string;
+    factoryProjectId: string;
+    input: CreateWorkItemInput;
+    /** Where a browser request came from; a session's tool call carries none. */
+    origin?: Pick<FactoryTransitionRequest, 'actorProfile' | 'context'>;
+}
+/**
+ * Upserts the card into its board's first phase, enters that phase as the
+ * person (rolling the card back if its entry rules refuse it), then audits
+ * `factory.work_item.created`. Throws `WorkItemRelationError` for a bad parent.
+ */
+export declare function createFactoryWorkItem({ workItems, boards, transitionService, audit, orgId, userId, factoryProjectId, input, origin, }: CreateFactoryWorkItemArgs): Promise<CreateFactoryWorkItemResult>;
+export {};
+//# sourceMappingURL=create-work-item.d.ts.map

package/dist/work-items/create-work-item.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-work-item.d.ts","sourceRoot":"","sources":["../../src/work-items/create-work-item.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AACxD,OAAO,KAAK,EAAE,wBAAwB,EAAE,wBAAwB,EAAE,MAAM,gCAAgC,CAAC;AACzG,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,KAAK,EAAE,mBAAmB,EAAE,WAAW,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAEhH,4GAA4G;AAC5G,MAAM,MAAM,gBAAgB,GAAG,CAAC,KAAK,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAExE,KAAK,gBAAgB,GAAG,OAAO,CAAC,UAAU,CAAC,wBAAwB,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;AAEpF,MAAM,MAAM,2BAA2B;AACrC,oEAAoE;AAClE;IAAE,MAAM,EAAE,SAAS,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE;AAC1C,wGAAwG;GACtG;IAAE,MAAM,EAAE,QAAQ,CAAC;IAAC,IAAI,EAAE,WAAW,CAAA;CAAE,GACvC;IACE,MAAM,EAAE,SAAS,CAAC;IAClB,IAAI,EAAE,eAAe,GAAG,8BAA8B,GAAG,iCAAiC,CAAC;IAC3F,OAAO,EAAE,MAAM,CAAC;CACjB;AACH,4EAA4E;GAC1E;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,IAAI,EAAE,OAAO,CAAC,gBAAgB,EAAE;QAAE,MAAM,EAAE,UAAU,CAAA;KAAE,CAAC,CAAC,MAAM,CAAC,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAE5G,MAAM,WAAW,yBAAyB;IACxC,SAAS,EAAE,gBAAgB,CAAC;IAC5B,MAAM,EAAE,aAAa,CAAC;IACtB,iBAAiB,EAAE,IAAI,CAAC,wBAAwB,EAAE,YAAY,CAAC,GAAG,SAAS,CAAC;IAC5E,KAAK,EAAE,gBAAgB,CAAC;IACxB,KAAK,EAAE,MAAM,CAAC;IACd,iGAAiG;IACjG,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,EAAE,MAAM,CAAC;IACzB,KAAK,EAAE,mBAAmB,CAAC;IAC3B,6EAA6E;IAC7E,MAAM,CAAC,EAAE,IAAI,CAAC,wBAAwB,EAAE,cAAc,GAAG,SAAS,CAAC,CAAC;CACrE;AAED;;;;GAIG;AACH,wBAAsB,qBAAqB,CAAC,EAC1C,SAAS,EACT,MAAM,EACN,iBAAiB,EACjB,KAAK,EACL,KAAK,EACL,MAAM,EACN,gBAAgB,EAChB,KAAK,EACL,MAAM,GACP,EAAE,yBAAyB,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAyDlE"}

package/dist/work-items/create-work-item.js

@@ -0,0 +1,101 @@
+//#region src/work-items/create-work-item.ts
+/**
+* Upserts the card into its board's first phase, enters that phase as the
+* person (rolling the card back if its entry rules refuse it), then audits
+* `factory.work_item.created`. Throws `WorkItemRelationError` for a bad parent.
+*/
+async function createFactoryWorkItem({ workItems, boards, transitionService, audit, orgId, userId, factoryProjectId, input, origin }) {
+	const boardId = input.board ?? (input.externalSource?.type === "pull-request" ? "review" : "work");
+	const board = boards.get(boardId);
+	if (!board) return {
+		status: "refused",
+		code: "invalid_board",
+		message: `Board '${boardId}' is not installed.`
+	};
+	const initialStages = input.stages ?? [board.initialPhase];
+	if (initialStages.length !== 1 || initialStages[0] !== board.initialPhase) return {
+		status: "refused",
+		code: "governed_transition_required",
+		message: `New work items must enter through the '${board.initialPhase}' phase of board '${boardId}'.`
+	};
+	await workItems.ensureReady();
+	const result = await workItems.upsert({
+		orgId,
+		userId,
+		factoryProjectId,
+		input: {
+			...input,
+			board: boardId,
+			stages: initialStages
+		},
+		reuseMode: "non-stage"
+	});
+	if (!result.created) return {
+		status: "reused",
+		item: result.item
+	};
+	const created = result.item;
+	if (!transitionService) {
+		await workItems.delete({
+			orgId,
+			id: created.id
+		});
+		return {
+			status: "refused",
+			code: "factory_transitions_unavailable",
+			message: "Factory stage transitions are not available right now."
+		};
+	}
+	const entered = await transitionService.transition({
+		orgId,
+		factoryProjectId,
+		workItemId: created.id,
+		board: boardId,
+		stage: board.initialPhase,
+		expectedRevision: created.revision,
+		actor: {
+			type: "human",
+			id: userId
+		},
+		...origin,
+		ingress: {
+			type: "human",
+			identity: `work-item:${created.id}:initial-entry`
+		},
+		cause: "work_item_created",
+		initialEntry: true
+	});
+	if (entered.status === "rejected") {
+		await workItems.delete({
+			orgId,
+			id: created.id
+		});
+		return {
+			status: "rejected",
+			code: entered.code,
+			reason: entered.reason
+		};
+	}
+	const item = await workItems.getForProject(orgId, factoryProjectId, created.id) ?? created;
+	await audit({
+		action: "factory.work_item.created",
+		factoryProjectId,
+		targets: [{
+			type: "work_item",
+			id: item.id,
+			name: item.title
+		}],
+		metadata: {
+			externalSource: item.externalSource,
+			stages: item.stages
+		}
+	});
+	return {
+		status: "created",
+		item
+	};
+}
+//#endregion
+export { createFactoryWorkItem };
+
+//# sourceMappingURL=create-work-item.js.map

package/dist/work-items/create-work-item.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-work-item.js","names":[],"sources":["../../src/work-items/create-work-item.ts"],"sourcesContent":["/**\n * Filing a work item, shared by the board's create route and the Factory tools\n * so a card filed from a session goes through exactly what \"New card\" does.\n */\n\nimport type { BoardRegistry } from '../boards/index.js';\nimport type { FactoryTransitionRequest, FactoryTransitionService } from '../rules/transition-service.js';\nimport type { EmitAuditInput } from '../storage/domains/audit/domain.js';\nimport type { CreateWorkItemInput, WorkItemRow, WorkItemsStorage } from '../storage/domains/work-items/base.js';\n\n/** Records one audit event for the caller; routes bind it to the request, tools to the session's person. */\nexport type FactoryAuditEmit = (input: EmitAuditInput) => Promise<void>;\n\ntype TransitionResult = Awaited<ReturnType<FactoryTransitionService['transition']>>;\n\nexport type CreateFactoryWorkItemResult =\n  /** A new card, entered into its board's first phase and audited. */\n  | { status: 'created'; item: WorkItemRow }\n  /** The source key matched an existing card, which was updated instead (the caller audits the patch). */\n  | { status: 'reused'; item: WorkItemRow }\n  | {\n      status: 'refused';\n      code: 'invalid_board' | 'governed_transition_required' | 'factory_transitions_unavailable';\n      message: string;\n    }\n  /** The first phase's entry rules refused the card; it was removed again. */\n  | { status: 'rejected'; code: Extract<TransitionResult, { status: 'rejected' }>['code']; reason: string };\n\nexport interface CreateFactoryWorkItemArgs {\n  workItems: WorkItemsStorage;\n  boards: BoardRegistry;\n  transitionService: Pick<FactoryTransitionService, 'transition'> | undefined;\n  audit: FactoryAuditEmit;\n  orgId: string;\n  /** Who files the card; becomes its `created_by` and the human actor of its first phase entry. */\n  userId: string;\n  factoryProjectId: string;\n  input: CreateWorkItemInput;\n  /** Where a browser request came from; a session's tool call carries none. */\n  origin?: Pick<FactoryTransitionRequest, 'actorProfile' | 'context'>;\n}\n\n/**\n * Upserts the card into its board's first phase, enters that phase as the\n * person (rolling the card back if its entry rules refuse it), then audits\n * `factory.work_item.created`. Throws `WorkItemRelationError` for a bad parent.\n */\nexport async function createFactoryWorkItem({\n  workItems,\n  boards,\n  transitionService,\n  audit,\n  orgId,\n  userId,\n  factoryProjectId,\n  input,\n  origin,\n}: CreateFactoryWorkItemArgs): Promise<CreateFactoryWorkItemResult> {\n  const boardId = input.board ?? (input.externalSource?.type === 'pull-request' ? 'review' : 'work');\n  const board = boards.get(boardId);\n  if (!board) return { status: 'refused', code: 'invalid_board', message: `Board '${boardId}' is not installed.` };\n  const initialStages = input.stages ?? [board.initialPhase];\n  if (initialStages.length !== 1 || initialStages[0] !== board.initialPhase) {\n    return {\n      status: 'refused',\n      code: 'governed_transition_required',\n      message: `New work items must enter through the '${board.initialPhase}' phase of board '${boardId}'.`,\n    };\n  }\n\n  await workItems.ensureReady();\n  const result = await workItems.upsert({\n    orgId,\n    userId,\n    factoryProjectId,\n    input: { ...input, board: boardId, stages: initialStages },\n    reuseMode: 'non-stage',\n  });\n  if (!result.created) return { status: 'reused', item: result.item };\n\n  const created = result.item;\n  if (!transitionService) {\n    await workItems.delete({ orgId, id: created.id });\n    return {\n      status: 'refused',\n      code: 'factory_transitions_unavailable',\n      message: 'Factory stage transitions are not available right now.',\n    };\n  }\n  const entered = await transitionService.transition({\n    orgId,\n    factoryProjectId,\n    workItemId: created.id,\n    board: boardId,\n    stage: board.initialPhase,\n    expectedRevision: created.revision,\n    actor: { type: 'human', id: userId },\n    ...origin,\n    ingress: { type: 'human', identity: `work-item:${created.id}:initial-entry` },\n    cause: 'work_item_created',\n    initialEntry: true,\n  });\n  if (entered.status === 'rejected') {\n    await workItems.delete({ orgId, id: created.id });\n    return { status: 'rejected', code: entered.code, reason: entered.reason };\n  }\n  const item = (await workItems.getForProject(orgId, factoryProjectId, created.id)) ?? created;\n  await audit({\n    action: 'factory.work_item.created',\n    factoryProjectId,\n    targets: [{ type: 'work_item', id: item.id, name: item.title }],\n    metadata: { externalSource: item.externalSource, stages: item.stages },\n  });\n  return { status: 'created', item };\n}\n"],"mappings":";;;;;;AA+CA,eAAsB,sBAAsB,EAC1C,WACA,QACA,mBACA,OACA,OACA,QACA,kBACA,OACA,UACkE;CAClE,MAAM,UAAU,MAAM,UAAU,MAAM,gBAAgB,SAAS,iBAAiB,WAAW;CAC3F,MAAM,QAAQ,OAAO,IAAI,OAAO;CAChC,IAAI,CAAC,OAAO,OAAO;EAAE,QAAQ;EAAW,MAAM;EAAiB,SAAS,UAAU,QAAQ;CAAqB;CAC/G,MAAM,gBAAgB,MAAM,UAAU,CAAC,MAAM,YAAY;CACzD,IAAI,cAAc,WAAW,KAAK,cAAc,OAAO,MAAM,cAC3D,OAAO;EACL,QAAQ;EACR,MAAM;EACN,SAAS,0CAA0C,MAAM,aAAa,oBAAoB,QAAQ;CACpG;CAGF,MAAM,UAAU,YAAY;CAC5B,MAAM,SAAS,MAAM,UAAU,OAAO;EACpC;EACA;EACA;EACA,OAAO;GAAE,GAAG;GAAO,OAAO;GAAS,QAAQ;EAAc;EACzD,WAAW;CACb,CAAC;CACD,IAAI,CAAC,OAAO,SAAS,OAAO;EAAE,QAAQ;EAAU,MAAM,OAAO;CAAK;CAElE,MAAM,UAAU,OAAO;CACvB,IAAI,CAAC,mBAAmB;EACtB,MAAM,UAAU,OAAO;GAAE;GAAO,IAAI,QAAQ;EAAG,CAAC;EAChD,OAAO;GACL,QAAQ;GACR,MAAM;GACN,SAAS;EACX;CACF;CACA,MAAM,UAAU,MAAM,kBAAkB,WAAW;EACjD;EACA;EACA,YAAY,QAAQ;EACpB,OAAO;EACP,OAAO,MAAM;EACb,kBAAkB,QAAQ;EAC1B,OAAO;GAAE,MAAM;GAAS,IAAI;EAAO;EACnC,GAAG;EACH,SAAS;GAAE,MAAM;GAAS,UAAU,aAAa,QAAQ,GAAG;EAAgB;EAC5E,OAAO;EACP,cAAc;CAChB,CAAC;CACD,IAAI,QAAQ,WAAW,YAAY;EACjC,MAAM,UAAU,OAAO;GAAE;GAAO,IAAI,QAAQ;EAAG,CAAC;EAChD,OAAO;GAAE,QAAQ;GAAY,MAAM,QAAQ;GAAM,QAAQ,QAAQ;EAAO;CAC1E;CACA,MAAM,OAAQ,MAAM,UAAU,cAAc,OAAO,kBAAkB,QAAQ,EAAE,KAAM;CACrF,MAAM,MAAM;EACV,QAAQ;EACR;EACA,SAAS,CAAC;GAAE,MAAM;GAAa,IAAI,KAAK;GAAI,MAAM,KAAK;EAAM,CAAC;EAC9D,UAAU;GAAE,gBAAgB,KAAK;GAAgB,QAAQ,KAAK;EAAO;CACvE,CAAC;CACD,OAAO;EAAE,QAAQ;EAAW;CAAK;AACnC"}

package/dist/work-items/decision-actions.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Retrying, approving and dismissing Factory decisions, shared by the board's
+ * routes and the Factory tools so both refuse and audit the same way.
+ */
+import type { BoardRegistry } from '../boards/index.js';
+import type { FactoryDeferredDecisionRecord, WorkItemsStorage } from '../storage/domains/work-items/base.js';
+import type { FactoryAuditEmit } from './create-work-item.js';
+export type FactoryDecisionActionResult = {
+    ok: true;
+    decision: FactoryDeferredDecisionRecord;
+} | {
+    ok: false;
+    code: 'decision_not_retryable' | 'decision_not_proposed';
+    message: string;
+};
+interface DecisionActionArgs {
+    workItems: WorkItemsStorage;
+    orgId: string;
+    factoryProjectId: string;
+    decisionId: string;
+}
+/** Re-queue a failed run, unless its failure can't be fixed by retrying or the card has left the run's phase. */
+export declare function retryFactoryDecision({ workItems, boards, orgId, factoryProjectId, decisionId, }: DecisionActionArgs & {
+    boards: BoardRegistry;
+}): Promise<FactoryDecisionActionResult>;
+/**
+ * Release (approve) or drop (dismiss) a parked proposal as `userId`, audited as
+ * consent. Approval arms the item's autonomy inside the same storage
+ * transaction (see approveDeferredDecision), so follow-up runs no longer wait.
+ */
+export declare function resolveFactoryProposal({ workItems, audit, orgId, factoryProjectId, userId, decisionId, action, }: DecisionActionArgs & {
+    audit: FactoryAuditEmit;
+    userId: string;
+    action: 'approve' | 'dismiss';
+}): Promise<FactoryDecisionActionResult>;
+/** Drop a parked proposal; the same as dismissing it through {@link resolveFactoryProposal}. */
+export declare function dismissFactoryDecision(args: DecisionActionArgs & {
+    audit: FactoryAuditEmit;
+    userId: string;
+}): Promise<FactoryDecisionActionResult>;
+export {};
+//# sourceMappingURL=decision-actions.d.ts.map

package/dist/work-items/decision-actions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decision-actions.d.ts","sourceRoot":"","sources":["../../src/work-items/decision-actions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,KAAK,EAAE,6BAA6B,EAAE,gBAAgB,EAAE,MAAM,uCAAuC,CAAC;AAC7G,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAE9D,MAAM,MAAM,2BAA2B,GACnC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,6BAA6B,CAAA;CAAE,GACrD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,IAAI,EAAE,wBAAwB,GAAG,uBAAuB,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AAE7F,UAAU,kBAAkB;IAC1B,SAAS,EAAE,gBAAgB,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,gBAAgB,EAAE,MAAM,CAAC;IACzB,UAAU,EAAE,MAAM,CAAC;CACpB;AAQD,iHAAiH;AACjH,wBAAsB,oBAAoB,CAAC,EACzC,SAAS,EACT,MAAM,EACN,KAAK,EACL,gBAAgB,EAChB,UAAU,GACX,EAAE,kBAAkB,GAAG;IAAE,MAAM,EAAE,aAAa,CAAA;CAAE,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAevF;AAED;;;;GAIG;AACH,wBAAsB,sBAAsB,CAAC,EAC3C,SAAS,EACT,KAAK,EACL,KAAK,EACL,gBAAgB,EAChB,MAAM,EACN,UAAU,EACV,MAAM,GACP,EAAE,kBAAkB,GAAG;IACtB,KAAK,EAAE,gBAAgB,CAAC;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,SAAS,GAAG,SAAS,CAAC;CAC/B,GAAG,OAAO,CAAC,2BAA2B,CAAC,CAuBvC;AAED,gGAAgG;AAChG,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,kBAAkB,GAAG;IAAE,KAAK,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACrE,OAAO,CAAC,2BAA2B,CAAC,CAEtC"}