Wire cloud workflow and integration runtime defaults

packages/runtime/src/clients/github.test.ts

@@ -12,7 +12,7 @@ async function tempMount(): Promise<string> {
 test('github.comment writes a draft comment file under issues/<n>/comments/', async () => {
   const root = await tempMount();
   try {
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.comment({ owner: 'o', repo: 'r', number: 2 }, 'hello');
 
     const dir = path.join(root, 'github/repos/o/r/issues/2/comments');
@@ -29,7 +29,7 @@ test('github.comment writes a draft comment file under issues/<n>/comments/', as
 test('github.createIssue writes a draft issue file under issues/', async () => {
   const root = await tempMount();
   try {
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.createIssue({
       owner: 'o',
       repo: 'r',
@@ -55,7 +55,7 @@ test('github.createIssue writes a draft issue file under issues/', async () => {
 test('github.createPullRequest writes a draft pull request file under pulls/', async () => {
   const root = await tempMount();
   try {
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.createPullRequest({
       owner: 'o',
       repo: 'r',
@@ -97,7 +97,7 @@ test('github.upsertIssue updates an existing flat issue match', async () => {
       })
     );
 
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     const result = await client.upsertIssue({
       owner: 'o',
       repo: 'r',
@@ -130,7 +130,7 @@ test('github.upsertIssue ignores a closed issue title match', async () => {
       })
     );
 
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     const result = await client.upsertIssue({
       owner: 'o',
       repo: 'r',
@@ -153,7 +153,7 @@ test('github.upsertIssue ignores a closed issue title match', async () => {
 test('github.upsertIssue creates a draft when no open match exists', async () => {
   const root = await tempMount();
   try {
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     const result = await client.upsertIssue({
       owner: 'o',
       repo: 'r',
@@ -188,7 +188,7 @@ test('github.getPr reads meta + diff from canonical paths', async () => {
     );
     await writeFile(path.join(pullRoot, 'diff.patch'), 'diff --git a/x b/x\n');
 
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     const pr = await client.getPr({ owner: 'o', repo: 'r', number: 42 });
     assert.equal(pr.title, 'Add deploy v1');
     assert.equal(pr.head, 'feature');
@@ -217,7 +217,7 @@ test('github.getPr reads a flat canonical pull request file', async () => {
       })
     );
 
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     const pr = await client.getPr({ owner: 'o', repo: 'r', number: 42 });
     assert.equal(pr.title, 'Add deploy v1');
     assert.equal(pr.head, 'feature');
@@ -232,7 +232,7 @@ test('github.getPr reads a flat canonical pull request file', async () => {
 test('github.postReview writes a review draft under pulls/<n>/reviews/', async () => {
   const root = await tempMount();
   try {
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.postReview(
       { owner: 'o', repo: 'r', number: 42 },
       {
@@ -256,7 +256,7 @@ test('github.postReview writes a review draft under pulls/<n>/reviews/', async (
 test('github.postReview accepts COMMENT/APPROVE/REQUEST_CHANGES events', async () => {
   const root = await tempMount();
   try {
-    const client = createGithubClient({ relayfileMountRoot: root });
+    const client = createGithubClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     for (const event of ['COMMENT', 'APPROVE', 'REQUEST_CHANGES'] as const) {
       await client.postReview({ owner: 'o', repo: 'r', number: event === 'COMMENT' ? 1 : event === 'APPROVE' ? 2 : 3 }, {
         body: event.toLowerCase(),

packages/runtime/src/clients/jira.test.ts

@@ -12,7 +12,7 @@ async function tempMount(): Promise<string> {
 test('jira createIssue writes a Jira issue draft', async () => {
   const root = await tempMount();
   try {
-    const client = createJiraClient({ relayfileMountRoot: root });
+    const client = createJiraClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.createIssue({
       cloudId: 'cloud_1',
       fields: { project: { key: 'ENG' }, summary: 'Ship it', issuetype: { name: 'Task' } }
@@ -33,7 +33,7 @@ test('jira createIssue writes a Jira issue draft', async () => {
 test('jira transition writes an issue transition draft', async () => {
   const root = await tempMount();
   try {
-    const client = createJiraClient({ relayfileMountRoot: root });
+    const client = createJiraClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.transition({ cloudId: 'cloud_1', issueIdOrKey: 'ENG-1' }, '31');
 
     const dir = path.join(root, 'jira/issues/ENG-1/transitions');

packages/runtime/src/clients/linear.test.ts

@@ -12,7 +12,7 @@ async function tempMount(): Promise<string> {
 test('linear createIssue writes an issue draft', async () => {
   const root = await tempMount();
   try {
-    const client = createLinearClient({ relayfileMountRoot: root });
+    const client = createLinearClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.createIssue({ teamId: 'team_1', title: 'Ship it', description: 'Soon' });
 
     const dir = path.join(root, 'linear/issues');
@@ -38,7 +38,7 @@ test('linear getIssue reads a canonical issue file', async () => {
       JSON.stringify({ id: 'i1', identifier: 'ENG-1', title: 'Ship it', description: null, url: 'https://linear.app/i1', state: null })
     );
 
-    const client = createLinearClient({ relayfileMountRoot: root });
+    const client = createLinearClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     assert.equal((await client.getIssue('ENG-1')).identifier, 'ENG-1');
   } finally {
     await rm(root, { recursive: true, force: true });

packages/runtime/src/clients/notion.test.ts

@@ -12,7 +12,7 @@ async function tempMount(): Promise<string> {
 test('notion createPage writes a database page draft', async () => {
   const root = await tempMount();
   try {
-    const client = createNotionClient({ relayfileMountRoot: root });
+    const client = createNotionClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.createPage(
       { database_id: 'db_1' },
       { Name: { title: [{ text: { content: 'Digest' } }] } },
@@ -32,7 +32,7 @@ test('notion createPage writes a database page draft', async () => {
 });
 
 test('notion createPage requires a database parent for file writeback', async () => {
-  const client = createNotionClient({ relayfileMountRoot: '/tmp/unused' });
+  const client = createNotionClient({ relayfileMountRoot: '/tmp/unused', writebackTimeoutMs: 0 });
   await assert.rejects(
     () => client.createPage({}, {}, []),
     /parent\.database_id/

packages/runtime/src/clients/request.ts

@@ -16,8 +16,8 @@ import { WorkforceIntegrationError } from '../errors.js';
  *
  * The handler-side ergonomics stay identical to the direct-REST shape
  * — `await ctx.github.comment(target, body)` returns when the write
- * lands. Whether the receipt is awaited synchronously, polled, or
- * fired-and-forgotten depends on `writebackTimeoutMs`.
+ * lands and, by default, waits briefly for the provider receipt.
+ * Setting `writebackTimeoutMs` to `0` keeps fire-and-forget behavior.
  */
 export interface IntegrationClientOptions {
   /** Absolute path to the Relayfile mount the handler is running in. */
@@ -30,9 +30,8 @@ export interface IntegrationClientOptions {
   workspaceCwd?: string;
   /**
    * Max wait, in ms, for the Relayfile writeback worker to emit a
-   * receipt onto the just-written draft. `0` (default) means
-   * fire-and-forget — the client returns immediately and the receipt
-   * is whatever was readable at write time.
+   * receipt onto the just-written draft. Defaults to 3000ms. `0` means
+   * fire-and-forget — the client returns immediately without a receipt.
    */
   writebackTimeoutMs?: number;
   /** Poll interval while waiting for a receipt. Default 250ms. */
@@ -71,6 +70,8 @@ export interface WritebackResult {
   receipt?: WritebackReceipt;
 }
 
+const DEFAULT_WRITEBACK_TIMEOUT_MS = 3_000;
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -196,7 +197,7 @@ function isNoEntryError(error: unknown): boolean {
 /**
  * Write a draft JSON payload atomically (write-then-rename) so the
  * writeback worker never sees a partial file. Waits for a receipt
- * when `writebackTimeoutMs > 0`; otherwise returns immediately.
+ * by default; pass `writebackTimeoutMs: 0` to return immediately.
  */
 export async function writeJsonFile(
   client: IntegrationClientOptions,
@@ -222,7 +223,7 @@ async function waitForReceipt(
   absolutePath: string,
   client: IntegrationClientOptions
 ): Promise<WritebackReceipt | undefined> {
-  const timeoutMs = client.writebackTimeoutMs ?? 0;
+  const timeoutMs = client.writebackTimeoutMs ?? DEFAULT_WRITEBACK_TIMEOUT_MS;
   // Fire-and-forget: never reinterpret the just-written draft as a
   // receipt. The draft payload may legitimately carry top-level `id` /
   // `path` / `created` fields (e.g. an upsert update writing back the

packages/runtime/src/clients/slack.test.ts

@@ -1,6 +1,6 @@
 import test from 'node:test';
 import assert from 'node:assert/strict';
-import { mkdtemp, readFile, readdir, rm } from 'node:fs/promises';
+import { mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { WorkforceIntegrationError } from '../errors.js';
@@ -13,7 +13,7 @@ async function tempMount(): Promise<string> {
 test('slack post writes a channel message draft', async () => {
   const root = await tempMount();
   try {
-    const client = createSlackClient({ relayfileMountRoot: root });
+    const client = createSlackClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.post('C123', 'hello');
 
     const dir = path.join(root, 'slack/channels/C123/messages');
@@ -27,10 +27,39 @@ test('slack post writes a channel message draft', async () => {
   }
 });
 
+test('slack post waits for the writeback receipt by default', async () => {
+  const root = await tempMount();
+  const dir = path.join(root, 'slack/channels/C123/messages');
+  let timer: NodeJS.Timeout | undefined;
+  try {
+    const client = createSlackClient({ relayfileMountRoot: root, writebackPollMs: 10 });
+    timer = setInterval(() => {
+      void readdir(dir)
+        .then(async (files) => {
+          const file = files.find((name) => name.endsWith('.json'));
+          if (!file) return;
+          await writeFile(
+            path.join(dir, file),
+            JSON.stringify({ created: '1716490000.123456', url: 'https://slack.example/C123/p1716490000123456' }),
+            'utf8'
+          );
+          if (timer) clearInterval(timer);
+        })
+        .catch(() => undefined);
+    }, 10);
+
+    const result = await client.post('C123', 'hello');
+    assert.equal(result.ts, '1716490000.123456');
+  } finally {
+    if (timer) clearInterval(timer);
+    await rm(root, { recursive: true, force: true });
+  }
+});
+
 test('slack dm writes a user direct-message draft', async () => {
   const root = await tempMount();
   try {
-    const client = createSlackClient({ relayfileMountRoot: root });
+    const client = createSlackClient({ relayfileMountRoot: root, writebackTimeoutMs: 0 });
     await client.dm('U123', 'ping');
 
     const dir = path.join(root, 'slack/users/U123/messages');
@@ -45,15 +74,15 @@ test('slack dm writes a user direct-message draft', async () => {
 });
 
 test('slack reply rejects malformed string thread refs', async () => {
-  const client = createSlackClient({ relayfileMountRoot: '/tmp/unused' });
+  const client = createSlackClient({ relayfileMountRoot: '/tmp/unused', writebackTimeoutMs: 0 });
   await assert.rejects(
     () => client.reply('missing-ts', 'hello'),
     (error) => error instanceof WorkforceIntegrationError && error.provider === 'slack'
   );
 });
 
 test('slack reply rejects malformed object thread refs', async () => {
-  const client = createSlackClient({ relayfileMountRoot: '/tmp/unused' });
+  const client = createSlackClient({ relayfileMountRoot: '/tmp/unused', writebackTimeoutMs: 0 });
   await assert.rejects(
     () => client.reply({ channel: '', ts: '123.456' }, 'hello'),
     (error) => error instanceof WorkforceIntegrationError && error.provider === 'slack'