kami/correx
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
8b6eedcf871bbf2c7d62047ac59bd5f0b83ffeaf
correx/docs/modules/core-tools-submodule-spec.md
T

6.3 KiB
Raw Blame History

name, description, depth, links
name description depth links
Core Tools Submodule Spec Specification for :core:tools – external side‑effect execution 2
../index.md
./core-module-spec.md
./core-approvals-submodule-spec.md

:core:tools module specification

version: 0.1-draft status: foundational specification

1. purpose

:core:tools defines the contract and orchestration model for external side‑effect execution (shell, git, filesystem, network, etc.).

It owns:

  • tool contracts
  • tool execution lifecycle
  • tool receipt model
  • sandboxing expectations
  • tool capability declarations
  • tool‑related events

All external side effects required by a stage are channelled through this module, ensuring they are auditable, replayable, and governed by approval tiers.

2. responsibilities

:core:tools owns:

  • Tool interface
  • tool execution lifecycle (prepare, execute, validate, receipt)
  • tool receipt schema (structured output of tool runs)
  • tool registration/capability mapping
  • sandboxing contracts
  • tool event definitions
  • deterministic replay guidance for tools

3. non-responsibilities

:core:tools MUST NOT own:

  • actual tool implementations (these live in infrastructure or plugins)
  • approval decisions (uses :core:approvals)
  • artifact generation directly (tools produce receipts, which may be wrapped into artifacts later)
  • UI for tool output viewing
  • persistence of receipts (events store does that)

4. architectural role

:core:tools acts as:

  • the gatekeeper for all side‑effects
  • the translator between model intentions ("run pytest") and validated, isolated executions
  • the owner of the tool audit trail

5. design principles

5.1 structured receipts only

Tool outputs must be typed. Raw text output is not allowed as a first‑class result. A receipt must include structured data (e.g., exit code, affected files, key metrics) in addition to a summary.

5.2 tier assignment

Every tool call has a tier (T0–T4). The tool itself declares its tier, and the approval subsystem checks it.

5.3 side‑effects are externalized

Tools mutate the outside world. The harness records what was done (receipt) and what was requested (invocation event), but never implies the world state changed exactly as intended—semantic validation compares receipts against expected changes later.

5.4 replay with simulated tools

During replay, actual tool execution is skipped; recorded receipts and events are replayed. For full replay or testing, deterministic mock tools can be used.

6. tool contract

interface Tool {
    val name: String
    val tier: ApprovalTier
    val requiredCapabilities: Set<ToolCapability>
    suspend fun execute(request: ToolRequest): ToolReceipt
    fun validateRequest(request: ToolRequest): ValidationResult
}

7. tool invocation lifecycle

  1. Model output (or stage config) contains a proposed ToolInvocation.
  2. :core:tools validates the invocation against the tool contract.
  3. Approval check (tier vs. session mode).
  4. If approved, tool executes in a sandboxed environment.
  5. A ToolReceipt is produced.
  6. Receipt is wrapped into a ToolResultArtifact for further validation.

8. tool receipt model

data class ToolReceipt(
    val invocationId: String,
    val toolName: String,
    val exitCode: Int,
    val outputSummary: String,
    val structuredOutput: JsonObject?,
    val affectedEntities: List<String>,
    val durationMs: Long,
    val tier: ApprovalTier,
    val timestamp: Instant
)

Structured output is mandatory for common tools but may be minimal for user‑defined tools.

9. event ownership

:core:tools emits:

  • ToolInvocationRequested
  • ToolExecutionStarted
  • ToolExecutionCompleted (with receipt)
  • ToolExecutionFailed
  • ToolExecutionRejected

All linked to the parent artifact or stage event.

10. consumed events

Consumes:

  • ArtifactProduced (may contain suggested tool calls)
  • ApprovalGranted (for tool execution)
  • StageScheduled (for pre‑defined tool sequences)

11. invariants

  • Receipts are immutable and append‑only.
  • No tool may execute without an approval event matching its tier.
  • Every tool execution is scoped to a session and stage.
  • Receipts are replayable without re‑execution.

12. replay semantics

During replay, tool execution events are replayed from history. If a tool is marked as non‑deterministic, its receipt is simply reused. Deterministic simulation may replay tool logic with the same inputs and compare receipts.

13. threading/concurrency

Tool execution is suspending and may use dedicated dispatchers. Long‑running tools are cancellable via the orchestration token. Concurrent tool executions within a stage are allowed only if explicitly configured and still serialized in event order.

14. failure semantics

Tool failures are captured in ToolExecutionFailed with structured error. They contribute to stage failure and trigger retry/recovery paths.

15. observable requirements

  • tool invocation counts
  • success/failure rates
  • execution duration
  • tier escalation frequencies
  • sandbox escape attempts (detected by policy)

16. security boundaries

Tools are the most dangerous part of the system. The module ensures:

  • sandboxing (via infrastructure) is enforced
  • network access is gated by tier
  • filesystem mutations are allowlist‑controlled
  • secrets are never exposed to tool input

All tool requests are inspected before execution against active policies.

17. extension model

New tools can be added as plugins implementing the Tool interface. They register their name, tier, capabilities, and execution logic. Plugins are sandboxed as much as possible.

18. forbidden patterns

  • tools that mutate event store directly
  • bypassing approval tier via hidden tool code
  • mutable receipts
  • tools that keep persistent state across invocations
  • tool output that is free‑form text without structured data

19. testing requirements

  • mock tool execution
  • tier enforcement
  • receipt validation
  • replay with recorded receipts
  • cancellation/timeout handling

20. philosophy

Tools are the harness’s hands, but the hands are clumsy and dangerous. This module ensures every grasp is planned, logged, and bounded, turning blunt instruments into precise, auditable actions.

Reference in New Issue View Git Blame Copy Permalink