Skip to content
Orbit Orbit Orbit

Activity / Job — Vision

Mirrored from docs/design/activity-job/3_vision.md. Edit the source document in the repository, not this generated page.

This document pressure-tests where the Activity / Job substrate may go next. It starts from the v2 runtime shipped across [T20260418-2010], [T20260418-2018], [T20260418-2143], [T20260418-2210], [T20260419-0104], and [T20260419-2156]. 2_design.md is the current contract; this file asks what should harden, collapse, or disappear.

1. Open Questions

Section titled “1. Open Questions”

1.1 How much of Activity / Job should remain public?

Section titled “1.1 How much of Activity / Job should remain public?”

README frames tasks, jobs, and activities as substrate. Should Orbit keep this layer mostly internal, with goals/sessions/locks as the API, or does a durable local system still need human-editable workflows?

1.2 Should target: grow beyond activity:<name>?

Section titled “1.2 Should target: grow beyond activity:<name>?”

TargetRef is namespace-prefixed, but only activity:<name> exists after [T20260418-2019]. Do nested job refs, subroutine refs, or cross-workspace refs help, or would they turn this layer into a generic workflow engine?

1.3 Is the provider model too closed-set?

Section titled “1.3 Is the provider model too closed-set?”

The schema names multiple providers, but the HTTP transport path is still effectively single-provider today. Do we keep the closed enum and wire each transport deliberately, or move toward a more explicit “provider capability” registry?

1.4 Should Orbit enforce tool allowlists on the CLI backend?

Section titled “1.4 Should Orbit enforce tool allowlists on the CLI backend?”

The gap from [T20260419-0104] is significant: HTTP enforces, CLI advises. Does backend: cli need a wrapper so tools: means the same thing everywhere?

1.5 Which limits should stay structural literals?

Section titled “1.5 Which limits should stay structural literals?”

task_auto_pipeline and task_epic_pipeline rely on literal max_workers and max_iterations. Should those stay static, or do we need templated numerics?

1.6 What is the right audit landing zone?

Section titled “1.6 What is the right audit landing zone?”

The v2 envelope from [T20260419-0002] makes runs traversable, but the full HTTP transcript still lives in the sibling loop sink. Should review converge on one query surface even if files remain separate?

1.7 How much more special-casing belongs in ActivityV2?

Section titled “1.7 How much more special-casing belongs in ActivityV2?”

Groundhog’s dedicated kind from [T20260420-0510-2] is justified today. If more modes arrive, do we keep adding variants, or is that a sign the abstraction is stale?

1.8 What should become the canonical reference corpus?

Section titled “1.8 What should become the canonical reference corpus?”

Seeded assets added in [T20260419-2347] and extended in [T20260419-0622-3], [T20260419-0623], and [T20260419-0623-2] already act as executable docs. Should they become the main reference set, or do we need smaller spec-only exemplars?

2. Prior Work

Section titled “2. Prior Work”

Activity / Job productizes familiar ideas. The interesting question is whether Orbit’s mix is local, inspectable, and agent-friendly enough to matter.

2.1 Durable workflow engines

Section titled “2.1 Durable workflow engines”
  • Temporal treats replay-safe orchestration and activity boundaries as first-class runtime concepts.
  • Argo Workflows and GitHub Actions show that human-authored YAML orchestration is still valuable even when higher-level product abstractions exist.
  • LangGraph has made durable, stateful control flow part of the mainstream agent-tooling vocabulary.

Activity / Job borrows the idea that orchestration must survive outside one model turn, but keeps the runtime local-first and repo-scoped.

2.2 Agent runtimes and tool loops

Section titled “2.2 Agent runtimes and tool loops”
  • Claude Code, Codex, Gemini CLI, and similar tools normalize the “agent loop plus tools” model.
  • OpenAI-compatible and provider-native HTTP APIs normalize direct transport-level loops.

Orbit’s difference is that a tool loop is one typed activity inside a durable runtime with local audit, policy, and job control-flow.

2.3 Policy-aware execution substrates

Section titled “2.3 Policy-aware execution substrates”
  • Sandbox and policy systems in CI/CD platforms establish the norm that execution policy is part of the runtime contract, not just ambient environment.
  • Agent harnesses frequently expose allowlists, but many treat them as soft guidance rather than a load-bearing runtime surface.

Orbit’s fsProfile attachment and the HTTP/CLI enforcement split make this concern explicit, even if the current behavior is still uneven.

2.4 Executable reference assets

Section titled “2.4 Executable reference assets”
  • Mature workflow systems almost always ship example pipelines, starter templates, or scaffolded defaults.

Orbit’s seeded activities and jobs from [T20260419-2347] are already more than examples; they are the closest thing to an executable spec corpus.

3. What May Be Distinctive

Section titled “3. What May Be Distinctive”

Soft claims only:

  • Load-time normalization as a public contract. Target-ref resolution, backend concretization, and loop/session rejection are part of what a job is, not just hidden parser details.
  • Backend choice separated from provider choice. Orbit treats backend: http|cli|auto and provider: ... as orthogonal schema fields, then makes mismatches explicit instead of silently recovering.
  • A two-layer audit tree tied to repo provenance. The v2 envelope from [T20260419-0002] gives runs, steps, activities, and workspace origin a stable skeleton while still preserving the underlying loop transcript and blobs.
  • Seeded workflows as load-bearing contracts. The shipped jobs from [T20260419-0622-3], [T20260419-0623], and [T20260419-0623-2] are not toy examples; they are how the control-flow substrate proves itself against real Orbit work.

None of these are research contributions. Activity / Job earns its keep only if it stays understandable, local, and inspectable while the product evolves.

4. References

Section titled “4. References”

Orbit-internal

Section titled “Orbit-internal”

External

Section titled “External”

Task References

Section titled “Task References”
  • [T20260418-2010] — Add the first v2 activity runtime scaffolding.
  • [T20260418-2018] — Add JobV2 DAG constructs (parallel, fan_out, loop, retry, when).
  • [T20260418-2019] — Add v2 activity name resolution and pipeline skeleton assets.
  • [T20260418-2143] — Wire V2RuntimeHost in orbit-core and add orbit activity run-v2.
  • [T20260418-2210] — Reshape V2RuntimeHost to keep orbit-agent types out of orbit-core.
  • [T20260419-0002] — Add workspace_path provenance to the v2 audit envelope.
  • [T20260419-0104] — Add backend: cli dispatch for v2 agent_loop.
  • [T20260419-0622-3] — Add task_gate_pipeline.
  • [T20260419-0623] — Add task_auto_pipeline.
  • [T20260419-0623-2] — Add task_epic_pipeline.
  • [T20260419-2156] — Retire v1 assets and drop the transitional v2 naming.
  • [T20260419-2347] — Seed activities and workflows on orbit init.
  • [T20260420-0510-2] — Add the Groundhog v1 activity runner.
  • [T20260430-19] — Shorten the Activity / Job design docs while preserving required structure.

Resolve any task above with orbit task show <ID> or git log --grep=<ID>.