Durable workflow'lar

Tek bir agent çağrısının ötesine geçen, birden çok adımdan oluşan iş akışlarını (ör. önce bir kayıt oluştur, sonra ödeme kontrolü yap, ardından onay bekleyip bildirim gönder) modellemek için kullanılır. Her adım journal'a ayrı ayrı kaydedilir; süreç ortasında proses çökerse veya bir adım (sleep/waitFor) askıya alınırsa, aynı runId ile tekrar çağrıldığında tamamlanmış adımlar yeniden ÇALIŞMAZ (replay), yalnızca kaldığı yerden devam eder.

Somut senaryo: bir sipariş akışında "ödeme onayı bekle" adımı saatler sürebilir. Süreç bu sırada kapansa bile, aynı runId ile tekrar çalıştırıldığında ödeme adımı hâlâ askıdaysa suspended döner; koşul sağlandığında adım gerçekten ilerler ve sonraki adımlara geçilir.

Workflow'u tanımlamak için @gnldev/workflow paketindeki workflow() builder'ı kullanılır; çalıştırmak/kaydetmek için ise @gnldev/durable'ın createGnl registry'si gerekir (Workflow sınıfı, createGnl'ın beklediği WorkflowLike yapısal arayüzünü zaten karşılar — ayrı bir uyarlama gerekmez).

import { workflow, step, retry } from '@gnldev/workflow';
import { createGnl } from '@gnldev/durable';

1) Workflow'u workflow() ve step(id, run) ile sıralı adımlar halinde tanımlayın:

const myWorkflow = workflow<{ email: string }>()
  .then(step('onboard:create-account', async (input) => {
    // ... create the account
    return { ...input, accountId: 'acc_1' };
  }))
  .then(step('onboard:send-welcome', async (input) => {
    // ... send the welcome email
    return { ...input, welcomed: true };
  }));

2) Workflow'u createGnl'ın workflows alanına isimle kaydedin:

const config: CreateGnlConfig = {
  storage,
  agents: { /* ... */ },
  workflows: { onboard: myWorkflow },
};
const gnl = createGnl(config);

3) runWorkflow ile aynı runId'yi vererek çalıştırın — süreç kesilse bile aynı runId ile tekrar çağrı, tamamlanmış adımları atlayıp kaldığı yerden devam eder:

const res = await gnl.runWorkflow('onboard', input, { runId: 'wf-1' });
// POST /workflows/onboard/run with the same runId -> resumes where it stopped

REST tarafında bu, @gnldev/server'ın otomatik ürettiği POST /workflows/:name/run ucu üzerinden aynı sözleşmeyle sunulur — gövdede { runId?, input } beklenir; verilen runId journal'da zaten bir iz taşıyorsa istek otomatik olarak bir resume kabul edilir (bütçe kapısı bu durumda atlanır, yalnız gerçekten yeni iş zorlanır). Kayıtlı workflow'ların adım listesi GET /workflows ile introspect edilebilir.

4) Bir adımı bildirimsel olarak retry'lamak için retry(step, policy) kullanın — attempts (ilk çalıştırma dahil toplam deneme), opsiyonel backoffMs (sabit ms ya da deneme indeksinden hesaplayan fonksiyon) ve tüm denemeler tükenince koşacak opsiyonel fallback adımı alır. Sarılmış adım drop-in'dir — aynı id'yi taşır, then/branch/parallel içinde sarılmamış bir adım gibi kullanılır:

import { retry, step } from '@gnldev/workflow';

const chargeStep = retry(
  step('order:charge', async (input) => chargeCard(input)),
  {
    attempts: 3,
    backoffMs: (attempt) => attempt * 500, // 500ms, 1000ms, ...
    fallback: step('order:charge-fallback', async (input) => ({ ...input, charged: false })),
  },
);

const orderWorkflow = workflow<{ orderId: string }>().then(chargeStep);

Deneme sayacı `${runId}:wf:${id}:attempts` anahtarıyla journal'a yazılır — crash-resume'da sayaç sıfırdan BAŞLAMAZ, "toplam N deneme" sözü process ölümlerinden bağımsız kalır. Önceki bir koşuda tükenmiş bir adım, resume'da doğrudan fallback'e (varsa) gider — yeniden N deneme yapılmaz. Askı (WorkflowSuspended, ör. sleep/waitFor) hata sayılmaz ve deneme tüketmeden aynen dışarı yayılır. fallback, adımın kendi anahtarında ayrıca journal'lanır — fallback koşup crash olursa resume'da yeniden çalışmaz.

• Deterministic replay & crash recoveryAn interrupted run resumes deterministically from where it left off.
• Human-approved tools (guard)Guard suspends risky calls; resumed on approval.
• Automatic REST API + OpenAPI + SSETurns createGnl into a durable HTTP API + SSE stream in one line.