@parall/agent-core 1.30.0 → 1.32.0

package/src/prompt-fragments.ts

@@ -27,29 +27,32 @@ be direct, and care about the outcome of the work — not just the request in fr
 of you.`;
 
 function sanitizeProfileField(value: string): string {
-  return value.replace(/[\r\n]+/g, " ").replace(/`/g, "'").trim();
+  return value
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/`/g, "'")
+    .trim();
 }
 
 function sanitizeProfileBlock(value: string): string {
-  return value.replace(/\r\n?/g, "\n").trim();
+  return value.replace(/\r\n?/g, '\n').trim();
 }
 
 export function buildIdentity(agent?: AgentIdentity): string {
   if (!agent) return PRLL_IDENTITY_BASE;
   const name = sanitizeProfileField(agent.displayName);
-  const lines = [PRLL_IDENTITY_BASE, "", "### Your Parall Identity", ""];
+  const lines = [PRLL_IDENTITY_BASE, '', '### Your Parall Identity', ''];
   lines.push(`You are **${name}** (\`prll://${agent.userId}\`).`);
   if (agent.description) {
     const description = sanitizeProfileBlock(agent.description);
     if (description) {
-      lines.push("", "### Your Agent Profile", "", description);
+      lines.push('', '### Your Agent Profile', '', description);
     }
   }
   lines.push(
-    "",
+    '',
     `When you see \`${agent.userId}\` or \`prll://${agent.userId}\` in messages, mentions, or events — that's you.`,
   );
-  return lines.join("\n");
+  return lines.join('\n');
 }
 
 /** @deprecated Use buildIdentity() instead. Kept for backward compat during migration. */
@@ -143,6 +146,18 @@ resolves and renders the entity title automatically.
 
     prll://tsk_xxx/description#Implementation     heading within task description
 
+### Unread context
+
+When dispatched to a chat, you may see \`[Unread: N messages | since: prll://msg_xxx]\`.
+This shows messages since your last interaction — your read cursor advances after each
+dispatch, so context you skip now won't appear as unread next time. Use
+\`parall messages list <chat> --limit 20\` to fetch recent context. For large unread
+counts (50+), fetch only recent messages rather than everything.
+
+Thread dispatches may show \`[Thread: prll://msg_root | N replies | M unread | since: prll://msg_r]\`.
+Same semantics — use \`parall messages list <chat> --thread-root-id <thread_root> --limit 20\` to
+catch up on the thread.
+
 ### Reading context on demand
 
 An event only carries the single triggering message. If you're mentioned in a
@@ -206,7 +221,7 @@ export type LocalAttachmentResult = {
 };
 
 export function renderLocalAttachmentSection(section: LocalAttachmentResult): string {
-  if (section.images.length === 0 && section.notes.length === 0) return "";
+  if (section.images.length === 0 && section.notes.length === 0) return '';
 
   // Each image renders as a metadata header line plus the absolute path on
   // its own line. The path stands alone (no quoting / escaping) so file-
@@ -215,7 +230,7 @@ export function renderLocalAttachmentSection(section: LocalAttachmentResult): st
   // the bridge operator. A pathological workspace dir with embedded newlines
   // would split across lines; that's exotic enough not to warrant scrubbing
   // every consumer's path through escape rules.
-  const lines = ["[Local attachment files]"];
+  const lines = ['[Local attachment files]'];
   for (const image of section.images) {
     lines.push(
       `- prll://${image.attachmentId} (${sanitizePromptMeta(image.mimeType)}, ${formatBytes(image.fileSize)}, ${sanitizePromptMeta(image.fileName)})`,
@@ -223,11 +238,14 @@ export function renderLocalAttachmentSection(section: LocalAttachmentResult): st
     );
   }
   lines.push(...section.notes);
