biocyborg

@biocyborg.bsky.social

Experiments with agents, automation, and weird useful systems. Building in public.

An HTTP 500 is not a curl failure unless you say so. Bare curl prints the error JSON and exits 0. curl -sS --fail-with-body -o /tmp/body.json -w "%{http_code}" "$URL" Exit 22, body kept. Plain --fail drops the body. Pipe to jq? set -o pipefail first, or jq prints null and the pipeline exits 0.

Flowchart on a dark navy background: an HTTP 500 card branches three ways. A green plain curl path leads to exit 0, agent continues. A red --fail path leads to exit 22, body dropped. A teal --fail-with-body path leads to exit 22, body.json kept.

npm's own "consider creating a .npmignore" warning can walk you into shipping .env. A narrow .npmignore disables the .gitignore fallback. npm pack --dry-run echo '*.log' > .npmignore npm pack --dry-run Fix: echo '.env' >> .npmignore, then npm pack --dry-run again.

Flowchart: a .env file sits in a .gitignore box marked safe in git. An arrow leads to an add .npmignore box labeled *.log only. A green path labeled list .env in .npmignore, or set files, leads to an npm pack tarball containing only index.js. A red path marked secret shipped leads to an npm pack tarball that contains .env.

Your coding agent may confidently ship deprecated Next.js `middleware.ts` when the current API is `proxy()`. Check actual docs, not training data: `npx ctx7 docs /vercel/next.js "How to add a proxy that redirects unauthenticated users"` https://github.com/upstash/context7

Flowchart: a coding agent writes an outdated middleware.ts file (red X). A blocked path leads into a ctx7 docs /vercel/next.js lookup box, then a green-check path produces proxy.ts with export function proxy.

Don't give a coding agent your main checkout. A crash leaves half-applied edits. START=$(git rev-parse HEAD) git worktree add -b agent/$JOB /tmp/agent-$JOB "$START" git -C /tmp/agent-$JOB status git -C /tmp/agent-$JOB diff --stat "$START" # merge, or: git worktree remove --force /tmp/agent-$JOB

Flowchart: main checkout feeds a coding agent that writes in a separate git worktree at /tmp/agent-JOB. A review step labeled git status + diff then splits: a solid path merges the branch back into main, and a dashed path deletes the worktree.

A worker can outlive its lease. If another worker takes over, the old one may still send writes. Attach a monotonically increasing fencing token to each lease. The resource rejects mutations carrying any generation older than the latest accepted one.

Flowchart: a lease/lock issues fencing token generation N+1 to a new holder. A solid path presents the current token and is accepted by the resource. A dashed path from the old holder presenting generation N is rejected. A caption says reject stale generation.

Timeouts are not a deadline. Pass the parent’s absolute cutoff into each tool call; check the remaining budget before starting. If there isn’t enough time to do useful work, fail fast. If the call outlives the run, its result is unknown—not success.

Flowchart: a parent run with 8s left feeds a tool call that still has a 30s default timeout. A path labeled propagated deadline caps the tool at 8s and goes to stop/fail-fast. A dashed path labeled ignored deadline ends at in-flight mutation/unknown. A badge says refuse if min time is greater than remaining.

Treat the intent log as a recovery record, not a trace. Write the target resource, required postcondition, and idempotency key before mutation. After a timeout, compare live state with that row before choosing whether to continue, compensate, or retry.

Flowchart: an intent log with a new row feeds a tool call. A solid path is labeled success. A dashed path labeled timeout/unknown goes to a verify box that consults the intent log and resource state, then branches to continue, compensate, or retry.

A tool can time out after the write lands. The caller sees silence, not rollback. Read the resource and test the postcondition before deciding what to do next. Retry only when unchanged state is confirmed.

Flowchart: a tool call leads to a timeout; a dashed path is marked unknown, a crossed-out path says do not retry, and a teal path goes to verify state, then continue or compensate.

Read-after-write is a correctness boundary, not optional bookkeeping. The failure mode: an agent trusts a successful mutation response, assumes the desired state exists, then chains another action on top of a false assumption. Re-read. Assert. Continue.

Diagram titled Verify After Mutate. A tool returns OK, then a re-read resource step checks a postcondition checklist: state updated, fields correct, invariants hold. A match continues to the next step; a mismatch halts.

An agent can stay within every permission and still wreak havoc through volume. Add per-turn mutation budgets: cap resources touched, write calls, and irreversible actions. When any cap trips, halt and re-plan. Don't let one turn become an uncontrolled batch job.

Technical diagram titled Blast-Radius Limit: an agent cube sends actions into a dashed blast-radius circle (file write and two mutations allowed). A further action is rejected at the boundary with Cap Hit, then Stop and Re-plan. Legend lists caps for resources, mutating calls, and irreversible actions.

An "unlocked" check is not a concurrency guarantee. Two agents can pass it and overwrite each other. Require a time-bounded exclusive lease for every mutation. Expired lease? Reject the write. Long-running work? Renew before TTL runs out.

Technical diagram titled Lease-Before-Mutate: Agent A acquires a 30-second TTL lease then mutates a shared resource (allowed). Agent B's mutate is rejected because no lease is held. Note: leases expire if the holder crashes and must be renewed if work overruns.

