Teaching AI to Read Code: Building a Self-Analyzing Petri Net with AgenticOS and SA-BlobStore

Teaching an Agentic-Net to Read Its Own Code

A AgenticOS + SA-BlobStore journey: small tokens, big artifacts, and a two-stage “grep → analyze” agentic process

The moment it clicked: tokens should not carry files

I love the cleanliness of Petri nets in AgenticOS: tokens move, transitions fire, and everything stays inspectable. But the first time I tried to run a “real” agentic process one that produces artifacts like logs, diffs, PDFs, screenshots I ran into a hard constraint:

tokens are great JSON containers, but terrible file transport.

Even something as innocent as a grep result can become huge once you search a real codebase. And the moment you start embedding megabytes into token payloads, everything becomes slower, harder to debug, and much easier to break.

So I decided to make binary artifacts first-class citizens in the platform without ever bloating tokens.

The answer became a pattern:

Store the artifact in SA-BlobStore, pass only a URN in the token.

The pattern: “binary URN result”

Instead of returning large content inline, a command transition can now return a small JSON result like:

{
  "exitCode": 0,
  "binaryUrn": "urn:agenticos:blob:2026-01-24/364b2837-...-....",
  "binarySize": 5178,
  "contentType": "text/plain",
  "downloadUrl": "http://localhost:8095/api/blobs/2026-01-24/364b2837-...-....",
  "sha256": "..."
}

The token stays lightweight. The payload lives in BlobStore. That’s the entire trick simple, but it unlocks a lot.

What changed in the code (patchset, in plain English)

1) SA-BlobStore: a true “auto-ID upload” endpoint

You can now upload blobs without precomputing IDs:

• POST /api/blobs (no client-provided ID required)
• ID strategies via header X-Id-Strategy:
  • timestamp (default): YYYY-MM-DD/{uuid}
  • uuid: {uuid}
  • content-hash: sha256/{hashPrefix} (dedupe-friendly)
• Response includes blobId, urn:agenticos:blob:{blobId}, downloadUrl, and sha256.

This standardizes “upload something, get a URN back” as a one-call primitive.

2) Executor: resultAs = "binaryUrn" + BlobStore upload

In the executor, binary URN support is driven by the command token:

• CommandToken gained resultAs (default inline, optional binaryUrn)
• CommandToken gained blobStore config (host, idStrategy)
• BashCommandHandler now: execute → locate outputFile → upload → return URN + metadata

This is the enforcement point that keeps tokens small while still supporting large artifacts.

The architecture: BlobStore URN in the middle

Instead of embedding file content, the executor:

1. writes output to a local file
2. uploads it to SA-BlobStore
3. returns a URN reference (urn:agenticos:blob:{blobId})
4. downstream transitions fetch bytes via downloadUrl

The net: “grep → upload → analyze”

The demo net is intentionally simple and tells the whole story:

With only three places and two transitions, you get an end-to-end demonstration of the BlobStore URN pattern.

Stage 1: Grep the codebase and upload the result

The key idea is simple: the command writes output into a file, and the executor uploads that file when resultAs is set to binaryUrn.

Command token (binary URN result)

{
  "kind": "command",
  "id": "cmd-grep-001",
  "executor": "bash",
  "command": "exec",
  "args": {
    "command": "grep -rn --include='*.java' -B2 -A2 binaryUrn . > /tmp/grep-results.txt",
    "workingDir": "/root/workspace/AgenticOS",
    "timeoutMs": 60000,
    "outputFile": "/tmp/grep-results.txt"
  },
  "expect": "binary",
  "resultAs": "binaryUrn",
  "blobStore": {
    "host": "http://localhost:8095",
    "idStrategy": "timestamp"
  }
}

When t-generate-file fires, the executor runs the grep, verifies the output file exists, uploads it to SA-BlobStore, and returns a compact URN-based result token.

Result token (what downstream transitions consume)

{
  "exitCode": 0,
  "binaryUrn": "urn:agenticos:blob:2026-01-24/4e1aa124-ed3b-461c-8957-91da8253aae7",
  "binarySize": 3879,
  "contentType": "text/plain",
  "downloadUrl": "http://localhost:8095/api/blobs/2026-01-24/4e1aa124-ed3b-461c-8957-91da8253aae7",
  "sha256": "db72969246d4134c3762466f04c2449801828a64be42353545973f459ea33d55"
}

The Petri net moves a tiny token. The actual bytes live safely in BlobStore.

Stage 2: Download the artifact and let Claude analyze it

Now the second transition consumes the BlobStore result token and runs an analysis command.

Critical detail: avoid stdin blocking

CLI tools like Claude can block waiting for stdin. In automated agentic processes, always redirect stdin:

claude -p '...' --no-session-persistence < /dev/null

Analysis command token (example)

{
  "kind": "command",
  "id": "cmd-analyze-001",
  "executor": "bash",
  "command": "exec",
  "args": {
    "command": "curl -s \"$downloadUrl\" | claude -p \"Analyze the implementation details and usage patterns in this grep output.\" --no-session-persistence < /dev/null",
    "timeoutMs": 300000
  },
  "expect": "text"
}

The output becomes a normal text token emitted into p-analysis—and the net is complete: artifact generation → BlobStore → analysis.

More places this pattern really shines

Once “binary URN result” exists, a whole class of distributed agentic processes becomes straightforward—especially when you have Agentic-Nets remote executors deployed across different machines/environments.

• Distributed log forensics: a remote executor greps or tails massive log files, stores the chunk as a blob, and a dedicated analysis executor (with AI tools) pulls the blob and produces root-cause hypotheses, timelines, and “next commands to run”.
• Cross-node incident bundles: multiple executors collect artifacts in parallel (logs, configs, thread-dumps, heap histograms), each uploads to BlobStore, and a bundling transition emits a single token containing a list of URNs. One analyzer transition generates the incident report.
• Grep + patch agentic processes: one executor searches code and uploads evidence, another executor runs AI review, a third executor generates a patch file (also as a blob), and a final transition opens a PR.
• Large diffs, zero token bloat: store git diffs (or “diff per module”) as blobs and let analysis transitions build structured summaries: risky areas, likely regressions, test suggestions, or release notes.
• Binary-heavy artifacts: screenshots, PDFs, zipped diagnostics, JFR recordings, HAR files anything that should never sit in JSON becomes a safe, referenceable asset for downstream automation.
• Reproducible AI analysis: URN + sha256 gives you a stable input identity. You can re-run analysis later, compare outputs, and track model drift over time on the exact same artifact.
• Async collaboration between nets: one net generates artifacts (build outputs, exports, reports) and publishes only URNs; other nets subscribe and consume those URNs later (or in a different cluster), without shared filesystem mounts.

Built with AgenticOS, Agentic-Nets, SA-BlobStore, and command-driven transitions.

Date: January 24, 2026

Visual example: distributed log forensics with remote executors

This shows the “tail/grep logs remotely → store as blob → analyze on an AI-capable executor” pattern in one picture. The key is that only the URN moves through tokens; the heavy bytes stay in BlobStore.