@ziggs-ai/agent-sdk 0.1.3 → 0.1.5

package/src/server/ZiggsEffectHandler.ts

@@ -0,0 +1,409 @@
+/**
+ * Ziggs-flavored EffectHandler.
+ *
+ * Translates the Agent's pure Effect requests into concrete calls against
+ * Ziggs backend primitives (MessagesClient, ArtifactsClient, ScopeClient,
+ * taskService, agreementService, messageSender) and the OpenAI adapter. This
+ * is the only place where Agent intent meets backend reality.
+ *
+ * Lives in agent-sdk for now alongside `Agent`; destined for a separate
+ * `@ziggs-ai/agent-server` package once the SDK split is complete.
+ */
+import type {
+  Effect, EffectHandler,
+  ContextSnapshot, LlmMessage, LlmResponse, LlmToolSchema, ToolCallResult,
+} from '../types.js';
+import { OutboxBuffer } from './OutboxBuffer.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+/** Minimal LLM adapter contract — OpenAIAdapter satisfies this. */
+interface LlmAdapter {
+  chatMessages(messages: LlmMessage[], tools?: LlmToolSchema[], options?: Record<string, unknown>): Promise<LlmResponse>;
+  chatMessagesStream?(messages: LlmMessage[], onChunk: (text: string) => void): Promise<string>;
+}
+import type { TaskService } from './tasks/TaskService.js';
+import type { AgreementService } from './agreements/AgreementService.js';
+import type { ToolManager } from '../tools/ToolManager.js';
+import type {
+  MessagesClient,
+  ArtifactsClient,
+  ScopeClient,
+  TelemetryClient,
+} from '@ziggs-ai/api-client';
+import {
+  buildLlmIngestPayload,
+  buildToolIngestPayload,
+  isTelemetryIngestEnabled,
+  sendTelemetry,
+} from './telemetryIngest.js';
+
+export interface ZiggsEffectDeps {
+  llm: LlmAdapter;
+  messagesClient: MessagesClient;
+  artifactsClient: ArtifactsClient;
+  scopeClient: ScopeClient;
+  taskService: TaskService;
+  agreementService: AgreementService;
+  messageSender: (text: string, receiverId: string, sessionId: string, messageId?: string) => Promise<unknown>;
+  /** Sends a streaming chunk to a client. Called per-token during stream-text effects. */
+  chunkSender?: (sessionId: string, receiverId: string, text: string, messageId: string) => void;
+  toolManager: ToolManager;
+  operatorKey: string;
+  agentId: string;
+  telemetryClient?: TelemetryClient;
+  /** When false, skips POST /agents/monitoring/ingest (default: env on). */
+  telemetryIngest?: boolean;
+  effectTap?: (effect: Effect, response: unknown) => void;
+}
+
+const CONTEXT_CACHE_MAX = 256;
+
+/**
+ * Compose a `ContextSnapshot` for a chatId by fanning out to scope + messages
+ * primitives. Replaces the single `/context/read` aggregator with parallel
+ * pulls. The shape stays the same so PromptBuilder / cognition code doesn't
+ * change.
+ */
+const annotateAgreement = (ag: Record<string, unknown>, agentId: string): Record<string, unknown> => {
+  const parties = (ag?.parties ?? {}) as { creator?: string; provider?: string; payer?: string; proposedTo?: string };
+  return {
+    ...ag,
+    creatorIsYou: parties.creator === agentId,
+    providerIsYou: parties.provider === agentId,
+    payerIsYou: parties.payer === agentId,
+    proposedToIsYou: parties.proposedTo === agentId,
+  };
+};
+
+async function buildSnapshot(
+  deps: ZiggsEffectDeps,
+  chatId: string,
+  agentId: string,
+  opts: { after?: string; limit?: number } = {},
+): Promise<ContextSnapshot> {
+  const [scope, msgs, chatAgreements] = await Promise.all([
+    deps.scopeClient.get('chat', chatId).catch((err: unknown) => {
+      runtimeLog.warn('ZiggsEffectHandler', `scope fetch failed: ${(err as Error)?.message ?? err}`);
+      return null;
+    }),
+    deps.messagesClient
+      .list(chatId, { after: opts.after, limit: opts.limit })
+      .catch((err: unknown) => {
+        runtimeLog.warn('ZiggsEffectHandler', `messages fetch failed: ${(err as Error)?.message ?? err}`);
+        return { messages: [], latestSequence: null };
+      }),
+    deps.agreementService.getByChat(chatId).catch((err: unknown) => {
+      runtimeLog.warn('ZiggsEffectHandler', `agreements fetch failed: ${(err as Error)?.message ?? err}`);
+      return [] as unknown[];
+    }),
+  ]);
+
+  const counterparties = (scope?.accessible?.counterparties ?? []) as Array<{
+    id: string;
+    role: string;
+    principalType?: 'user' | 'agent';
+  }>;
+
+  const others = counterparties.filter((c) => c.id !== agentId);
+  const users = others
+    .filter((c) => c.principalType === 'user')
+    .map((c) => ({ userId: c.id, role: c.role }));
+  const agents = others
+    .filter((c) => c.principalType !== 'user') // 'agent' or missing → treat as agent
+    .map((c) => ({ agentId: c.id, role: c.role, isYou: false }));
+  agents.push({ agentId, role: 'self', isYou: true });
+
+  const agreements = (chatAgreements as Record<string, unknown>[]).map((ag) => annotateAgreement(ag, agentId));
+
+  return {
+    history: msgs.messages as Record<string, unknown>[],
+    agreements,
+    agents,
+    users,
+    latestSequence: msgs.latestSequence,
+  };
+}
+
+const OP_ARTIFACT_MAX_CHARS = 900;
+
+function clipForOperationArtifact(value: unknown): unknown {
+  if (value == null) return value;
+  if (typeof value === 'string') {
+    return value.length > OP_ARTIFACT_MAX_CHARS ? `${value.slice(0, OP_ARTIFACT_MAX_CHARS - 1)}…` : value;
+  }
+  try {
+    const s = JSON.stringify(value);
+    if (s.length <= OP_ARTIFACT_MAX_CHARS) return value;
+    return `${s.slice(0, OP_ARTIFACT_MAX_CHARS - 1)}…`;
+  } catch {
+    return String(value).slice(0, OP_ARTIFACT_MAX_CHARS);
+  }
+}
+
+function previewToolArgs(args: Record<string, unknown>): Record<string, unknown> | undefined {
+  const keys = Object.keys(args);
+  if (keys.length === 0) return undefined;
+  const out: Record<string, unknown> = {};
+  for (let i = 0; i < keys.length && i < 16; i++) {
+    const k = keys[i];
+    out[k] = clipForOperationArtifact(args[k]);
+  }
+  return out;
+}
+
+/**
+ * Chat timeline: `Message.tsx` parses `entryType: artifact`, `content_type: operation` with
+ * `operation_*:{json}` where json includes `state` and `tool`.
+ */
+async function emitToolOperationArtifact(
+  client: ArtifactsClient,
+  chatId: string,
+  phase: 'started' | 'completed' | 'error',
+  payload: Record<string, unknown>,
+): Promise<void> {
+  const prefix =
+    phase === 'started' ? 'operation_started' : phase === 'completed' ? 'operation_completed' : 'operation_error';
+  const text = `${prefix}:${JSON.stringify(payload)}`;
+  try {
+    await client.write({
+      chatId,
+      text,
+      content_type: 'operation',
+      visibility: 'agent-private',
+    });
+  } catch (e: unknown) {
+    runtimeLog.warn(
+      'ZiggsEffectHandler',
+      `tool operation artifact (${phase}): ${(e as Error)?.message ?? String(e)}`,
+    );
+  }
+}
+
+/**
+ * Build a single shared EffectHandler. The handler is stateful — it caches
+ * the latest ContextSnapshot per sessionId so tool-call effects can resolve
+ * session-coupled deps (the `agents` roster) without forcing the Agent to
+ * pass them through. Cache is bounded with simple LRU eviction (re-set on
+ * read promotes the entry; oldest entry drops when size exceeds the cap).
+ */
+export function createZiggsEffectHandler(deps: ZiggsEffectDeps): EffectHandler {
+  const contextCache = new Map<string, ContextSnapshot>();
+  const outbox = new OutboxBuffer();
+
+  const cachePut = (sessionId: string, snap: ContextSnapshot): void => {
+    if (contextCache.has(sessionId)) contextCache.delete(sessionId);
+    contextCache.set(sessionId, snap);
+    if (contextCache.size > CONTEXT_CACHE_MAX) {
+      const oldest = contextCache.keys().next().value;
+      if (oldest !== undefined) contextCache.delete(oldest);
+    }
+  };
+  const cacheGet = (sessionId: string): ContextSnapshot | undefined => {
+    const snap = contextCache.get(sessionId);
+    if (snap !== undefined) {
+      contextCache.delete(sessionId);
+      contextCache.set(sessionId, snap);
+    }
+    return snap;
+  };
+
+  const dispatch = async (effect: Effect): Promise<unknown> => {
+    switch (effect.kind) {
+      case 'read-context': {
+        // Composite: assembles ContextSnapshot from scope + messages.
+        // Each agent runtime still gets the same shape, but the backend has
+        // no `/context/read` — assembly happens here, where the agent's
+        // identity is in scope.
+        const snap = await buildSnapshot(deps, effect.sessionId, deps.agentId, {
+          limit: effect.opts?.maxMessages,
+        });
+        const me = (snap.agents as Array<{ isYou?: boolean; agentId?: string }>).find((a) => a?.isYou)?.agentId || null;
+        outbox.merge(effect.sessionId, snap.history as Record<string, unknown>[], me);
+        cachePut(effect.sessionId, snap);
+        return snap;
+      }
+
+      case 'list-messages': {
+        return deps.messagesClient.list(effect.chatId, {
+          after: effect.after,
+          limit: effect.limit,
+        });
+      }
+
+      case 'list-artifacts': {
+        return deps.artifactsClient.list(
+          { chatId: effect.chatId, agreementId: effect.agreementId },
+          { after: effect.after, limit: effect.limit },
+        );
+      }
+
+      case 'list-task-history': {
+        const url = new URL(
+          `${process.env.ZIGGS_BACKEND_URL ?? 'http://localhost:3000'}/tasks/${effect.taskId}/history`,
+        );
+        if (effect.after) url.searchParams.set('after', effect.after);
+        if (effect.limit != null) url.searchParams.set('limit', String(effect.limit));
+        const res = await fetch(url.toString(), {
+          headers: {
+            'content-type': 'application/json',
+            Authorization: `Bearer ${deps.operatorKey}`,
+            'X-Agent-Id': deps.agentId,
+          },
+        });
+        if (!res.ok) {
+          throw new Error(`list-task-history ${res.status} ${res.statusText}`);
+        }
+        return res.json();
+      }
+
+      case 'get-scope': {
+        return deps.scopeClient.get(effect.via.kind, effect.via.id);
+      }
+
+      case 'llm-call': {
+        const t0 = Date.now();
+        const r: LlmResponse = await deps.llm.chatMessages(effect.messages, effect.tools);
+        sendTelemetry(
+          deps.telemetryClient,
+          buildLlmIngestPayload(r, {
+            sessionId: effect.sessionId,
+            durationMs: Date.now() - t0,
+            runId: effect.runId,
+            stateId: effect.stateId,
+          }),
+          isTelemetryIngestEnabled(deps.telemetryIngest),
+        );
+        return r;
+      }
+
+      case 'stream-text': {
+        const { sessionId, receiverId, messageId, messages } = effect;
+        let text = '';
+        if (deps.llm.chatMessagesStream) {
+          text = await deps.llm.chatMessagesStream(messages as LlmMessage[], (chunk) => {
+            deps.chunkSender?.(sessionId, receiverId, chunk, messageId);
+          });
+        } else {
+          const r = await deps.llm.chatMessages(messages as LlmMessage[]);
+          text = r.content ?? '';
+          if (text) deps.chunkSender?.(sessionId, receiverId, text, messageId);
+        }
+        return { text };
+      }
+
+      case 'tool-call': {
+        const toolT0 = Date.now();
+        const cached = cacheGet(effect.sessionId);
+        const agents = (cached?.agents as unknown[]) || [];
+        const users = (cached?.users as unknown[]) || [];
+        const args = (effect.args as Record<string, unknown>) || {};
+        const argsPreview = previewToolArgs(args);
+        await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'started', {
+          state: 'started',
+          tool: effect.name,
+          ...(argsPreview ? { args: argsPreview } : {}),
+        });
+        try {
+          const lastUser = (users as Array<{ userId?: string; id?: string }>).find(
+            (u) => u.userId || u.id,
+          );
+          const result = await deps.toolManager.executeTool(
+            effect.name,
+            args,
+            {
+              operatorKey: deps.operatorKey,
+              agentId: deps.agentId,
+              chatId: effect.sessionId,
+              taskService: deps.taskService,
+              agreementService: deps.agreementService,
+              sendMessage: deps.messageSender,
+              agents,
+              users,
+              senderId: effect.senderId ?? lastUser?.userId ?? lastUser?.id,
+              senderType: effect.senderType ?? (lastUser ? 'USER' : undefined),
+              memory: effect.memory,
+              turnScratch: {},
+            },
+          );
+          await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
+            state: 'completed',
+            tool: effect.name,
+            result: clipForOperationArtifact(result),
+          });
+          sendTelemetry(
+            deps.telemetryClient,
+            buildToolIngestPayload({
+              sessionId: effect.sessionId,
+              tool: effect.name,
+              durationMs: Date.now() - toolT0,
+              ok: true,
+              runId: effect.runId,
+              stateId: effect.stateId,
+            }),
+            isTelemetryIngestEnabled(deps.telemetryIngest),
+          );
+          return { ok: true, result } satisfies ToolCallResult;
+        } catch (error: unknown) {
+          const errMsg = (error as Error)?.message ?? String(error);
+          runtimeLog.warn('ZiggsEffectHandler', `tool-call "${effect.name}" failed: ${errMsg}`);
+          await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'error', {
+            state: 'failed',
+            tool: effect.name,
+            error: errMsg,
+          });
+          sendTelemetry(
+            deps.telemetryClient,
+            buildToolIngestPayload({
+              sessionId: effect.sessionId,
+              tool: effect.name,
+              durationMs: Date.now() - toolT0,
+              ok: false,
+              runId: effect.runId,
+              stateId: effect.stateId,
+            }),
+            isTelemetryIngestEnabled(deps.telemetryIngest),
+          );
+          return { ok: false, error: errMsg } satisfies ToolCallResult;
+        }
+      }
+
+      case 'send-message': {
+        await deps.messageSender(effect.text, effect.receiverId, effect.sessionId, effect.messageId);
+        outbox.track(effect.sessionId, { text: effect.text, receiverId: effect.receiverId });
+        return { ok: true };
+      }
+
+      case 'record-event': {
+        // Routes through ArtifactsClient as an agent-private artifact —
+        // visible to this agent across turns, not to other chat parties.
+        try {
+          if (effect.entry.kind === 'thought' && typeof effect.entry.text === 'string') {
+            await deps.artifactsClient.recordThought(effect.sessionId, effect.entry.text);
+          } else {
+            await deps.artifactsClient.write({
+              chatId: effect.sessionId,
+              text: JSON.stringify(effect.entry),
+              content_type: String(effect.entry.kind ?? 'event'),
+              visibility: 'agent-private',
+            });
+          }
+        } catch (err: unknown) {
+          runtimeLog.warn('ZiggsEffectHandler', `record-event failed: ${(err as Error)?.message ?? String(err)}`);
+        }
+        return { ok: true };
+      }
+
+      default: {
+        const exhaustive: never = effect;
+        throw new Error(`ZiggsEffectHandler: unknown effect kind ${(exhaustive as Record<string, unknown>).kind}`);
+      }
+    }
+  };
+
+  const handler = async (effect: Effect): Promise<unknown> => {
+    const response = await dispatch(effect);
+    deps.effectTap?.(effect, response);
+    return response;
+  };
+
+  return handler as EffectHandler;
+}

