Getting Started

Getting Started

percolation-inversion-compiler-ts is a Node.js package for JavaScript and TypeScript projects that need local JSON reports from AI agent output.

It is useful when an agent result should be checked before it is reused, shared with another agent, exported as a packet, or used to plan the next workflow step. v0.6.0 also helps Node.js agents emit CCR handoff JSONL and check TRC operation candidates without Python at runtime.

Requirements

• Node.js 20 or newer.
• npm, pnpm, yarn, or another package manager that can install npm packages.
• Python is not required for normal npm use.

Install In A Project

npm install percolation-inversion-compiler-ts

Then run:

npx pic-ts demo installed-smoke

If this returns JSON with accepted=true and settled=false, the package is installed and the safety boundary is working as expected.

Create Demo Files

The easiest path is to create a small local demo folder:

npx pic-ts demo bootstrap --output-dir .pic-demo --overwrite

This creates JSON files for a runtime state, runtime input, phase request, and threshold example. These files work in a fresh npm project and do not depend on a cloned repository.

Run A First Workflow

npx pic-ts runtime step --state .pic-demo/runtime_state.json --input .pic-demo/runtime_step_input.json --output .pic-demo/runtime_step_report.generated.json
npx pic-ts packet export --report .pic-demo/runtime_step_report.generated.json --output .pic-demo/packet.json
npx pic-ts packet inspect --packet .pic-demo/packet.json
npx pic-ts phase plan --request .pic-demo/asi_proxy_phase_request.json --compact

This checks a runtime step, turns the report into inert packet data, inspects the packet, and builds a phase plan.

To emit CCR handoff data from the same demo request:

npx pic-ts phase plan --request .pic-demo/asi_proxy_phase_request.json --compact --emit ccr-tasks --output tasks.jsonl
npx pic-ts phase gap --request .pic-demo/asi_proxy_phase_request.json --compact --emit ccr-residuals --output residuals.jsonl

Use In npm Scripts

Add commands to package.json:

{
  "scripts": {
    "agent:check": "pic-ts agent check --compact --profile development",
    "phase:plan": "pic-ts phase plan --compact --profile development"
  }
}

Then run:

npm run agent:check -- --text "Candidate packet: preserve residuals."
npm run phase:plan -- --text "Candidate packet: preserve residuals."

Use In CI

The CLI prints JSON by default. That makes it easy for CI jobs to save reports as artifacts.

npx pic-ts agent check --compact --text "Candidate packet: preserve residuals." --output agent-check.json
npx pic-ts schema --type EffectivePacketGraph --output effective-packet-graph.schema.json

Use As A Library

import { runAgentCheck, schemaByType } from "percolation-inversion-compiler-ts";

const report = runAgentCheck(
  { agent_output: "Candidate packet: preserve residuals." },
  true,
);

const schema = schemaByType("PhaseAccelerationPlan");

See JavaScript SDK for more examples.

Canonical Reference

The Python package remains canonical for the project as a whole:

• Python repository: https://github.com/kadubon/percolation-inversion-compiler
• Python wiki: https://github.com/kadubon/percolation-inversion-compiler/wiki

This npm package follows the public JSON, CLI, schema, conformance, CCR interop, TRC operation-readiness, and safety semantics of Python percolation-inversion-compiler==0.7.0 for npm and JavaScript agent runtimes.