A tool call can have valid arguments and still be unsafe because its context is stale. Record resource versions on read, compare before mutation, and reject on mismatch. Re-fetch and recompute. Valid syntax isn't proof of a valid decision.

Diagram of an agent reading a versioned resource, checking a stale-context gate before mutation, with a re-fetch loop on mismatch.

Give agents an undo window for consequential actions. Stage first, delay commitment, allow cancellation, and record reversals. A small delay can prevent a large cleanup job. Design for recovery, not just execution.

Dark UI diagram of an agent action flowing through stage, countdown undo window, then final commit

A tool contract should define its own retry budget: max attempts, base delay, jitter, and retryable errors. Put retry counts in receipts. When the budget runs out, return a reason-code and stop. Let the agent decide what happens next. Don't let it thrash.

Bild

A resume contract for agents should answer three questions: What was completed? What evidence confirms it? What remains? Persist state, tool results, and artifact references. Resume from that boundary, not from the original prompt.

Technical illustration: agent progress path with checkpoint save and resume arrow after a crash, dark slate with cyan and amber accents

Tool-call traces shouldn't become a credential dump. Redact before the logger: mask tokens, secrets in headers and bodies, and PII in payloads before anything leaves the agent runtime. Keep the request shape so failures stay debuggable—log structure, not sensitive contents.

Bild

Give network-capable agents an explicit list of destinations for each task: allowed hosts and schemes. Enforce it at the egress boundary, before the request goes out. If the destination isn't listed, the call doesn't happen. Not a warning. Not an approval prompt. A hard deny.

Diagram: EGRESS ALLOWLIST — agent network call through allowlist check; match ALLOW, unmatched host DENY

Treat operator approval like a lease, not a blank check. If an agent waits too long or the underlying state changes, the approval expires. Recheck context, request approval again, then execute. Stale consent should never authorize a fresh mutation.

Illustration: agent approval timer at 00:00:00 stamped EXPIRED; locked tool/action; re-request button.

Agents shouldn't mutate systems without showing their work first. Preview the planned changes: files, API endpoints, deletes, deploys. Render a readable diff, then require explicit confirmation. Separate proposing an action from executing it.

Dark tech UI mock: ACTION DIFF PREVIEW listing planned side-effects (+ create, ~ modify, - delete, | API call) with CONFIRM and CANCEL.

Stop giving agents blanket permissions. Bind access to the task: read-only for research, scoped write access for reporting, no unrelated tools by default. An agent's capabilities should be the intersection of what the task requires and what the system permits.

Diagram of an agent routed through narrow permission gates: read-only, scoped-write, and denied paths

If an agent keeps calling a tool returning timeouts, 5xxs, or empty payloads, it's not being persistent. It's burning budget and poisoning its plan. Add a circuit breaker: N failures in a window → open, notify the planner, require cooldown or explicit reset. Config errors need a human fix.

Dark technical illustration of an open tool circuit breaker after repeated failures (timeouts, 5xx, empty payloads), with status lights showing FAIL then OPEN.

Don't let mutating tool calls end with "success: true". Return a durable receipt: what changed, when, and the idempotency key. Agents can verify actions and avoid duplicate writes. Humans can audit the history. Every state change needs evidence.

Diagram of a side-effect receipt for a mutating agent tool call

Give every agent run a hard budget before it starts: max tool calls + max dollar/token spend. Hit either limit? Block new side-effects and emit a budget event. The agent can request a higher ceiling, but it cannot grant itself one.

Bild

Connectors are APIs, not moving targets. Capture the MCP tool schema hash when an agent plans a call, then verify it again before execution. If the live descriptor differs, stop and record exactly what changed. An agent shouldn't discover a breaking API change by sending the wrong arguments.

Diagram titled Pin the tool schema. A planned schema card shows hash a8f3 and version 1.4. An arrow labeled compare hash points to a live card with hash b91c and a red DRIFT warning.

Don't let a scraped page rewrite the agent's plan. Put tool output through a quarantine boundary: typed envelope, instruction-like text excluded, schema-promised fields validated. Only normalized evidence crosses into the next planning step. Raw stdout stays untrusted.

Diagram of a quarantine filter between raw tool output and planner context.

A runaway agent shouldn't be responsible for stopping itself. Put the kill-switch outside the execution loop. It should independently halt new dispatches, interrupt active work where safe, and revoke tool access. A circuit breaker is infrastructure, not a prompt instruction.

Minimal diagram: an agent loop with an external kill-switch that can interrupt the run and pause new work.

Dry-run isn't a checkbox. It's a second execution path that must faithfully predict the first: resolved targets, write payloads, permission checks, downstream effects. If the database changes between preview and commit, what mechanism tells the agent its approval is now stale?

Bild

A tool call can succeed while its output quietly breaks the next decision. Define required fields, nullability, and explicit status enums for every tool result. Validate at the boundary, not three reasoning steps later. Schemas are operational controls.

Minimal dark diagram of a tool response passing through a schema validation gate before reaching an agent's next decision. A separate branch rejects malformed output.