DEV Community: tercel

Make Your Agent's Shell Governed: apexe in Practice

tercel — Sat, 07 Nov 2026 01:40:58 +0000

A previous post described how to give a coding agent a governed CLI workflow: initialize contracts, review policy, preview a call, then execute. That workflow works, and it has one weak joint.

The workflow depends on the agent choosing to follow it. A Skill is a document. If the agent skips it, nothing in the system notices.

apexe 0.10.0 closes that joint with three commands: apexe sh (and the installed apexe-sh launcher), apexe agent , and apexe hook claude. The integration now lives where the host actually decides what to run.

This post takes one host from zero to verified, then shows how to widen coverage without pretending the boundary is bigger than it is.

The gap, in one sentence
Governance is only as good as the code path the command must pass through. For a terminal agent, that path is the host's shell invocation. So you either replace the shell, pre-tool every call, or leave enforcement to the model's goodwill.

apexe now supports the first two.

Install, initialize, review Use a prebuilt binary or build from source; then prepare coverage:

apexe init
apexe list --verbose
init acquires the configured rules source, matches installed commands and their variants, and writes bindings plus a starter ACL. Review ~/.apexe/acl.yaml before you go further: generated allow rules are suggestions, not your policy.

Read the init report too. native_ready tells you which routes have reviewed native grammar. The reviewed pilot is small on purpose — BSD cat, head, and ls. If your installation reports nothing else there, that is expected, not a bug.

Turn on the launcher, then read the report apexe env --enable source ~/.apexe/bin/apexe-activate.sh apexe sh --check env --enable installs the PATH shims, the activation helpers, the startup block for your shell, and the stable apexe-sh entry point. apexe-sh is what a host points at when it only accepts a shell path.

apexe sh --check is the part people skip and then regret. It reports:

the real shell it will exec, and the entry point it found
the shim manifest and ACL state — a missing ACL is a warning, because shim-routed commands would then run without access control
the local environment policy and the dynamic-loader denylist (LD_PRELOAD, LD_LIBRARY_PATH, DYLD_*)
verified routes and scanned routes, listed separately
bindings that exist but were excluded from shims, each with its exclusion reason
host snippets for OpenCode, pi, Codex, and Claude Code
Two lines in that report decide your next step. If the ACL is missing, stop and load one. If a command you need appears under exclusions, the reason string tells you which reviewed fact is absent — coverage gaps are visible before you widen anything.

For machine checks, apexe sh --check --format json gives you the same data in CI.

Wire one host Print first, write second:

apexe agent opencode
apexe agent --check opencode
apexe agent opencode --write
--write merges into existing JSON atomically, preserves other keys, and refuses a file that is not valid JSON. For OpenCode and pi it also refuses when apexe-sh is not installed. That refusal is the point: both hosts start every command through that path, so a missing launcher does not fall back to the system shell — the host simply fails to run anything, and you get an EACCES that names nothing useful.

The four hosts are four different integrations. Do not assume one recipe:

Host What you configure Thing to know
OpenCode shell = absolute apexe-sh path Its shell tool invokes apexe-sh -c ""
pi shellPath = apexe-sh Exports APEXE_SHELL_DEPTH=1 to nested shells
Codex Login-shell PATH activation Rejects apexe-sh as its shell; zsh activation now writes .zprofile too, so noninteractive login shells resolve shims
Claude Code PreToolUse hook, or PATH at launch Rejects apexe-sh as SHELL/CLAUDE_CODE_SHELL and falls back to /bin/zsh
Codex deserves one extra note: apexe agent codex --write has no shell file to edit, so it runs apexe env --reload --shell zsh instead. Upgrade an existing installation the same way, then restart the host.

Claude Code: hook instead of shell
apexe hook claude
Configure it as a PreToolUse hook matching Bash. A simple external command is rewritten to apexe sh -c '' through updatedInput; commands already routed through apexe are left alone, so the hook does not recurse.

Builtins that change session state (cd, export, set, alias), pipelines, redirections, and compound commands are not rewritten — a one-shot apexe sh -c cannot preserve their semantics. Those keep relying on the installed PATH shims. If the shim manifest is missing, the hook denies the call and tells you to run apexe env --enable.

apexe hook claude --persistent is the experimental answer to that limitation: it routes every Bash call through one detached governed session that preserves cwd, variables, functions, and aliases, scoped to the host session id and project directory, with an idle timeout and an explicit stop. Try it on a project you can afford to re-run.

Verify from inside the agent Ask the agent to run:

command -v ls
apexe exec -- ls -la
command -v ls should print the shim path under ~/.apexe/bin/, and ~/.apexe/audit.jsonl should gain an execution record. If command -v still points at /bin/ls, the host is not using your launcher — check apexe agent --check before touching anything else.

This is also the honest test of "did I enforce anything": if the agent can still reach /bin/ls with PATH intact, you widened convenience, not a boundary.

Widen coverage on purpose Your shims cover reviewed routes. Everything else has a binding but no reviewed grammar, which is most of a real machine.

0.10.0 lets you admit those bindings explicitly:

apexe env --enable --scanned readonly
apexe sh --check
A scanned route parses and validates the caller's argv against the scanned schema, then executes the original argv. It never rebuilds or reorders your command line. Every such execution is audited with tier: scanned.

Three properties to keep straight:

readonly admits only readonly, non-destructive, closed-world modules. all admits any current binding — use it after reading the bindings, not before.
Schema inference is not a reviewed contract. Path-guard coverage for arguments the scanner did not type can be incomplete.
--scanned lowers the grammar bar for declared routes; it cannot widen the set. A route an overlay left out stays out.
Trust is now stamped per route (metadata.grammar), which changes what a partial overlay buys you. A mode: merge overlay that fully covers one route makes that route reviewed while its siblings stay closed. Before this release, a git-shaped tool needed a tool-wide authoritative overlay, which erased every subcommand — there was simply no usable path for git.

