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

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

@@ -7,13 +7,13 @@ import { planningArgsSchema } from "./schema.ts";
 import { planningAgentResponseSchema } from "./schema.ts";
 
 export const planningWorkflow = developmentLoopScope.workflow({
-	id: "planning",
+	name: "planning",
 	isEntrypoint: false,
 	instructions: "Create an implementation plan for a repository task.",
 	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,24 @@ import { ensureCommandSucceeded } from "../../shared/commands.ts";
 import { reviewAgentResponseSchema } from "./schema.ts";
 
 export const reviewWorkflow = developmentLoopScope.workflow({
-	id: "review",
+	name: "review",
 	isEntrypoint: false,
 	instructions: "Review the current repository boundary changes.",
 	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,7 +7,7 @@ import { reviewRouterArgsSchema } from "./schema.ts";
 import type { StoredReview } from "../review/schema.ts";
 
 export const reviewRouterWorkflow = developmentLoopScope.workflow({
-	id: "reviewRouter",
+	name: "reviewRouter",
 	isEntrypoint: false,
 	instructions: "Route implementation and review iterations based on the latest review decision.",
 	gate: {

package/assets/package.json

@@ -1 +1 @@
-{"version":"0.1.0-tip.35436871363.1"}
+{"version":"0.1.0-tip.35568631545.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.35568631545.1",
+  "commit": "f16f4b16ede3d325d56cdbd1f21193b3a3d45d38",
   "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;
@@ -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,
 		};
 	}
 

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

@@ -79,18 +79,21 @@ 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 args: ArgsSchema;
 	readonly config?: ConfigSchema;
 	readonly gate?: NornWorkflowGate<ArgsSchema> & {
@@ -104,48 +107,48 @@ export type NornWorkflowScopeInfo = {
 	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}`);
+	if (!isWorkflowDeclaration(result)) throw new Error(`Invalid workflow definition: ${id}`);
 	assertWorkflowMetadata(result);
 	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 +470,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,8 +558,8 @@ 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 {

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", isEntrypoint: 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.35568631545.1";
+    readonly commit: "f16f4b16ede3d325d56cdbd1f21193b3a3d45d38";
     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.35568631545.1",
+  "commit": "f16f4b16ede3d325d56cdbd1f21193b3a3d45d38",
   "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;

package/dist/internal/engine.js

@@ -12,7 +12,7 @@ import { NornRunLease } from "./run-lease.js";
 import { NornRunLogger } from "./run-log.js";
 import { assertRunVersion, getRunInfo, mergeInterruptedWorkflowArgs, NornRunStateStore, resolveRunRoot } from "./run-state.js";
 import { NornRunStore, runCurrentRoot } from "./run-store.js";
-import { NornRunContext } from "./run.js";
+import { NornExecutionContext } from "./execution-context.js";
 import { NornWorkflowRegistry } from "./workflow-registry.js";
 var RUNS_DIR_NAME = ".norn";
 var MANIFEST_FILE_NAME = "manifest.json";
@@ -127,12 +127,12 @@ var NornEngine = class {
       for (let step = 1; step <= 1e3; 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);
@@ -141,12 +141,12 @@ var NornEngine = class {
           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));
@@ -159,7 +159,7 @@ var NornEngine = class {
       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) });
@@ -174,7 +174,7 @@ var NornEngine = class {
     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 });
@@ -224,7 +224,7 @@ var NornEngine = class {
         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,
@@ -241,7 +241,7 @@ var NornEngine = class {
         },
         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;
@@ -261,19 +261,19 @@ var NornEngine = class {
       const currentRoot = runCurrentRoot(runRoot);
       const logger = await NornRunLogger.load(join(currentRoot, MANIFEST_FILE_NAME), createRunFileCoordinator(runRoot));
       const paths = { 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;
     }
   }
-  async buildRun(input) {
+  async buildExecutionContext(input) {
     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,