@bastani/atomic 0.5.12-3 → 0.5.12-5

package/src/commands/cli/workflow.ts

@@ -391,7 +391,7 @@ async function runPickerMode(
 
 /**
  * Execute a workflow selected via the picker. The picker already stores
- * free-form prompts under the `prompt` key (via `DEFAULT_PROMPT_INPUT`),
+ * free-form prompts under the canonical `prompt` key,
  * so we can hand the inputs record straight through — no split between
  * "prompt" and "structured inputs" is needed.
  */

package/src/sdk/components/workflow-picker-panel.tsx

@@ -30,6 +30,7 @@ import {
   createCliRenderer,
   type CliRenderer,
   type KeyEvent,
+  type ScrollBoxRenderable,
   type TextareaRenderable,
 } from "@opentui/core";
 import {
@@ -117,19 +118,6 @@ export interface WorkflowPickerResult {
   inputs: Record<string, string>;
 }
 
-/** Fallback field used when a workflow has no structured input schema. */
-const DEFAULT_PROMPT_INPUT: WorkflowInput = {
-  name: "prompt",
-  type: "text",
-  required: true,
-  description: "what do you want this workflow to do?",
-  placeholder: "describe your task…",
-};
-
-/** Stable single-element array for free-form workflows — avoids allocating
- *  a new `[DEFAULT_PROMPT_INPUT]` on every useMemo recomputation. */
-const DEFAULT_FIELDS: WorkflowInput[] = [DEFAULT_PROMPT_INPUT];
-
 // ─── Helpers ────────────────────────────────────
 
 const SOURCE_DISPLAY: Record<Source, string> = {
@@ -477,8 +465,7 @@ const Preview = memo(function Preview({
   wf: WorkflowWithMetadata;
 }) {
   const theme = usePickerTheme();
-  const args: readonly WorkflowInput[] =
-    wf.inputs.length > 0 ? wf.inputs : DEFAULT_FIELDS;
+  const args = wf.inputs;
 
   return (
     <box
@@ -512,13 +499,16 @@ const Preview = memo(function Preview({
         </span>
       </text>
 
-      <box height={2} />
-
-      <SectionLabel label="ARGUMENTS" />
-      <box height={1} />
-      {args.map((f) => (
-        <ArgumentRow key={f.name} field={f} />
-      ))}
+      {args.length > 0 && (
+        <>
+          <box height={2} />
+          <SectionLabel label="ARGUMENTS" />
+          <box height={1} />
+          {args.map((f) => (
+            <ArgumentRow key={f.name} field={f} />
+          ))}
+        </>
+      )}
     </box>
   );
 });
@@ -651,7 +641,7 @@ function EnumContent({
   selected,
   focused,
 }: {
-  values: string[];
+  values: readonly string[];
   selected: string;
   focused: boolean;
 }) {
@@ -690,12 +680,14 @@ function EnumContent({
 }
 
 const Field = memo(function Field({
+  id,
   field,
   value,
   focused,
   onFieldInput,
   onTextChangeRef,
 }: {
+  id?: string;
   field: WorkflowInput;
   value: string;
   focused: boolean;
@@ -719,7 +711,7 @@ const Field = memo(function Field({
   );
 
   return (
-    <box flexDirection="column">
+    <box id={id} flexDirection="column">
       <box
         border
         borderStyle="rounded"
@@ -789,6 +781,54 @@ function InputPhase({
 }) {
   const theme = usePickerTheme();
   const isStructured = workflow.inputs.length > 0;
+  const scrollboxRef = useRef<ScrollBoxRenderable>(null);
+  const [scrollTop, setScrollTop] = useState(0);
+
+  // Auto-scroll to keep the focused field visible.
+  // Sync scrollTop immediately so the visibility check below
+  // marks the field as visible on the same render pass.
+  useEffect(() => {
+    const sb = scrollboxRef.current;
+    const field = fields[focusedFieldIdx];
+    if (!sb || !field) return;
+    sb.scrollChildIntoView(`field-${field.name}`);
+    setScrollTop(sb.scrollTop);
+  }, [focusedFieldIdx, fields]);
+
+  // Sync scrollTop on every OpenTUI render frame via renderBefore.
+  // This replaces a polling timer — it fires at the renderer's native
+  // frame rate so the focused field defocuses within one frame of
+  // scrolling out of view, preventing the terminal cursor from
+  // bleeding into the fixed header above.
+  const syncScrollFrame = useCallback(function (this: unknown) {
+    const sb = scrollboxRef.current;
+    if (!sb) return;
+    setScrollTop((prev) => {
+      const cur = sb.scrollTop;
+      return cur !== prev ? cur : prev;
+    });
+  }, []);
+
+  // The bordered content box (where the cursor lives) must be fully
+  // inside the viewport. If even one row is clipped the field loses
+  // focus so the cursor can never land in a clipped row.
+  const isFocusedFieldVisible = useMemo(() => {
+    const sb = scrollboxRef.current;
+    if (!sb) return true;
+    const vpH = sb.viewport.height;
+    if (vpH <= 0) return true;
+    let y = 0;
+    for (let i = 0; i < fields.length; i++) {
+      const f = fields[i]!;
+      const inputH = f.type === "text" ? TEXT_FIELD_LINES + 2 : 3;
+      if (i === focusedFieldIdx) {
+        return y >= scrollTop && y + inputH <= scrollTop + vpH;
+      }
+      // Caption row (1) + spacer row (1) below the bordered box.
+      y += inputH + 2;
+    }
+    return true;
+  }, [fields, focusedFieldIdx, scrollTop]);
 
   return (
     <box
@@ -839,7 +879,7 @@ function InputPhase({
       <box flexDirection="row" height={1}>
         <text>
           <span fg={theme.textDim}>
-            <strong>{isStructured ? "INPUTS" : "PROMPT"}</strong>
+            <strong>INPUTS</strong>
           </span>
         </text>
         <box flexGrow={1} />
@@ -851,20 +891,48 @@ function InputPhase({
       </box>
       <box height={1} />
 
-      {fields.map((f, i) => (
-        <Field
-          key={f.name}
-          field={f}
-          value={values[f.name] ?? ""}
-          focused={i === focusedFieldIdx}
-          onFieldInput={onFieldInput}
-          onTextChangeRef={
-            f.type === "text" && i === focusedFieldIdx
-              ? onTextChangeRef
-              : undefined
-          }
-        />
-      ))}
+      <scrollbox
+        ref={scrollboxRef}
+        scrollY
+        viewportCulling
+        flexGrow={1}
+        renderBefore={syncScrollFrame}
+        style={{
+          rootOptions: {
+            backgroundColor: "transparent",
+            border: false,
+          },
+          contentOptions: {
+            flexDirection: "column",
+          },
+          verticalScrollbarOptions: {
+            showArrows: false,
+            trackOptions: {
+              foregroundColor: theme.border,
+              backgroundColor: theme.backgroundElement,
+            },
+          },
+        }}
+      >
+        {fields.map((f, i) => {
+          const active = i === focusedFieldIdx && isFocusedFieldVisible;
+          return (
+            <Field
+              key={f.name}
+              id={`field-${f.name}`}
+              field={f}
+              value={values[f.name] ?? ""}
+              focused={active}
+              onFieldInput={onFieldInput}
+              onTextChangeRef={
+                f.type === "text" && active
+                  ? onTextChangeRef
+                  : undefined
+              }
+            />
+          );
+        })}
+      </scrollbox>
     </box>
   );
 }
@@ -1171,12 +1239,8 @@ function usePickerKeyboard(state: PickerKeyboardState): void {
       key.stopPropagation();
       const wf = focusedWfRef.current;
       if (wf) {
-        const inputs: readonly WorkflowInput[] =
-          wf.inputs.length > 0
-            ? wf.inputs
-            : DEFAULT_FIELDS;
         const initial: Record<string, string> = {};
-        for (const f of inputs) {
+        for (const f of wf.inputs) {
           initial[f.name] =
             f.default ??
             (f.type === "enum" ? (f.values?.[0] ?? "") : "");
@@ -1290,9 +1354,7 @@ export function WorkflowPicker({
   const focusedWf = entries[clampedEntryIdx]?.workflow;
 
   const currentFields = useMemo<readonly WorkflowInput[]>(
-    () => focusedWf && focusedWf.inputs.length > 0
-      ? focusedWf.inputs
-      : DEFAULT_FIELDS,
+    () => focusedWf?.inputs ?? [],
     [focusedWf],
   );
   const currentField = currentFields[focusedFieldIdx];

package/src/sdk/define-workflow.test.ts

@@ -170,3 +170,61 @@ describe("WorkflowBuilder.compile()", () => {
     expect(() => builder.compile()).toThrow("has no run callback");
   });
 });
+
+describe("WorkflowBuilder.for()", () => {
+  test("returns the same builder instance (type-only narrowing)", () => {
+    const builder = defineWorkflow({ name: "test" });
+    const narrowed = builder.for<"copilot">();
+    // Same instance — .for() only changes the TypeScript type, not the value
+    expect(narrowed === (builder as unknown)).toBe(true);
+  });
+
+  test("chains with run and compile", () => {
+    const def = defineWorkflow({
+      name: "test",
+      inputs: [{ name: "greeting", type: "string" }],
+    })
+      .for<"copilot">()
+      .run(async () => {})
+      .compile();
+    expect(def.__brand).toBe("WorkflowDefinition");
+    expect(def.inputs[0]?.name).toBe("greeting");
+  });
+});
+
+describe("typed inputs (compile-time)", () => {
+  test("structured inputs restrict ctx.inputs keys", () => {
+    // This test validates that the type system correctly narrows
+    // ctx.inputs to only declared field names. The assertions below
+    // are runtime no-ops — the real check is that tsc compiles this
+    // file without errors (or produces errors only where expected).
+    defineWorkflow({
+      name: "typed-test",
+      inputs: [
+        { name: "greeting", type: "string", required: true },
+        { name: "style", type: "enum", values: ["formal", "casual"] },
+      ],
+    })
+      .for<"copilot">()
+      .run(async (ctx) => {
+        // Declared keys are valid
+        const _g: string | undefined = ctx.inputs.greeting;
+        const _s: string | undefined = ctx.inputs.style;
+        // Undeclared key — would be a compile error without @ts-expect-error
+        // @ts-expect-error — "prompt" is not a declared input
+        ctx.inputs.prompt;
+        expect(true).toBe(true);
+      })
+      .compile();
+  });
+
+  test("free-form workflows allow any key", () => {
+    defineWorkflow({ name: "freeform-test" })
+      .for<"copilot">()
+      .run(async (ctx) => {
+        const _p: string | undefined = ctx.inputs.prompt;
+        expect(true).toBe(true);
+      })
+      .compile();
+  });
+});

package/src/sdk/define-workflow.ts

@@ -2,7 +2,8 @@
  * Workflow Builder — defines a workflow with a single `.run()` entry point.
  *
  * Usage:
- *   defineWorkflow<"copilot">({ name: "my-workflow", description: "..." })
+ *   defineWorkflow({ name: "my-workflow", inputs: [...] })
+ *     .for<"copilot">()
  *     .run(async (ctx) => {
  *       await ctx.stage({ name: "research" }, {}, {}, async (s) => { ... });
  *       await ctx.stage({ name: "plan" }, {}, {}, async (s) => { ... });
@@ -58,16 +59,42 @@ function validateWorkflowInput(input: WorkflowInput, workflowName: string): void
  * Chainable workflow builder. Records the run callback,
  * then .compile() seals it into a WorkflowDefinition.
  */
-export class WorkflowBuilder<A extends AgentType = AgentType> {
+export class WorkflowBuilder<A extends AgentType = AgentType, N extends string = string> {
   /** @internal Brand for detection across package boundaries */
   readonly __brand = "WorkflowBuilder" as const;
   private readonly options: WorkflowOptions;
-  private runFn: ((ctx: WorkflowContext<A>) => Promise<void>) | null = null;
+  private runFn: ((ctx: WorkflowContext<A, N>) => Promise<void>) | null = null;
 
   constructor(options: WorkflowOptions) {
     this.options = options;
   }
 
+  /**
+   * Narrow the agent type for this workflow while preserving typed inputs.
+   *
+   * Use `.for<"copilot">()` **before** `.run()` instead of passing the
+   * agent as a type parameter to `defineWorkflow`. This allows TypeScript
+   * to infer input names from the `inputs` array AND narrow the agent
+   * type for `stage()` callbacks.
+   *
+   * @example
+   * ```typescript
+   * defineWorkflow({
+   *   name: "my-workflow",
+   *   inputs: [{ name: "greeting", type: "string" }],
+   * })
+   *   .for<"copilot">()
+   *   .run(async (ctx) => {
+   *     ctx.inputs.greeting; // ✓ typed
+   *     ctx.inputs.prompt;   // ✗ compile error
+   *   })
+   *   .compile();
+   * ```
+   */
+  for<B extends AgentType>(): WorkflowBuilder<B, N> {
+    return this as unknown as WorkflowBuilder<B, N>;
+  }
+
   /**
    * Set the workflow's entry point.
    *
@@ -76,7 +103,7 @@ export class WorkflowBuilder<A extends AgentType = AgentType> {
    * reading completed session outputs. Use native TypeScript control flow
    * (loops, conditionals, `Promise.all()`) for orchestration.
    */
-  run(fn: (ctx: WorkflowContext<A>) => Promise<void>): this {
+  run(fn: (ctx: WorkflowContext<A, N>) => Promise<void>): this {
     if (this.runFn) {
       throw new Error("run() can only be called once per workflow.");
     }
@@ -93,7 +120,7 @@ export class WorkflowBuilder<A extends AgentType = AgentType> {
    * After calling compile(), the returned object is consumed by the
    * Atomic CLI runtime.
    */
-  compile(): WorkflowDefinition<A> {
+  compile(): WorkflowDefinition<A, N> {
     if (!this.runFn) {
       throw new Error(
         `Workflow "${this.options.name}" has no run callback. ` +
@@ -133,45 +160,36 @@ export class WorkflowBuilder<A extends AgentType = AgentType> {
 /**
  * Entry point for defining a workflow.
  *
- * Pass a type parameter to narrow all context types to a specific agent:
+ * Write the `inputs` array inline so TypeScript infers literal field
+ * names and enforces them on `ctx.inputs`. Use `.for<Agent>()` to
+ * narrow the agent type while keeping typed inputs:
  *
  * @example
  * ```typescript
  * import { defineWorkflow } from "@bastani/atomic/workflows";
  *
- * export default defineWorkflow<"copilot">({
+ * export default defineWorkflow({
  *   name: "hello",
  *   description: "Two-session demo",
+ *   inputs: [
+ *     { name: "greeting", type: "string", required: true },
+ *   ],
  * })
+ *   .for<"copilot">()
  *   .run(async (ctx) => {
- *     const describe = await ctx.stage(
- *       { name: "describe" },
- *       {},
- *       {},
- *       async (s) => {
- *         // s.client: CopilotClient, s.session: CopilotSession
- *         await s.session.send({ prompt: s.inputs.prompt ?? "" });
- *         s.save(await s.session.getMessages());
- *       },
- *     );
- *     await ctx.stage(
- *       { name: "summarize" },
- *       {},
- *       {},
- *       async (s) => {
- *         const research = await s.transcript(describe);
- *         // ...
- *       },
- *     );
+ *     ctx.inputs.greeting; // ✓ string | undefined
+ *     ctx.inputs.prompt;   // ✗ compile error — not declared
  *   })
  *   .compile();
  * ```
  */
-export function defineWorkflow<A extends AgentType = AgentType>(
-  options: WorkflowOptions,
-): WorkflowBuilder<A> {
+export function defineWorkflow<
+  const I extends readonly WorkflowInput[] = readonly WorkflowInput[],
+>(
+  options: WorkflowOptions<I>,
+): WorkflowBuilder<AgentType, I[number]["name"]> {
   if (!options.name || options.name.trim() === "") {
     throw new Error("Workflow name is required.");
   }
-  return new WorkflowBuilder<A>(options);
+  return new WorkflowBuilder<AgentType, I[number]["name"]>(options);
 }