@hasna/workflows 0.2.0 → 0.2.1

package/README.md

@@ -87,6 +87,34 @@ run API includes `triggerRun`, `getRun`, `listNodes`, `events`, `cancelRun` and
 the graph, context and cycle budget. Reusing a key for a different request returns
 HTTP 409. Run context cannot contain the reserved `__wf` or `steps` fields.
 
+A step's optional `cwd` names its working directory on the server executing the
+workflow. It applies to shell commands and model lanes; prefer an absolute path.
+Codex prompts keep their native repository, sandbox and approval defaults. Supply
+`cwd` for work in an existing trusted repository. For a prompt that needs no file
+changes and may run outside a repository, explicitly set `codexMode: "read-only"`:
+
+```ts
+import { createWorkflowsClient, type WorkflowGraph } from "@hasna/workflows/sdk";
+
+const workflows = createWorkflowsClient();
+const graph: WorkflowGraph = {
+  name: "read-only-answer", version: "1",
+  nodes: [
+    { id: "start", type: "start", next: "answer" },
+    { id: "answer", type: "step", lane: "codex", codexMode: "read-only",
+      prompt: "Return the requested answer without changing files.", next: "end" },
+    { id: "end", type: "end" },
+  ],
+};
+await workflows.triggerRun(graph, {}, { idempotencyKey: "read-only-answer-1" });
+```
+
+This explicit mode uses Codex's read-only sandbox, permits a nonrepository
+directory and refuses approval escalation. It applies only to Codex prompt steps;
+shell commands cannot select it. An empty Codex response fails the step even when
+the native process exits successfully. Memoization distinguishes the working
+directory, lane and execution mode.
+
 ## MCP
 
 Register `workflows-mcp` as a stdio command in Codex, Claude Code, OpenCode, Sumi,