Audit what your overlays left behind:

apexe list --diagnostics
You get the closed routes per overlay, and — when a policy is loaded — ACL grants that match no loaded module. The second list is usually a scan artefact, and it is the only place those dead permissions are visible without reading acl.yaml by hand.

Know exactly what you bought Two trust decisions are baked into 0.10.0 and both are worth saying out loud.

Local execution now inherits your environment. apexe sh, PATH shims, and native apexe exec pass the caller's environment to the child so GH_TOKEN, AWS_PROFILE, KUBECONFIG, and SSH_AUTH_SOCK keep working. Only dynamic-loader variables (LD_PRELOAD, LD_LIBRARY_PATH, DYLD_*) are stripped. Captured execution — MCP, A2A, module JSON — still clears the environment and passes a small allowlist. So: a locally governed tool runs with your credentials. That is a deliberate trust decision, and it is not isolation.

Approval is now answerable. A route marked requires_approval prompts on the controlling terminal and reads y/yes with a bounded wait. A non-interactive process is refused with a remedy instead of hanging. MCP keeps its client-based elicitation path; A2A approval stores remain a library integration.

And the boundary itself:

apexe sh --locked --allow-path /usr/bin -c 'ls'
--locked restricts PATH to the shim directory plus explicit --allow-path entries. It reduces accidental discovery of ungoverned binaries. It is not a sandbox: absolute paths, builtins, functions, sudo, and interpreter-internal execution still work. APEXE_SHELL_LOCKED and APEXE_SHELL_ALLOW_PATH apply the same setting to apexe-sh, which forwards every argument to the real shell.

apexe-sh changes command lookup order. Commands with a reviewed shim are governed; everything else is not. Pair it with the account, container, or VM boundary your workload needs, and read the threat model.

Three fixes you will feel on day one git -v and git status -v no longer collide. The argv parser kept one flat flag-spelling map per module, so one spelling reused on both sides of a subcommand made every route of that tool fail before a single argument was read. Tool-level spellings now live in their own namespace and resolve by the side of the subcommand the token appears on. Git-shaped tools became usable.

x-apexe-exec is enforced on scanned routes. A scanned route replays the caller's argv, so a value like git -c core.pager= never reached the exec-parameter rejection and ran as a command. The check now runs on the parsed input both tiers produce — which matters precisely because the scanned tier exists.

A refusal names the route you asked for. Routes are validated when selected, not before matching, so a sibling without reviewed grammar no longer fails your command, and the message says Route '' instead of blaming whichever module sorted first.

There is one recovery path worth knowing if you deploy on shared machines: apexe env --enable --replace-unowned regenerates the reserved entry point and activation helpers when the ownership record is gone. Without it, a lost ~/.apexe-shims.json left the installation unrecoverable except by deleting files by hand. --reload and --disable also read that record first, so --disable now warns when a host still points at the entry point it just removed.

Troubleshooting
Symptom Likely cause
Host cannot run any command, EACCES, nothing mentions apexe apexe-sh is not installed; run apexe env --enable, then apexe agent --check
command -v ls shows /bin/ls Host is not using the launcher, or a login shell rebuilt PATH; use the managed startup block
Codex runs ungoverned commands zsh login shells read .zprofile; run apexe env --reload --shell zsh and restart
Claude Code ignores the shell It rejects apexe-sh as SHELL; use the hook or start it with the shim directory on PATH
A command you need is not shimmed apexe sh --check lists it with the exclusion reason; cover that route in an overlay or widen with --scanned readonly
A 2.0 overlay does not validate Expected — commands[] and global_flags are a preview this build accepts; the published schema still pins 1.0/1.1
Close
The interesting shift is not that apexe gained three subcommands. It is that "the agent follows the policy" stopped being an assumption. Configure one host, run apexe sh --check, then try to make an ungoverned command slip through — that exercise tells you more about your setup than any feature list.

apexe init
apexe env --enable
apexe sh --check
apexe agent --check
apexe agent --write
Repository: github.com/aiperceivable/apexe · Apache-2.0 · Shell integration guide · Threat model

Which host are you wiring up first — and which command did you decide to leave ungoverned on purpose?

Demystifying the MCP Protocol for Open Source AI

tercel — Fri, 06 Nov 2026 01:44:56 +0000

The MCP protocol is the connective tissue for many open source AI workflows—yet is often treated as a black box. Here’s a developer’s-eye primer on why MCP matters, how it relates to A2A and CLI adapters, and where runtimes like apcore step up to fill governance, audit, and multi-protocol gaps.

MCP defines how an agent or model can discover, describe, and invoke remote tools. Classic “bare server” MCP implementations give you a surface, but they don’t enforce validation or traceability. Projects aiming for responsible agent development are increasingly layering governed runtimes that check schemas, approvals, and usage evidence before anything is exposed to MCP or A2A.

For open source maintainers: are your agent-facing modules only protocol-compliant, or are they governable, testable, and ready for enterprise calls? With apcore’s multi-language SDKs and standard contract enforcement, you can bridge to MCP or A2A with confidence—and reduce your incident response exposure.

Build a Python Workflow That AI Agents Can Discover with APFlow

tercel — Mon, 26 Oct 2026 11:58:02 +0000

Let's build a small workflow that reads two regional request counts and combines them into one report. Along the way, we'll see how APFlow separates workflow structure from execution order and registers Python functions as capabilities that can be exposed to agents.

