Skip to content

CHANGELOG.md

Latest commit

 

History

History
48 lines (37 loc) · 10.5 KB

CHANGELOG.md

File metadata and controls

48 lines (37 loc) · 10.5 KB
Raw

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.

[Unreleased]

Added

  • Durable AI agents -- the Agentspan TypeScript SDK (@conductor-oss/conductor-agent-sdk) is merged into this package as new subpath exports: @io-orkes/conductor-javascript/agents (core: Agent, AgentRuntime, tool, guardrails, handoffs, memory, schedules, streaming, HITL), /agents/testing, and framework wrappers /agents/vercel-ai, /agents/langgraph, /agents/langchain. The agent clients are also first-class citizens of the root export (AgentClient, WorkflowClient, Schedule, ScheduleInfo, schedule errors) — the root surface grows additively (minor). Docs at docs/agents/; 60+ examples at examples/agents/.
    • Migration for @conductor-oss/conductor-agent-sdk users: install @io-orkes/conductor-javascript and rewrite import specifiers -- @conductor-oss/conductor-agent-sdk becomes @io-orkes/conductor-javascript/agents, and the wrapper subpaths gain the /agents prefix (e.g. .../vercel-ai becomes .../agents/vercel-ai).
    • New optional peer dependencies (all lazily resolved, install only what you use): zod, zod-to-json-schema, ai, @langchain/core, @langchain/langgraph. dotenv becomes a runtime dependency (the agent entry points load it at import time; the package sideEffects field allowlists dist/agents/** so bundlers keep that bootstrap).
  • Agent clients in sdk/clients, one client for both planes -- AgentClient is an interface (the /agent/* control-plane surface); OrkesAgentClient is the implementation, obtained via runtime.client or OrkesClients.getAgentClient(). Both share a single underlying ConductorClient (and its one token mint) across control-plane and worker-plane calls -- no bespoke agent-layer auth/transport code exists. Naming note: getWorkflowClient() returns the general-purpose WorkflowExecutor; the agent WorkflowClient (OrkesClients.getAgentClient().workflows / getAgentWorkflowClient()) adds the agent-execution 404 fallback and token-usage rollup.
  • AgentRuntime(configuration?, settings?) -- two independent, optional constructor arguments: configuration (connection/auth -- OrkesApiConfig or a pre-built ConductorClient, same env chain as every other Conductor client: CONDUCTOR_* -> explicit config -> AGENTSPAN_* fallback -> http://localhost:8080 default) and settings (behavior-only AgentConfigOptions: worker polling/threads, streaming, liveness -- no connection fields). AgentConfig carries only behavior now.
  • Verb contract -- serve(...agents, { blocking? }) now deploys (registers the workflow def, same as deploy) and serves in one call; { blocking: false } returns once deploy + worker registration + polling have started instead of blocking until SIGINT/SIGTERM. deploy(...agents) gained a variadic form (DeploymentInfo[]) alongside the existing single-agent deploy(agent, { schedules? }) form. AgentHandle/ClientHandle gained stop(). wait() (both handle flavors) now rejects once a deadline passes (timeoutSeconds-derived, or 10 min default) with an AgentAPIError naming the last known status, instead of polling forever.
  • RunSettings -- RunOptions.runSettings (model, temperature, maxTokens, reasoningEffort, thinkingBudgetTokens) applies per-run LLM overrides to run/start/stream without mutating the agent's own config; unset fields keep the agent's values and overrides don't cascade to sub-agents. RunOptions.model is sugar for runSettings.model.
  • Credentials via Task.runtimeMetadata, fail-closed -- the server resolves declared credentials at poll time and delivers them wire-only on the polled task's runtimeMetadata; the SDK injects them into the worker's process.env for the call (mutate-invoke-restore) and never fetches or persists them separately. A tool whose declared credential wasn't delivered fails non-retryably naming the missing name -- there is no ambient-env fallback. Requires a server that persists TaskDef.runtimeMetadata and delivers Task.runtimeMetadata (conductor-oss PR #1255 / agentspan server > 0.4.2); the CI matrix now runs the full agent e2e suite against both agentspan-server and the mainline conductor-oss boot jar.
  • Liveness monitoring -- for a stateful (domain-routed) run, a new liveness monitor polls the execution's workflow every livenessCheckIntervalSeconds (AgentConfigOptions.livenessEnabled, default true); a SCHEDULED/IN_PROGRESS task in that run's domain unpolled (pollCount === 0) past livenessStallSeconds (default 30s) rejects a blocking wait() with the new WorkerStallError instead of hanging forever. Framework-spawned agents (no per-run domain) are unaffected.
  • Swarm hand-off contract -- the per-tool {source}_transfer_to_{target} no-op worker now accepts an optional message string and echoes it back; the {agent}_check_transfer worker adds transfer_message (the winning transfer call's message) and, when an LLM turn emits more than one transfer call, dropped_transfers (with a warning identifying the honored vs. dropped targets) so a fan-out intent is never silently collapsed to one transfer.
  • SchedulerClient pause/resume works on both server families -- per-schedule pause/resume verbs differ by Conductor family (OSS/embedded map them PUT-only, Orkes GET-only). pauseSchedule/resumeSchedule now issue PUT first and retry via GET only on HTTP 405 (stateless per call; the new optional reason on pause survives the fallback). Previously the GET-only calls failed against OSS/embedded servers. Admin bulk endpoints are unchanged.
  • SchedulerClient typed agent-schedule lifecycle -- absorbed from the deleted agent ScheduleClient (below): save/get/listForAgent/pause/resume/delete/runNow/previewNext/reconcile operating on Schedule/ScheduleInfo with ${agent}-${name} wire-name prefixing and typed errors (ScheduleNotFound, ScheduleNameConflict, InvalidCronExpression). The constructor also accepts PromiseLike<Client> for callers with async client construction.
  • Canonical metrics -- opt-in harmonized metric surface via WORKER_CANONICAL_METRICS=true. See METRICS.md for the full catalog, configuration, and migration guide.
  • Bounded uri label on http_api_client_request_seconds: canonical mode uses path templates (e.g. /workflow/{workflowId}) instead of fully-resolved paths, preventing metric cardinality explosion from dynamic IDs.
  • TaskPaused event type and PollerOptions.onPaused callback: emitted when a poll cycle is skipped because the worker is paused. Canonical mode records task_paused_total; legacy mode does not (see Implementation Notes in METRICS.md).
  • measurePayloadSize option in MetricsCollectorConfig: controls whether workflow_input_size_bytes is recorded via JSON.stringify on each startWorkflow call. Defaults to true for canonical, false for legacy.
  • retryServerErrors option in OrkesApiConfig / RetryFetchOptions and CONDUCTOR_RETRY_SERVER_ERRORS env var: opt-in retry of HTTP 502/503/504 for idempotent methods (GET, HEAD, OPTIONS, PUT, DELETE). Default false; set to true to enable.
  • WorkflowStatusProbe in harness: opt-in probe (via HARNESS_PROBE_RATE_PER_SEC) that exercises UUID-bearing endpoints to validate template URI metrics.
  • WORKER_LEGACY_METRICS is reserved for future use. Once canonical metrics become the default, setting WORKER_LEGACY_METRICS=true will re-activate the legacy surface. It is not read by the current implementation.
  • resolveOrkesConfig (used by createConductorClient, and so every OrkesApiConfig-based client) gains an AGENTSPAN_* fallback tier for server URL and auth: CONDUCTOR_SERVER_URL -> explicit config -> AGENTSPAN_SERVER_URL -> default http://localhost:8080 (previously an unset server URL threw; it now defaults instead). Auth follows the same shape: CONDUCTOR_AUTH_KEY/SECRET -> explicit config -> AGENTSPAN_AUTH_KEY/SECRET.
  • createConductorClient()'s returned client gains getAuthenticationHeaders() (the same X-Authorization header the standard call path attaches, for transports that can't go through client.request, e.g. SSE -- borrows the client's TTL-aware token, mints/caches nothing of its own) and stopBackgroundRefresh() (stops the client's background token-refresh interval; previously that handle was captured locally and dropped, leaking the interval for the life of the process).
  • Logger env chain: DefaultLogger now also reads AGENTSPAN_LOG_LEVEL as a fallback when CONDUCTOR_LOG_LEVEL is unset.

Changed

  • Legacy metrics emit unchanged when constructing LegacyMetricsCollector directly (the pre-existing pattern). Using createMetricsCollector() additionally enables automatic HTTP request timing via OpenAPI interceptors for both legacy and canonical modes; no other action required for existing deployments.
  • MetricsCollector.ts renamed to LegacyMetricsCollector.ts; the public symbol is preserved via re-export so existing imports keep working.
  • http_api_client_request timing is now recorded automatically by wrapFetchWithRetry when a metrics collector is active (via createMetricsCollector() or setHttpMetricsObserver), covering both successful responses and network-error fallback paths. A lightweight request interceptor captures OpenAPI path templates so the canonical uri label uses bounded-cardinality templates in all cases. Previously, recordApiRequestTime existed but was not wired into the HTTP pipeline -- details.
  • Added optional durationMs field to TaskUpdateFailure event, recording the duration of the last update attempt. Declared optional so existing event listener implementations are unaffected.

Removed

  • Agent ScheduleClient and SchedulerFetcher (agents subpath; never released, no backward compatibility) -- schedules now ride the SDK SchedulerClient, re-exported from @io-orkes/conductor-javascript/agents. Method names and signatures are unchanged; migration is the import/type rename only (ScheduleClient -> SchedulerClient). The schedules.* namespace, runtime.schedulesClient(), deploy({ schedules }) and AgentClient.schedule() are untouched.

Deprecated

  • Legacy metric names remain the default during the transition period. Migration guidance is in METRICS.md.