@vimhead.dev/norn-cli 0.1.0-tip.35436871363.1 → 0.1.0-tip.35570530940.1

package/assets/examples/worktree-development-loop/workflows/implementation/execute.ts

@@ -8,28 +8,27 @@ import { ensureCommandSucceeded } from "../../shared/commands.ts";
 import { implementationAgentResponseSchema } from "./schema.ts";
 
 export const implementationWorkflow = developmentLoopScope.workflow({
-	id: "implementation",
-	isEntrypoint: false,
-	instructions: "Apply one implementation pass in the current repository.",
+	name: "implementation",
+	entrypoint: false,
 	args: implementationArgsSchema,
-	async execute({ args, paths, run }): Promise<WorkflowResult> {
+	async execute({ args, paths, agents, commands, logs }): Promise<WorkflowResult> {
 		const repositoryPath = resolve(paths.workspace, args.repositoryPath);
 		const plan = await readFile(join(paths.workspace, args.planPath), "utf8");
 		const previousReview = args.previousReviewPath ? await readFile(join(paths.workspace, args.previousReviewPath), "utf8") : undefined;
-		const implementation = await run.agents.prompt({
+		const implementation = await agents.prompt({
 			label: `implementation-${args.iteration}`,
 			cwd: repositoryPath,
 			tools: ["read", "grep", "find", "ls", "edit", "write", "bash"],
 			prompt: buildImplementationPrompt(args.task, plan, args.iteration, previousReview),
 			response: implementationAgentResponseSchema,
 		});
-		const status = await run.commands.run({
+		const status = await commands.run({
 			label: `implementation-${args.iteration}-status`,
 			cwd: repositoryPath,
 			command: "git status --short",
 		});
 		await ensureCommandSucceeded(status);
-		const statusOutput = await run.logs.read(status.stdoutLog);
+		const statusOutput = await logs.read(status.stdoutLog);
 		await mkdir(join(paths.workspace, "implementation"), { recursive: true });
 		await writeFile(join(paths.workspace, `implementation/iteration-${args.iteration}-status.txt`), statusOutput);
 		return reviewWorkflow({ ...args, implementationSummary: implementation.summary });

package/assets/examples/worktree-development-loop/workflows/planning/execute.ts

@@ -7,13 +7,12 @@ import { planningArgsSchema } from "./schema.ts";
 import { planningAgentResponseSchema } from "./schema.ts";
 
 export const planningWorkflow = developmentLoopScope.workflow({
-	id: "planning",
-	isEntrypoint: false,
-	instructions: "Create an implementation plan for a repository task.",
+	name: "planning",
+	entrypoint: false,
 	args: planningArgsSchema,
-	async execute({ args, paths, run }): Promise<WorkflowResult> {
+	async execute({ args, paths, agents }): Promise<WorkflowResult> {
 		const repositoryPath = resolve(paths.workspace, args.repositoryPath);
-		const planning = await run.agents.prompt({
+		const planning = await agents.prompt({
 			label: "planning",
 			cwd: repositoryPath,
 			tools: ["read", "grep", "find", "ls"],

package/assets/examples/worktree-development-loop/workflows/review/execute.ts

@@ -8,24 +8,23 @@ import { ensureCommandSucceeded } from "../../shared/commands.ts";
 import { reviewAgentResponseSchema } from "./schema.ts";
 
 export const reviewWorkflow = developmentLoopScope.workflow({
-	id: "review",
-	isEntrypoint: false,
-	instructions: "Review the current repository boundary changes.",
+	name: "review",
+	entrypoint: false,
 	args: reviewArgsSchema,
-	async execute({ args, paths, run }): Promise<WorkflowResult> {
+	async execute({ args, paths, agents, commands, logs }): Promise<WorkflowResult> {
 		const repositoryPath = resolve(paths.workspace, args.repositoryPath);
 		const implementationSummary = args.implementationSummary;
 		const plan = await readFile(join(paths.workspace, args.planPath), "utf8");
-		const diff = await run.commands.run({
+		const diff = await commands.run({
 			label: `review-${args.iteration}-diff`,
 			cwd: repositoryPath,
 			command: "git status --short && git diff --stat HEAD -- . && git diff HEAD -- .",
 		});
 		await ensureCommandSucceeded(diff);
-		const diffOutput = await run.logs.read(diff.stdoutLog);
+		const diffOutput = await logs.read(diff.stdoutLog);
 		await mkdir(join(paths.workspace, "review"), { recursive: true });
 		await writeFile(join(paths.workspace, `review/iteration-${args.iteration}-diff.txt`), diffOutput);
-		const review = await run.agents.prompt({
+		const review = await agents.prompt({
 			label: `review-${args.iteration}`,
 			cwd: repositoryPath,
 			tools: ["read", "grep", "find", "ls", "bash"],

package/assets/examples/worktree-development-loop/workflows/review-router/execute.ts

@@ -7,9 +7,8 @@ import { reviewRouterArgsSchema } from "./schema.ts";
 import type { StoredReview } from "../review/schema.ts";
 
 export const reviewRouterWorkflow = developmentLoopScope.workflow({
-	id: "reviewRouter",
-	isEntrypoint: false,
-	instructions: "Route implementation and review iterations based on the latest review decision.",
+	name: "reviewRouter",
+	entrypoint: false,
 	gate: {
 		enabled: true,
 		describe: ({ args }) => `Review iteration ${args.iteration}. Confirm or edit the automated decision before continuing. Plan: ${args.planPath}.`,

package/assets/package.json

@@ -1 +1 @@
-{"version":"0.1.0-tip.35436871363.1"}
+{"version":"0.1.0-tip.35570530940.1"}

package/assets/packages/cli/src/generated-build-info.ts

@@ -2,8 +2,8 @@ import type { NornBuildInfo } from "./build-info.ts";
 
 export const NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35436871363.1",
-  "commit": "49b14d0ed0c9633fc6ee530a557ec7babbf52b22",
+  "version": "0.1.0-tip.35570530940.1",
+  "commit": "48ecaf47ae0e82e17970db9465497a4e1ad5ff10",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/assets/packages/cli/src/internal/engine.ts

@@ -22,7 +22,7 @@ import { NornRunLease } from "./run-lease.ts";
 import { NornRunLogger } from "./run-log.ts";
 import { assertRunVersion, getRunInfo, mergeInterruptedWorkflowArgs, NornRunStateStore, resolveRunRoot, type NornRunState } from "./run-state.ts";
 import { NornRunStore, runCurrentRoot } from "./run-store.ts";
-import { NornRunContext } from "./run.ts";
+import { NornExecutionContext } from "./execution-context.ts";
 import { NornWorkflowRegistry, type NornRegisteredWorkflow, type NornWorkflowStepResult } from "./workflow-registry.ts";
 
 const RUNS_DIR_NAME = ".norn";
@@ -40,7 +40,7 @@ export type NornEngineInput = {
 type RunSession = {
 	readonly runRoot: string;
 	readonly cwd: string;
-	readonly run: NornRunContext;
+	readonly execution: NornExecutionContext;
 	readonly paths: NornWorkflowPaths;
 	readonly state: NornRunStateStore;
 	readonly lease: NornRunLease;
@@ -185,12 +185,12 @@ export class NornEngine {
 			for (let step = 1; step <= 1_000; step++) {
 				throwIfRunAborted(session.activeRun);
 				if (shouldPauseForGate(currentStep)) {
-					const description = await this.registry.describeGate({ workflow: currentStep.workflow, run: session.run, paths: session.paths, args: currentStep.args, configOverride: session.state.currentState().configOverride });
+					const description = await this.registry.describeGate({ workflow: currentStep.workflow, execution: session.execution, paths: session.paths, args: currentStep.args, configOverride: session.state.currentState().configOverride });
 					const interruption = { description, fields: currentStep.workflow.gate?.fields };
 					await session.state.interruptCurrent(currentStep.args, interruption);
 					await recordRunEvent(session, { type: "run.interrupted", workflowId: currentStep.workflow.id });
 					await commitRunBoundary(session, `run interrupted: ${currentStep.workflow.id}`);
-					return interruptedLaunchResult({ id: session.run.id, name: session.state.currentState().name, workspace: session.paths.workspace, cwd: session.cwd }, currentStep.workflow, currentStep.args, interruption);
+					return interruptedLaunchResult({ id: session.execution.run.id, name: session.state.currentState().name, workspace: session.paths.workspace, cwd: session.cwd }, currentStep.workflow, currentStep.args, interruption);
 				}
 				await session.state.startStep(toRunStateStep(currentStep));
 				const stepResult = await this.executeWorkflowStep(session, currentStep);
@@ -199,12 +199,12 @@ export class NornEngine {
 					await session.state.completeRun(stepResult.workflow.id, stepResult.metadata);
 					await recordRunEvent(session, { type: "run.completed", workflowId: stepResult.workflow.id, metadata: stepResult.metadata });
 					await commitRunBoundary(session, `run completed: ${stepResult.workflow.id}`);
-					return { status: "completed", id: session.run.id, name: session.state.currentState().name, workspace: session.paths.workspace, cwd: session.cwd, workflowId: stepResult.workflow.id, metadata: stepResult.metadata };
+					return { status: "completed", id: session.execution.run.id, name: session.state.currentState().name, workspace: session.paths.workspace, cwd: session.cwd, workflowId: stepResult.workflow.id, metadata: stepResult.metadata };
 				}
 				if (stepResult.type === "fail") {
 					await session.state.failRun(stepResult.workflow.id, stepResult.metadata);
 					await recordRunEvent(session, { type: "run.failed", workflowId: stepResult.workflow.id, metadata: stepResult.metadata });
-					return { status: "failed", id: session.run.id, name: session.state.currentState().name, workspace: session.paths.workspace, cwd: session.cwd, workflowId: stepResult.workflow.id, metadata: stepResult.metadata };
+					return { status: "failed", id: session.execution.run.id, name: session.state.currentState().name, workspace: session.paths.workspace, cwd: session.cwd, workflowId: stepResult.workflow.id, metadata: stepResult.metadata };
 				}
 				const nextStep = this.nextWorkflowStep(stepResult);
 				await session.state.completeWithNext(currentStep.workflow.id, toRunStateStep(nextStep));
@@ -217,7 +217,7 @@ export class NornEngine {
 			if (isRunStopped(session, error)) {
 				await session.state.stopCurrent();
 				await recordRunEvent(session, { type: "run.stopped", workflowId: currentStep.workflow.id });
-				return { status: "stopped", id: session.run.id, name: session.state.currentState().name, workspace: session.paths.workspace, cwd: session.cwd, workflowId: currentStep.workflow.id };
+				return { status: "stopped", id: session.execution.run.id, name: session.state.currentState().name, workspace: session.paths.workspace, cwd: session.cwd, workflowId: currentStep.workflow.id };
 			}
 			await session.state.failCurrent(errorMessage(error));
 			await recordRunEvent(session, { type: "run.failed", workflowId: currentStep.workflow.id, error: errorMessage(error) });
@@ -233,7 +233,7 @@ export class NornEngine {
 		try {
 			await assertWorkspaceBoundary(session, session.paths.workspace);
 			await recordRunEvent(session, { type: "workflow.started", workflowId: step.workflow.id });
-			const result = await this.registry.execute({ workflow: step.workflow, run: session.run, paths: session.paths, args: step.args, configOverride: session.state.currentState().configOverride });
+			const result = await this.registry.execute({ workflow: step.workflow, execution: session.execution, paths: session.paths, args: step.args, configOverride: session.state.currentState().configOverride });
 			await assertWorkspaceBoundary(session, session.paths.workspace);
 			const durationMs = Date.now() - startedAtMs;
 			if (result.type === "complete") await recordRunEvent(session, { type: "workflow.completed", workflowId: result.workflow.id, durationMs, metadata: result.metadata });
@@ -289,7 +289,7 @@ export class NornEngine {
 				initialCwd: cwd,
 				startedAt,
 			} });
-			const run = await this.buildRun({ id, currentRoot, paths, signal: activeRun.controller.signal, logger });
+			const execution = await this.buildExecutionContext({ id, currentRoot, paths, signal: activeRun.controller.signal, logger });
 			const state = await NornRunStateStore.create(runRoot, {
 				projectRoot: paths.project,
 				id,
@@ -303,7 +303,7 @@ export class NornEngine {
 				},
 				startedAt,
 			});
-			const session = { runRoot, cwd, run, paths, state, lease, runStore, logger, activeRun };
+			const session = { runRoot, cwd, execution, paths, state, lease, runStore, logger, activeRun };
 			await logger.record({ type: "run.started", workflowId: workflow.id, cwd, workspace });
 			await commitRunBoundary(session, `run started: ${workflow.id}`);
 			return session;
@@ -324,26 +324,26 @@ export class NornEngine {
 			const currentRoot = runCurrentRoot(runRoot);
 			const logger = await NornRunLogger.load(join(currentRoot, MANIFEST_FILE_NAME), createRunFileCoordinator(runRoot));
 			const paths: NornWorkflowPaths = { project: currentState.projectRoot ?? resolve(runRoot, "../../.."), workspace: currentState.workspace };
-			const run = await this.buildRun({ id: currentState.id, currentRoot, paths, signal: activeRun.controller.signal, logger });
-			return { runRoot, cwd: process.cwd(), run, paths, state, lease, runStore, logger, activeRun };
+			const execution = await this.buildExecutionContext({ id: currentState.id, currentRoot, paths, signal: activeRun.controller.signal, logger });
+			return { runRoot, cwd: process.cwd(), execution, paths, state, lease, runStore, logger, activeRun };
 		} catch (error) {
 			this.failActiveRun(runRoot, activeRun);
 			throw error;
 		}
 	}
 
-	private async buildRun(input: {
+	private async buildExecutionContext(input: {
 		readonly id: string;
 		readonly currentRoot: string;
 		readonly paths: NornWorkflowPaths;
 		readonly signal: AbortSignal;
 		readonly logger: NornRunLogger;
-	}): Promise<NornRunContext> {
+	}): Promise<NornExecutionContext> {
 		const logsRoot = join(input.currentRoot, "logs");
 		await mkdir(input.paths.workspace, { recursive: true });
 		await mkdir(logsRoot, { recursive: true });
 		const files = createRunFileCoordinator(dirname(input.currentRoot));
-		return new NornRunContext({
+		return new NornExecutionContext({
 			id: input.id,
 			runRoot: input.currentRoot,
 			signal: input.signal,

package/assets/packages/cli/src/internal/{run.ts → execution-context.ts}

@@ -1,5 +1,5 @@
 import type { CreateAgentSessionOptions } from "@earendil-works/pi-coding-agent";
-import type { NornRunOutcomeMetadata, NornRun } from "@vimhead.dev/norn";
+import type { NornAgents, NornCommands, NornLogs, NornRun } from "@vimhead.dev/norn";
 import { createWorkflowTransition } from "@vimhead.dev/norn-core/workflow-transition";
 import type { NornAgentResponseCollector } from "./agent-response-tool.ts";
 import { NornAgentRunner } from "./agents.ts";
@@ -7,7 +7,7 @@ import { NornCommandRunner } from "./commands.ts";
 import type { NornRunLogs } from "./logs.ts";
 import type { NornRunLogger } from "./run-log.ts";
 
-type DefaultNornRunInput = {
+type NornExecutionContextInput = {
 	readonly id: string;
 	readonly runRoot: string;
 	readonly signal?: AbortSignal;
@@ -19,34 +19,38 @@ type DefaultNornRunInput = {
 	readonly logs: NornRunLogs;
 };
 
-export class NornRunContext implements NornRun {
-	readonly logs: NornRun["logs"];
-	readonly commands: NornRun["commands"];
-	readonly agents: NornRun["agents"];
-	readonly id: string;
+export class NornExecutionContext {
+	readonly run: NornRun;
+	readonly logs: NornLogs;
+	readonly commands: NornCommands;
+	readonly agents: NornAgents;
 
-	constructor(private readonly input: DefaultNornRunInput) {
-		this.id = input.id;
+	constructor(private readonly input: NornExecutionContextInput) {
+		this.run = {
+			id: input.id,
+			next: (workflowId, args) => createWorkflowTransition({ workflowId, args }),
+			complete: metadata => ({ type: "complete", metadata }),
+			fail: metadata => ({ type: "fail", metadata }),
+		};
 		this.logs = {
-			read: (log) => this.input.logs.read(log),
+			read: log => this.input.logs.read(log),
 		};
 		this.commands = {
-			run: (commandInput) =>
-				new NornCommandRunner({
-					signal: this.input.signal,
-					logs: this.input.logs,
-					logger: this.input.logger,
-				}).run(commandInput),
+			run: commandInput => new NornCommandRunner({
+				signal: this.input.signal,
+				logs: this.input.logs,
+				logger: this.input.logger,
+			}).run(commandInput),
 		};
 		this.agents = {
-			createSession: (agentInput) => this.createAgentRunner().createSession(agentInput),
-			prompt: (agentInput) => this.createAgentRunner().prompt(agentInput),
+			createSession: agentInput => this.createAgentRunner().createSession(agentInput),
+			prompt: agentInput => this.createAgentRunner().prompt(agentInput),
 		};
 	}
 
 	private createAgentRunner(): NornAgentRunner {
 		return new NornAgentRunner({
-			id: this.id,
+			id: this.input.id,
 			runRoot: this.input.runRoot,
 			signal: this.input.signal,
 			model: this.input.model,
@@ -57,16 +61,4 @@ export class NornRunContext implements NornRun {
 			responseCollector: this.input.responseCollector,
 		});
 	}
-
-	next(workflowId: string, args: unknown): ReturnType<NornRun["next"]> {
-		return createWorkflowTransition({ workflowId, args });
-	}
-
-	complete(metadata?: NornRunOutcomeMetadata): ReturnType<NornRun["complete"]> {
-		return { type: "complete", metadata };
-	}
-
-	fail(metadata: NornRunOutcomeMetadata & { readonly summary: string }): ReturnType<NornRun["fail"]> {
-		return { type: "fail", metadata };
-	}
 }

package/assets/packages/cli/src/internal/workflow-registry.ts

@@ -1,4 +1,4 @@
-import { isWorkflowComplete, isWorkflowDeclaration, isWorkflowFail, isWorkflowNext, type NornAnyWorkflowDeclaration, type NornDispose, type NornInspectedWorkflowInfo, type NornRegisteredWorkflowInfo, type NornRunComplete, type NornRunFail, type NornRun, type NornRunNext, type NornWorkflowPaths, type NornWorkflowContext, type NornWorkflowGateInfo, type NornWorkflowSource, type NornWorkflowScopeInfo, type NornProjectConfigurationInfo } from "@vimhead.dev/norn";
+import { isWorkflowComplete, isWorkflowDeclaration, isWorkflowFail, isWorkflowNext, type NornAnyWorkflowDeclaration, type NornDispose, type NornInspectedWorkflowInfo, type NornRegisteredWorkflowInfo, type NornRunComplete, type NornRunFail, type NornRunNext, type NornWorkflowPaths, type NornWorkflowContext, type NornWorkflowGateInfo, type NornWorkflowSource, type NornWorkflowScopeInfo, type NornProjectConfigurationInfo } from "@vimhead.dev/norn";
 import { assertWorkflowMetadata, inspectSchema, isPlainObject, schemaShape, schemaType, unwrapSchema } from "@vimhead.dev/norn/schema";
 import type { TSchema } from "typebox";
 import { Value } from "typebox/value";
@@ -43,7 +43,7 @@ export type NornWorkflowStepResult =
 	| { readonly type: "fail"; readonly workflow: NornAnyWorkflowDeclaration; readonly metadata: NornRunFail["metadata"] };
 
 type NornExecutionContextInput = {
-	readonly run: NornRun;
+	readonly execution: Pick<NornWorkflowContext, "run" | "agents" | "commands" | "logs">;
 	readonly paths: NornWorkflowPaths;
 	readonly args: unknown;
 	readonly configOverride: unknown;
@@ -105,7 +105,7 @@ export class NornWorkflowRegistry {
 		].map(({ configuration, scopeId }) => ({ key: configuration.key, scopeId, configSchema: configuration.schema ? inspectSchema(configuration.schema) : null, config: configuration.value }));
 	}
 
-	launchableEntries(): NornRegisteredWorkflow[] { return this.sortedEntries().filter(({ workflow }) => workflow.isEntrypoint); }
+	launchableEntries(): NornRegisteredWorkflow[] { return this.sortedEntries().filter(({ workflow }) => workflow.entrypoint !== false); }
 	workflowById(workflowId: string): NornAnyWorkflowDeclaration | undefined { return this.entries.get(workflowId)?.workflow; }
 
 	async describeGate(input: NornWorkflowExecutionInput): Promise<string> {
@@ -129,14 +129,17 @@ export class NornWorkflowRegistry {
 	}
 
 	private createExecutionContext(input: NornExecutionContextInput & { readonly entry: NornRegisteredWorkflow }): NornWorkflowContext {
-		const { entry, run, paths, configOverride } = input;
+		const { entry, execution, paths, configOverride } = input;
 		const scope = entry.scopeId ? this.scopes.get(entry.scopeId) : undefined;
 		return {
 			args: Value.Decode(entry.workflow.args, input.args),
 			config: parseExecutionConfig(entry.configuration, configOverride),
 			...(scope ? { scope: { id: scope.definition.id, config: parseExecutionConfig(scope.configuration, configOverride) } } : {}),
 			paths,
-			run,
+			run: execution.run,
+			agents: execution.agents,
+			commands: execution.commands,
+			logs: execution.logs,
 		};
 	}
 
@@ -186,7 +189,9 @@ function assertGateWorkflow(workflow: NornAnyWorkflowDeclaration): void {
 
 function workflowInfo(entry: NornRegisteredWorkflow): NornRegisteredWorkflowInfo {
 	return {
-		id: entry.workflow.id, instructions: entry.workflow.instructions, isEntrypoint: entry.workflow.isEntrypoint,
+		id: entry.workflow.id,
+		instructions: entry.workflow.entrypoint === false ? undefined : entry.workflow.entrypoint.instructions,
+		isEntrypoint: entry.workflow.entrypoint !== false,
 		source: entry.source,
 		configKey: entry.workflow.id,
 		scope: entry.scopeId ? { id: entry.scopeId } : undefined,

package/assets/packages/sdk/src/api.ts

@@ -32,8 +32,7 @@ export type NornWorkflowDeclaration<
 	(args: StaticEncode<ArgsSchema>): NornRunNext;
 	readonly kind: typeof WORKFLOW_DECLARATION_KIND;
 	readonly id: Id;
-	readonly isEntrypoint: boolean;
-	readonly instructions?: string;
+	readonly entrypoint: NornWorkflowEntrypoint;
 	readonly args: ArgsSchema;
 	readonly gate?: NornWorkflowGate<ArgsSchema> & {
 		describe?(context: NornWorkflowContext<ArgsSchema, ConfigSchema, Scope>): MaybePromise<string>;
@@ -65,9 +64,7 @@ export type NornWorkflowGate<ArgsSchema extends TSchema> = unknown extends Stati
 			readonly fields?: never;
 		};
 
-type NornWorkflowInstructions =
-	| { readonly isEntrypoint: true; readonly instructions: string }
-	| { readonly isEntrypoint: false; readonly instructions?: string };
+export type NornWorkflowEntrypoint = false | { readonly instructions: string };
 
 type WorkflowConfig<Schema extends TSchema | undefined> = Schema extends TSchema ? StaticDecode<Schema> : undefined;
 
@@ -79,73 +76,77 @@ export type NornWorkflowContext<
 	readonly args: StaticDecode<ArgsSchema>;
 	readonly config: WorkflowConfig<ConfigSchema>;
 	readonly paths: NornWorkflowPaths;
+	readonly agents: NornAgents;
+	readonly commands: NornCommands;
+	readonly logs: NornLogs;
 	readonly run: NornRun;
 } & (Scope extends NornWorkflowScopeInfo ? {
 	readonly scope: { readonly id: Scope["id"]; readonly config: WorkflowConfig<Scope["config"]> };
 } : {});
 
 export type NornWorkflowDefinition<
-	Id extends string = string,
+	Name extends string = string,
 	ArgsSchema extends TSchema = TSchema,
 	ConfigSchema extends TSchema | undefined = undefined,
 	Scope extends NornWorkflowScopeInfo | undefined = undefined,
 > = {
-	readonly id: Id;
+	readonly name: Name;
+	readonly entrypoint: NornWorkflowEntrypoint;
 	readonly args: ArgsSchema;
 	readonly config?: ConfigSchema;
 	readonly gate?: NornWorkflowGate<ArgsSchema> & {
 		describe?(context: NornWorkflowContext<ArgsSchema, ConfigSchema, Scope>): MaybePromise<string>;
 	};
 	execute(context: NornWorkflowContext<ArgsSchema, ConfigSchema, Scope>): MaybePromise<WorkflowResult>;
-} & NornWorkflowInstructions;
+};
 
 export type NornWorkflowScopeInfo = {
 	readonly id: string;
 	readonly config?: TSchema;
 };
 
-export type NornWorkflowScope<Id extends string, ConfigSchema extends TSchema | undefined> = {
-	readonly id: Id;
+export type NornWorkflowScope<Name extends string, ConfigSchema extends TSchema | undefined> = {
+	readonly id: Name;
 	readonly config: ConfigSchema;
-	workflow<const LocalId extends string, ArgsSchema extends TSchema, LocalConfig extends TSchema | undefined = undefined>(
-		definition: NornWorkflowDefinition<LocalId, ArgsSchema, LocalConfig, { readonly id: Id; readonly config: ConfigSchema }>,
-	): NornWorkflowDeclaration<`${Id}.${LocalId}`, ArgsSchema, LocalConfig, { readonly id: Id; readonly config: ConfigSchema }>;
+	workflow<const LocalName extends string, ArgsSchema extends TSchema, LocalConfig extends TSchema | undefined = undefined>(
+		definition: NornWorkflowDefinition<LocalName, ArgsSchema, LocalConfig, { readonly id: Name; readonly config: ConfigSchema }>,
+	): NornWorkflowDeclaration<`${Name}.${LocalName}`, ArgsSchema, LocalConfig, { readonly id: Name; readonly config: ConfigSchema }>;
 };
 
 export function workflow<
-	const Id extends string,
+	const Name extends string,
 	ArgsSchema extends TSchema,
 	ConfigSchema extends TSchema | undefined = undefined,
->(definition: NornWorkflowDefinition<Id, ArgsSchema, ConfigSchema>): NornWorkflowDeclaration<Id, ArgsSchema, ConfigSchema, undefined> {
-	return createWorkflow({ definition, scope: undefined });
+>(definition: NornWorkflowDefinition<Name, ArgsSchema, ConfigSchema>): NornWorkflowDeclaration<Name, ArgsSchema, ConfigSchema, undefined> {
+	return createWorkflow({ definition, id: definition.name, scope: undefined });
 }
 
 function createWorkflow<Id extends string, ArgsSchema extends TSchema, ConfigSchema extends TSchema | undefined, Scope extends NornWorkflowScopeInfo | undefined>(
-	input: { readonly definition: NornWorkflowDefinition<Id, ArgsSchema, ConfigSchema, Scope>; readonly scope: Scope },
+	input: { readonly definition: NornWorkflowDefinition<string, ArgsSchema, ConfigSchema, Scope>; readonly id: Id; readonly scope: Scope },
 ): NornWorkflowDeclaration<Id, ArgsSchema, ConfigSchema, Scope> {
-	const { definition, scope } = input;
-	assertDeclarationId(definition.id);
-	const callable = (args: StaticEncode<ArgsSchema>): NornRunNext => createWorkflowTransition({ workflowId: definition.id, args });
-	const result = Object.assign(callable, definition, {
+	const { definition: { name, ...properties }, id, scope } = input;
+	assertDeclarationName(name);
+	const callable = (args: StaticEncode<ArgsSchema>): NornRunNext => createWorkflowTransition({ workflowId: id, args });
+	const result = Object.assign(callable, properties, {
 		kind: WORKFLOW_DECLARATION_KIND,
+		id,
 		scope,
 	}) as NornWorkflowDeclaration<Id, ArgsSchema, ConfigSchema, Scope>;
-	if (!isWorkflowDeclaration(result)) throw new Error(`Invalid workflow definition: ${definition.id}`);
 	assertWorkflowMetadata(result);
+	if (!isWorkflowDeclaration(result)) throw new Error(`Invalid workflow definition: ${id}`);
 	return result;
 }
 
-export function workflowScope<const Id extends string, ConfigSchema extends TSchema | undefined = undefined>(
-	input: { readonly id: Id; readonly config?: ConfigSchema },
-): NornWorkflowScope<Id, ConfigSchema> {
-	assertDeclarationId(input.id);
-	const scope = { id: input.id, config: input.config as ConfigSchema };
+export function workflowScope<const Name extends string, ConfigSchema extends TSchema | undefined = undefined>(
+	input: { readonly name: Name; readonly config?: ConfigSchema },
+): NornWorkflowScope<Name, ConfigSchema> {
+	assertDeclarationName(input.name);
+	const scope = { id: input.name, config: input.config as ConfigSchema };
 	return {
-		id: input.id,
-		config: input.config as ConfigSchema,
+		id: scope.id,
+		config: scope.config,
 		workflow(definition) {
-			assertDeclarationId(definition.id);
-			return createWorkflow({ definition: { ...definition, id: `${input.id}.${definition.id}` }, scope });
+			return createWorkflow({ definition, id: `${scope.id}.${definition.name}`, scope });
 		},
 	};
 }
@@ -467,16 +468,19 @@ export type NornRun = {
 	next(workflowId: string, args: unknown): NornRunNext;
 	complete(metadata?: NornRunOutcomeMetadata): NornRunComplete;
 	fail(metadata: NornRunOutcomeMetadata & { readonly summary: string }): NornRunFail;
-	logs: {
-		read(log: NornLogRef): Promise<string>;
-	};
-	commands: {
-		run(input: NornCommandRunInput): Promise<NornCommandRunResult>;
-	};
-	agents: {
-		createSession(input: NornAgentCreateSessionInput): Promise<NornAgentSession>;
-		prompt<ResponseSchema extends TSchema>(input: NornAgentSinglePromptInput<ResponseSchema>): Promise<StaticDecode<ResponseSchema>>;
-	};
+};
+
+export type NornLogs = {
+	read(log: NornLogRef): Promise<string>;
+};
+
+export type NornCommands = {
+	run(input: NornCommandRunInput): Promise<NornCommandRunResult>;
+};
+
+export type NornAgents = {
+	createSession(input: NornAgentCreateSessionInput): Promise<NornAgentSession>;
+	prompt<ResponseSchema extends TSchema>(input: NornAgentSinglePromptInput<ResponseSchema>): Promise<StaticDecode<ResponseSchema>>;
 };
 
 export type NornWorkflowSource = {
@@ -552,19 +556,18 @@ export type NornProjectInfo = {
 	readonly modules: readonly NornWorkflowSource[];
 };
 
-function assertDeclarationId(id: string): void {
-	if (typeof id !== "string" || id.trim().length === 0 || id.split(".").some(segment => segment.length === 0)) throw new Error(`Invalid workflow or scope id: ${id}`);
+function assertDeclarationName(name: string): void {
+	if (typeof name !== "string" || name.trim().length === 0 || name.includes(".")) throw new Error(`Invalid workflow or scope name: ${name}; expected a nonempty name without dots`);
 }
 
 export function isWorkflowDeclaration(value: unknown): value is NornAnyWorkflowDeclaration {
 	if (typeof value !== "function") return false;
-	const candidate = value as { kind?: unknown; id?: unknown; instructions?: unknown; isEntrypoint?: unknown; args?: unknown; execute?: unknown };
+	const candidate = value as { kind?: unknown; id?: unknown; entrypoint?: unknown; args?: unknown; execute?: unknown };
 	return (
 		candidate.kind === WORKFLOW_DECLARATION_KIND &&
 		typeof candidate.id === "string" &&
 		candidate.id.length > 0 &&
-		(candidate.instructions === undefined || typeof candidate.instructions === "string") &&
-		typeof candidate.isEntrypoint === "boolean" &&
+		(candidate.entrypoint === false || (isPlainObject(candidate.entrypoint) && typeof candidate.entrypoint.instructions === "string")) &&
 		Boolean(candidate.args) &&
 		typeof candidate.execute === "function"
 	);

package/assets/packages/sdk/src/schema.ts

@@ -43,11 +43,11 @@ function assertWorkflowReferenceAnnotations(schema: unknown): void {
 }
 
 export function assertWorkflowMetadata(workflow: NornAnyWorkflowDeclaration): void {
-	if (workflow.instructions !== undefined && (typeof workflow.instructions !== "string" || workflow.instructions.trim().length === 0)) {
-		throw new Error(`Workflow instructions must be a nonempty string: ${workflow.id}`);
-	}
-	if (workflow.isEntrypoint && workflow.instructions === undefined) {
-		throw new Error(`Entrypoint workflow requires instructions: ${workflow.id}`);
+	const { entrypoint } = workflow;
+	if (entrypoint === false) return;
+	if (!isPlainObject(entrypoint)) throw new Error(`Workflow entrypoint must be false or an object with instructions: ${workflow.id}`);
+	if (typeof entrypoint.instructions !== "string" || entrypoint.instructions.trim().length === 0) {
+		throw new Error(`Workflow entrypoint.instructions must be a nonempty string: ${workflow.id}`);
 	}
 }
 

package/assets/tests/workflow-ref.test.ts

@@ -1,12 +1,13 @@
-import { workflow, isWorkflowDeclaration, workflowRefSchema, type NornWorkflowRefSchemaOptions } from "@vimhead.dev/norn";
+import { workflowScope, isWorkflowDeclaration, workflowRefSchema, type NornWorkflowRefSchemaOptions } from "@vimhead.dev/norn";
 import { inspectSchema } from "@vimhead.dev/norn/schema";
 import assert from "node:assert/strict";
 import { Type } from "typebox";
 import { Value } from "typebox/value";
 import { expect, expectTypeOf, test } from "vitest";
 
-const target = workflow({
-	id: "refs.finish", isEntrypoint: false, args: Type.Object({ report: Type.String() }),
+const refs = workflowScope({ name: "refs" });
+const target = refs.workflow({
+	name: "finish", entrypoint: false, args: Type.Object({ report: Type.String() }),
 	execute() { throw new Error("A callable must select a transition, not execute it"); },
 });
 

package/dist/generated-build-info.d.ts

@@ -1,7 +1,7 @@
 export declare const NORN_GENERATED_BUILD_INFO: {
     readonly kind: "npm-registry";
-    readonly version: "0.1.0-tip.35436871363.1";
-    readonly commit: "49b14d0ed0c9633fc6ee530a557ec7babbf52b22";
+    readonly version: "0.1.0-tip.35570530940.1";
+    readonly commit: "48ecaf47ae0e82e17970db9465497a4e1ad5ff10";
     readonly packageSpec: "@vimhead.dev/norn-cli@tip";
     readonly upgrade: {
         readonly supported: false;

package/dist/generated-build-info.js

@@ -1,8 +1,8 @@
 // src/generated-build-info.ts
 var NORN_GENERATED_BUILD_INFO = {
   "kind": "npm-registry",
-  "version": "0.1.0-tip.35436871363.1",
-  "commit": "49b14d0ed0c9633fc6ee530a557ec7babbf52b22",
+  "version": "0.1.0-tip.35570530940.1",
+  "commit": "48ecaf47ae0e82e17970db9465497a4e1ad5ff10",
   "packageSpec": "@vimhead.dev/norn-cli@tip",
   "upgrade": {
     "supported": false,

package/dist/internal/engine.d.ts

@@ -33,7 +33,7 @@ export declare class NornEngine {
     private nextWorkflowStep;
     private createRunSession;
     private openRunSession;
-    private buildRun;
+    private buildExecutionContext;
     private startActiveRun;
     private finishActiveRun;
     private failActiveRun;