ObneyAI/orc / orc-skills/orc-tools
orc-tools
VerifiedBuild and use ORC tools through authored tool leaves, guarded code callers, described catalogs, typed dynamic or finite arguments, recursive specialist chains and parallel actions. Use when selecting, invoking, composing or debugging tools, including researcher-generated tool nodes.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 15.2 KB |
| agents/openai.yaml | config | 249 B |
| references/bounded-workspace-acceptance.md | markdown | 4.0 KB |
| references/catalogs-and-arguments.md | markdown | 10.1 KB |
| references/current-invocation.md | markdown | 6.3 KB |
| references/current-proofs-and-limits.md | markdown | 9.6 KB |
| references/researcher-tools.md | markdown | 14.1 KB |
| references/tools-as-behaviors.md | markdown | 8.8 KB |
references/researcher-tools.md
View on GitHub# Researcher tools and generated code
For the recursive adaptive design/execution loop, use [orc-repl-researcher](../../orc-repl-researcher/SKILL.md). For described prior-pattern context and R-inject, use [researcher pattern reuse](../../orc-researcher-pattern-reuse/SKILL.md). This reference owns the tool binding seam.
Current boundaries were source-inspected at ORC `1851212396cced2fc4533fda30b824bd4b691390`; inspect the consuming revision's DSL, executor, SCI bindings and recursive tree compiler before using them. Researcher recursion is iterative design–execute–observe–refine. Nested hand-assembled delegates are a separate durable composition mechanism.
## Bind described capabilities
The public `repl-researcher` constructor accepts `:mcp-tools`, `:tool-contracts`, and `:tool-caller-fn`. Contracts map a bound name to `{:arguments <Malli schema> :result <Malli schema> :checkpoint-safe? <boolean>}`. The contract schema is closed and has no top-level `:description` slot at this pin. Put field descriptions in schema properties and supply capability purpose/applicability in model-visible inputs/instructions. Confirm the actual model input includes them. Missing contracts can become `:untyped`; legacy argument-name specs use `:any`, so do not treat those as adequate guidance for typed tools.
The sandbox wrapper binds allowed tool names and map/keyword argument forms. The common invocation seam now enforces declared Malli arguments before dispatch and results before return, preserving original values. Researchers receive safe structured failure data; the host still owns authority, tool-name allowlisting and domain completion. Missing contracts can remain permissive. Explicit purpose remains model-visible data/instructions because the contract record has no top-level description field.
### Handle failure at the invocation surface actually used
Named SCI tool functions catch exceptions and return data. A seam failure normally returns `{:error <safe message> :orc.tool/outcome :tool-error}` (or `:invalid-arguments`/`:invalid-result`); an exception without that marker retains `{:error <message>}`. A surrounding try/catch does not detect either returned map. Check these literal protocol fields before treating the observation as a valid tool result; preserve the discovered identity and successful observations, and retry only a permitted transient failed operation. Do not classify error prose with word lists or regex. Hosts must sanitize exceptions at their own boundary, especially the older error-only surface.
Generated code should use its injected three-argument `(call-tool-fn tool-name args tool-context)`. That caller can throw a host exception and fail the leaf; the next researcher turn can inspect and repair that failed child. A named SCI helper captured inside emitted code adds a different catch-to-data layer, so it must not be assumed equivalent. Verify the actual invocation, host receipt and returned/error shape.
When the same host caller also serves authored code, implement both the authored two-argument and researcher three-argument invocation surfaces against one guarded capability, preserving actual arguments/results. Close over trusted campaign authority and its original deadline; do not trust a model-supplied context to extend that deadline. Validate names, arguments, result schema and literal source/reference identity at the host boundary. A schema-valid result from the wrong source is still wrong.
Build model-visible construction guidance deliberately: [model-facing construction](../../orc-repl-researcher/references/model-facing-construction.md) shows complete local map schemas and quoted caller source. The authoring agent reading that page does not automatically provide it to the runtime model. Supply the relevant contracts and supported invocation forms in the actual researcher request, then inspect that request.
Do not finalize a data failure, coerce it to a false domain answer, or rerun successful discovery/retrieval to repair a later status check. A typed model judgment and an unavailable tool observation are different facts.
Public `dsl/code` and `dsl/tool` retain caller-builder and contracts. Generated child code/tool calls inherit authoritative parent contracts and configured gate; missing or invalid gates fail closed. Hand-assembled tools are ordinary actions, not a reason to introduce a researcher.
## Checkpoint and process boundaries
For an explicitly noncheckpointed, tool-context-free SCI host, the supported raw caller is two-argument `(tool-name args)`. If trusted nonnil `:tool-context` is supplied, `phase1-call-tool-fn` adapts named SCI calls to the host's three-argument surface. A three-argument-only host with no such context can fail before its body is entered, and a named tool returns that failure as data. A following form may still finish successfully if the program ignores it. Verify actual invocation counts, arguments and contracted tool results; do not count root success as proof that the action ran. This is a host setup distinction, not a model-specific calling convention. Keep the default checkpointed mode unless the application deliberately opts out.
Default recursive research is checkpointed. Bound tools must declare checkpoint safety and the caller must accept `(tool-name args tool-context)`. Treat this as a promise requiring host implementation: enforce operation identity, payload binding and deadlines. ORC does not make an arbitrary external action replay-safe merely because a boolean was set. Reconcile uncertain external outcomes before repeating a mutation.
`:mcp-session` and `:call-tool-fn` supplied to a tick are held in a process-local registry. They do not survive JVM restart. Persist serializable tool context where needed and reconstruct trusted capabilities when starting processors against the same store. Rebuild projections and resume the original in-progress tick rather than manufacturing a new tick. Preserve original identities. Generated child calls carry campaign effect identity/receipts. Do not assume every invocation surface synthesizes the same timeout fields: the inline researcher adapter supplies `:orc/timeout-ms`, while a real checkpointed generated-code trial did not receive that field. Its child wrapper merges supplied/application context plus effect identity and iteration. Bound the host operation itself, derive/enforce remaining time through the trusted application capability where available, and verify the actual context. The host must honor provided identity, original payload and effective deadline; uncertain external effects still require reconciliation.
## Generated code is not a durable registered tool
Each researcher iteration starts a fresh SCI context; retained sandbox values are not arbitrary retained function definitions. A generated `defn` does not register a permanent application capability. Inline functions executed in child trees have temporary registry identities and are cleaned up; qualified host function names resolve through the JVM. For checkpointed `emit-tree!`, use quoted function source, not an evaluated closure. This supplies reconstructible source but does not prove restoration of every original in-flight function handle: a real fresh-JVM trial failed that original leaf before a new generated continuation repaired the task. Inspect [current source/recovery status](../../orc-repl-researcher/references/source-status.md) and prove the exact restart frontier.
The inspected emitted vector DSL accepts `:sequence`, `:parallel`, `:llm`, `:code`, `:map-each`, `:chunk-document`, `:aggregate`, and `:final`. It does not accept emitted `:delegate`, `:fallback`, `:condition`, or `:repl-researcher`. Sandbox helper APIs and the hand-assembled public DSL are different surfaces; similarly named functions or older docs do not widen the compiler's accepted palette.
Use generated code for deterministic processing/composition of actual observations where iteration needs it: joining by IDs, computing arguments, aggregating results or preparing a generated action subtree. Keep semantic judgments in suitable models. Execute in the supported sandbox with bounded resources, injected capabilities and explicit outputs. [CodeAct](https://arxiv.org/html/2402.01030v4) informs compositional code actions and feedback-driven correction; [Voyager](https://arxiv.org/html/2305.16291v2) illustrates verification before reusing executable skills. These are research patterns, not ORC API or safety guarantees. Promotion to a durable tool requires an explicit reviewed implementation, schema, description, effect authority and regression proof; generated success in one run is insufficient.
At the inspected revision, a code leaf with `:writes []` fails output reconciliation even when its function returns `{}`. Construction alone does not reveal this restriction. Give validators/actions a concrete described boolean completion write or domain receipt, return it under the exact declared key, and test the downstream consumer through a real tick. This is a current code-output restriction; it does not prevent tools from working recursively.
The earlier generated-child probe at ORC `490816267b76b0428c53437052980a25f5905209` lacked inline effect identity/deadline metadata. That is historical evidence, not current guidance. At the merged revision, generated `code`/`tool` calls inside a checkpointed campaign participate in claim/receipt handling. Use a three-argument host caller and checkpoint-safe contracts. Verify completed effect reuse, context and reconstruction through public boundaries; this does not guarantee exactly-once external mutation across the uncertain effect/receipt window.
## Verify the complete loop
Inspect the advertised contracts and descriptions at the actual model boundary, host received args, accepted/rejected results, phase/child events, generated source, final typed outputs and domain projections. Prove a dependent chain with a runtime-only source ID, malformed proposal feedback and bounded repair, and a quoted transformation reconstructed in a fresh process without repeating a completed effect. Distinguish scripted model responses from live model behavior and same-process resume from genuine JVM reconstruction. Store model artifacts verbatim; store allowlisted transport errors without auth. Report any unsupported recovery seam explicitly.
Name the actual capability boundary in the evidence: local injected caller, real MCP adapter/RPC, or external service. A configured `:mcp-tools` name can be served by a host callback. To establish MCP transport, retain initialization, advertised catalog and actual tools/call request/response IDs, then correlate them with host receipts and canonical node execution. A catalog-only session proves availability; it does not prove that a generated tree invoked the server.
Historical controlled live calls at ORC `490816267b76b0428c53437052980a25f5905209` demonstrated discovery → retrieval of its runtime-only reference → recording through a command → quoted generated computation → finalization. Acceptance independently compared the calculated value, record identity/content, root/child writes and actual function registration/execution/cleanup. A scripted negative case returned a schema-valid wrong value without generating a child; ORC success alone accepted it, while the consumer acceptance checks rejected it. Put the application's useful completion check in its executable control or delivery boundary, rather than relying on a prompt or valid schema.
A historical deterministic crash proof at ORC `490816267b76b0428c53437052980a25f5905209` stopped after a generated child and its checkpoint were durably committed. A fresh JVM resumed the **same unfinished root tick** with only the remaining final turn, no repeated tool calls and one unchanged domain fact. It then compiled the publicly stored quoted source into a new child with different temporary function IDs. This proves continuation at that completed-child frontier and compilation of preserved source into a new child. It does not establish restoration of an original unfinished callable or recovery after an external service accepts a mutation before its receipt is recorded. The latter still needs the callee reconciliation contract described above.
Source anchors under `components/orc-service/src/ai/obney/orc/orc_service/`: `core/dsl.clj` (`code`, `repl-researcher`); `interface/schemas.clj` (`tool-contracts`); `core/executor.clj` (`bound-tool-contracts`, Phase 1 inputs, caller binding, checkpoint path); `core/sci_sandbox.clj` tool wrapper; `core/rlm_sandbox.clj` `emit-tree!`; `core/rlm_dsl.clj` emitted palette; `core/rlm_tree_executor.clj` temporary function lifecycle; `core/runtime.clj` caller registry. Read the target source rather than relying on line numbers from another revision.
For the new real MCP test and the difference between successful tool execution and failed semantic task completion, read [current proofs and limits](current-proofs-and-limits.md). The original test failed its answer-quality assertion; a separately guided consumer passed. Keep these separate from the historical reconstruction proofs above.
## Observe host invocation, effects and admission separately
Keep a journal of every caller invocation, a separate journal of actual dispatched effects and explicit receipt hits. A host cache can prevent repeated external work while concealing that the researcher invoked a completed tool again. Require canonical engine receipt evidence and both journals when proving focused repair or process recovery.
Enforce the trusted original deadline before admission and again after any concurrency or session wait, immediately before effects. Bound actual RPC/read bodies and join their owning process/executor on failure; abandoning a waiting future is not cleanup. Verify allowed tool identity, tenant/claims, argument/result schema and relational source/reference authority in the actual host boundary. Contract metadata does not perform authorization.
Measure concurrency at the claimed boundary. Overlapping host invocations can wait behind one serialized MCP session; highwater2 does not prove simultaneous MCP requests or remote authority work. Record host admission/effect intervals and actual MCP request/response/server evidence separately. Use compatible bounded parallel capabilities where the task benefits; retain complete identity joins.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| add-product-e2e-evalpaperclipai/paperclipAdd or extend a Paperclip full-stack runner E2E workflow, fixture, matcher, or report evidence path for local or Daytona execution. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| add-runner-evalpaperclipai/paperclipAdd or extend a Paperclip Runner protocol evaluation definition, roster, assertion, or report fixture with provenance and narrow validation. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| diagnose-why-work-stoppedpaperclipai/paperclipCompatibility entry point for failed, stalled, looping, or over-recovered Paperclip work. Use fix-failed-paperclip-run for the full diagnosis, regression, repair, real verification, and green-PR workflow; honor an explicitly requested diagnosis-only scope. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |
| fix-failed-paperclip-runpaperclipai/paperclipDiagnose and fix failed, stuck, slow, or incorrectly blocked Paperclip tasks and runs. Use with a task/run URL or failure report to trace the root cause, prove a regression red then green, check second-order effects, verify the real workflow, and deliver a PR with passing checks. | Stars: 115k | Updated | Claude CodeCodex | Verified | Install |