ique-agentic-dx

name	ique-agentic-dx
description	Use when building agentic systems with @zaby-ai/ique: durable workflows, queue workers, signals, queries, updates, retries, compensation, replay validation, and production-ready Redis-backed orchestration in Node.js/TypeScript.
argument-hint	Describe the agentic use case, throughput/reliability goals, and whether to use workflows, queues, or both.
user-invocable	true

ique Agentic DX

Create high-DX, production-safe agentic flows with @zaby-ai/ique.

When To Use

• Building long-running agent workflows with durable state.
• Adding realtime control paths using signals and synchronous updates.
• Designing background task pipelines with queue workers.
• Implementing retries, compensation, and replay-safe workflow evolution.
• Hardening systems for Redis-backed reliability and operational recovery.

Core Outcomes

• Deterministic workflow behavior that can be replay-validated.
• Clear split between command paths:
  • Signal: asynchronous, fire-and-forget intent.
  • Update: synchronous mutation with immediate response.
  • Query: synchronous read-only state projection.
• Operational safeguards: timeouts, retries, compensation, stale recovery.

Canonical Setup

1. Install and import:

import "reflect-metadata";
import {
  Activity,
  Query,
  Signal,
  Update,
  Workflow,
  WorkflowEngine,
  Queue,
  Worker,
  type ExecutionContext,
  type RedisConnectionOptions,
} from "@zaby-ai/ique";

2. Use explicit Redis options in production:

const redisOptions: RedisConnectionOptions = {
  url: process.env.REDIS_URL,
};

3. Prefer a service-specific key prefix for isolation:

const engine = new WorkflowEngine(redisOptions, "my-service");

Workflow Blueprint

Use this structure as default for agentic orchestration:

@Workflow({ name: "agent.task", maxDurationMs: 15 * 60_000, maxEventHistory: 2000 })
class AgentTaskWorkflow {
  @Activity({ retries: 3, timeoutMs: 10_000 })
  async plan(ctx: ExecutionContext): Promise<{ planId: string }> {
    const planId = `plan-${ctx.workflowId}`;
    ctx.setMemory("planId", planId);
    return { planId };
  }

  @Activity({ retries: 2, timeoutMs: 30_000 })
  async execute(ctx: ExecutionContext, previous: { planId: string }) {
    return { ok: true, planId: previous.planId, run: ctx.getMemory<number>("run") ?? 1 };
  }

  @Signal({ name: "cancel" })
  async cancel() {
    ctx.(, payload. ?? );
  }

  ({ :  })
   () {
    ctx.(, payload.);
     { : , : payload. };
  }

  ({ :  })
   () {
     {
      : ctx.,
      : ctx..,
      : ctx..,
      : ctx.() ?? ,
      : ctx.() ?? ,
    };
  }
}

Queue Blueprint

Use queue workers for high-throughput, short-lived work units:

const queue = new Queue<{ taskId: string }>("agent-jobs", {}, redisOptions);

const worker = new Worker<{ taskId: string }, { done: boolean }>(
  queue,
  async (job) => {
    await job.updateProgress({ phase: "running" });
    return { done: true };
  },
  {
    autorun: true,
    concurrency: 10,
    lockDuration: 30_000,
    lockRenewTime: 15_000,
  },
);

Recommended Design Pattern

1. Front-door API receives request and starts a workflow.
2. Workflow activities coordinate decisions and persistent state.
3. Burst or parallel side work is delegated to queues.
4. Operators/other services send signals for async intent changes.
5. Clients call updates when they need immediate mutation + response.
6. Clients call queries to render current state.
7. Replay histories after workflow-code changes.

Reliability Checklist

• Set retries and timeoutMs on every activity.
• Add compensation handlers for externally visible side effects.
• Avoid nondeterministic branching without version guards.
• Use getVersion/patched when changing activity order or logic paths.
• Keep workflow memory small and serializable.
• Configure maxEventHistory for long-running workflows.
• Run replay validation before/after shipping workflow changes.

Agent Prompting Hints

When asked to implement features with @zaby-ai/ique, always capture:

• Business intent and expected terminal states.
• Throughput target and concurrency assumptions.
• Recovery expectation (resume, retry, compensation).
• Control-plane needs (signal/update/query names and payloads).
• Observability requirements (what status/metadata must be queryable).

Definition Of Done

• Workflow/queue implementation compiles and passes tests.
• Signal, query, and update paths are covered by integration tests.
• Failure path verifies retries and compensation behavior.
• Replay validation is run for changed workflow definitions.
• Shutdown closes worker/queue/engine connections cleanly.

Verify Commands

Use project scripts:

npm run verify:local
npm run verify:all

For local workflow smoke checks:

npm run example:workflow
npm run example:interactive