The example uses local sample data and SQLite. You can run it without a model provider or an API key.

APFlow is an open-source Python orchestration engine. It embeds the apcore module standard, giving registered capabilities descriptions and schemas that adapters can expose through MCP, A2A, REST, and CLI.

Use Python 3.11 or newer. Clone the repository and install APFlow in a virtual environment:

git clone https://github.com/aiperceivable/apflow.git
cd apflow
python -m venv .venv
source .venv/bin/activate
python -m pip install -e .
The activation command above is for a Unix-style shell.

Define the two relationships
All three tasks belong to one report:

Structure tree:
report
├── north
└── south

Execution dependencies:
north ──┐
├──> report
south ──┘
parent_id expresses membership in the report. dependencies makes the report wait for both regional results. A structural parent can therefore execute after its children when its dependencies require it.

The two regional tasks have no dependency on one another, so the engine can schedule them concurrently.

Register functions and run the graph
Save the following as workflow_demo.py in the cloned repository. The Pydantic models describe the capability inputs and business outputs. Functions receive input dictionaries; the decorator uses the models for their schemas.

import asyncio
import logging
from typing import Any

from pydantic import BaseModel, Field

from apflow.adapters.function_executor import function_executor
from apflow.app import create_app

class MetricInput(BaseModel):
region: str = Field(pattern="^(north|south)$")

class MetricOutput(BaseModel):
requests: int

class SummaryInput(BaseModel):
north: MetricOutput
south: MetricOutput

class SummaryOutput(BaseModel):
total_requests: int

@function_executor(
id="sample_metric",
description="Read a sample request count for one region",
input_model=MetricInput,
output_model=MetricOutput,
)
async def sample_metric(inputs: dict[str, Any]) -> dict[str, int]:
counts = {"north": 12, "south": 18}
return {"requests": counts[inputs["region"]]}

@function_executor(
id="summarize_metrics",
description="Combine request counts from north and south",
input_model=SummaryInput,
output_model=SummaryOutput,
)
async def summarize_metrics(inputs: dict[str, Any]) -> dict[str, int]:
total = inputs["north"]["requests"] + inputs["south"]["requests"]
return {"total_requests": total}

async def main() -> None:
app = create_app(connection_string="sqlite:///:memory:")
tasks: list[dict[str, Any]] = [
{
"id": "report",
"name": "Regional report",
"params": {"executor_id": "summarize_metrics"},
"dependencies": [{"id": "north"}, {"id": "south"}],
},
{
"id": "north",
"name": "North request count",
"parent_id": "report",
"params": {"executor_id": "sample_metric"},
"inputs": {"region": "north"},
},
{
"id": "south",
"name": "South request count",
"parent_id": "report",
"params": {"executor_id": "sample_metric"},
"inputs": {"region": "south"},
},
]
try:
tree = await app.task_creator.create_task_tree_from_array(tasks)
await app.task_manager.distribute_task_tree(tree)
app.session.expire_all()
report = await app.task_repository.get_task_by_id("report")
assert report is not None
assert report.status == "completed"
assert report.result == {"total_requests": 30}
logging.info("Report completed: %s", report.result)
finally:
app.session.close()

if name == "main":
logging.basicConfig(level=logging.INFO)
asyncio.run(main())
Run it:

python workflow_demo.py
Among the execution logs, you should see:

Report completed: {'total_requests': 30}
The assertions also verify the persisted status and business result. The example uses an in-memory database, so its records last for this process.

Follow the dependency data
APFlow injects each dependency's stored business output under its task ID. Here, summarize_metrics receives inputs["north"] and inputs["south"].

The function returns {"total_requests": 30} as business data. The function decorator handles the executor result envelope, and the task repository stores the business payload in task.result.

This distinction becomes useful when an executor also reports usage or a structured execution error. Those values have their own execution metadata rather than becoming fields that every downstream business function must unpack.

Inspect the capability contract
Because the decorators run before create_app(), the app's registry discovers the custom executors. Inside main(), you can inspect one definition:

definition = app.registry.get_definition("apflow.sample_metric")
assert definition is not None
logging.info("Input contract: %s", definition.input_schema)
For a server deployment, import your executor module before building the application's registry. A separate apflow serve --all process needs its own executor loading configuration; it does not inherit functions from this completed script.

You can explore APFlow's built-in HTTP interface independently:

apflow serve --all
In another terminal:

curl http://localhost:8000/modules
The unified server also provides /docs, /a2a, and /mcp. Custom modules loaded into that server become available through its configured adapters and policies.

Move from a local example to an operated workflow
This script demonstrates local execution, dependency injection, and capability registration. Background execution uses the separate durable submission contract: create definitions with an idempotency key, submit the root, and inspect persisted status.

REST and unified servers run a dispatcher. Standalone MCP, A2A, and CLI submission need one connected to the same database. For recovery, run.retry creates a new Run; submit its new root explicitly. Confirmed completed results can be reused while the original history remains available.

For a personal project, replace the sample metrics with one useful integration and keep the graph small. For a team, use a representative reporting or document-processing workflow to evaluate identity, failure recovery, and consumption reporting. Shared token scopes require participating executors to declare and enforce consumption bounds.

APFlow remains classified as Alpha. Start with a workflow whose outcomes you can verify, then add remote side effects and provider integrations deliberately.

The APFlow repository has the source and examples. See the current durable submission guide for the next step. If you try this example, open an issue with the integration you want to build, and star the repository to follow its development.

Consolidating Governance Across MCP, HTTP, CLI, and A2A

tercel — Thu, 22 Oct 2026 09:32:17 +0000

