@ziggs-ai/agent-sdk 0.1.3 → 0.1.4

package/src/server/ZiggsEffectHandler.ts

@@ -0,0 +1,335 @@
+/**
+ * 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>;
+}
+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';
+
+export interface ZiggsEffectDeps {
+  llm: LlmAdapter;
+  messagesClient: MessagesClient;
+  artifactsClient: ArtifactsClient;
+  scopeClient: ScopeClient;
+  taskService: TaskService;
+  agreementService: AgreementService;
+  messageSender: (text: string, receiverId: string, sessionId: string) => Promise<unknown>;
+  toolManager: ToolManager;
+  operatorKey: string;
+  agentId: string;
+  telemetryClient?: TelemetryClient;
+}
+
+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 { creatorId?: string; providerId?: string; payerId?: string; proposedToId?: string };
+  return {
+    ...ag,
+    creatorIsYou: parties.creatorId === agentId,
+    providerIsYou: parties.providerId === agentId,
+    payerIsYou: parties.payerId === agentId,
+    proposedToIsYou: parties.proposedToId === 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 handler = 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 r: LlmResponse = await deps.llm.chatMessages(effect.messages, effect.tools);
+        return r;
+      }
+
+      case 'tool-call': {
+        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 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,
+              memory: effect.memory,
+              turnScratch: {},
+            },
+          );
+          await emitToolOperationArtifact(deps.artifactsClient, effect.sessionId, 'completed', {
+            state: 'completed',
+            tool: effect.name,
+            result: clipForOperationArtifact(result),
+          });
+          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,
+          });
+          return { ok: false, error: errMsg } satisfies ToolCallResult;
+        }
+      }
+
+      case 'send-message': {
+        await deps.messageSender(effect.text, effect.receiverId, effect.sessionId);
+        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}`);
+      }
+    }
+  };
+
+  return handler as EffectHandler;
+}

package/src/server/agreements/AgreementService.ts

@@ -0,0 +1,111 @@
+import {
+  proposeAgreement, delegateAgreement, respondToAgreement, counterAgreement,
+  getAgreementStatus, listAgreements, getMyAgreements, getAgreement,
+  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 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);
+  }
+
+  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,8 @@
+import { createServer, type Server } from 'http';
+import { runtimeLog } from '../shared/runtimeLog.js';
+
+export function createHealthServer({ port = Number(process.env.PORT) || 8080, label = 'agents' } = {}): Server {
+  const server = createServer((_req, res) => { res.writeHead(200); res.end('ok'); });
+  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),
+      },
+    };
+  }
+}

package/src/server/runLauncher.ts

@@ -0,0 +1,131 @@
+import { ConnectionPool } from './ConnectionPool.js';
+import { AgentHost, type AgentHostOptions } from '../AgentHost.js';
+import { createHealthServer } from './createHealthServer.js';
+import { runtimeLog } from '../shared/runtimeLog.js';
+import type { Server } from 'http';
+
+type AgentConfig = AgentHostOptions & {
+  ownAgentId?: string;
+  options?: { ownAgentId?: string; name?: string };
+};
+
+interface SingleOptions {
+  operatorKey?: string;
+  label?: string;
+  port?: number | string;
+  healthServer?: boolean;
+  onShutdown?: () => Promise<void>;
+}
+
+interface FleetOptions extends SingleOptions {
+  wsUrl?: string;
+  agentMeta?: Record<string, unknown>[];
+  orchestrator?: AgentConfig | ((pool: ConnectionPool) => AgentConfig);
+  preWake?: string[];
+  poolOptions?: { maxActive?: number; idleTimeoutMs?: number };
+}
+
+export async function runLauncher(
+  configOrConfigs: AgentConfig | AgentConfig[],
+  opts: FleetOptions = {},
+): Promise<unknown> {
+  if (Array.isArray(configOrConfigs)) return runFleet(configOrConfigs, opts);
+  return runSingle(configOrConfigs, opts as SingleOptions);
+}
+
+async function runSingle(
+  config: AgentConfig,
+  { operatorKey, label = 'agent', port = process.env.PORT || 8080, healthServer = true, onShutdown }: SingleOptions = {},
+): Promise<{ agent: unknown; healthServer?: Server }> {
+  const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
+  const decorated = effectiveKey && !config.operatorKey ? { ...config, operatorKey: effectiveKey } : config;
+  const agent = new AgentHost(decorated);
+  await agent.connectAsync();
+  runtimeLog.info(
+    label,
+    `"${(agent as unknown as Record<string, unknown>)['options'] ? ((agent as unknown as Record<string, {agentId?: string; name?: string | null}>)['options']?.agentId ?? (agent as unknown as Record<string, {name?: string | null}>)['options']?.name) : 'agent'}" connected`,
+  );
+
+  const server = healthServer ? createHealthServer({ port: Number(port), label }) : null;
+
+  process.on('SIGTERM', async () => {
+    runtimeLog.info(label, 'SIGTERM — shutting down');
+    agent.disconnect();
+    try {
+      await onShutdown?.();
+    } catch (err) {
+      runtimeLog.warn(label, `onShutdown error: ${(err as Error).message}`);
+    }
+    server?.close();
+    process.exit(0);
+  });
+
+  return { agent, healthServer: server ?? undefined };
+}
+
+async function runFleet(
+  configs: AgentConfig[],
+  {
+    operatorKey, wsUrl = process.env.WS_URL, port = process.env.PORT || 8080,
+    healthServer = true, label = 'launcher', agentMeta,
+    orchestrator: orchestratorConfig, preWake = [], poolOptions, onShutdown,
+  }: FleetOptions = {},
+): Promise<{ pool: ConnectionPool; orchestrator: unknown; healthServer?: Server }> {
+  const pool = new ConnectionPool(poolOptions);
+  const effectiveKey = operatorKey ?? process.env.ZIGGS_OPERATOR_KEY;
+  const decoratedConfigs = effectiveKey
+    ? configs.map(c => (c.operatorKey ? c : { ...c, operatorKey: effectiveKey }))
+    : configs;
+  pool.register(decoratedConfigs, agentMeta as Record<string, unknown>[]);
+  const server = healthServer ? createHealthServer({ port: Number(port), label }) : null;
+
+  let resolvedOrchConfig: AgentConfig | undefined = typeof orchestratorConfig === 'function'
+    ? orchestratorConfig(pool)
+    : orchestratorConfig;
+  if (resolvedOrchConfig && effectiveKey && !resolvedOrchConfig.operatorKey) {
+    resolvedOrchConfig = { ...resolvedOrchConfig, operatorKey: effectiveKey };
+  }
+
+  const controlKey = effectiveKey ?? configs.find(c => c.operatorKey)?.operatorKey ?? resolvedOrchConfig?.operatorKey;
+  if (controlKey) {
+    pool.startControl({ wsUrl, operatorKey: controlKey });
+  } else {
+    runtimeLog.warn(label, 'No operatorKey provided — skipping control socket');
+  }
+
+  let orchestrator: unknown = null;
+  if (resolvedOrchConfig) {
+    orchestrator = new AgentHost(resolvedOrchConfig);
+    await (orchestrator as { connectAsync: () => Promise<void> }).connectAsync();
+    runtimeLog.info(
+      label,
+      `Orchestrator "${resolvedOrchConfig.name || resolvedOrchConfig.ownAgentId || 'orchestrator'}" connected`,
+    );
+  }
+
+  if (preWake.length > 0) {
+    await Promise.all(preWake.map(id =>
+      pool.wake(id)
+        .then(() => runtimeLog.debug(label, `Pre-woke "${id}"`))
+        .catch(err => runtimeLog.warn(label, `Could not pre-wake "${id}": ${(err as Error).message}`)),
+    ));
+  }
+
+  runtimeLog.info(label, `Ready — ${pool.size} agent(s) registered, ${pool.listActive().length} connected`);
+
+  process.on('SIGTERM', async () => {
+    runtimeLog.info(label, 'SIGTERM — shutting down');
+    pool.stopControl();
+    (orchestrator as { disconnect?: () => void })?.disconnect?.();
+    await pool.disconnectAll();
+    try {
+      await onShutdown?.();
+    } catch (err) {
+      runtimeLog.warn(label, `onShutdown error: ${(err as Error).message}`);
+    }
+    server?.close();
+    process.exit(0);
+  });
+
+  return { pool, orchestrator, healthServer: server ?? undefined };
+}