@shiit/mycelium

The network under the mushroom.

One system for attaching capabilities to an agent. Workspaces, connections, anything with tools to lend. The mycelium is the part you don't see: it runs under the forest floor, finds the good stuff, and feeds it to the fruiting body. Your agent is the mushroom. This is everything underneath.

What it's for

Agents want tools; tools live in capabilities that come and go. The mycelium keeps the books and answers the three questions an agent always has: what's attached, what can I call, and what do I call it with. Rename a connection and get a loud, friendly notice instead of a broken call. Rotate a token and the very next call picks it up, because nothing downstream is allowed to remember it.

What the package promises is the bookkeeping: an attach or detach is one atomic, durable transition; the tool surface is a rebuildable value; and you get exactly one event when it changes. What you do with the event is yours. Our host rebuilds its execution context per call, so the next tool call sees the new surface and the session never notices. Yours can do the same — the registry makes that possible, not automatic.

The ruling that shapes it

Closures holding auth are slop.

Most integrations capture a token once, at setup, inside a closure, and then act surprised when it expires. Not here. Auth is resolved per call, just in time, from the source of truth. The connector never holds credentials. It holds a resolver.

The three pieces

The registry (the root import) is the capability ledger: durable identity rows, a lifecycle state machine, namespace allocation with friendly loud renames, batch transitions, and the surface builder that compiles "what's attached" into "what tools exist." It owns no storage and no network — you hand it a plain options bag (readRows, persistRow, emitEvent, your factories) and it keeps the books on your behalf.

The execute door (@shiit/mycelium/execute) is how the model uses the network: one tool with a stable schema. The model writes code; the code runs against live bindings in a sandbox; only results come back. Attach a capability and the next execution sees it — the tool list never changes because the door never changes.

import { createExecuteTool } from "@shiit/mycelium/execute";

const execute = createExecuteTool({
  executor, // a SandboxExecutor you choose: a Worker, a QuickJS box, your own
  connectors, // the capabilities, from your registry or the factories below
});

// `execute` is a structural tool: { name, description, parameters, execute }.
// Wrap it for your harness in two lines — pi's AgentTool, the AI SDK's
// tool(), or anything else that holds a tool.

The door is structural on purpose: this package never imports your agent framework, and it never will.

Per-call auth (the root import) is the contract every outbound call answers to: an AuthResolver you supply, consulted just-in-time, never cached.

const resolver: AuthResolver = {
  resolve: async (ref) => {
    const row = await db.connections.find(ref.id);
    if (!row) return { ok: false, error: new ConnectionNotFoundError(ref) };
    if (!row.token)
      return { ok: false, error: new AuthNotConfiguredError(ref) };
    return {
      ok: true,
      auth: {
        kind: "header",
        headers: { authorization: `Bearer ${row.token}` },
      },
    };
  },
};

Rotated the token? The next call already knows. Nobody re-attached anything. That is the whole trick.

The connectors that answer to the resolver ship in the box. Attach an MCP server or an OpenAPI service and never think about tokens:

import {
  setupMcpConnection,
  createOpenApiRequestHandler,
} from "@shiit/mycelium/connectors";

// One connection's config, your resolver, and the SDK constructors
// from your side — the package stays zero-dep by never importing them.
const { client, tools } = await setupMcpConnection(
  config, // the connection row's config (url, transport type, ...)
  resolver, // your AuthResolver from above — consulted on setup
  connectionId, // the ref the resolver keys on
  { Client: McpSdkClient, Transport: McpSdkTransport },
);
// client.callTool(...) talks to the server; tools describes what it offers.

// OpenAPI gets the same shape: one bag in, a handler out — auth
// resolved per call, never cached.
const handler = createOpenApiRequestHandler({
  connectionId,
  config, // base url + spec source
  authResolver: resolver,
  authKind: "header", // or "oauth"
});
await handler.request({
  path: "/repos/{owner}/{repo}",
  params: { owner: "fungi-computer", repo: "Botanical" },
});

In the box

The root, @shiit/mycelium:

• Mycelium — the registry class. Attach, detach, list, transition, build the surface.
• NamespaceAllocator — friendly aliases, loud rename notices, zero collisions.
• CapabilityFactory — one interface, registered per kind. The registry never switches on kind.
• Lifecycle types — requested → active → releasing → released, validated transitions.
• AuthResolver, connectionRef, typed failures (ConnectionNotFoundError, AuthNotConfiguredError, TokenExpiredError, RefreshFailedError), withRefreshRetry, and the noResolveAuth / fromLegacyAuth migration ramps (ramps, not destinations).

@shiit/mycelium/execute:

• createExecuteTool(options) — the door, as a structural tool.
• SandboxExecutor — the one-method adapter contract (execute(code, bindings)). Bring your own sandbox.
• The image collector and the structural types.

@shiit/mycelium/connectors:

• The provided connector factories — files, skills, ui — with host seams as options.
• The Connector contract they all answer to.

Zero runtime dependencies, everywhere in the package. That is a rule, not a coincidence.

The family

Part of the shiit stack: @shiit/watchdog guards the jobs, @shiit/bird-dog carries the mail, @shiit/forage finds the tools, and the mycelium feeds the agent its capabilities. Beware of dog. Mind the network.

MIT.