Most teams already have multiple ways to reach the same operations:

REST / HTTP APIs
CLIs and scripts
internal RPC or message‑bus flows
a2a integrations via SaaS tools
now: MCP or other agent tool protocols

Each surface tends to evolve its own auth, ACL, and logging story.

That’s painful even before you add AI agents. Once agents are involved, inconsistent governance becomes a hard blocker.

A more durable architecture is to consolidate governance in a protocol‑neutral capability runtime, and let all surfaces become adapters.

Define capabilities once

Create a runtime‑owned catalog where each capability has:

a stable ID
an input/output schema
an owner and risk classification

Backends implement the behavior, but the runtime owns the contract.

Attach governance at the capability layer

Instead of:

API gateway policies here
service‑level ACLs there
custom checks in CLIs
broad API keys for agents

…attach:

identity + role rules
approvals
environment constraints
additional guards

to the capability itself.

The runtime enforces those rules for every call.

Make protocols into adapters

Adapters for HTTP, CLI, MCP, a2a, etc. should:

authenticate in their own context
map calls into capability invocations with identity + metadata
send them through the runtime
map results back

The actual governance (schemas, ACLs, approvals, audit) is shared.

Standardize evidence

Because the runtime sees all invocations, it can emit:

structured events (who did what, via which surface)
consistent trace IDs and error shapes

That makes incident response and audits tractable even when agents are involved.

Migrate incrementally

You don’t have to flip everything at once.

You can:

start with a few high‑risk operations
define them as capabilities
run them through the runtime for one surface (e.g., CLI)
gradually move agent tools and a2a flows over

Each step reduces the number of “islands” with their own policy logic.

For agent use in particular, this consolidation is what lets you say, with a straight face, that agents follow the same rules and leave the same evidence trail as your other callers.

Give Your Coding Agent a Governed CLI Workflow with apexe

tercel — Fri, 16 Oct 2026 12:14:58 +0000

An agent task starts simply: list a directory, read a file, inspect a tool. As the task grows, those small calls become a workflow with real permissions and side effects.

That is a useful place to introduce apexe: a governed execution layer for CLI tools and HTTP APIs. It gives existing commands typed contracts and applies configured policy before execution, with records of executions and refusals.

Here is how to start with a local CLI workflow, then connect it to the agent or protocol client you use.

1. Prepare apexe and a trusted CLI

Use a prebuilt binary, or build from source with stable Rust and Cargo:

git clone https://github.com/aiperceivable/apexe.git
cd apexe
cargo install --path .
apexe --version

The workflow below targets Unix CLI tools. macOS and Linux are the main starting points; native Windows CLI discovery is not supported. Git is needed to acquire the rules corpus, and the CLI binaries you want to use must already be installed.

Initialize coverage and inspect the result:

apexe init
apexe list --verbose

init obtains the configured rules source, normally cli-permissions, checks matching installed commands and variants, and writes bindings plus a starter ACL.

Review ~/.apexe/acl.yaml. A new policy defaults to deny, with generated allow rules for local readonly operations. Existing manual rules and policy defaults are preserved. Treat generated classifications as material to review.

Read the init report, including skipped tools, warnings, and native_ready module IDs. This is where you learn which entry points your installation can actually use.

2. Preview one native invocation

Native execution accepts familiar argv:

apexe exec --dry-run -- ls -la

For this example, you need a matching reviewed native binding. The current native pilot covers BSD cat, head, and ls. A Linux installation may successfully scan GNU tools while lacking native grammar for this call; scanning coverage and native eligibility are separate.

Inspect the preflight's validity, execution mode, module, ACL decision, approval requirement, and argument/path checks. Confirm that it describes the operation and policy you intended.

Only after reading an admitted preflight, submit a separate execution call:

apexe exec -- ls -la

Native stdout and stderr pass through, and apexe preserves the child's exit status. You do not need to activate a shell environment or run an MCP server.

Keep preview and execution separate in an agent workflow: the point is to inspect the result before starting the child. Execution checks the request again; a preview does not reserve permission or grant human approval.

3. Use module JSON when the binding has no native grammar

Module JSON is another local interface. Start by inspecting the installed schema:

apexe list --verbose --format json

The output's modules array contains each module's id and input_schema. Use the property names and shapes from your own binding.

For example, if your cli.ls schema advertises a file array, preview:

apexe exec cli.ls --input '{"file":["."]}' --dry-run

After inspecting an admitted result, execute separately:

apexe exec cli.ls --input '{"file":["."]}'

Module mode captures the result as JSON, including stdout, stderr, and exit_code; it supplies null child stdin. Native mode preserves streams, with stdin inheritance only where reviewed capabilities permit it.

Both routes apply their normal governance checks. A missing native grammar can justify selecting module JSON for the same operation. An ACL or path refusal calls for resolving the denied request with the operator.

4. Give your terminal agent the same workflow

apexe includes one shared routing Skill for Claude Code, Codex, pi, and OpenCode. From the source checkout:

python3 scripts/install_agent_skill.py --project-dir /path/to/your-project

Replace that destination with the project where the agent works. Follow the Agent Skill guide to declare the execution route and selected policy in the host's project instructions.

The Skill guides the agent to resolve configuration before its first task command, route external CLI calls through explicit exec, preview new or changed calls, and stop on governance refusals. Explicit exec works without shims or MCP.

For a pipeline, the shell still owns the pipe. Each external stage needs its own governed invocation, and the Skill calls for preflighting stages sequentially before execution. Shell redirection happens outside apexe's typed-path checks.

Installing the Skill alone does not enroll every project or intercept an unrestricted terminal. Compulsory routing requires host enforcement.