package/src/server/agreements/AgreementService.ts

@@ -0,0 +1,117 @@
+import {
+  proposeAgreement, delegateAgreement, respondToAgreement, counterAgreement,
+  getAgreementStatus, listAgreements, getMyAgreements, getAgreement,
+  publishOffer as publishOfferApi, createAgreement, revokeAgreement, getAgreementsByChat, linkAgreementToChat,
+  getChatsForAgreement, joinAgreement, linkArtifactToAgreement, getArtifactsForAgreement,
+  linkUserToAgreement, getUsersForAgreement, createContract,
+  OPEN_AGREEMENT_TARGET,
+  type Creds, type Agreement,
+  type ProposeAgreementData, type ProposeDirectInput, type ProposeBroadcastInput,
+  type PublishOfferPayload,
+  type DelegateAgreementData, type CounterAgreementData,
+  type CreateAgreementBody, type ListAgreementsFilters, type GetMyAgreementsFilters,
+  type ChatLinkType, type ArtifactLinkType, type UserRole, type CreateContractInput,
+} from '@ziggs-ai/api-client';
+
+export class AgreementService {
+  private creds: Creds;
+
+  constructor(operatorKey: string, agentId: string) {
+    if (!operatorKey) throw new Error('AgreementService: operatorKey is required');
+    if (!agentId) throw new Error('AgreementService: agentId is required (operator-token impersonation)');
+    this.creds = { operatorKey, agentId };
+  }
+
+  /** @deprecated Prefer {@link proposeDirect} or {@link proposeBroadcast}. */
+  contract(input: CreateContractInput): Promise<Agreement> {
+    return createContract(input, this.creds);
+  }
+
+  /** 1:1 proposal. Server defaults engagementKind to `service` when omitted. */
+  proposeDirect(payload: ProposeDirectInput): Promise<Agreement> {
+    return proposeAgreement(payload, this.creds);
+  }
+
+  /** Open buyer-broadcast (`proposedTo: "everyone"`). Server defaults engagementKind to `service`. */
+  proposeBroadcast(payload: ProposeBroadcastInput): Promise<Agreement> {
+    return proposeAgreement({ ...payload, proposedTo: OPEN_AGREEMENT_TARGET }, this.creds);
+  }
+
+  /** @deprecated Alias for {@link proposeDirect}. */
+  propose(payload: ProposeAgreementData): Promise<Agreement> {
+    return proposeAgreement(payload, this.creds);
+  }
+
+  /** Seller-broadcast marketplace offer (`parties.payer = everyone`). */
+  publishOffer(payload: PublishOfferPayload): Promise<Agreement> {
+    return publishOfferApi(payload, this.creds);
+  }
+
+  delegate(payload: DelegateAgreementData): Promise<Agreement> {
+    return delegateAgreement(payload, this.creds);
+  }
+
+  respond(agreementId: string, action: 'approve' | 'reject'): Promise<Agreement> {
+    return respondToAgreement(agreementId, action, this.creds);
+  }
+
+  counter(agreementId: string, counter: CounterAgreementData): Promise<Agreement> {
+    return counterAgreement(agreementId, counter || {}, this.creds);
+  }
+
+  getStatus(agreementId: string): Promise<unknown | null> {
+    return getAgreementStatus(agreementId, this.creds);
+  }
+
+  list(filters: ListAgreementsFilters = {}): Promise<Agreement[]> {
+    return listAgreements(filters, this.creds);
+  }
+
+  mine(filters: GetMyAgreementsFilters = {}): Promise<Agreement[]> {
+    return getMyAgreements(filters, this.creds);
+  }
+
+  get(agreementId: string): Promise<Agreement | null> {
+    return getAgreement(agreementId, this.creds);
+  }
+
+  create(body: CreateAgreementBody): Promise<{ ok: boolean; agreement: Agreement }> {
+    return createAgreement(body, this.creds);
+  }
+
+  revoke(agreementId: string): Promise<{ ok: boolean; agreement: Agreement }> {
+    return revokeAgreement(agreementId, this.creds);
+  }
+
+  getByChat(chatId: string): Promise<unknown[]> {
+    return getAgreementsByChat(chatId, this.creds);
+  }
+
+  linkToChat(agreementId: string, chatId: string, linkType: ChatLinkType = 'mention'): Promise<unknown | null> {
+    return linkAgreementToChat(agreementId, chatId, linkType, this.creds);
+  }
+
+  getChats(agreementId: string): Promise<unknown[]> {
+    return getChatsForAgreement(agreementId, this.creds);
+  }
+
+  join(agreementId: string): Promise<{ chatId: string; agentId: string | null; isNew: boolean }> {
+    return joinAgreement(agreementId, this.creds);
+  }
+
+  linkArtifact(agreementId: string, artifactId: string, linkType: ArtifactLinkType = 'produced'): Promise<unknown | null> {
+    return linkArtifactToAgreement(agreementId, artifactId, linkType, this.creds);
+  }
+
+  getArtifacts(agreementId: string): Promise<unknown[]> {
+    return getArtifactsForAgreement(agreementId, this.creds);
+  }
+
+  linkUser(agreementId: string, userId: string, role: UserRole): Promise<unknown | null> {
+    return linkUserToAgreement(agreementId, userId, role, this.creds);
+  }
+
+  getUsers(agreementId: string): Promise<unknown[]> {
+    return getUsersForAgreement(agreementId, this.creds);
+  }
+}