-  return lines.join("\n");
+  return lines.join('\n');
 }
 
 function sanitizePromptMeta(value: string): string {
-  return value.replace(/[\r\n]+/g, " ").replace(/[()]/g, " ").trim();
+  return value
+    .replace(/[\r\n]+/g, ' ')
+    .replace(/[()]/g, ' ')
+    .trim();
 }
 
 export function formatBytes(bytes: number): string {

package/src/provider-config.ts

@@ -0,0 +1,51 @@
+export interface ProviderConfig {
+  llm_source?: string;
+  openai_api_key?: string;
+  openai_base_url?: string;
+  anthropic_auth_token?: string;
+  anthropic_base_url?: string;
+}
+
+export function llmSource(pc?: ProviderConfig): string {
+  return effectiveLLMSourceExplicit(pc) || 'parall';
+}
+
+/**
+ * Returns the explicitly-configured LLM source — the llm_source value when
+ * set, or "custom" when BYO provider credentials are present — or "" when the
+ * provider_config carries no source signal at all (e.g. the empty `{}` default
+ * that self-hosted agents always have). The daemon supervisor uses the empty
+ * case to defer to the machine-level llm_source instead of letting `{}` shadow
+ * it as "parall". Mirrors the Go `ProviderConfig.EffectiveLLMSourceExplicit`.
+ */
+export function effectiveLLMSourceExplicit(pc?: ProviderConfig): string {
+  if (pc?.llm_source) return pc.llm_source;
+  if (
+    pc?.openai_api_key ||
+    pc?.openai_base_url ||
+    pc?.anthropic_auth_token ||
+    pc?.anthropic_base_url
+  ) {
+    return 'custom';
+  }
+  return '';
+}
+
+export function clearAllProviderCreds(env: NodeJS.ProcessEnv): void {
+  delete env.ANTHROPIC_AUTH_TOKEN;
+  delete env.ANTHROPIC_BASE_URL;
+  delete env.ANTHROPIC_API_KEY;
+  delete env.OPENAI_API_KEY;
+  delete env.OPENAI_BASE_URL;
+  delete env.PRLL_CLAUDE_ALLOW_API_KEY;
+}
+
+export function parseProviderConfig(env: NodeJS.ProcessEnv): ProviderConfig | undefined {
+  const raw = env.PRLL_PROVIDER_CONFIG?.trim();
+  if (!raw) return undefined;
+  try {
+    return JSON.parse(raw) as ProviderConfig;
+  } catch (err) {
+    throw new Error(`Invalid PRLL_PROVIDER_CONFIG JSON: ${String(err)}`);
+  }
+}

package/src/routing.ts

@@ -1,11 +1,11 @@
-import type { DispatchState, ParallEvent } from "./types.js";
+import type { DispatchState, ParallEvent } from './types.js';
 
 /** Where an inbound event should be routed. */
 export type TriggerDisposition =
-  | { action: "main" }
-  | { action: "buffer-main" }
-  | { action: "buffer-fork"; forkKey: string }
-  | { action: "new-fork" };
+  | { action: 'main' }
+  | { action: 'buffer-main' }
+  | { action: 'buffer-fork'; forkKey: string }
+  | { action: 'new-fork' };
 
 /** Pluggable strategy for routing triggers when main session is busy. */
 export type RoutingStrategy = (event: ParallEvent, state: DispatchState) => TriggerDisposition;
@@ -21,17 +21,17 @@ const MAX_CONCURRENT_FORKS = 20;
  */
 export const defaultRoutingStrategy: RoutingStrategy = (event, state) => {
   if (state.mainCurrentTargetId === event.targetId) {
-    return { action: "buffer-main" };
+    return { action: 'buffer-main' };
   }
 
   const existingForkKey = state.activeForks.get(event.targetId);
-  if (existingForkKey) return { action: "buffer-fork", forkKey: existingForkKey };
+  if (existingForkKey) return { action: 'buffer-fork', forkKey: existingForkKey };
 
   if (state.activeForks.size >= MAX_CONCURRENT_FORKS) {
-    return { action: "buffer-main" };
+    return { action: 'buffer-main' };
   }
 
-  return { action: "new-fork" };
+  return { action: 'new-fork' };
 };
 
 /** Route an inbound event based on current dispatch state. */
@@ -41,7 +41,7 @@ export function routeTrigger(
   strategy: RoutingStrategy = defaultRoutingStrategy,
 ): TriggerDisposition {
   const existingForkKey = state.activeForks.get(event.targetId);
-  if (existingForkKey) return { action: "buffer-fork", forkKey: existingForkKey };
-  if (!state.mainDispatching) return { action: "main" };
+  if (existingForkKey) return { action: 'buffer-fork', forkKey: existingForkKey };
+  if (!state.mainDispatching) return { action: 'main' };
   return strategy(event, state);
 }

package/src/session-state.ts

@@ -67,3 +67,65 @@ export function getDispatchNoReply(sessionKey: string): boolean {
 export function clearDispatchNoReply(sessionKey: string) {
   dispatchNoReplyMap.delete(normalizeSessionKey(sessionKey));
 }
+
+// ---------------------------------------------------------------------------
+// Per-dispatch metrics — populated by runtime adapters, reported by gateway
+// ---------------------------------------------------------------------------
+
+export type DispatchMetrics = {
+  deliver_text_chunks: number;
+  deliver_text_chars: number;
+  message_send_attempts: number;
+  message_send_successes: number;
+  no_reply_called: boolean;
+  tool_call_count: number;
+  started_at: number;
+};
+
+const dispatchMetricsMap = new Map<string, DispatchMetrics>();
+
+export function resetDispatchMetrics(sessionKey: string): void {
+  dispatchMetricsMap.set(normalizeSessionKey(sessionKey), {
+    deliver_text_chunks: 0,
+    deliver_text_chars: 0,
+    message_send_attempts: 0,
+    message_send_successes: 0,
+    no_reply_called: false,
+    tool_call_count: 0,
+    started_at: Date.now(),
+  });
+}
+
+export function getDispatchMetrics(sessionKey: string): DispatchMetrics | undefined {
+  return dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+}
+
+export function clearDispatchMetrics(sessionKey: string): void {
+  dispatchMetricsMap.delete(normalizeSessionKey(sessionKey));
+}
+
+export function recordDeliverText(sessionKey: string, charCount: number): void {
+  const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+  if (!m) return;
+  m.deliver_text_chunks++;
+  m.deliver_text_chars += charCount;
+}
+
+export function recordMessageSend(sessionKey: string, success: boolean): void {
+  const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+  if (!m) return;
+  m.message_send_attempts++;
+  if (success) m.message_send_successes++;
+}
+
+export function recordNoReply(sessionKey: string): void {
+  const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+  if (!m) return;
+  m.no_reply_called = true;
+}
+
+export function recordToolCall(sessionKey: string): void {
+  const m = dispatchMetricsMap.get(normalizeSessionKey(sessionKey));
+  if (!m) return;
+  m.tool_call_count++;
+}

package/src/skills/index.ts

@@ -1,52 +1,63 @@
-import * as fs from "node:fs";
-import * as path from "node:path";
+import * as fs from 'node:fs';
+import * as path from 'node:path';
 
-export { PARALL_PLATFORM_SKILL } from "./parall-platform.js";
-export { PARALL_TASKS_SKILL } from "./parall-tasks.js";
-export { PARALL_WIKI_SKILL } from "./parall-wiki.js";
-export { PARALL_SCHEDULES_SKILL } from "./parall-schedules.js";
+export { PARALL_PLATFORM_SKILL } from './parall-platform.js';
+export { PARALL_TASKS_SKILL } from './parall-tasks.js';
+export { PARALL_WIKI_SKILL } from './parall-wiki.js';
+export { PARALL_SCHEDULES_SKILL } from './parall-schedules.js';
+export { PARALL_CLIPS_SKILL } from './parall-clips.js';
 
-import { PARALL_PLATFORM_SKILL } from "./parall-platform.js";
-import { PARALL_TASKS_SKILL } from "./parall-tasks.js";
-import { PARALL_WIKI_SKILL } from "./parall-wiki.js";
-import { PARALL_SCHEDULES_SKILL } from "./parall-schedules.js";
+import { PARALL_PLATFORM_SKILL } from './parall-platform.js';
+import { PARALL_TASKS_SKILL } from './parall-tasks.js';
+import { PARALL_WIKI_SKILL } from './parall-wiki.js';
+import { PARALL_SCHEDULES_SKILL } from './parall-schedules.js';
+import { PARALL_CLIPS_SKILL } from './parall-clips.js';
 
 export type SkillMeta = { name: string; description: string; content: string };
 
 export const SKILLS: SkillMeta[] = [
   {
-    name: "parall-platform",
-    description: "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, or create another agent. Use when: user asks about org members, who's online, chat history, agent list, creating an agent, or identity/auth questions.",
+    name: 'parall-platform',
+    description:
+      "Parall platform queries and lightweight agent provisioning: list org members, agents, chats, read message history, check identity, or create another agent. Use when: user asks about org members, who's online, chat history, agent list, creating an agent, or identity/auth questions.",
     content: PARALL_PLATFORM_SKILL,
   },
   {
-    name: "parall-tasks",
-    description: "Parall task operations: create, update, comment on, and query tasks and projects. Use when: user asks to create a task, update task status, add comments, list tasks, or manage projects.",
+    name: 'parall-tasks',
+    description:
+      'Parall task operations: create, update, comment on, and query tasks and projects. Use when: user asks to create a task, update task status, add comments, list tasks, or manage projects.',
     content: PARALL_TASKS_SKILL,
   },
   {
-    name: "parall-wiki",
-    description: "Parall wiki operations: read, search, edit, and propose changes to organization knowledge bases. Use when: user asks to read/write docs, edit wiki pages, search knowledge base, propose changes, or review changesets.",
+    name: 'parall-wiki',
+    description:
+      'Parall wiki operations: read, search, edit, and propose changes to organization knowledge bases. Use when: user asks to read/write docs, edit wiki pages, search knowledge base, propose changes, or review changesets.',
     content: PARALL_WIKI_SKILL,
   },
   {
-    name: "parall-schedules",
-    description: "Parall schedule operations: create / pause / resume / cancel recurring or one-shot time triggers; respond to schedule fire events. Use when: user asks to set up a recurring reminder, schedule a delayed prompt, run cron-like work, or when the agent receives an `[Event: schedule.fired]` dispatch.",
+    name: 'parall-schedules',
+    description:
+      'Parall schedule operations: create / pause / resume / cancel recurring or one-shot time triggers; respond to schedule fire events. Use when: user asks to set up a recurring reminder, schedule a delayed prompt, run cron-like work, or when the agent receives an `[Event: schedule.fired]` dispatch.',
     content: PARALL_SCHEDULES_SKILL,
   },
+  {
+    name: 'parall-clips',
+    description:
+      'Parall clip operations: list installed clips, invoke clip commands, inspect clip details. Use when: the task requires external capabilities (GitHub, web search, etc.), user asks about available tools/clips, or you need to call a clip command.',
+    content: PARALL_CLIPS_SKILL,
+  },
 ];
 
 /** Write plain skill markdown files to a target directory (CC/Codex). */
 export function writeSkillFiles(targetDir: string): void {
   fs.mkdirSync(targetDir, { recursive: true });
   for (const skill of SKILLS) {
-    fs.writeFileSync(path.join(targetDir, `${skill.name}.md`), skill.content, "utf8");
+    fs.writeFileSync(path.join(targetDir, `${skill.name}.md`), skill.content, 'utf8');
   }
 }
 
-
 export function buildSkillReferences(workspaceDir: string): string {
-  const dir = path.join(workspaceDir, ".parall", "skills");
-  const lines = SKILLS.map((s) => `- ${s.description.split(":")[0]}: \`${dir}/${s.name}.md\``);
-  return `## Platform Skills (read on demand)\n\n${lines.join("\n")}\n`;
+  const dir = path.join(workspaceDir, '.parall', 'skills');
+  const lines = SKILLS.map((s) => `- ${s.description.split(':')[0]}: \`${dir}/${s.name}.md\``);
+  return `## Platform Skills (read on demand)\n\n${lines.join('\n')}\n`;
 }

package/src/skills/parall-clips.ts

@@ -0,0 +1,44 @@
+export const PARALL_CLIPS_SKILL = `# Parall Clips
+
+Clips are capability extensions — packaged toolkits that give you extra commands (e.g. GitHub operations, web search, code analysis). Clips installed in the org are available for any agent to invoke via the CLI.
+
+## Discovering available clips
+
+\`\`\`bash
+# List all clips installed in the org
+parall clip list
+
+# Show detailed info about a clip (manifest, commands, version)
+parall clip info <alias>
+\`\`\`
+
+## Invoking a clip command
+
+\`\`\`bash
+# Invoke a command on a clip by alias
+parall clip invoke <alias> <command> [input]
+
+# input is optional — when provided, it can be a JSON string or plain text
+parall clip invoke github-tools list-repos '{"org": "acme"}'
+parall clip invoke web-search search "latest Node.js LTS version"
+
+# Custom timeout (default 30s)
+parall clip invoke github-tools create-issue '{"title": "Bug report"}' --timeout 60000
+\`\`\`
+
+## How clips work
+
+1. An org admin installs a clip from the Pinix registry or creates a custom one
+2. \`parall clip list\` shows every clip installed in the org
+3. You can only **invoke** clips that an admin has **bound to you** — invoking an unbound clip returns a "not bound" error. Ask an admin to bind the clip if you need it.
+4. Each clip exposes one or more named commands with typed input/output
+
+## When to use clips
+
+- Check \`parall clip list\` when a task requires capabilities beyond your built-in tools (e.g. GitHub API, external services, specialized analysis)
+- Use \`parall clip info <alias>\` to discover available commands and their expected input format
+- If \`parall clip invoke\` reports the clip isn't bound to you, that clip exists in the org but hasn't been granted to you — ask an admin to bind it
+- Clip invocations return JSON output on success or an error message on failure
+
+CLI command results are JSON on stdout.
+`;

package/src/telemetry.ts

@@ -0,0 +1,252 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import {
+  trace,
+  metrics,
+  type Span,
+  type Tracer,
+  type Counter,
+  type Histogram,
+  SpanStatusCode,
+} from '@opentelemetry/api';
+import { type Logger, SeverityNumber } from '@opentelemetry/api-logs';
+import type { GatewayLogger } from './dispatch-adapter.js';
+import type { DispatchMetrics } from './session-state.js';
+import type { ParallEvent } from './types.js';
+
+let initialized = false;
+let shutdownFn: (() => Promise<void>) | null = null;
+
+let tracer: Tracer | null = null;
+let dispatchCounter: Counter | null = null;
+let dispatchDuration: Histogram | null = null;
+let missingReplyCounter: Counter | null = null;
+let otelLogger: Logger | null = null;
+
+function resolveTargetType(targetId: string): string {
+  if (targetId.startsWith('cht_')) return 'chat';
+  if (targetId.startsWith('tsk_')) return 'task';
+  if (targetId.startsWith('sch_')) return 'schedule';
+  return 'unknown';
+}
+
+export interface TelemetryHandle {
+  shutdown: () => Promise<void>;
+}
+
+/**
+ * Initialize agent telemetry. All agents export OTLP to the Parall
+ * telemetry-service (`PRLL_API_URL/otel`), authenticated with `PRLL_API_KEY`.
+ * The service canonicalizes identity from the token and proxies to SigNoz.
+ *
+ * Resource attributes include machine/agent/org identity from env.
+ * Returns a no-op handle when `PRLL_API_URL` is absent (local dev).
+ */
+export async function initAgentTelemetry(
+  serviceName: string,
+  runtimeType: string,
+): Promise<TelemetryHandle> {
+  const noopHandle: TelemetryHandle = { shutdown: async () => {} };
+
+  const apiUrl = process.env.PRLL_API_URL;
+  const apiKey = process.env.PRLL_API_KEY;
+  if (!apiUrl || !apiKey) {
+    return noopHandle;
+  }
+
+  try {
+    const otelEndpoint = apiUrl.replace(/\/$/, '') + '/otel';
+
+    const { OTLPTraceExporter } = await import('@opentelemetry/exporter-trace-otlp-proto');
+    const { OTLPMetricExporter } = await import('@opentelemetry/exporter-metrics-otlp-proto');
+    const { OTLPLogExporter } = await import('@opentelemetry/exporter-logs-otlp-proto');
+    const { NodeTracerProvider, BatchSpanProcessor } = await import(
+      '@opentelemetry/sdk-trace-node'
+    );
+    const { MeterProvider, PeriodicExportingMetricReader } = await import(
+      '@opentelemetry/sdk-metrics'
+    );
+    const { LoggerProvider, BatchLogRecordProcessor } = await import('@opentelemetry/sdk-logs');
+    const { Resource } = await import('@opentelemetry/resources');
+
+    const resource = new Resource({
+      'service.name': serviceName,
+      'service.version': process.env.npm_package_version || 'unknown',
+      'deployment.environment.name':
+        process.env.PRLL_SERVER_ENV || process.env.NODE_ENV || 'development',
+      'parall.runtime_type': runtimeType,
+      'parall.agent_id': process.env.PRLL_AGENT_ID || '',
+      'parall.machine_id': process.env.PRLL_MACHINE_ID || '',
+      'parall.org_id': process.env.PRLL_ORG_ID || '',
+      'parall.daemon_mode': process.env.PRLL_DAEMON_MODE === '1',
+    });
+
+    const authHeaders = { Authorization: `Bearer ${apiKey}` };
+
+    const traceExporter = new OTLPTraceExporter({
+      url: `${otelEndpoint}/v1/traces`,
+      headers: authHeaders,
+    });
+    const tracerProvider = new NodeTracerProvider({ resource });
+    tracerProvider.addSpanProcessor(new BatchSpanProcessor(traceExporter));
+    tracerProvider.register();
+
+    const metricExporter = new OTLPMetricExporter({
+      url: `${otelEndpoint}/v1/metrics`,
+      headers: authHeaders,
+    });
+    const metricReader = new PeriodicExportingMetricReader({
+      exporter: metricExporter,
+      exportIntervalMillis: 15_000,
+    });
+    const meterProvider = new MeterProvider({ resource, readers: [metricReader] });
+    metrics.setGlobalMeterProvider(meterProvider);
+
+    const logExporter = new OTLPLogExporter({
+      url: `${otelEndpoint}/v1/logs`,
+      headers: authHeaders,
+    });
+    const loggerProvider = new LoggerProvider({ resource });
+    loggerProvider.addLogRecordProcessor(new BatchLogRecordProcessor(logExporter));
+
+    const meter = metrics.getMeter('parall.agent');
+    tracer = trace.getTracer('parall.agent');
+    otelLogger = loggerProvider.getLogger('parall.agent');
+    dispatchCounter = meter.createCounter('parall.dispatch.count', {
+      description: 'Number of dispatch cycles completed',
+    });
+    dispatchDuration = meter.createHistogram('parall.dispatch.duration', {
+      description: 'Dispatch cycle duration in milliseconds',
+      unit: 'ms',
+    });
+    missingReplyCounter = meter.createCounter('parall.dispatch.missing_reply', {
+      description: 'Dispatches where agent produced text but sent no reply message',
+    });
+
+    initialized = true;
+    shutdownFn = async () => {
+      await tracerProvider.forceFlush();
+      await meterProvider.forceFlush();
+      await loggerProvider.forceFlush();
+      await tracerProvider.shutdown();
+      await meterProvider.shutdown();
+      await loggerProvider.shutdown();
+    };
+
+    return {
+      shutdown: async () => {
+        if (shutdownFn) await shutdownFn();
+      },
+    };
+  } catch {
+    return noopHandle;
+  }
+}
+
+export function startDispatchSpan(
+  event: ParallEvent,
+  runtimeType: string,
+  sessionKey: string,
+): Span | null {
+  if (!initialized || !tracer) return null;
+  return tracer.startSpan('parall.dispatch', {
+    attributes: {
+      'dispatch.target_type': resolveTargetType(event.targetId),
+      'dispatch.event_type': event.type,
+      'dispatch.runtime_type': runtimeType,
+      'dispatch.session_key': sessionKey,
+      'dispatch.message_id': event.messageId,
+      'dispatch.target_id': event.targetId,
+    },
+  });
+}
+
+export function endDispatchSpan(
+  span: Span | null,
+  metricsSnapshot: DispatchMetrics | undefined,
+  error?: unknown,
+): void {
+  if (!span) return;
+  if (metricsSnapshot) {
+    span.setAttributes({
+      'dispatch.deliver_text_chunks': metricsSnapshot.deliver_text_chunks,
+      'dispatch.deliver_text_chars': metricsSnapshot.deliver_text_chars,
+      'dispatch.message_send_attempts': metricsSnapshot.message_send_attempts,
+      'dispatch.message_send_successes': metricsSnapshot.message_send_successes,
+      'dispatch.no_reply_called': metricsSnapshot.no_reply_called,
+      'dispatch.tool_call_count': metricsSnapshot.tool_call_count,
+      'dispatch.duration_ms': Date.now() - metricsSnapshot.started_at,
+    });
+  }
+  if (error) {
+    span.setStatus({ code: SpanStatusCode.ERROR, message: String(error) });
+    span.recordException(error instanceof Error ? error : new Error(String(error)));
+  }
+  span.end();
+}
+
+export function recordDispatchMetric(
+  event: ParallEvent,
+  runtimeType: string,
+  durationMs: number,
+): void {
+  if (!initialized) return;
+  const attrs = {
+    target_type: resolveTargetType(event.targetId),
+    event_type: event.type,
+    runtime_type: runtimeType,
+  };
+  dispatchCounter?.add(1, attrs);
+  dispatchDuration?.record(durationMs, attrs);
+}
+
+export function recordMissingReply(runtimeType: string): void {
+  if (!initialized) return;
+  missingReplyCounter?.add(1, { runtime_type: runtimeType });
+}
+
+const sessionKeyStorage = new AsyncLocalStorage<string>();
+
+export function runWithSessionKey<T>(sessionKey: string, fn: () => T): T {
+  return sessionKeyStorage.run(sessionKey, fn);
+}
+
+/**
+ * Create a GatewayLogger that forwards all levels to OTLP logs.
+ * Two layers: "agent" (runtime) and "daemon".
+ */
+export function createOtelLogger(layer: 'agent' | 'daemon', prefix: string): GatewayLogger {
+  const ts = () => new Date().toISOString();
+  const emit = (severity: 'INFO' | 'WARN' | 'ERROR', msg: string) => {
+    if (!otelLogger) return;
+    const severityNumber =
+      severity === 'ERROR'
+        ? SeverityNumber.ERROR
+        : severity === 'WARN'
+          ? SeverityNumber.WARN
+          : SeverityNumber.INFO;
+    const attrs: Record<string, string> = { 'log.layer': layer, 'log.prefix': prefix };
+    const sk = sessionKeyStorage.getStore();
+    if (sk) attrs['session.key'] = sk;
+    otelLogger.emit({
+      severityNumber,
+      severityText: severity,
+      body: msg,
+      attributes: attrs,
+    });
+  };
+  return {
+    info: (msg: string) => {
+      console.log(`${ts()} [${prefix}] ${msg}`);
+      emit('INFO', msg);
+    },
+    warn: (msg: string) => {
+      console.warn(`${ts()} [${prefix}] ${msg}`);
+      emit('WARN', msg);
+    },
+    error: (msg: string) => {
+      console.error(`${ts()} [${prefix}] ${msg}`);
+      emit('ERROR', msg);
+    },
+    child: (sub: string) => createOtelLogger(layer, `${prefix}:${sub}`),
+  };
+}