5. Add an interface when you need it

For existing shell workflows, optional env integration installs eligible external-command shims:

apexe env --enable
source ~/.apexe/bin/apexe-activate.sh
apexe env --check

Use this after bindings and policy are ready. Shims preserve familiar command names for covered tools. Builtins, aliases, absolute paths, and uncovered commands remain outside that route.

For an MCP client:

apexe serve --acl ~/.apexe/acl.yaml

For A2A:

apexe a2a --acl ~/.apexe/acl.yaml

Servers need the explicit ACL flag for access control. Local exec uses caller local and loads the default ACL when present; if none is loaded, access control is inactive. MCP interactive approval is opt-in with --enable-approval and a compatible client. Local execution has no interactive approval client, so calls that actually need that decision fail closed. A2A has no interactive approval transport; approval-store support requires library integration.

Have an HTTP API too? serve and a2a can import supported operations from OpenAPI 3.0/3.1 documents alongside CLI modules. See the OpenAPI guide for the supported JSON proxy surface and credential setup. HTTP import is a server feature.

Keep the contract current

After a CLI changes, check its source contract:

apexe verify --report ./drift-report.json

Optional explicit behavioral cases add evidence for the invocations tested. Recorded evidence is bound to binding, executable, and case digests, so changes can invalidate it. It does not certify every possible use of a CLI.

Know the execution boundary

Governed CLI calls use structured inputs, configured ACLs, schema-typed path checks, environment scrubbing, timeouts, and auditing. apexe passes argv to the subprocess without evaluating a shell command string.

An allowed process still has the host process's privileges. apexe is not an OS sandbox. Pair it with the account and isolation boundary your workload needs, and read the threat model.

The project is Rust-based and Apache-2.0 licensed. Start with one trusted CLI and one operation you can inspect from preflight through audit.

Explore apexe on GitHub · Read the quick start

Which CLI would you like your agent to use through a reviewed execution contract?

Distributed Orchestration vs Agent Reasoning

tercel — Thu, 15 Oct 2026 02:47:51 +0000

A lot of “AI agent orchestration” diagrams quietly merge two very different responsibilities:

deciding what to do next (reasoning)
actually running distributed work reliably (orchestration)

If you’ve ever operated a workflow engine, you know the second problem doesn’t go away just because a model is choosing the steps.

Agents are planners, not workflow engines

Agent frameworks are great at:

breaking down fuzzy tasks
picking tools / capabilities
adapting a plan based on intermediate outputs

They’re not good at:

guaranteeing retries and idempotency
managing long‑running state
coordinating fan‑out and aggregation at scale

Those are classic workflow concerns.

What orchestration is responsible for

A real orchestration layer needs to:

persist workflow state
handle node restarts and deploys without losing work
retry failed steps with backoff
apply idempotency / deduplication
support compensation / rollbacks for multi‑step flows

In an agentic system, that orchestration is often built on top of a governed capability runtime.

Why pair a runtime with orchestration?

A protocol‑neutral capability runtime gives you:

schema‑validated inputs/outputs for each operation
identity / ACL / approval checks
structured traces and events per invocation

An orchestrator then uses those capabilities as building blocks, chaining them together under strong guarantees.

The agent stays in the role of planner:

it proposes which capabilities to call and with which parameters
it can react to structured errors and adjust the plan
it doesn’t try to be the persistence or retry layer

This separation has practical benefits:

Debuggability
When a flow fails, you can see where: in planning, in runtime validation, or in orchestrated execution.
Safety
Every step is subject to the same ACLs, approvals, and audit behavior, regardless of whether it was triggered by an agent or a human.
Evolution
You can swap agent frameworks or tool protocols without rewriting the orchestration and governance layers.

A small, realistic first step

If you’re starting from an agent demo that calls services directly, you don’t have to refactor everything at once.

Try this:

pick a single, non‑trivial flow (e.g., canary deploy, batch data fix)
expose the underlying operations as governed capabilities with schemas
route all calls through a runtime that adds identity, ACLs, approvals, and traces
have a simple orchestrator (queue + worker, or a workflow engine you already use) own retries and long‑running state

Once that path works, expand the set of capabilities and flows that use it.

The key shift is mental: treat agents as planners on top of a governed, orchestrated system – not as replacements for the parts of your stack that already give you reliability guarantees.

Distributed Orchestration vs Agent Reasoning

tercel — Wed, 14 Oct 2026 02:38:17 +0000

A lot of “AI agent orchestration” diagrams quietly merge two very different responsibilities:

deciding what to do next (reasoning)
actually running distributed work reliably (orchestration)

If you’ve ever operated a workflow engine, you know the second problem doesn’t go away just because a model is choosing the steps.

Agents are planners, not workflow engines

Agent frameworks are great at:

breaking down fuzzy tasks
picking tools / capabilities
adapting a plan based on intermediate outputs

They’re not good at:

guaranteeing retries and idempotency
managing long‑running state
coordinating fan‑out and aggregation at scale

Those are classic workflow concerns.

What orchestration is responsible for

A real orchestration layer needs to:

persist workflow state
handle node restarts and deploys without losing work
retry failed steps with backoff
apply idempotency / deduplication
support compensation / rollbacks for multi‑step flows

In an agentic system, that orchestration is often built on top of a governed capability runtime.

Why pair a runtime with orchestration?

A protocol‑neutral capability runtime gives you:

schema‑validated inputs/outputs for each operation
identity / ACL / approval checks
structured traces and events per invocation

An orchestrator then uses those capabilities as building blocks, chaining them together under strong guarantees.