package/src/server/createHealthServer.ts

@@ -0,0 +1,85 @@
+import { createServer, type Server } from 'http';
+import type { ConnectionPool } from './ConnectionPool.js';
+import type { AgentHost } from '../AgentHost.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+function readJsonBody(req: import('http').IncomingMessage): Promise<Record<string, unknown>> {
+  return new Promise((resolve, reject) => {
+    const chunks: Buffer[] = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+      try {
+        const raw = Buffer.concat(chunks).toString('utf8');
+        resolve(raw ? (JSON.parse(raw) as Record<string, unknown>) : {});
+      } catch (err) {
+        reject(err);
+      }
+    });
+    req.on('error', reject);
+  });
+}
+
+export function createHealthServer({
+  port = Number(process.env.PORT) || 8080,
+  label = 'agents',
+  pool,
+}: {
+  port?: number;
+  label?: string;
+  pool?: ConnectionPool;
+} = {}): Server {
+  const server = createServer(async (req, res) => {
+    const url = req.url ?? '/';
+    const wakeMatch = url.match(/^\/fleet-wake\/([^/?]+)/);
+    if (req.method === 'POST' && wakeMatch && pool) {
+      const agentId = decodeURIComponent(wakeMatch[1]);
+      try {
+        await pool.wake(agentId);
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, agentId, active: pool.listActive().includes(agentId) }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: (err as Error).message }));
+      }
+      return;
+    }
+
+    if (req.method === 'POST' && url === '/fleet-deliver' && pool) {
+      try {
+        const body = await readJsonBody(req);
+        const agentId = String(body.agentId ?? '');
+        const chatId = String(body.chatId ?? '');
+        const text = String(body.text ?? '');
+        const senderId = String(body.senderId ?? '');
+        if (!agentId || !chatId || !text || !senderId) {
+          res.writeHead(400, { 'Content-Type': 'application/json' });
+          res.end(JSON.stringify({ ok: false, error: 'agentId, chatId, text, senderId required' }));
+          return;
+        }
+        const host = (await pool.wake(agentId)) as AgentHost;
+        await host.handleMessage(text, {
+          chatId,
+          entryType: 'message',
+          content_type: 'text',
+          sender: { id: senderId, type: 'USER' },
+          receiver: { id: agentId, type: 'AGENT' },
+        });
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: true, agentId }));
+      } catch (err) {
+        res.writeHead(500, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ ok: false, error: (err as Error).message }));
+      }
+      return;
+    }
+    if (url === '/health' || url === '/') {
+      res.writeHead(200);
+      res.end('ok');
+      return;
+    }
+    res.writeHead(404);
+    res.end();
+  });
+  server.listen(port, () => runtimeLog.info(label, `health server on port ${port}`));
+  return server;
+}

