npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@fungi.computer/approvals

v0.2.4

Published

Durable principal-bound approval records and auto-approve policy

Readme

Approvals

One durable approval record, many renderers. Mycelium owns operation admission; this package owns the decision lifecycle beside it. Team storage on the Hub and the Oyster host supply the homes. Bonsai is not a ledger home.

Install

npm install @fungi.computer/approvals @fungi.computer/watchdog

Approvals ships ESM and TypeScript declarations from its root entrypoint. The example below uses Node.js 24's native SQLite adapter from Watchdog. Your host owns the database, requester identity, current grants and dispatch.

Quick start

Stage a proposed write without executing it. This disposable in-memory example prints pending; use a persistent, host-owned database for real requests.

import { DatabaseSync } from "node:sqlite";
import { fromNodeSqlite } from "@fungi.computer/watchdog/node-sqlite";
import { ApprovalLedger } from "@fungi.computer/approvals";

const database = new DatabaseSync(":memory:");
try {
  const ledger = new ApprovalLedger({
    owner: fromNodeSqlite(database),
    home: { kind: "team", id: "example-team" },
    now: Date.now,
  });
  const staged = await ledger.request({
    requester: {
      principalId: "agent:example",
      agentId: "example-agent",
      sessionId: "example-session",
      displayName: "Example",
    },
    module: "notes",
    operation: "saveNote",
    access: "write",
    reversibility: "reversible",
    authorityFence: "grant-generation:1",
    idempotencyKey: "turn:1/tool:1/operation:0",
    inputJson: '{"text":"hello"}',
  });
  if (staged.kind !== "record") throw new Error(staged.reason);
  console.log(staged.record.state); // "pending"
} finally {
  database.close();
}

The identities and fence here are illustrative host-attested values, not fields to trust from an Agent or browser. Keep the same idempotency key when retrying the same operation. request stages a record and records the home's auto-approve decision without dispatching. submit additionally applies a newly policy-approved request inline through the authority recheck.

Examples

The home example stages one pending write using native SQLite. The packed consumer in test/stranger/runtime.mjs continues through a human answer and application. It observes one dispatch across sequential successful retries; it is not a real Agent transport proof.

To integrate those steps, pass answer a freshly resolved human member and the record's expected revision. Supply apply with an ApprovalApplyHost: recheck reads the requester's current authority and fence, and dispatch calls your existing operation door. Approval does not grant missing authority. The result belongs to the call that asked: the host that staged the record waits for the answer inside its own tool call, applies it there and returns the output as that call's result. Nothing is sent as a message.

Contract model

submit stages a write needing approval and returns a typed pending_approval status with its recordId and description; the host keeps that tool call open until the answer. A request staged with expiresAt (the waiting call's own deadline) never outlives the call: withdraw expires an unclaimed record when the call is cancelled or ends, and withdrawWaiting does so for every unclaimed record at native boot. On approval the ledger durably claims, rechecks the exact fence and requester's current Mycelium authority, dispatches the existing host operation at most once, and stores applied/denied/outcome_unknown. Auto-approve applies inline through the same record. No MuleTool.resume, Watchdog park/wake, stored tool suspension, or unsafe execute replay belongs to this model.

The member-bound capability exposes approvals.list/get/answer/setAutoApprove. Actors and live grants come from the host, never from request bodies. Reads are bounded and project current answer/policy rights. Answering never grants the requester authority over an operation.

Auto-approve matches a module (or all modules) and access class write/external, optionally for one Agent. ON includes irreversible actions, still records the decision, and never overrides revoked authority. Local and the solo Oyster owner default ON; Teams default OFF. Only the Oyster owner answers on an Oyster. A request with no expiresAt expires after 24 hours (the Oyster home, whose host applies approved records from its own work loop). A call-owned request expires with its call. Expiry never approves.

Current implementation boundary

ApprovalLedger uses a host-supplied native SQLite owner. It stages a stable intended effect, snapshots metadata before hashing yields, stores private input/output separately, serializes answers and claims, and records typed completion or unknown outcome without blindly redispatching. A known host refusal is distinct from App JSON. recoverClaims transitions orphan claims in bounded batches; the native host must call it only at boot, never during a live dispatch.

ledger.capability({ actor, decision }) binds the four public methods. The host must supply fresh member/operation facts on every call and actual durable apply work after a decision; there is no success-shaped default hook. List reads are bounded to at most 100 records with a continuation cursor. Request bodies cannot select their actor. Policy is persisted by home and Agent/module/access family.

Private input bytes are never part of a result sent anywhere: a waiting call receives the operation's own output or a typed refusal. The Local and Hub hosts resolve the waiting call from their own answer hook; the ledger keeps one claim and one effect attempt per record, so a duplicate waiter cannot dispatch twice.

Store tests and the page/RPC consumer fixture do not establish the production behaviors of the hosts or the ten full-host laws.

Host admission policy read

The runtime calls ledger.selectAutoApprove({ agentId, module, access }) to read one effective boolean. This is the same selection request/submit uses: persisted Agent rules win over home rules, then a module rule wins over all modules. setAutoApprove persists the single enabled field in approval_rules; the read neither stages an action nor dispatches it. A true policy value does not attest to current grants, the authority fence, or containment.

Local is an explicit ledger home with default ON, like Oyster; Team defaults OFF. The Local adapter supplies its native SQLite owner. Containment is owned by the Local sandbox integration, not this policy read. Sandbox escapes set requireHumanApproval, so general auto-approve cannot widen a sandboxed command. After the Local host verifies a protected direct-argv prefix rule, it sets prefixPolicyApproved for that one request; the ledger records a policy decision and applies it inline through the ordinary authority recheck. The ledger does not parse shell text, store prefixes, or let an Agent manage them.

Capability-attached visual evidence

ApprovalRecord optionally carries evidence: an array of at most 4 descriptors, each with kind artifact, ref sha256:<64 lowercase hex>, mediaType image/png and bytes (integer 1 through 5 MiB). ApprovalEvidenceSchema is the maintained Effect Schema decoder. These are defensive display ceilings, not execution authority. The ref is a content address, not a URL or a release's opaque artifact: name.

Only the submitting capability supplies ApprovalSubmitHost.evidence to ledger.submit(request, host). The host-only staging API request(request, evidence?) uses the same decoder. ApprovalRequest and tool arguments do not gain an evidence field. Never spread Agent/tool input into the host adapter. Metadata is snapshotted before hashing yields and persisted with the record; get/list and ApprovalView carry it. The immediate pending tool result remains unchanged.

Image content is untrusted display-only data, even when capture was performed by a capability. Never OCR it into instructions, inject it as Agent text or treat it as authority. This package stores metadata only: it does not capture, fetch or validate PNG bytes. Producers/store adapters and display renderers own actual bounded artifact reads, digest/length verification and maintained image decoding. Screenshot capture, workflow result cards, Grove display and the TUI's interactive open-screenshot link are separate owner work, not implemented by this contract. An idempotent retry retains its original evidence: substituting, adding or removing descriptors under the same effect identity returns identity-conflict, never silently changes the reviewed image. Omitted and empty lists both mean no evidence.