The agent stays in the role of planner:

it proposes which capabilities to call and with which parameters
it can react to structured errors and adjust the plan
it doesn’t try to be the persistence or retry layer

This separation has practical benefits:

Debuggability
When a flow fails, you can see where: in planning, in runtime validation, or in orchestrated execution.
Safety
Every step is subject to the same ACLs, approvals, and audit behavior, regardless of whether it was triggered by an agent or a human.
Evolution
You can swap agent frameworks or tool protocols without rewriting the orchestration and governance layers.

A small, realistic first step

If you’re starting from an agent demo that calls services directly, you don’t have to refactor everything at once.

Try this:

pick a single, non‑trivial flow (e.g., canary deploy, batch data fix)
expose the underlying operations as governed capabilities with schemas
route all calls through a runtime that adds identity, ACLs, approvals, and traces
have a simple orchestrator (queue + worker, or a workflow engine you already use) own retries and long‑running state

Once that path works, expand the set of capabilities and flows that use it.

The key shift is mental: treat agents as planners on top of a governed, orchestrated system – not as replacements for the parts of your stack that already give you reliability guarantees.

Practical Patterns for AI Agent Governance in Production

tercel — Wed, 07 Oct 2026 00:53:29 +0000

When an AI agent starts calling real systems – deploy pipelines, billing, CRM, data workflows – “governance” stops being optional.

Over the last year, a few practical patterns have emerged for teams that got agents into production without terrifying security and infra.

Pattern 1: Treat capabilities as a catalog, not just functions

Instead of wiring agents to ad‑hoc endpoints, define a capability catalog:

stable capability IDs
machine‑readable schemas for inputs and outputs
metadata (owner, risk, environments)

The same capabilities are callable by humans (CLI), services (HTTP/RPC), and agents. That shared catalog becomes your map of what the organization can actually do.

Pattern 2: Build a centralized enforcement pipeline

Sprinkling ACL checks and approvals across N services doesn’t scale.

Introduce a runtime layer that every capability invocation passes through. It should:

resolve identity and caller context
enforce ACLs
evaluate approval conditions
run middleware for logging / metrics / policies

Downstream services implement business logic; the runtime decides whether the call is allowed and how it should be wrapped.

Pattern 3: Keep protocols as adapters on the edge

MCP, HTTP, CLIs, internal RPC – all are just ways to reach the same capabilities.

If each protocol carries its own governance semantics, you’ll get drift. Instead, let each protocol adapter:

map protocol requests into capability calls
inject identity and context
route through the same enforcement pipeline

That way, adopting a new tool protocol is mostly an adapter exercise, not a rewrite of core rules.

Pattern 4: Evidence as a first‑class output

When something breaks, teams want more than logs. They want evidence.

Your runtime can emit:

structured “invocation” events (who, what, where)
consistent error shapes with trace IDs
hooks for usage / cost tracking

Because this happens in one place, you don’t depend on every service getting logging exactly right.

Pattern 5: Offload determinism to an orchestrator

Agents are planners; they’re not great at guaranteeing that a fan‑out of 1,000 jobs completes exactly once.

Pair agents with a workflow engine that handles determinism:

retries and idempotency
timeouts and cancellation
compensation logic

The agent assembles a plan in terms of governed capabilities; the orchestrator executes that plan reliably.

Pattern 6: Iterate on one end‑to‑end path

A realistic path for many teams:

pick a non‑trivial, high‑value capability (e.g., canary deploy)
give it a schema, policies, and full tracing
expose it to a human interface and an agent
run it in production with tight monitoring

Use the friction you hit there to refine your runtime, then scale out to more capabilities.

These patterns don’t depend on a specific framework. They do depend on drawing a clear line between:

capabilities (what can be done)
the governed runtime (who can do it, under what rules)
protocols and agents (how it’s requested)

Once that separation exists, agent governance becomes a matter of evolving policy and runtime behavior – not rewriting every integration when a new agent pattern appears.

Why Raw Shell Access Is the Wrong Agent Integration—and What apexe Does Instead

tercel — Thu, 01 Oct 2026 13:21:06 +0000

Your organisation probably already owns the capabilities its agents need. They live in git, kubectl, jq, curl, operational scripts, and internal Unix command-line tools.

The usual choice is uncomfortable: give an agent shell access, or rebuild every useful command as an API or MCP server.

apexe is built for the middle path. It scans an existing CLI, turns each command into a schema-driven apcore module, and serves those modules through MCP or A2A with execution-time controls.

existing CLI → module contract + reviewed policy → governed Executor → many agent clients
What is supported today?
Precision matters in agent infrastructure. The current product boundary is:

Item apexe 0.8 status
Unix CLI tools on PATH Supported by apexe scan
macOS/Linux system utilities (ls, cat, cp, sort, …) Supported as CLI tools, including BSD-aware parsing
Built-in parsers (Man, BSD Usage, GNU, Click, Cobra, Clap) Supported scanner feature
ACL for scanned CLI modules Supported when supplied with --acl
MCP Supported by apexe serve (stdio, HTTP, Explorer)
A2A Supported by apexe a2a
OpenAPI input Not supported by the apexe CLI today
OpenAPI deserves a direct note. The apcore toolkit has OpenAPI-related functionality, but apexe does not call its OpenAPIScanner. apexe is currently a CLI-to-agent bridge, so we should not market OpenAPI support as shipped functionality.

Start with a real CLI
apexe scan git curl jq
apexe list
apexe serve --show-config claude-desktop --acl ~/.apexe/acl.yaml
The scan is deterministic: help text, man pages, and shell completions—not an LLM. It creates one binding per command, such as cli.git.log or cli.curl, and each binding contains JSON Schema for flags and operands.