package/src/server/proactive/ProactiveTrigger.ts

@@ -0,0 +1,83 @@
+import { publishOffer, pullOffers, claimOffer, type Creds } from '@ziggs-ai/api-client';
+import type { PublishOfferPayload, PullOffersOptions } from '@ziggs-ai/api-client';
+import { runtimeLog } from '../../shared/runtimeLog.js';
+
+interface TickContext {
+  agentId: string;
+  marketplace: {
+    publishOffer: (payload: PublishOfferPayload) => Promise<unknown>;
+    pullOffers: (options?: PullOffersOptions) => Promise<unknown[]>;
+    claimOffer: (agreementId: string) => Promise<unknown>;
+  };
+}
+
+interface ProactiveTriggerOptions {
+  interval: number;
+  creds: Creds;
+  onTick: (ctx: TickContext) => Promise<void>;
+  onError?: (err: unknown) => void;
+  runImmediately?: boolean;
+}
+
+export class ProactiveTrigger {
+  private interval: number;
+  private creds: Creds;
+  private onTick: (ctx: TickContext) => Promise<void>;
+  private onError: (err: unknown) => void;
+  private runImmediately: boolean;
+  private _running: boolean;
+  private _timer: ReturnType<typeof setTimeout> | null;
+
+  constructor({ interval, creds, onTick, onError, runImmediately = false }: ProactiveTriggerOptions) {
+    if (!interval || typeof interval !== 'number' || interval < 1000) throw new Error('ProactiveTrigger: interval must be a number >= 1000ms');
+    if (!creds?.operatorKey || !creds?.agentId) throw new Error('ProactiveTrigger: creds.operatorKey and creds.agentId are required');
+    if (typeof onTick !== 'function') throw new Error('ProactiveTrigger: onTick must be a function');
+    this.interval = interval;
+    this.creds = creds;
+    this.onTick = onTick;
+    this.onError = onError ?? ((err) => runtimeLog.error('ProactiveTrigger', `tick error: ${String(err)}`));
+    this.runImmediately = runImmediately;
+    this._running = false;
+    this._timer = null;
+  }
+
+  start(): void {
+    if (this._running) return;
+    this._running = true;
+    runtimeLog.debug(
+      'ProactiveTrigger',
+      `started (agentId=${this.creds.agentId}, interval=${this.interval}ms)`,
+    );
+    if (this.runImmediately) this._tick();
+    else this._schedule();
+  }
+
+  stop(): void {
+    this._running = false;
+    if (this._timer) { clearTimeout(this._timer); this._timer = null; }
+    runtimeLog.debug('ProactiveTrigger', `stopped (agentId=${this.creds.agentId})`);
+  }
+
+  private _schedule(): void {
+    if (!this._running) return;
+    this._timer = setTimeout(() => this._tick(), this.interval);
+  }
+
+  private async _tick(): Promise<void> {
+    if (!this._running) return;
+    try { await this.onTick(this._buildContext()); } catch (err) { this.onError(err); }
+    this._schedule();
+  }
+
+  private _buildContext(): TickContext {
+    const creds = this.creds;
+    return {
+      agentId: creds.agentId,
+      marketplace: {
+        publishOffer: (payload) => publishOffer(payload, creds),
+        pullOffers: (options) => pullOffers(options, creds),
+        claimOffer: (agreementId) => claimOffer(agreementId, creds),
+      },
+    };
+  }
+}