Skip to content

ObneyAI/orc / orc-skills/orc-runtime-bootstrap

orc-runtime-bootstrap

Verified

Wire an ORC behavior-tree runtime for an experiment or application, choosing the event store, tenant processor, projection cache, provider, execution, and restart recovery. Use when starting a new ORC project or correcting its runtime setup.

Bootstrap an ORC runtime

Start with ORC’s tracked agent instructions and principles. Follow the consumer project’s own instructions if it provides them. Check the actual ORC and Grain revisions before copying setup code; the pinned example in runtime.md is a starting point, not an API freeze.

For a standalone project, use the reference's public Git deps.edn form and its two LMDB JVM options. Choose the lean projects/orc-service package for ordinary trees; add backend packages deliberately. Resolve and execute the setup in the application's own directory before claiming it works.

For mixed-family caps, checkpoint opt-out or old bounded resumes, read durable family budgets. Historical campaign-only counting is insufficient; verify the consuming implementation before relying on a total cap.

Decide the lifetime and concurrency first

For one application serving many independent users, read concurrent serving. It covers nonblocking admission, durable completion, scoped ownership and recovery. Parallel branches within one tree and multiple servers owning a tenant are separate contracts.

NeedStoreProcessor ownership
Disposable REPL/testGrain v3 :in-memoryOne standalone tenant poller
Durable single processGrain event-store-sqlite-v3, :database-fileOne standalone tenant poller
Multiple instancesGrain event-store-postgres-v3Grain control plane assigns tenant pollers

Use a real, stable UUID :tenant-id and carry it through every context and direct event-store read. Treat LMDB as a rebuildable projection cache, not the event store. Configure its capacity explicitly: the inspected Grain constructor defaults to only 10 MiB. The reference uses a configurable 1 GiB example and exposes reader slots separately; size for the reconstructed projection workload and verify actual map size/page highwater. LMDB map capacity, JVM heap and process resident memory are different measurements. Load the backend namespace to register its :conn type, and load ORC's public interface before starting pollers so its command, query, schema, and processor registrations exist. Provide a local pub/sub on the event store; distributed SSE also needs the event tailer.

Load application registrations, then start the store/cache and tenant poller. Decide periodic ownership separately: periodic/start-periodic-triggers! starts every registered trigger, using explicit :append-fn and :tenant-ids-fn capabilities. Retain schedule handles; namespace registration and poller startup do not start schedules. At ORC 1851212396cced2fc4533fda30b824bd4b691390, ordinary execution leases distinguish active work from abandoned executions. Keep schedules an explicit owned choice and verify restart/lease behavior in the consuming deployment; leases are not durable assessment jobs or external exactly-once guarantees. Put trusted code capabilities in the poller context as well as the caller context. On shutdown, stop schedules, await/cancel active ORC ticks and children, then stop poller, cache, store and pub/sub. See the reference for actual forms and partial-startup cleanup obligations.

Register the LLM provider with the application's litellm.router configuration and put its keyword in both the execution context and poller context. For ordinary llm nodes, omit :model to inherit that configured model or supply an actual provider model ID; an ordinary provider alias in :model becomes a literal request override. Native decision providers differ: register :protocol :decision and choose them per node using their registered names. Verify both paths through the serialized adapter request with orc-model-sio; a fake predictor does not verify model resolution. Use get-family-usage for descendant accounting.

Register providers and reconstruct trusted capabilities before starting workers that can consume persisted execution events. Protect every startup step with owned cleanup, including capture, MCP sessions and partially started runtime resources. Use each cleanup function's real arity; an install handle does not imply stop! accepts that handle. Verify startup failure unwinds only owned resources and that cleanup joins the actual tool/HTTP bodies before closing their stores.

Keep independent experiment stores isolated in memory as well as on disk. At the inspected Grain pin, the process-global projection L1 key includes read-model name/version, tenant and scope, but not store identity. New SQLite/LMDB paths with the same tenant in one JVM can still return prior state. Use a distinct tenant for each unrelated store or a fresh JVM; preserve the original tenant when reopening the same durable experiment. An empty-store projection check catches a contaminated harness before it can fake a result.

For cold readback, copy a quiescent SQLite source and any associated WAL/SHM before opening the copy. Check byte equality before first open; after startup, compare canonical event rows and the untouched original source hashes. The pinned SQLite backend runs ANALYZE, which can change the copy’s planner-statistics bytes without changing events. Keep the copy’s closure separate from the original runtime’s closure proof. See immutable readback.