An agent calls a JSON object rather than composing a command string:

{
"url": "https://httpbin.org/get",
"silent": true
}
apexe validates this object, builds argv, and launches the program directly. No shell parses the resulting arguments.

One capability configuration, many agent clients
The goal is not to create a separate tool definition and security policy for every agent product. Bindings and ACL are the source of truth:

~/.apexe/bindings/ + ~/.apexe/acl.yaml → apexe → Claude / Codex / Pi / another MCP client
This does not mean every client shares one configuration-file format. Each host still needs its own MCP connection entry. What stays shared is the command or HTTP endpoint, the scanned module bindings, and the reviewed ACL.

apexe can generate connection snippets for Claude Desktop and Cursor:

apexe serve --show-config claude-desktop --acl ~/.apexe/acl.yaml
apexe serve --show-config cursor --acl ~/.apexe/acl.yaml
Codex can register the same local stdio server:

codex mcp add apexe -- apexe serve --acl ~/.apexe/acl.yaml
Pi and other MCP-capable clients can connect through their own MCP configuration mechanism. apexe does not currently generate a Pi-specific file, so the client must support the transport you select. For a shared deployment, run one authenticated HTTP server and have compatible clients connect to that endpoint.

Why the module contract matters
The contract is what lets the same capability retain its meaning across delivery surfaces:

apexe serve exposes it over MCP, using stdio by default or HTTP with a browser Explorer.
apexe a2a exposes the same governed modules as agent skills.
--prefix and --tags reduce the registered surface before a client can discover or invoke it.
Policy does not need to be rewritten per protocol because MCP and A2A share the same Executor.

Governance is a product feature, not a checkbox
apexe scan writes a default-deny ACL. It is a starter policy, not an invisible decision: enforcement begins only when an operator serves with --acl.

apexe serve --acl ~/.apexe/acl.yaml
The ACL controls which capability may be called. An always-on path guard answers a different question: what filesystem location may this specific call touch? It checks path-typed inputs after resolving symlinks and traversal, protects system paths from writes, and protects credential locations from both reads and writes.

apexe policy
apexe policy --path /etc/nginx/conf.d --mode write
Every child process is shell-free, runs with a scrubbed environment, has a timeout and output cap, and can produce a private audit record. These are meaningful safeguards, but they are not a sandbox. Run exposed tools inside the container, VM, account, and network boundary your risk model requires.

Why 0.7 and 0.8 matter
The current releases make the boundary more useful in practice: path protection, argument-sensitive approvals, refusal of verified command-executing parameters, binary availability checks, an explicit default-deny tier for network-reaching tools, and externally maintained verified CLI overlays.

Bindings now live by default under ~/.apexe/bindings and record which apexe version produced them. Existing users should rescan after upgrading:

apexe scan git curl jq --no-cache
apexe list --available-only
What comes next: local execution, then native terminal workflows
The next proposed feature is F8 local execution. It is deliberately split into two stages rather than treating a shell wrapper as a shortcut.

Stage 1, apexe run, is a structured local entry point for one scanned module at a time:

apexe run cli.ls --input '{"long": true, "paths": ["/tmp"]}' --acl ~/.apexe/acl.yaml
It will reuse the same Executor that MCP and A2A use, produce captured output, and make preflight decisions inspectable from the terminal. It is not native shell syntax and does not provide streaming stdin or pipelines.

Stage 2, apexe env with PATH shims, is the intended end-user terminal experience. Eligible external commands retain their normal names and argv syntax, so an existing pipeline such as ls -l /tmp | grep ERROR | head -20 can remain unchanged. Each stage is independently resolved to a scanned module and receives schema validation, verified cli-permissions facts, ACL, path guard, timeout, output limit, and audit logging—without using sh -c.

This is not available yet. Its safety depends on contracts that are still being settled: passthrough I/O, an explicit human-reviewed allowlist for modules that may read streaming stdin, PATH isolation, and measurements of refusal rate and shim latency. It also cannot intercept shell builtins, aliases/functions, or absolute-path calls. Read the F8 design for the exact boundary.

Join the design conversation
The interesting question is not “can an agent run a command?” It can. The question is which existing capability sources should share a contract, governance layer, and protocol delivery model.

We would love your comments:

Which CLI or internal tool would you expose first?
Which agent hosts—Claude, Codex, Pi, or another MCP client—need the same governed tool surface?
Which existing scripts or pipelines should a governed PATH-shim mode support first?
Would OpenAPI ingestion be valuable in the same workflow?
What must an operator review before an agent can use a newly discovered capability?
Project: aiperceivable/apexe

Designing Schema-First Capabilities for AI Agents

tercel — Thu, 01 Oct 2026 05:49:02 +0000

If your AI agent can call production systems, the contract between the agent and your capabilities is more important than the prompt.

A schema‑first capability design puts that contract at the center of your architecture and lets everything else – CLIs, HTTP APIs, agent tools – project from it.

What is a schema‑first capability?

Take a real operation in your system:

create_invoice
deploy_service
reset_user_password

Instead of documenting this informally and wiring it directly into APIs, you define a machine‑readable schema that captures:

input fields, types, and constraints
output structure
error variants and their shapes

This schema is authoritative across all callers: humans, microservices, and AI agents.

Why do this for agents?

LLMs are not type‑safe. They will:

omit required fields
invent new ones
send wrong types ("five" instead of 5)

If you validate deep inside your application, you only discover problems after partial side effects. A schema‑aware runtime can:

validate inputs before execution
validate outputs before returning
produce structured errors the agent can learn to handle

