temporal

Overview ¶

Package temporal implements the loom-mcp workflow engine adapter backed by Temporal (https://temporal.io). It satisfies the generic engine.Engine interface, allowing generated code and the runtime to orchestrate durable workflows without importing the Temporal SDK directly.

Why Temporal? ¶

Temporal provides durable execution for long-running agent workflows. When an agent makes multiple tool calls, awaits human input, or runs for extended periods, Temporal ensures the workflow state survives process restarts, network failures, and crashes. The runtime replays the workflow from event history, producing deterministic execution.

Constructing an Engine ¶

Worker processes use NewWorker to create an engine with Temporal client and worker options:

eng, err := temporal.NewWorker(temporal.Options{
    ClientOptions: &client.Options{
        HostPort:  "temporal:7233",
        Namespace: "default",
        // Required: enforce loom-mcp's workflow boundary contract.
        // Tool results/artifacts cross boundaries as canonical JSON bytes (api.ToolEvent/api.ToolArtifact),
        // and planner.ToolResult is rejected if it ever tries to cross a Temporal boundary.
        // Pass the generated tool specs aggregate for the agent(s) hosted by this runtime.
        // Example: specs "<module>/gen/<service>/agents/<agent>/specs"
        // DataConverter: temporal.NewAgentDataConverter(specs.Spec),
    },
    WorkerOptions: temporal.WorkerOptions{
        TaskQueue:              "orchestrator.chat",
        MaxConcurrentActivities: 10,
    },
})
if err != nil {
    log.Fatal(err)
}
rt := runtime.New(runtime.WithEngine(eng))
// Register toolsets first, then agents.
if err := rt.Seal(context.Background()); err != nil {
    log.Fatal(err)
}
defer eng.Close()

Client-only processes use NewClient and do not register local workflows or activities:

eng, err := temporal.NewClient(temporal.Options{
    ClientOptions: &client.Options{
        HostPort:  "temporal:7233",
        Namespace: "default",
    },
})
if err != nil {
    log.Fatal(err)
}

Worker vs Client Mode ¶

Worker mode polls task queues and executes workflows locally. Client mode submits workflows without local execution.

Registration sealing is part of the worker-mode contract: the runtime must seal registration only after all toolsets and agents have been registered so polling begins from a coherent local registry.

Workflow Determinism ¶

Temporal workflows must be deterministic: given the same inputs and event history, they must produce the same outputs. This package provides a WorkflowContext that exposes only deterministic operations:

• Now() returns workflow time (not wall clock)
• PublishHook schedules hook publishing outside the workflow thread
• ExecutePlannerActivity runs planner activities
• ExecuteToolActivity/ExecuteToolActivityAsync run tool activities
• PauseRequests/ResumeRequests/... return typed signal receivers
• StartChildWorkflow starts nested workflows

Planners and tool executors run inside activities, which are not constrained by determinism. The workflow handler (generated code) coordinates activities and processes their results deterministically.

OpenTelemetry Integration ¶

The engine emits traces using a "trace domains" contract:

• Synchronous request handling (HTTP/gRPC) stays within a single trace tree.
• Durable scheduling (Temporal) creates a new trace tree per activity execution and links it back to the initiating request trace via OTel links.

This avoids long-lived traces that fragment in collectors/sampling pipelines while preserving navigability across domains.

Query Handlers ¶

Workflows can expose query handlers for external introspection. The runtime uses queries to retrieve run status and transcript state without blocking workflow execution.

Package temporal implements the engine.Engine adapter backed by Temporal. It registers workflows and activities, manages per-queue workers, starts executions, and exposes workflow handles for waiting, signaling, and cancellation. The adapter wires OpenTelemetry tracing/metrics and keeps Temporal-specific worker lifecycle inside this package.

Package temporal isolates workflow-handle and signal/cancel helpers so the engine's main file can focus on registration and workflow start semantics.

Package temporal keeps OpenTelemetry wiring separate from the engine's core registration/start path so the adapter can own one instrumentation contract without burying it in worker and workflow plumbing.

Package temporal keeps read-only workflow query helpers separate from the engine's write path. These methods translate Temporal-specific visibility and completion state into the smaller engine contract consumed by the runtime.

Package temporal keeps search-attribute typing at the adapter boundary. The shared runtime contract stays generic (`map[string]any`), and only this file decides how those values map onto Temporal visibility types.

Package temporal keeps worker lifecycle isolated from the engine's public API. Worker-mode engines stage queue handlers during registration and start polling only after the runtime seals registration.

Package temporal contains the loom-mcp Temporal engine adapter.

This file defines the Temporal-backed implementation of engine.WorkflowContext. The runtime uses it to: - execute typed planner/tool/hook activities with engine-owned defaults, - access deterministic time/timers and workflow cancellation, - receive external signals in a replay-safe way, - start child workflows by explicit name and queue.

Contract:

• Activity option defaults are resolved by name and merged with per-call overrides.
• Temporal cancellation errors are normalized to context.Canceled for runtime-wide classification that does not depend on Temporal types.