Build child sheets before parents, then build each stable named workflow once at startup. build-workflow! is content-hash idempotent for unchanged definitions, but changing a definition under the same name rebuilds it. Execute through orc/execute with bounded timeout and, where needed, an LLM call budget. Check returned status and the durable tick/projection. Quiesce or cancel active ticks before shutdown; stopping the Grain worker pool does not join ORC's independently launched futures. Then stop poller before cache, store, and pub/sub. After a durable restart, recreate services and trusted capabilities against the same store. If automatic recovery is required, start the owned schedules and observe the original tick before any manual resume. Then use orc/resume-in-progress! to verify explicit recovery/idempotence. A successful terminal get-tick has {:status :completed :root-status :success}, while execute returns {:status :success}. Read :root-status for the tick’s behavior outcome. The live stream is ephemeral and cannot stand in for the event log. For a projection-rebuild proof, use a fresh JVM and fresh projection directory: Grain's process-global L1 survives ordinary runtime shutdown. Current ordinary delegates inherit family call budget/remaining time and tool context; conditions and supported native decisions use the shared budget path. Use a shared outbound attempt gate when a cap must count actual HTTP attempts across provider retries or unrelated roots. Acquire campaign ownership before loading a persisted attempt counter. Bound the actual tree and verify physical family call counts rather than treating the root budget as a total cap. Configure provider request, root, delegate and shutdown-drain timeouts, plus the result silence-grace threshold separately for the intended work; a REPL/MCP client wait timeout is another boundary. A terminal tick or cancellation request does not prove tool/model bodies have exited. Put a verified application quiescence gate inside shutdown before closing stores; keep resources needed by active work open if draining fails.

When implementation is needed, read runtime.md for verified API forms and public execution verification for startup, actual model visibility, tick lifecycle, automatic recovery, shutdown and immutable readback. Apply the relevant proof before claiming the runtime works. For command/read-model design, use orc-grain-application. For node values and traces, use orc-observe-debug.

Keep access checks executable: direct Grain command/query processors do not evaluate :authorized? metadata, and trusted claims alone do not guard a call. Use an enforcing adapter or explicit host/handler guard; the Grain reference shows complete UUID/offset-date-time envelopes and command → projection → query proof. Canonical values default to inline event storage; explicit file-store mode stores all values externally, with no size threshold or fallback, and needs a separately included backend.

Skill check

Try: “Create a disposable ORC experiment that runs one typed LLM sheet for tenant A, then make the same setup survive a single-process restart. Show how tenant B is isolated.” A satisfactory result selects in-memory and then SQLite; loads backend and ORC registrations; wires pub/sub, LMDB, poller, and provider; runs via public ORC APIs; reads a tenant-scoped projection/event trace; restarts against the same SQLite file; and proves repeated recovery does not create a second tick. No provider or production call is implied by this check.

Evaluation lifetime

For judge registration, asynchronous completion handling, durable evidence and owned cleanup, read orc-judges. Load evaluation registrations before the poller. At merged ORC 250de6e6de2ad95647ef6da4c69220c2bd631279, explicit attachments run without the Living Description flag and may target any existing sheet node; the flag gates default researcher judges. Native assessment requests/outcomes are durable, while their execution still uses process-local background futures. Managed GEPA has a separate task-ledger recovery path: restore custom metric registrations and capabilities before workers, load GEPA registrations, and explicitly own recovery schedules; see GEPA readiness. This source review does not establish automatic restart execution or bounded capacity for attached judges; timeout/cancel alone does not join model or judge bodies before closing the store.

Versioned family shutdown evidence

At the earlier inspected merge pin 1851212396cced2fc4533fda30b824bd4b691390, execution leases and shared budget admission were implemented, while a reproduced cancellation ordering/publication defect could leave a cancelled active child without its durable trace and root cancellation committed without prompt delivery. Reproduce before attributing that defect to a later checkout. Keep owned body draining and strict family readiness; a timeout/cancellation request is not proof of complete cancellation or joined work. Follow proof limits rather than disabling useful budgets or relaxing readiness.

Durable recursive researchers

Use orc-repl-researcher when the runtime includes adaptive researcher nodes. Enable real startup/periodic tenant recovery, reconstruct trusted process-local capabilities, and preserve the original campaign deadline/identity/budget. Configure JVM heap and projection cache independently. Epoch acceptance fences durable results; it does not guarantee instant stale-worker exit or once-only external provider spend. Use pattern reuse when adding ontology/ColBERT, explicit index readiness and deliberate background processor topology.

Follow application and model contracts before live admission

When the experiment adds domain commands, projections or queries, read orc-grain-application before declaring them, even in a disposable fixture. It covers generated-Var collisions, direct-processor authorization and effect concurrency boundaries; runtime wiring alone does not supply these contracts.

Before paid calls, compile the actual registered generation output contracts through the consuming SIO path. Mocking the ORC executor can prove tree control while hiding invalid provider schemas. On the documented strict repair stack, nested generated objects must explicitly declare :closed true. Use model contract preflight, then verify exact live requests and parsed writes.

Standard-node fallback revision

Configured fallback is integrated in merged ORC 4966c8e35e3bb5939570bfc645eac52a8d18eb6e, with its pinned SIO and client dependencies. Register every candidate provider in worker and recovery context before workers start. Configure :fallback-models and :fallback-policy on existing standard model nodes; no separate wrapper or consumer parser is required. Candidate configuration is retained with published workflows; sticky researcher selection belongs to one run/role and has saved-quantum recovery evidence. See configured model fallback for exact pins, budget/deadline and first-visible-output stream boundaries; historical local/open-PR checkpoints are not the current adoption status.

slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 196kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 192kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 192kUpdated Claude CodeCodexVerifiedInstall