zeitlich 0.2.15 → 0.2.17

package/src/lib/types.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+import { isTerminalStatus } from "./types";
+import type { AgentStatus } from "./types";
+
+describe("isTerminalStatus", () => {
+  it("returns true for COMPLETED", () => {
+    expect(isTerminalStatus("COMPLETED")).toBe(true);
+  });
+
+  it("returns true for FAILED", () => {
+    expect(isTerminalStatus("FAILED")).toBe(true);
+  });
+
+  it("returns true for CANCELLED", () => {
+    expect(isTerminalStatus("CANCELLED")).toBe(true);
+  });
+
+  it("returns false for RUNNING", () => {
+    expect(isTerminalStatus("RUNNING")).toBe(false);
+  });
+
+  it("returns false for WAITING_FOR_INPUT", () => {
+    expect(isTerminalStatus("WAITING_FOR_INPUT")).toBe(false);
+  });
+
+  it("returns false for unknown status", () => {
+    expect(isTerminalStatus("UNKNOWN" as AgentStatus)).toBe(false);
+  });
+});

package/src/lib/workflow.test.ts

@@ -0,0 +1,131 @@
+import { describe, expect, it } from "vitest";
+import {
+  defineWorkflow,
+  type WorkflowInput,
+  type WorkflowSessionInput,
+} from "./workflow";
+
+describe("defineWorkflow", () => {
+  it("maps previousThreadId to threadId + continueThread", async () => {
+    let capturedSession: WorkflowSessionInput | undefined;
+
+    const workflow = defineWorkflow(async (_input, sessionInput) => {
+      capturedSession = sessionInput;
+      return { ok: true };
+    });
+
+    await workflow({}, { previousThreadId: "prev-42" });
+
+    expect(capturedSession).toEqual({
+      threadId: "prev-42",
+      continueThread: true,
+    });
+  });
+
+  it("maps sandboxId", async () => {
+    let capturedSession: WorkflowSessionInput | undefined;
+
+    const workflow = defineWorkflow(async (_input, sessionInput) => {
+      capturedSession = sessionInput;
+      return { ok: true };
+    });
+
+    await workflow({}, { sandboxId: "sb-123" });
+
+    expect(capturedSession).toEqual({ sandboxId: "sb-123" });
+  });
+
+  it("maps both previousThreadId and sandboxId together", async () => {
+    let capturedSession: WorkflowSessionInput | undefined;
+
+    const workflow = defineWorkflow(async (_input, sessionInput) => {
+      capturedSession = sessionInput;
+      return { ok: true };
+    });
+
+    await workflow({}, { previousThreadId: "prev-1", sandboxId: "sb-1" });
+
+    expect(capturedSession).toEqual({
+      threadId: "prev-1",
+      continueThread: true,
+      sandboxId: "sb-1",
+    });
+  });
+
+  it("returns empty sessionInput when no previousThreadId or sandboxId", async () => {
+    let capturedSession: WorkflowSessionInput | undefined;
+
+    const workflow = defineWorkflow(async (_input, sessionInput) => {
+      capturedSession = sessionInput;
+      return { ok: true };
+    });
+
+    await workflow({});
+
+    expect(capturedSession).toEqual({});
+  });
+
+  it("passes full input as first argument", async () => {
+    let capturedInput: unknown;
+
+    const workflow = defineWorkflow<{
+      prompt: string;
+      metadata: { key: string };
+      previousThreadId?: string;
+      sandboxId?: string;
+    }, { ok: boolean }>(async (input, _sessionInput) => {
+      capturedInput = input;
+      return { ok: true };
+    });
+
+    await workflow({
+      prompt: "research",
+      metadata: { key: "val" },
+    });
+
+    expect(capturedInput).toEqual({
+      prompt: "research",
+      metadata: { key: "val" },
+    });
+  });
+
+  it("passes workflowInput as second argument only", async () => {
+    let capturedInput: unknown;
+    let capturedSession: WorkflowSessionInput | undefined;
+
+    const workflow = defineWorkflow<{ prompt: string }, { ok: boolean }>(
+      async (input, sessionInput) => {
+        capturedInput = input;
+        capturedSession = sessionInput;
+        return { ok: true };
+      },
+    );
+
+    const workflowInput: WorkflowInput = {
+      previousThreadId: "prev",
+      sandboxId: "sb",
+    };
+    await workflow({ prompt: "go" }, workflowInput);
+
+    expect(capturedInput).toEqual({ prompt: "go" });
+    expect(capturedSession).toEqual({
+      threadId: "prev",
+      continueThread: true,
+      sandboxId: "sb",
+    });
+  });
+
+  it("returns the handler response unchanged", async () => {
+    const workflow = defineWorkflow(async () => ({
+      finalMessage: "result text",
+      threadId: "thread-123",
+    }));
+
+    const result = await workflow({});
+
+    expect(result).toEqual({
+      finalMessage: "result text",
+      threadId: "thread-123",
+    });
+  });
+});

