@vimhead.dev/norn 0.1.0-tip.0

package/README.md

@@ -0,0 +1,13 @@
+# Norn SDK
+
+TypeScript authoring APIs for reusable Norn workflows.
+
+```bash
+npm install -D @vimhead.dev/norn@tip
+```
+
+Import declarations and helpers from `@vimhead.dev/norn`. Match the SDK version
+to the runtime reported by `norn version`.
+
+Use `norn docs inspect` for matching local documentation and runnable examples.
+[Installation and project overview](https://github.com/vimhead/norn#readme).

package/dist/agent-resource-adapter.d.ts

@@ -0,0 +1,12 @@
+import type { ToolDefinition } from "@earendil-works/pi-coding-agent";
+export type NornAgentResourceBinding = {
+    readonly tools: readonly ToolDefinition[];
+    dispose(): Promise<void>;
+};
+export type NornAgentResourceAdapter = {
+    readonly name: string;
+    bind(context: {
+        readonly runId: string;
+        readonly label: string;
+    }): Promise<NornAgentResourceBinding>;
+};

package/dist/api.d.ts

@@ -0,0 +1,550 @@
+import type { CreateAgentSessionOptions, EventBus, PromptOptions } from "@earendil-works/pi-coding-agent";
+import { z } from "zod";
+import type { NornResolvedSeerModeConfig } from "./seer/config.ts";
+declare const WORKFLOW_DECLARATION_KIND = "norn.workflow";
+export type MaybePromise<T> = T | Promise<T>;
+export type NornDispose = () => void;
+export type NornWorkflowAnyGate = {
+    readonly enabled: true;
+    readonly fields?: readonly string[];
+};
+export type NornWorkflowIsolationMode = "runWorkspace" | "project";
+export type NornWorkflowIsolation<Mode extends NornWorkflowIsolationMode = NornWorkflowIsolationMode> = {
+    readonly mode: Mode;
+};
+declare const nornWorkflowRefParamsBrand: unique symbol;
+declare const nornWorkflowRefForwardParamsBrand: unique symbol;
+type NornWorkflowRefForwardParams = Record<string, unknown> & {
+    readonly [nornWorkflowRefForwardParamsBrand]: true;
+};
+export type NornWorkflowRef<ParamsSchema extends z.ZodType = z.ZodType, Id extends string = string, ForwardParams = unknown> = Id & {
+    readonly [nornWorkflowRefParamsBrand]: (params: z.input<ParamsSchema> & ForwardParams) => z.input<ParamsSchema> & ForwardParams;
+};
+export type NornWorkflowDeclaration<Id extends string = string, ParamsSchema extends z.ZodType = z.ZodType, IsolationMode extends NornWorkflowIsolationMode = NornWorkflowIsolationMode> = {
+    readonly kind: typeof WORKFLOW_DECLARATION_KIND;
+    readonly id: NornWorkflowRef<ParamsSchema, Id>;
+    readonly isEntrypoint: boolean;
+    readonly instructions?: string;
+    readonly params: ParamsSchema;
+    readonly gate?: NornWorkflowAnyGate;
+    readonly isolation: NornWorkflowIsolation<IsolationMode>;
+};
+export type NornAnyWorkflowDeclaration = NornWorkflowDeclaration<string, z.ZodType<any, any>>;
+export type NornWorkflowTarget<ParamsSchema extends z.ZodType = z.ZodType> = NornWorkflowDeclaration<string, ParamsSchema> | NornWorkflowRef<ParamsSchema>;
+export type NornWorkflowRefSchemaInput<ParamsSchema extends z.ZodType = z.ZodType> = string | {
+    readonly id: NornWorkflowRef<ParamsSchema>;
+    readonly workflow?: never;
+    readonly forwardParams?: never;
+};
+export type NornWorkflowRefSchemaOptions<ParamsSchema extends z.ZodType = z.ZodType> = {
+    readonly params?: ParamsSchema;
+};
+export type NornWorkflowRefInput<ParamsSchema extends z.ZodType> = NornWorkflowRefSchemaInput<ParamsSchema> | {
+    readonly workflow: NornWorkflowRefSchemaInput<z.ZodType<any, any>>;
+    readonly forwardParams: Record<string, unknown>;
+};
+export type NornWorkflowRefOutput<ParamsSchema extends z.ZodType> = {
+    readonly workflow: NornWorkflowRef<ParamsSchema, string, NornWorkflowRefForwardParams>;
+    readonly forwardParams: NornWorkflowRefForwardParams;
+};
+export type NornWorkflowParamsInput<TWorkflow extends NornAnyWorkflowDeclaration> = z.input<TWorkflow["params"]>;
+export type NornWorkflowParams<TWorkflow extends NornAnyWorkflowDeclaration> = z.output<TWorkflow["params"]>;
+export type NornWorkflowTargetParamsInput<TWorkflow extends NornWorkflowTarget<any>> = TWorkflow extends NornWorkflowDeclaration<string, infer ParamsSchema> ? z.input<ParamsSchema> : TWorkflow extends NornWorkflowRef<infer ParamsSchema, string, infer ForwardParams> ? z.input<ParamsSchema> & ForwardParams : never;
+export type NornWorkflowGate<ParamsSchema extends z.ZodType> = unknown extends z.input<ParamsSchema> ? NornWorkflowAnyGate : z.input<ParamsSchema> extends Record<string, unknown> ? {
+    readonly enabled: true;
+    readonly fields?: readonly Extract<keyof z.input<ParamsSchema>, string>[];
+} : {
+    readonly enabled: true;
+    readonly fields?: never;
+};
+type NornWorkflowInstructions = {
+    readonly isEntrypoint: true;
+    readonly instructions: string;
+} | {
+    readonly isEntrypoint: false;
+    readonly instructions?: string;
+};
+export type NornWorkflowDefinition<Id extends string | undefined = string | undefined, ParamsSchema extends z.ZodType = z.ZodType, IsolationMode extends NornWorkflowIsolationMode = NornWorkflowIsolationMode> = {
+    readonly id?: Id;
+    readonly params: ParamsSchema;
+    readonly gate?: NornWorkflowGate<ParamsSchema>;
+    readonly isolation?: NornWorkflowIsolation<IsolationMode>;
+} & NornWorkflowInstructions;
+export type NornAnyWorkflowDefinition = {
+    readonly id?: string;
+    readonly params: z.ZodType;
+    readonly gate?: NornWorkflowAnyGate;
+    readonly isolation?: NornWorkflowIsolation;
+} & NornWorkflowInstructions;
+export type NornWorkflowStateDefinition<T = unknown, Id extends string = string> = {
+    readonly id: Id;
+    readonly description?: string;
+    readonly schema: z.ZodType<T>;
+};
+export type NornWorkflowStateDefinitionInput<T = unknown, Id extends string | undefined = string | undefined> = {
+    readonly id?: Id;
+    readonly description?: string;
+    readonly schema: z.ZodType<T>;
+};
+export type NornWorkflowPluginWorkflows = Record<string, NornAnyWorkflowDefinition>;
+export type NornWorkflowPluginStateTree = {
+    readonly [key: string]: NornWorkflowPluginStateTreeNode;
+};
+export type NornWorkflowPluginStateTreeNode = z.ZodType | NornWorkflowStateDefinitionInput | NornWorkflowPluginStateTree;
+type JoinPath<Head extends string, Parts extends readonly string[]> = Parts extends readonly [] ? Head : Parts extends readonly [infer First extends string, ...infer Rest extends string[]] ? JoinPath<`${Head}.${First}`, Rest> : string;
+type NornInvalidGateFields<TWorkflow> = TWorkflow extends {
+    readonly params: infer ParamsSchema extends z.ZodType;
+    readonly gate: {
+        readonly fields: infer Fields extends readonly string[];
+    };
+} ? Exclude<Fields[number], Extract<keyof z.input<ParamsSchema>, string>> : never;
+type NornValidatedWorkflowGate<TWorkflow> = [NornInvalidGateFields<TWorkflow>] extends [never] ? unknown : {
+    readonly gate: {
+        readonly fields: readonly Extract<keyof z.input<TWorkflow extends {
+            readonly params: infer ParamsSchema extends z.ZodType;
+        } ? ParamsSchema : z.ZodType>, string>[];
+    };
+};
+export type NornValidatedWorkflowGates<Workflows> = {
+    readonly [Key in keyof Workflows]: NornValidatedWorkflowGate<Workflows[Key]>;
+};
+export type NornQualifiedPluginWorkflow<PluginId extends string, WorkflowKey extends string, TWorkflow extends NornAnyWorkflowDefinition> = TWorkflow extends {
+    readonly params: infer ParamsSchema extends z.ZodType;
+} ? NornWorkflowDeclaration<TWorkflow extends {
+    readonly id: infer ExplicitId extends string;
+} ? ExplicitId : `${PluginId}.${WorkflowKey}`, ParamsSchema, TWorkflow extends {
+    readonly isolation: {
+        readonly mode: infer IsolationMode extends NornWorkflowIsolationMode;
+    };
+} ? IsolationMode : "runWorkspace"> : never;
+export type NornQualifiedPluginWorkflows<PluginId extends string, Workflows extends NornWorkflowPluginWorkflows> = {
+    readonly [Key in keyof Workflows]: NornQualifiedPluginWorkflow<PluginId, Key & string, Workflows[Key]>;
+};
+export type NornQualifiedPluginStates<PluginId extends string, States, Path extends readonly string[] = []> = {
+    readonly [Key in keyof States]: States[Key] extends z.ZodType ? NornWorkflowStateDefinition<z.output<States[Key]>, JoinPath<PluginId, [...Path, Key & string]>> : States[Key] extends NornWorkflowStateDefinitionInput<infer Value> ? NornWorkflowStateDefinition<Value, States[Key] extends {
+        readonly id: infer ExplicitId extends string;
+    } ? ExplicitId : JoinPath<PluginId, [...Path, Key & string]>> : States[Key] extends NornWorkflowPluginStateTree ? NornQualifiedPluginStates<PluginId, States[Key], [...Path, Key & string]> : never;
+};
+export type NornWorkflowPluginManifest<PluginId extends string = string, ConfigSchema extends z.ZodType | undefined = z.ZodType | undefined, Workflows extends Record<string, NornAnyWorkflowDeclaration> = Record<string, NornAnyWorkflowDeclaration>, States = undefined> = {
+    readonly id: PluginId;
+    readonly config?: ConfigSchema;
+    readonly workflows: Workflows;
+    readonly states: States;
+};
+export type NornAnyWorkflowPluginManifest = NornWorkflowPluginManifest<string, z.ZodType | undefined, Record<string, NornAnyWorkflowDeclaration>, unknown>;
+export type NornWorkflowPluginConfigSchema<TManifest extends NornAnyWorkflowPluginManifest> = TManifest extends {
+    readonly config?: infer ConfigSchema extends z.ZodType | undefined;
+} ? ConfigSchema : undefined;
+export type NornWorkflowPluginConfig<TManifest extends NornAnyWorkflowPluginManifest> = NonNullable<NornWorkflowPluginConfigSchema<TManifest>> extends z.ZodType ? z.output<NonNullable<NornWorkflowPluginConfigSchema<TManifest>>> : undefined;
+export type NornDefinePluginManifestInput<PluginId extends string, ConfigSchema extends z.ZodType | undefined, Workflows extends NornWorkflowPluginWorkflows, States extends NornWorkflowPluginStateTree | undefined> = {
+    readonly id: PluginId;
+    readonly config?: ConfigSchema;
+    readonly workflows: Workflows & NornValidatedWorkflowGates<Workflows>;
+    readonly states?: States;
+};
+export declare function definePluginManifest<const PluginId extends string, const ConfigSchema extends z.ZodType | undefined = undefined, const Workflows extends NornWorkflowPluginWorkflows = NornWorkflowPluginWorkflows, const States extends NornWorkflowPluginStateTree | undefined = undefined>(input: NornDefinePluginManifestInput<PluginId, ConfigSchema, Workflows, States>): NornWorkflowPluginManifest<PluginId, ConfigSchema, NornQualifiedPluginWorkflows<PluginId, Workflows>, States extends NornWorkflowPluginStateTree ? NornQualifiedPluginStates<PluginId, States> : undefined>;
+export type NornRunNext = {
+    readonly type: "next";
+    readonly workflowId: string;
+    readonly params: unknown;
+};
+export type NornRunOutcomeMetadata = {
+    readonly summary?: string;
+    readonly artifacts?: Record<string, NornArtifactRef>;
+    readonly logs?: Record<string, NornLogRef>;
+    readonly data?: Record<string, unknown>;
+};
+export type NornRunComplete = {
+    readonly type: "complete";
+    readonly metadata?: NornRunOutcomeMetadata;
+};
+export type NornRunFail = {
+    readonly type: "fail";
+    readonly metadata: NornRunOutcomeMetadata & {
+        readonly summary: string;
+    };
+};
+export type NornWorkflowExecutionResult = NornRunNext | NornRunComplete | NornRunFail;
+export type NornRunFor<TWorkflow extends NornAnyWorkflowDeclaration> = TWorkflow extends {
+    readonly isolation: {
+        readonly mode: "project";
+    };
+} ? NornProjectRun : NornRun;
+export type NornWorkflowGateImplementation<TWorkflow extends NornAnyWorkflowDeclaration, TConfig> = {
+    describe(run: NornRunFor<TWorkflow>, params: NornWorkflowParams<TWorkflow>, config: TConfig): MaybePromise<string>;
+};
+export type NornWorkflowImplementation<TWorkflow extends NornAnyWorkflowDeclaration, TConfig = unknown> = {
+    readonly gate?: NornWorkflowGateImplementation<TWorkflow, TConfig>;
+    execute(run: NornRunFor<TWorkflow>, params: NornWorkflowParams<TWorkflow>, config: TConfig): MaybePromise<NornWorkflowExecutionResult>;
+};
+export type NornRunStartOptions = {
+    readonly id?: string;
+    readonly name?: string;
+    readonly configOverride?: unknown;
+};
+export type NornStartedRunResult = {
+    readonly status: "running";
+    readonly id: string;
+    readonly name: string;
+    readonly path: string;
+    readonly workspace: string;
+    readonly cwd: string;
+    readonly workflowId: string;
+};
+export type NornCompletedRunResult = {
+    readonly status: "completed";
+    readonly id: string;
+    readonly name: string;
+    readonly workspace: string;
+    readonly cwd: string;
+    readonly workflowId: string;
+    readonly metadata?: NornRunOutcomeMetadata;
+};
+export type NornFailedRunResult = {
+    readonly status: "failed";
+    readonly id: string;
+    readonly name: string;
+    readonly workspace: string;
+    readonly cwd: string;
+    readonly workflowId: string;
+    readonly metadata: NornRunOutcomeMetadata & {
+        readonly summary: string;
+    };
+};
+export type NornStoppedRunResult = {
+    readonly status: "stopped";
+    readonly id: string;
+    readonly name: string;
+    readonly workspace: string;
+    readonly cwd: string;
+    readonly workflowId: string;
+};
+export type NornRunInterruption = {
+    readonly workflowId: string;
+    readonly params: unknown;
+    readonly description: string;
+    readonly fields?: readonly string[];
+};
+export type NornInterruptedRunResult = {
+    readonly status: "interrupted";
+    readonly id: string;
+    readonly name: string;
+    readonly workspace: string;
+    readonly cwd: string;
+    readonly workflowId: string;
+    readonly interruption: NornRunInterruption;
+};
+export type NornRunResult = NornStartedRunResult | NornCompletedRunResult | NornFailedRunResult | NornStoppedRunResult | NornInterruptedRunResult;
+export type NornRunStatus = "running" | "interrupted" | "stopped" | "pendingResume" | "completed" | "failed";
+export type NornRunHealth = "healthy" | "unhealthy";
+export type NornRunOutcomeInfo = {
+    readonly workflowId: string;
+    readonly completedAt: string;
+    readonly status: "completed" | "failed";
+    readonly metadata?: NornRunOutcomeMetadata;
+};
+export type NornRunFailureInfo = {
+    readonly workflowId: string;
+    readonly error: string;
+    readonly metadata?: NornRunOutcomeMetadata;
+    readonly failedAt: string;
+};
+export type NornRunInfo = {
+    readonly version: number;
+    readonly id: string;
+    readonly name: string;
+    readonly path: string;
+    readonly entrypointWorkflowId: string;
+    readonly currentWorkflowId?: string;
+    readonly status: NornRunStatus;
+    readonly health: NornRunHealth;
+    readonly interruption?: NornRunInterruption;
+    readonly outcome?: NornRunOutcomeInfo;
+    readonly failed?: NornRunFailureInfo;
+    readonly startedAt: string;
+    readonly updatedAt: string;
+};
+export type DeletedNornRunInfo = {
+    readonly id: string;
+    readonly name: string;
+    readonly path: string;
+};
+export type NornRunCheckpoint = {
+    readonly id: string;
+    readonly path: string;
+    readonly index: number;
+    readonly message: string;
+    readonly createdAt: string;
+};
+export type NornWorkflowStateReader = {
+    get<T>(state: NornWorkflowStateDefinition<T>): Promise<T>;
+    getOptional<T>(state: NornWorkflowStateDefinition<T>): Promise<T | undefined>;
+};
+export type NornWorkflowState = NornWorkflowStateReader & {
+    set<T>(state: NornWorkflowStateDefinition<T>, value: T): Promise<void>;
+};
+export type NornWorkflowPluginContext = {
+    readonly cwd: string;
+    readonly state: NornWorkflowState;
+};
+export type NornWorkflowPluginImplementation<TManifest extends NornAnyWorkflowPluginManifest> = {
+    readonly workflows: {
+        readonly [Key in keyof TManifest["workflows"]]: NornWorkflowImplementation<TManifest["workflows"][Key], NornWorkflowPluginConfig<TManifest>>;
+    };
+};
+export type NornWorkflowPluginImplementationFactory<TManifest extends NornAnyWorkflowPluginManifest> = (context: NornWorkflowPluginContext) => NornWorkflowPluginImplementation<TManifest>;
+export type NornWorkflowPluginImplementationInput<TManifest extends NornAnyWorkflowPluginManifest> = NornWorkflowPluginImplementation<TManifest> | NornWorkflowPluginImplementationFactory<TManifest>;
+export type NornWorkflowPlugin<TManifest extends NornAnyWorkflowPluginManifest = NornAnyWorkflowPluginManifest> = {
+    readonly manifest: TManifest;
+    readonly implementation: NornWorkflowPluginImplementationInput<TManifest>;
+};
+export declare function definePlugin<TManifest extends NornAnyWorkflowPluginManifest>(manifest: TManifest, implementation: NornWorkflowPluginImplementationInput<TManifest>): NornWorkflowPlugin<TManifest>;
+export type NornCommandRunInput = {
+    readonly label: string;
+    readonly command: string | readonly [string, ...string[]];
+    readonly cwd?: string;
+    readonly env?: Record<string, string>;
+    readonly timeoutMs?: number;
+};
+export declare const artifactRefSchema: z.ZodObject<{
+    path: z.ZodString;
+}, z.core.$strip>;
+export type NornArtifactRef = z.output<typeof artifactRefSchema>;
+declare const emptyWorkflowRefParamsSchema: z.ZodObject<{}, z.core.$strip>;
+export declare function workflowRefSchema(): z.ZodType<NornWorkflowRefOutput<typeof emptyWorkflowRefParamsSchema>, NornWorkflowRefInput<typeof emptyWorkflowRefParamsSchema>>;
+export declare function workflowRefSchema(options: {
+    readonly params?: undefined;
+}): z.ZodType<NornWorkflowRefOutput<typeof emptyWorkflowRefParamsSchema>, NornWorkflowRefInput<typeof emptyWorkflowRefParamsSchema>>;
+export declare function workflowRefSchema<ParamsSchema extends z.ZodType>(options: NornWorkflowRefSchemaOptions<ParamsSchema>): z.ZodType<NornWorkflowRefOutput<ParamsSchema>, NornWorkflowRefInput<ParamsSchema>>;
+export type NornLogRef = {
+    readonly id: string;
+};
+export type NornCommandRunResult = {
+    readonly label: string;
+    readonly command: string | readonly [string, ...string[]];
+    readonly cwd: string;
+    readonly exitCode: number | null;
+    readonly stdoutTail: string;
+    readonly stderrTail: string;
+    readonly killed: boolean;
+    readonly stdoutLog: NornLogRef;
+    readonly stderrLog: NornLogRef;
+};
+export type NornAgentBeforeSessionStartContext = {
+    readonly events: EventBus;
+};
+export type NornAgentCreateSessionInput = {
+    readonly resourceAdapters?: readonly import("./agent-resource-adapter.ts").NornAgentResourceAdapter[];
+    readonly label: string;
+    readonly cwd?: string;
+    readonly tools?: string[];
+    readonly beforeSessionStart?: (context: NornAgentBeforeSessionStartContext) => MaybePromise<void>;
+    readonly model?: CreateAgentSessionOptions["model"];
+    readonly thinkingLevel?: CreateAgentSessionOptions["thinkingLevel"];
+    readonly systemPrompt?: string;
+    readonly appendSystemPrompt?: readonly string[];
+};
+export type NornAgentPromptInput<ResponseSchema extends z.ZodType> = {
+    readonly prompt: string;
+    readonly response: ResponseSchema;
+    readonly maxAttempts?: number;
+    readonly options?: PromptOptions;
+};
+export type NornAgentSinglePromptInput<ResponseSchema extends z.ZodType> = NornAgentCreateSessionInput & NornAgentPromptInput<ResponseSchema>;
+export type NornAgentSessionEvents = EventBus;
+export type NornAgentUsageCost = {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly total: number;
+};
+export type NornAgentUsage = {
+    readonly input: number;
+    readonly output: number;
+    readonly cacheRead: number;
+    readonly cacheWrite: number;
+    readonly reasoning?: number;
+    readonly totalTokens: number;
+    readonly cost: NornAgentUsageCost;
+};
+export type NornAgentMetrics = {
+    readonly index: number;
+    readonly label: string;
+    readonly status: "running" | "completed" | "failed";
+    readonly startedAt: string;
+    readonly endedAt?: string;
+    readonly wallMs: number;
+    readonly attempts?: number;
+    readonly usage: NornAgentUsage;
+};
+export type NornCommandMetrics = {
+    readonly index: number;
+    readonly label: string;
+    readonly status: "running" | "completed" | "failed";
+    readonly startedAt: string;
+    readonly endedAt?: string;
+    readonly wallMs: number;
+    readonly exitCode?: number | null;
+    readonly killed?: boolean;
+};
+export type NornWorkflowMetrics = {
+    readonly index: number;
+    readonly workflowId: string;
+    readonly status: "running" | "completed" | "failed" | "transitioned";
+    readonly startedAt: string;
+    readonly endedAt?: string;
+    readonly wallMs: number;
+    readonly ownMs: number;
+    readonly agentsMs: number;
+    readonly commandsMs: number;
+    readonly agentUsage: NornAgentUsage;
+    readonly agents: readonly NornAgentMetrics[];
+    readonly commands: readonly NornCommandMetrics[];
+};
+export type NornRunMetrics = {
+    readonly status: NornRunStatus;
+    readonly startedAt: string;
+    readonly endedAt?: string;
+    readonly wallMs: number;
+    readonly activeMs: number;
+    readonly gateWaitMs: number;
+    readonly workflowsMs: number;
+    readonly workflowOwnMs: number;
+    readonly agentsMs: number;
+    readonly commandsMs: number;
+    readonly agentUsage: NornAgentUsage;
+    readonly workflows: readonly NornWorkflowMetrics[];
+};
+export type NornAgentRunRawAttempt = {
+    readonly attempt: number;
+    readonly text: string;
+    readonly messages: unknown[];
+    readonly responseToolCalled: boolean;
+    readonly usage: NornAgentUsage;
+    readonly toolResponse?: unknown;
+    readonly sessionFile?: string;
+    readonly error?: string;
+};
+export type NornAgentRunResult<ResponseSchema extends z.ZodType> = {
+    readonly label: string;
+    readonly cwd: string;
+    readonly response: z.output<ResponseSchema>;
+    readonly usage: NornAgentUsage;
+    readonly raw: {
+        readonly text: string;
+        readonly messages: unknown[];
+        readonly responseToolCalled: boolean;
+        readonly usage: NornAgentUsage;
+        readonly toolResponse?: unknown;
+        readonly sessionFile?: string;
+        readonly attempts: readonly NornAgentRunRawAttempt[];
+    };
+};
+export type NornAgentSession = {
+    readonly label: string;
+    readonly cwd: string;
+    readonly events: NornAgentSessionEvents;
+    prompt<ResponseSchema extends z.ZodType>(input: NornAgentPromptInput<ResponseSchema>): Promise<z.output<ResponseSchema>>;
+    dispose(): Promise<void>;
+};
+export type NornRun = NornRunBase;
+export type NornProjectRun = NornRunBase & {
+    projectRoot: string;
+    projectPath(relativePath: string): string;
+};
+type NornRunBase = {
+    id: string;
+    workspace: string;
+    cwd: string;
+    path(relativePath: string): string;
+    next<TWorkflow extends NornWorkflowTarget<any>>(workflow: TWorkflow, params: NornWorkflowTargetParamsInput<TWorkflow>): NornRunNext;
+    complete(metadata?: NornRunOutcomeMetadata): NornRunComplete;
+    fail(metadata: NornRunOutcomeMetadata & {
+        readonly summary: string;
+    }): NornRunFail;
+    resources: import("./resources.ts").NornResources;
+    state: NornWorkflowState;
+    artifacts: {
+        write(path: string, content: string): Promise<NornArtifactRef>;
+        read(ref: NornArtifactRef): Promise<string>;
+    };
+    logs: {
+        read(log: NornLogRef): Promise<string>;
+    };
+    commands: {
+        run(input: NornCommandRunInput): Promise<NornCommandRunResult>;
+    };
+    agents: {
+        createSession(input: NornAgentCreateSessionInput): Promise<NornAgentSession>;
+        prompt<ResponseSchema extends z.ZodType>(input: NornAgentSinglePromptInput<ResponseSchema>): Promise<z.output<ResponseSchema>>;
+    };
+};
+export type NornWorkflowPluginInfo = {
+    readonly id: string;
+    readonly path?: string;
+    readonly configPath?: string;
+};
+export type NornJsonSchema = Record<string, unknown>;
+export type NornWorkflowGateInfo = {
+    readonly enabled: true;
+    readonly fields?: readonly string[];
+};
+export type NornRegisteredWorkflowInfo = {
+    readonly id: string;
+    readonly instructions?: string;
+    readonly isEntrypoint: boolean;
+    readonly isolation: NornWorkflowIsolation;
+    readonly plugin?: NornWorkflowPluginInfo;
+};
+export type NornInspectedWorkflowInfo = NornRegisteredWorkflowInfo & {
+    readonly paramsSchema: NornJsonSchema;
+    readonly gate: NornWorkflowGateInfo | null;
+};
+export type NornPluginDiagnostic = {
+    readonly configPath: string;
+    readonly pluginPath: string;
+    readonly pluginId: string | null;
+    readonly workflowId: string | null;
+    readonly stage: "import" | "declaration" | "config" | "implementation" | "duplicate" | "schema";
+    readonly message: string;
+    readonly issues: readonly {
+        readonly path: readonly (string | number)[];
+        readonly code: string;
+        readonly message: string;
+    }[];
+};
+export type NornProjectLoadStatus = {
+    readonly isComplete: boolean;
+    readonly diagnostics: readonly NornPluginDiagnostic[];
+};
+export type NornWorkflowCatalogInfo = NornProjectLoadStatus & {
+    readonly workflows: readonly NornRegisteredWorkflowInfo[];
+};
+export type NornWorkflowInspection = NornProjectLoadStatus & {
+    readonly workflow: NornInspectedWorkflowInfo | null;
+};
+export type NornProjectInspection = NornProjectLoadStatus & {
+    readonly project: NornProjectInfo;
+};
+export type NornProjectPluginInfo = NornWorkflowPluginInfo & {
+    readonly configSchema: NornJsonSchema | null;
+    readonly config: unknown;
+};
+export type NornProjectInfo = {
+    readonly cwd: string;
+    readonly projectPath: string;
+    readonly projectRoot: string;
+    readonly configPath: string;
+    readonly configRoot: string;
+    readonly configFiles: readonly string[];
+    readonly plugins: readonly NornProjectPluginInfo[];
+    readonly seerMode: NornResolvedSeerModeConfig | null;
+};
+export declare function isWorkflowDeclaration(value: unknown): value is NornAnyWorkflowDeclaration;
+export declare function isWorkflowPlugin(value: unknown): value is NornWorkflowPlugin;
+export declare function isWorkflowPluginManifest(value: unknown): value is NornAnyWorkflowPluginManifest;
+export declare function isWorkflowNext(value: unknown): value is NornRunNext;
+export declare function isWorkflowComplete(value: unknown): value is NornRunComplete;
+export declare function isWorkflowFail(value: unknown): value is NornRunFail;
+export {};

package/dist/api.js

@@ -0,0 +1,120 @@
+// src/api.ts
+import { z } from "zod";
+var WORKFLOW_DECLARATION_KIND = "norn.workflow";
+function definePluginManifest(input) {
+  assertLocalDeclarationId(input.id, "plugin");
+  const declaredIds = /* @__PURE__ */ new Set();
+  const workflows = Object.fromEntries(
+    Object.entries(input.workflows).map(([key, workflow]) => [key, qualifyWorkflow(input.id, key, workflow, declaredIds)])
+  );
+  return {
+    id: input.id,
+    config: input.config,
+    workflows,
+    states: qualifyStateTree(input.id, input.states, [], declaredIds)
+  };
+}
+function definePlugin(manifest, implementation) {
+  return { manifest, implementation };
+}
+var artifactRefSchema = z.object({
+  path: z.string()
+});
+var emptyWorkflowRefParamsSchema = z.object({});
+function workflowRefSchema(options) {
+  const contributedParams = options?.params ?? emptyWorkflowRefParamsSchema;
+  const targetSchema = z.union([
+    z.string().min(1),
+    z.object({ id: z.string().min(1) })
+  ]).transform((target) => typeof target === "string" ? target : target.id);
+  return z.union([
+    targetSchema,
+    z.object({ workflow: targetSchema, forwardParams: z.record(z.string(), z.unknown()) })
+  ]).transform((reference) => typeof reference === "string" ? { workflow: reference, forwardParams: {} } : reference).meta({
+    "x-norn-workflow-ref": {
+      get contributedParamsSchema() {
+        return z.toJSONSchema(contributedParams, { io: "input" });
+      }
+    }
+  });
+}
+function assertLocalDeclarationId(id, kind) {
+  if (id.length === 0) throw new Error(`Workflow ${kind} id must not be empty`);
+  if (id.includes(".")) throw new Error(`Workflow ${kind} id must not contain dots: ${id}`);
+}
+function resolveDeclarationId(pluginId, path, explicitId, kind, declaredIds) {
+  for (const segment of path) assertLocalDeclarationId(segment, kind);
+  const id = explicitId ?? [pluginId, ...path].join(".");
+  if (explicitId !== void 0) assertPluginQualifiedId(pluginId, explicitId, kind);
+  if (declaredIds.has(id)) throw new Error(`Duplicate Norn ${kind} id: ${id}`);
+  declaredIds.add(id);
+  return id;
+}
+function assertPluginQualifiedId(pluginId, id, kind) {
+  if (!id.startsWith(`${pluginId}.`)) throw new Error(`Explicit Norn ${kind} id must start with ${pluginId}.: ${id}`);
+  if (id.length === pluginId.length + 1) throw new Error(`Explicit Norn ${kind} id must not be empty after ${pluginId}.`);
+}
+function qualifyWorkflow(pluginId, key, workflow, declaredIds) {
+  const id = resolveDeclarationId(pluginId, [key], workflow.id, "workflow", declaredIds);
+  return { kind: WORKFLOW_DECLARATION_KIND, ...workflow, id, isolation: workflow.isolation ?? { mode: "runWorkspace" } };
+}
+function qualifyStateTree(pluginId, node, path, declaredIds) {
+  if (!node) return void 0;
+  if (isZodSchema(node)) return { id: resolveDeclarationId(pluginId, path, void 0, "state", declaredIds), schema: node };
+  if (isWorkflowStateDefinitionInput(node)) {
+    return { ...node, id: resolveDeclarationId(pluginId, path, node.id, "state", declaredIds) };
+  }
+  return Object.fromEntries(Object.entries(node).map(([key, child]) => [key, qualifyStateTree(pluginId, child, [...path, key], declaredIds)]));
+}
+function isWorkflowDeclaration(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return candidate.kind === WORKFLOW_DECLARATION_KIND && typeof candidate.id === "string" && candidate.id.length > 0 && (candidate.instructions === void 0 || typeof candidate.instructions === "string") && typeof candidate.isEntrypoint === "boolean" && Boolean(candidate.params) && (candidate.isolation?.mode === "runWorkspace" || candidate.isolation?.mode === "project");
+}
+function isWorkflowStateDefinitionInput(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return (candidate.id === void 0 || typeof candidate.id === "string") && isZodSchema(candidate.schema);
+}
+function isZodSchema(value) {
+  return Boolean(value && typeof value === "object" && typeof value.safeParse === "function");
+}
+function isWorkflowPlugin(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return isWorkflowPluginManifest(candidate.manifest) && Boolean(candidate.implementation);
+}
+function isWorkflowPluginManifest(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  if (typeof candidate.id !== "string" || candidate.id.length === 0) return false;
+  if (!candidate.workflows || typeof candidate.workflows !== "object") return false;
+  return Object.values(candidate.workflows).every(isWorkflowDeclaration);
+}
+function isWorkflowNext(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return candidate.type === "next" && typeof candidate.workflowId === "string" && candidate.workflowId.length > 0;
+}
+function isWorkflowComplete(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return candidate.type === "complete";
+}
+function isWorkflowFail(value) {
+  if (!value || typeof value !== "object") return false;
+  const candidate = value;
+  return candidate.type === "fail" && typeof candidate.metadata?.summary === "string" && candidate.metadata.summary.length > 0;
+}
+export {
+  artifactRefSchema,
+  definePlugin,
+  definePluginManifest,
+  isWorkflowComplete,
+  isWorkflowDeclaration,
+  isWorkflowFail,
+  isWorkflowNext,
+  isWorkflowPlugin,
+  isWorkflowPluginManifest,
+  workflowRefSchema
+};

package/dist/files.d.ts

@@ -0,0 +1,17 @@
+export declare class NornFileCoordinator {
+    private readonly input;
+    private readonly lockRoot;
+    constructor(input: {
+        readonly lockRoot: string;
+        readonly waitTimeoutMs: number;
+    });
+    withExclusiveLock<T>(path: string, operation: (lockedPath: string) => Promise<T>): Promise<T>;
+    readText(path: string): Promise<string>;
+    writeText(path: string, content: string): Promise<void>;
+    private withCleanup;
+    private resolveTarget;
+    private acquire;
+    private reclaimDeadOwner;
+    private removeEmptyLock;
+}
+export declare function createRunFileCoordinator(runRoot: string): NornFileCoordinator;

package/dist/files.js

@@ -0,0 +1,161 @@
+// src/files.ts
+import { createHash, randomUUID as randomUUID2 } from "node:crypto";
+import { lstat, mkdir as mkdir2, mkdtemp, readFile, readdir, realpath, rename as rename2, rm as rm2, rmdir, unlink, writeFile as writeFile2 } from "node:fs/promises";
+import { hostname } from "node:os";
+import { basename, dirname as dirname2, join, resolve } from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+import { z } from "zod";
+
+// ../core/src/errors.ts
+function isNodeError(error) {
+  return error instanceof Error && "code" in error;
+}
+
+// ../core/src/atomic-files.ts
+import { randomUUID } from "node:crypto";
+import { chmod, mkdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+async function writeTextAtomically(path, content) {
+  await mkdir(dirname(path), { recursive: true });
+  let existingMode;
+  try {
+    existingMode = (await stat(path)).mode & 511;
+  } catch (error) {
+    if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+  }
+  const tmpPath = `${path}.${randomUUID()}.tmp`;
+  try {
+    await writeFile(tmpPath, content, { encoding: "utf8", mode: existingMode });
+    if (existingMode !== void 0) await chmod(tmpPath, existingMode);
+    await rename(tmpPath, path);
+  } catch (error) {
+    await rm(tmpPath, { force: true }).catch(() => void 0);
+    throw error;
+  }
+}
+
+// src/files.ts
+var ownerSchema = z.strictObject({
+  token: z.uuid(),
+  pid: z.number().int().positive(),
+  host: z.string(),
+  target: z.string()
+});
+var NornFileCoordinator = class {
+  constructor(input) {
+    this.input = input;
+    if (!Number.isSafeInteger(input.waitTimeoutMs) || input.waitTimeoutMs <= 0) throw new Error("Lock wait timeout must be a positive integer");
+    this.lockRoot = resolve(input.lockRoot);
+  }
+  input;
+  lockRoot;
+  async withExclusiveLock(path, operation) {
+    const target = await this.resolveTarget(path);
+    await mkdir2(this.lockRoot, { recursive: true, mode: 448 });
+    const key = createHash("sha256").update(target).digest("hex");
+    const lockPath = join(this.lockRoot, `${key}.lock`);
+    const stagingPath = await mkdtemp(join(this.lockRoot, `${key}.pending-`));
+    const token = randomUUID2();
+    const marker = `${token}.json`;
+    return this.withCleanup({
+      operation: async () => {
+        await writeFile2(join(stagingPath, marker), JSON.stringify({ token, pid: process.pid, host: hostname(), target }), { mode: 384 });
+        await this.acquire({ stagingPath, lockPath, target });
+        return this.withCleanup({
+          operation: () => operation(target),
+          cleanup: async () => {
+            await unlink(join(lockPath, marker));
+            await this.removeEmptyLock(lockPath);
+          }
+        });
+      },
+      cleanup: () => rm2(stagingPath, { recursive: true, force: true })
+    });
+  }
+  async readText(path) {
+    return this.withExclusiveLock(path, (lockedPath) => readFile(lockedPath, "utf8"));
+  }
+  async writeText(path, content) {
+    await mkdir2(dirname2(path), { recursive: true });
+    await this.withExclusiveLock(path, (lockedPath) => writeTextAtomically(lockedPath, content));
+  }
+  async withCleanup(input) {
+    let result;
+    try {
+      result = await input.operation();
+    } catch (error) {
+      try {
+        await input.cleanup();
+      } catch (cleanupError) {
+        throw new AggregateError([error, cleanupError], "File operation and lock cleanup failed");
+      }
+      throw error;
+    }
+    await input.cleanup();
+    return result;
+  }
+  async resolveTarget(path) {
+    try {
+      return await realpath(path);
+    } catch (error) {
+      if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+      const entry = await lstat(path).catch((error2) => {
+        if (isNodeError(error2) && error2.code === "ENOENT") return void 0;
+        throw error2;
+      });
+      if (entry?.isSymbolicLink()) throw new Error(`Cannot lock a dangling symbolic link: ${path}`);
+      return join(await realpath(dirname2(path)), basename(path));
+    }
+  }
+  async acquire(input) {
+    const deadline = Date.now() + this.input.waitTimeoutMs;
+    while (true) {
+      try {
+        await rename2(input.stagingPath, input.lockPath);
+        return;
+      } catch (error) {
+        if (!isNodeError(error) || !["ENOTEMPTY", "EEXIST"].includes(error.code ?? "")) throw error;
+      }
+      await this.reclaimDeadOwner(input);
+      if (Date.now() >= deadline) throw new Error(`Timed out waiting for file lock: ${input.target}`);
+      await delay(10);
+    }
+  }
+  async reclaimDeadOwner(input) {
+    try {
+      const entries = await readdir(input.lockPath);
+      if (entries.length === 0) return;
+      if (entries.length !== 1) throw new Error(`Invalid file lock ownership: ${input.lockPath}`);
+      const marker = entries[0];
+      const owner = ownerSchema.parse(JSON.parse(await readFile(join(input.lockPath, marker), "utf8")));
+      if (marker !== `${owner.token}.json` || owner.target !== input.target || owner.host !== hostname()) {
+        throw new Error(`Incompatible file lock ownership: ${input.lockPath}`);
+      }
+      try {
+        process.kill(owner.pid, 0);
+        return;
+      } catch (error) {
+        if (isNodeError(error) && error.code === "EPERM") return;
+        if (!isNodeError(error) || error.code !== "ESRCH") throw error;
+      }
+      await unlink(join(input.lockPath, marker));
+      await this.removeEmptyLock(input.lockPath);
+    } catch (error) {
+      if (!isNodeError(error) || error.code !== "ENOENT") throw error;
+    }
+  }
+  async removeEmptyLock(path) {
+    try {
+      await rmdir(path);
+    } catch (error) {
+      if (!isNodeError(error) || !["ENOENT", "ENOTEMPTY", "EEXIST"].includes(error.code ?? "")) throw error;
+    }
+  }
+};
+function createRunFileCoordinator(runRoot) {
+  return new NornFileCoordinator({ lockRoot: join(runRoot, "locks"), waitTimeoutMs: 3e4 });
+}
+export {
+  NornFileCoordinator,
+  createRunFileCoordinator
+};

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export * from "./api.ts";
+export { NornFileCoordinator } from "./files.ts";
+export * from "./resources.ts";
+export * from "./agent-resource-adapter.ts";
+export * from "./state-adapter.ts";
+export * from "./seer/index.ts";

package/dist/index.js

@@ -0,0 +1,10 @@
+// src/index.ts
+export * from "./api.js";
+import { NornFileCoordinator } from "./files.js";
+export * from "./resources.js";
+export * from "./agent-resource-adapter.js";
+export * from "./state-adapter.js";
+export * from "./seer/index.js";
+export {
+  NornFileCoordinator
+};

package/dist/resources.d.ts

@@ -0,0 +1,17 @@
+import type { z } from "zod";
+import type { NornFileCoordinator } from "./files.ts";
+export type NornResourceContext = {
+    readonly mode: "create" | "open";
+    readonly directory: string;
+    readonly files: NornFileCoordinator;
+};
+export type NornResourceDefinition<T> = {
+    readonly name: string;
+    readonly kind: string;
+    readonly configuration: z.infer<ReturnType<typeof z.json>>;
+    initialize(context: NornResourceContext): Promise<T>;
+};
+export type NornResources = {
+    readonly files: NornFileCoordinator;
+    ensure<T>(definition: NornResourceDefinition<T>): Promise<T>;
+};

package/dist/schema.d.ts

@@ -0,0 +1,6 @@
+import type { NornAnyWorkflowDeclaration } from "./api.ts";
+export declare function assertWorkflowMetadata(workflow: NornAnyWorkflowDeclaration): void;
+export declare function unwrapSchema(schema: unknown): unknown;
+export declare function schemaShape(schema: unknown): Record<string, unknown>;
+export declare function schemaType(schema: unknown): string | undefined;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;

package/dist/schema.js

@@ -0,0 +1,43 @@
+// src/schema.ts
+function assertWorkflowMetadata(workflow) {
+  if (workflow.instructions !== void 0 && (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 === void 0) {
+    throw new Error(`Entrypoint workflow requires instructions: ${workflow.id}`);
+  }
+}
+function unwrapSchema(schema) {
+  let current = schema;
+  while (true) {
+    const def = schemaDef(current);
+    if (["optional", "nullable", "default", "catch", "readonly", "prefault"].includes(def.type ?? "") && def.innerType) {
+      current = def.innerType;
+      continue;
+    }
+    return current;
+  }
+}
+function schemaShape(schema) {
+  const shape = schemaDef(unwrapSchema(schema)).shape;
+  if (!shape) return {};
+  return typeof shape === "function" ? shape() : shape;
+}
+function schemaType(schema) {
+  return schemaDef(unwrapSchema(schema)).type;
+}
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === "object" && !Array.isArray(value);
+}
+function schemaDef(schema) {
+  if (!schema || typeof schema !== "object") return {};
+  const candidate = schema;
+  return candidate._def ?? candidate.def ?? {};
+}
+export {
+  assertWorkflowMetadata,
+  isPlainObject,
+  schemaShape,
+  schemaType,
+  unwrapSchema
+};

package/dist/seer/config.d.ts

@@ -0,0 +1,17 @@
+export type NornSeerModeConfig = {
+    readonly writableRoots: readonly string[];
+};
+export type NornResolvedSeerModeConfig = {
+    readonly configPath: string;
+    readonly projectRoot: string;
+    readonly writableRoots: readonly string[];
+};
+type ResolveSeerModeConfigInput = {
+    readonly configPath: string;
+    readonly configRoot: string;
+    readonly seerMode: NornSeerModeConfig | undefined;
+};
+export declare function resolveSeerModeConfig(input: ResolveSeerModeConfigInput): NornResolvedSeerModeConfig | undefined;
+export declare function assertSeerModeWritablePath(seerMode: NornResolvedSeerModeConfig, cwd: string, path: string): string;
+export declare function isSeerModeWritablePath(seerMode: NornResolvedSeerModeConfig, cwd: string, path: string): boolean;
+export {};

package/dist/seer/config.js

@@ -0,0 +1,45 @@
+// src/seer/config.ts
+import { isAbsolute, relative, resolve, sep } from "node:path";
+function resolveSeerModeConfig(input) {
+  if (!input.seerMode) return void 0;
+  if (input.seerMode.writableRoots.length === 0) throw new Error("Norn seerMode.writableRoots must not be empty");
+  const projectRoot = resolve(input.configRoot);
+  const writableRoots = Array.from(new Set(input.seerMode.writableRoots.map((path) => resolveWritableRoot(projectRoot, path))));
+  return { configPath: input.configPath, projectRoot, writableRoots };
+}
+function assertSeerModeWritablePath(seerMode, cwd, path) {
+  const resolvedPath = resolveSeerModePath(seerMode, cwd, path);
+  if (!isSeerModeWritableResolvedPath(seerMode, resolvedPath)) {
+    throw new Error(`Path is outside Norn seerMode writable roots: ${path}`);
+  }
+  return resolvedPath;
+}
+function isSeerModeWritablePath(seerMode, cwd, path) {
+  return isSeerModeWritableResolvedPath(seerMode, resolveSeerModePath(seerMode, cwd, path));
+}
+function resolveWritableRoot(projectRoot, path) {
+  if (path.length === 0) throw new Error("Norn seerMode writable root must not be empty");
+  const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(projectRoot, path);
+  if (!isInsideOrEqual(projectRoot, resolvedPath)) throw new Error(`Norn seerMode writable root escapes project root: ${path}`);
+  return resolvedPath;
+}
+function resolveSeerModePath(seerMode, cwd, path) {
+  if (path.length === 0) throw new Error("Norn seerMode path must not be empty");
+  const resolvedCwd = resolve(cwd);
+  if (!isInsideOrEqual(seerMode.projectRoot, resolvedCwd)) throw new Error(`Norn seerMode cwd escapes project root: ${cwd}`);
+  const resolvedPath = isAbsolute(path) ? resolve(path) : resolve(resolvedCwd, path);
+  if (!isInsideOrEqual(seerMode.projectRoot, resolvedPath)) return resolvedPath;
+  return resolvedPath;
+}
+function isSeerModeWritableResolvedPath(seerMode, path) {
+  return seerMode.writableRoots.some((root) => isInsideOrEqual(root, path));
+}
+function isInsideOrEqual(root, path) {
+  const pathFromRoot = relative(root, path);
+  return pathFromRoot === "" || !pathFromRoot.startsWith(`..${sep}`) && pathFromRoot !== ".." && !isAbsolute(pathFromRoot);
+}
+export {
+  assertSeerModeWritablePath,
+  isSeerModeWritablePath,
+  resolveSeerModeConfig
+};

package/dist/seer/index.d.ts

@@ -0,0 +1 @@
+export { assertSeerModeWritablePath, isSeerModeWritablePath, resolveSeerModeConfig, type NornResolvedSeerModeConfig, type NornSeerModeConfig, } from "./config.ts";

package/dist/seer/index.js

@@ -0,0 +1,11 @@
+// src/seer/index.ts
+import {
+  assertSeerModeWritablePath,
+  isSeerModeWritablePath,
+  resolveSeerModeConfig
+} from "./config.js";
+export {
+  assertSeerModeWritablePath,
+  isSeerModeWritablePath,
+  resolveSeerModeConfig
+};

package/dist/state-adapter.d.ts

@@ -0,0 +1,10 @@
+import type { NornWorkflowState, NornWorkflowStateDefinition } from "./api.ts";
+import type { NornAgentResourceAdapter } from "./agent-resource-adapter.ts";
+export type NornStateFieldAccess = {
+    readonly field: NornWorkflowStateDefinition;
+    readonly access: "read" | "write" | "read-write";
+};
+export declare function StateAdapter(input: {
+    readonly state: NornWorkflowState;
+    readonly fields: readonly NornStateFieldAccess[];
+}): NornAgentResourceAdapter;

package/dist/state-adapter.js

@@ -0,0 +1,70 @@
+// src/state-adapter.ts
+import { createHash } from "node:crypto";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+import { z } from "zod";
+var pageParameters = {
+  offset: Type.Integer({ minimum: 0, description: "Zero-based UTF-16 offset into the serialized JSON. Start at 0." }),
+  limit: Type.Integer({ minimum: 1, maximum: 1e4 })
+};
+function StateAdapter(input) {
+  const fields = new Map(input.fields.map((grant) => [grant.field.id, grant]));
+  if (fields.size !== input.fields.length || fields.size === 0) throw new Error("State attachment requires unique, explicitly selected fields");
+  const selectField = (key, access) => {
+    const grant = fields.get(key);
+    if (!grant || grant.access !== access && grant.access !== "read-write") throw new Error(`State ${access} is not attached: ${key}`);
+    return grant.field;
+  };
+  return {
+    name: "norn.state",
+    async bind() {
+      return {
+        tools: [
+          defineTool({
+            name: "norn_state_list",
+            label: "Attached workflow state",
+            description: "List only attached workflow-state field IDs, permissions and value schemas. JSON is paginated; use nextOffset until null.",
+            parameters: Type.Object(pageParameters),
+            async execute(_id, params) {
+              return serializePage({ value: [...fields.values()].map(({ field, access }) => ({ id: field.id, access, schema: z.toJSONSchema(field.schema, { io: "input" }) })), ...params });
+            }
+          }),
+          defineTool({
+            name: "norn_state_get",
+            label: "Read workflow state",
+            description: "Read a selected workflow-state field. Unset fields return isSet:false. JSON is paginated; concurrent writes can change later pages, so compare revision before combining pages.",
+            parameters: Type.Object({ key: Type.String(), ...pageParameters }),
+            async execute(_id, params) {
+              const value = await input.state.getOptional(selectField(params.key, "read"));
+              return serializePage({ value: value === void 0 ? { isSet: false } : { isSet: true, value }, ...params });
+            }
+          }),
+          defineTool({
+            name: "norn_state_set",
+            label: "Write workflow state",
+            description: "Set an explicitly writable workflow-state field. Validate the value against its schema from norn_state_list. A get followed by set is not a transaction.",
+            parameters: Type.Object({ key: Type.String(), value: Type.Unknown() }),
+            async execute(_id, params, signal) {
+              signal?.throwIfAborted();
+              const field = selectField(params.key, "write");
+              await input.state.set(field, params.value);
+              return { content: [{ type: "text", text: "Workflow state saved." }], details: {} };
+            }
+          })
+        ],
+        async dispose() {
+        }
+      };
+    }
+  };
+}
+function serializePage(input) {
+  const serialized = JSON.stringify(input.value);
+  if (!Number.isInteger(input.offset) || input.offset < 0 || !Number.isInteger(input.limit) || input.limit < 1 || input.limit > 1e4) throw new Error("Invalid state output page");
+  const end = Math.min(serialized.length, input.offset + input.limit);
+  const details = { text: serialized.slice(input.offset, end), nextOffset: end < serialized.length ? end : null, revision: createHash("sha256").update(serialized).digest("hex") };
+  return { content: [{ type: "text", text: JSON.stringify(details) }], details };
+}
+export {
+  StateAdapter
+};

package/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@vimhead.dev/norn",
+  "version": "0.1.0-tip.0",
+  "description": "TypeScript SDK for building agent-driven and code-driven Norn workflows.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vimhead/norn.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://github.com/vimhead/norn#readme",
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "tip"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./files": {
+      "types": "./dist/files.d.ts",
+      "import": "./dist/files.js"
+    },
+    "./schema": {
+      "types": "./dist/schema.d.ts",
+      "import": "./dist/schema.js"
+    },
+    "./seer": {
+      "types": "./dist/seer/index.d.ts",
+      "import": "./dist/seer/index.js"
+    }
+  },
+  "devDependencies": {
+    "@vimhead.dev/norn-core": "0.0.0"
+  },
+  "dependencies": {
+    "@earendil-works/pi-coding-agent": "0.85.1",
+    "typebox": "^1.3.17",
+    "zod": "^4.4.3"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.ts"
+  }
+}