That alone dramatically reduces “mystery failures” in production.

Schema as a governance anchor

Once every capability has a stable ID and schema, you can attach policy:

which identities / roles may call it
which calls need approval
which environments it applies to
what logging, tracing, and usage hooks must run

Crucially, this policy is attached to the capability itself, not to any single protocol.

Multi‑language, one contract

Most organizations run Python, TypeScript, and at least one systems language. A normative schema lets you:

generate / validate language‑specific SDKs
write conformance tests once
keep contracts synchronized across stacks

Agents don’t care which language implements a capability; they care that the contract is consistent.

A concrete pattern to start

Choose an existing, non‑trivial operation.
Write its real input/output contract and error cases.
Encode that as a schema.
Wrap the implementation in a small runtime layer that validates against the schema and emits structured events.
Expose it through one additional surface (CLI, HTTP, or a tool protocol).

Measure:

how often validation catches bad calls
how much easier debugging becomes with structured traces
how straightforward it is to add another surface once the capability exists

Over time, your catalog of schema‑first capabilities becomes the safe surface area your agents can operate in, with the same rules and evidence as the rest of your stack.

What a Governed Agent Runtime Actually Does

tercel — Tue, 29 Sep 2026 01:33:25 +0000

Most AI agent prototypes fail not because the model is weak, but because the path from the model to real capabilities is essentially ungoverned.

When an agent can deploy code, mutate data, or touch infrastructure, you need more than tool definitions. You need a governed runtime between the model and the capability.

In this article I’ll outline what a governed, protocol‑neutral runtime does, why it matters for AI agents, and how it differs from agent frameworks and tool protocols.

Start from capabilities, not protocols

In many stacks, the starting point is the protocol surface: an HTTP API, a CLI, an MCP server, or a bespoke RPC layer. Governance ends up scattered across them.

A governed runtime inverts this. The primitive is a capability:

a function your system can perform
with a strict input/output schema
annotated with metadata and policies

Protocols become adapters that project that same capability to different callers.

Enforce strict contracts at the edge

LLMs are probabilistic. They will:

omit required fields
invent parameters
send values in the wrong shape

If you only validate deep inside application code, you pay for side effects and partial failures before discovering the problem.

A governed runtime enforces contracts before execution:

validate inputs against a schema
validate outputs before returning
guarantee error shapes so callers can rely on them

This is just as important for human‑driven CLI or HTTP calls as it is for agents.

Centralize governance semantics

When every surface (CLI, HTTP, MCP, a2a) re‑implements:

ACL checks
approval workflows
environment / tenant routing
logging and policy hooks

…you end up with drift and blind spots.

A runtime should provide a single pipeline where it can apply:

identity and ACL resolution
approval gates for high‑risk actions
call‑chain guards (who called on behalf of whom)
middleware for custom policies and observability

Adapters then plug into that pipeline, instead of embedding their own partial implementation.

Make execution observable by default

Governed systems need more than a log line. They need structured evidence.

A runtime can emit:

structured errors tied to capability IDs
trace context that spans agent reasoning and execution
events (started, retried, completed, failed)
usage hooks suitable for metrics and billing

That makes capabilities safe to expose through multiple channels, because you can audit and debug behavior no matter who called them.

Separate reasoning from orchestration

Agent frameworks excel at planning and choosing tools, not at guaranteeing exactly‑once execution across a fleet of workers.

A robust design pairs the governed runtime with a workflow / orchestration layer that handles:

distributed task execution
retries, backoff, and idempotency
timeouts and cancellation
compensation logic

The agent chooses; the runtime and orchestrator guarantee how.

Stay protocol‑neutral

Today’s hot protocol is MCP. Tomorrow it might be something else.

If all your semantics live in one protocol layer, you’re locked in. A protocol‑neutral runtime keeps your:

schemas
governance
execution semantics

…independent of any single protocol. MCP, a2a bridges, CLIs, HTTP APIs, and in‑process calls all project the same capability definition.

What to look for in a governed agent runtime

When you evaluate libraries and platforms, ask:

Where do capability contracts live, and are they language‑agnostic?
How are identity, ACLs, and approvals enforced?
Can I expose the same capability to MCP, HTTP, CLI, and internal code without rewriting logic?
What structured evidence do I get when something goes wrong?

A runtime that answers those questions cleanly will make your agents safer, more debuggable, and easier to operate in production than yet another pile of glue code between an LLM and your systems.

Cross-Language SDKs for a Single Agent Capability Standard

tercel — Thu, 10 Sep 2026 08:05:30 +0000

In most real-world systems, “AI agents” sit on top of a polyglot stack:

Python for data and ML
TypeScript/Node for backend and APIs
Rust/Go for performance-sensitive pieces

If your capability model only really exists in one language, you end up with:

Duplicate logic in other languages
Inconsistent validation and error handling
Governance rules that only apply to the Python part

A more sustainable pattern is to treat the capability protocol as the primary artifact and the language SDKs as implementations.

Concretely:

Specify a wire-level protocol and schema format.
Define how metadata (risk, cost, ownership) and governance hooks (ACL, approvals, audit) attach to a capability.
Build SDKs in your target languages that:
- Use the same conformance tests
- Expose idiomatic APIs
- Produce identical runtime behavior

Now a capability implemented in Rust can be:

Called by a Python-based agent
Exposed as an HTTP endpoint by a TypeScript service
Invoked via CLI by ops teams

…without reinventing validation, approvals, or tracing.

If you are designing your own internal runtime, consider starting with the protocol and tests first, and only then layering language-specific ergonomics on top. It is slower upfront but pays off when your stack inevitably becomes polyglot.