package/src/lib/workflow.ts

@@ -0,0 +1,45 @@
+/**
+ * Session config fields derived from a main workflow input, ready to spread
+ * into `createSession`.
+ */
+export interface WorkflowSessionInput {
+  /** Thread ID to continue (set from `input.previousThreadId`) */
+  threadId?: string;
+  /** Whether to continue an existing thread (true when `previousThreadId` is present) */
+  continueThread?: boolean;
+  /** Optional sandbox ID forwarded to the session */
+  sandboxId?: string;
+}
+
+/** Raw workflow input fields that map into `WorkflowSessionInput`. */
+export interface WorkflowInput {
+  /** When set, continue this thread instead of starting fresh */
+  previousThreadId?: string;
+  /** Optional sandbox ID to reuse */
+  sandboxId?: string;
+}
+
+/**
+ * Wraps a main workflow function, translating workflow input fields into
+ * session-compatible fields that can be spread directly into `createSession`.
+ *
+ * The wrapper:
+ * - Accepts a generic typed `input` as first argument
+ * - Accepts optional `workflowInput` ({ previousThreadId, sandboxId }) as second argument
+ * - Derives `threadId` + `continueThread` from `workflowInput.previousThreadId`
+ * - Derives `sandboxId` from `workflowInput.sandboxId`
+ */
+export function defineWorkflow<TInput, TResult>(
+  fn: (input: TInput, sessionInput: WorkflowSessionInput) => Promise<TResult>,
+): (input: TInput, workflowInput?: WorkflowInput) => Promise<TResult> {
+  return async (input, workflowInput = {}) => {
+    const sessionInput: WorkflowSessionInput = {
+      ...(workflowInput.previousThreadId && {
+        threadId: workflowInput.previousThreadId,
+        continueThread: true,
+      }),
+      ...(workflowInput.sandboxId && { sandboxId: workflowInput.sandboxId }),
+    };
+    return fn(input, sessionInput);
+  };
+}

package/src/workflow.ts

@@ -25,6 +25,8 @@ export {
   proxySandboxOps,
 } from "./lib/session";
 export type { ZeitlichSession, ThreadOps, SessionConfig } from "./lib/session";
+export { defineWorkflow } from "./lib/workflow";
+export type { WorkflowInput, WorkflowSessionInput } from "./lib/workflow";
 
 // Thread utilities
 export { getShortId } from "./lib/thread";
@@ -45,7 +47,7 @@ export {
   hasNoOtherToolCalls,
   defineTool,
 } from "./lib/tool-router";
-export { defineSubagent } from "./lib/subagent";
+export { defineSubagent, defineSubagentWorkflow } from "./lib/subagent";
 export type {
   // Tool definition types
   ToolDefinition,
@@ -130,10 +132,12 @@ export type {
 // Subagent types
 export type {
   SubagentConfig,
+  SubagentDefinition,
   SubagentHooks,
-  SubagentInput,
   SubagentHandlerResponse,
   SubagentWorkflow,
+  SubagentWorkflowInput,
+  SubagentSessionInput,
 } from "./lib/subagent/types";
 // Sandbox types (workflow-safe — no activity-side code)
 export type {
@@ -159,6 +163,12 @@ export {
 // pulling activity-side code like VirtualSandboxFileSystem / Provider).
 export { applyVirtualTreeMutations } from "./adapters/sandbox/virtual/mutations";
 export { formatVirtualFileTree } from "./adapters/sandbox/virtual/tree";
+export {
+  hasFileWithMimeType,
+  filesWithMimeType,
+  hasDirectory,
+} from "./adapters/sandbox/virtual/queries";
+
 export type {
   FileEntry,
   FileEntryMetadata,