aacp-ts 1.1.0

package/README.md

@@ -0,0 +1,122 @@
+# aacp-ts — AACP TypeScript SDK
+
+**Agent Action Compression Protocol — TypeScript SDK**
+
+Deterministic, zero-cost encoding of agent coordination messages.
+TypeScript port of the [Python SDK](https://github.com/MackayAndrew/aacp).
+
+## Install
+
+```bash
+npm install aacp-ts
+```
+
+## Quick start
+
+```typescript
+import { PayrollEncoder, AACPValidator, AACPDecoder } from "aacp-ts";
+
+// Zero-cost rule-based encoding
+const enc = new PayrollEncoder();
+const pkt = enc.fetchEmployees("2026-03");
+console.log(pkt.packet);
+// FETCH|HR|return:HR-Agent|p:1|aacp:1.1|res:emp_salary|period:2026-03|filter:status=active|fmt:json
+console.log(pkt.apiCostUsd); // 0
+
+// Validate any packet
+const validator = new AACPValidator();
+const result = validator.validate(pkt.packet);
+console.log(result.valid);   // true
+console.log(result.summary());
+
+// Decode any packet to English
+const decoder = new AACPDecoder();
+const decoded = decoder.decode(pkt.packet);
+console.log(decoded.english);
+```
+
+## Workflow encoders
+
+```typescript
+import {
+  PayrollEncoder,   // HR payroll — 6 hops
+  ITEncoder,        // IT provisioning — 5 hops
+  InvoiceEncoder,   // AP invoice processing — 3 hops
+  ContractEncoder,  // Legal contract review — 2+ hops
+} from "aacp-ts";
+
+// Full payroll run — all 6 packets, $0.00 total
+const payroll = new PayrollEncoder();
+const packets = payroll.fullRun("2026-03", "2026-02");
+
+// IT provisioning
+const it = new ITEncoder();
+const provision = it.fullProvision("j.smith", "Engineering", ["M365", "Slack"]);
+
+// Invoice processing
+const inv = new InvoiceEncoder();
+const invoice = inv.fullProcess("Acme-Ltd", 4200, "GBP", "PO-441");
+
+// Legal contract review
+const contract = new ContractEncoder();
+contract.flagClause("NDA", "Acme-Ltd", "s7", "ip_rights_restriction", "high", "signature");
+```
+
+## Rule-based encoder (direct)
+
+```typescript
+import { RuleBasedEncoder } from "aacp-ts";
+
+const enc = new RuleBasedEncoder();
+const pkt = enc.encode({
+  task: "FETCH",
+  domain: "HR",
+  returnAgent: "HR-Agent",
+  res: "emp_salary",
+  period: "2026-03",
+  filterExpr: "status=active",
+  fmt: "json",
+});
+```
+
+## Packet format
+
+```
+TASK|DOM|return:AGENT|p:PRIORITY|aacp:1.1|key:value...
+
+TASK and DOM are positional. Everything else is named key:value.
+No empty positional slots.
+
+Valid TASK: FETCH PROC FLAG RESOLVE LOG SEND BUILD MERGE CALC REPORT ACK SYNC
+Valid DOM:  HR FIN SALES LEGAL IT CS MKT
+```
+
+## Development
+
+```bash
+npm install
+npm run build
+npm test
+```
+
+## Relationship to Python SDK
+
+This TypeScript SDK mirrors the Python SDK exactly:
+- Same packet format and AACP version (v1.1)
+- Same workflow encoders with identical output
+- Same validator logic and rules
+- Same decoder output structure
+
+Packets produced by the TypeScript SDK are valid inputs
+to the Python SDK and vice versa.
+
+## Links
+
+- Spec: https://aacp.dev
+- Python SDK: https://github.com/MackayAndrew/aacp
+- IETF Draft: https://datatracker.ietf.org/doc/draft-mackay-aacp/
+- PyPI: https://pypi.org/project/aacp/
+
+## Licence
+
+MIT

package/Src/decoder.ts

@@ -0,0 +1,131 @@
+/**
+ * AACP v1.1 Decoder
+ * Expands AACP packets into human-readable English.
+ * Pure logic. No LLM calls.
+ * Note: decoded output is structural, not semantic.
+ * The packet is always the canonical record.
+ */
+
+import { DecodedPacket } from "./schema";
+
+const TASK_VERBS: Record<string, string> = {
+  FETCH:   "Retrieve",
+  PROC:    "Process",
+  FLAG:    "Flag for review",
+  RESOLVE: "Resolve",
+  LOG:     "Log to audit trail",
+  SEND:    "Send",
+  BUILD:   "Build or provision",
+  MERGE:   "Merge and process",
+  CALC:    "Calculate",
+  REPORT:  "Generate report",
+  ACK:     "Acknowledge",
+  SYNC:    "Synchronise",
+};
+
+const DOMAIN_NAMES: Record<string, string> = {
+  HR:     "Human Resources",
+  FIN:    "Finance",
+  SALES:  "Sales",
+  LEGAL:  "Legal",
+  IT:     "IT",
+  CS:     "Customer Services",
+  MKT:    "Marketing",
+};
+
+export class AACPDecoder {
+
+  decode(packet: string): DecodedPacket {
+    if (!packet || !packet.trim()) {
+      return {
+        english: "Empty packet.",
+        parsed: {},
+        isComplete: false,
+        caveat: "Decoded output is structural. Packet is the canonical record.",
+      };
+    }
+
+    const fields = packet.trim().split("|");
+    const task = fields[0]?.trim() ?? "";
+    const dom  = fields[1]?.trim() ?? "";
+
+    const named: Record<string, string> = {};
+    for (const f of fields.slice(2)) {
+      const trimmed = f.trim();
+      if (!trimmed) continue;
+      const colonIdx = trimmed.indexOf(":");
+      if (colonIdx !== -1) {
+        const key = trimmed.slice(0, colonIdx).toLowerCase();
+        const val = trimmed.slice(colonIdx + 1);
+        named[key] = val;
+      }
+    }
+
+    const verb       = TASK_VERBS[task]   ?? task.toLowerCase();
+    const domainName = DOMAIN_NAMES[dom]  ?? dom;
+    const returnTo   = named["return"]    ?? "unknown agent";
+    const priority   = named["p"]         ?? "2";
+    const priorityLabel = priority === "1" ? "critical priority"
+                        : priority === "3" ? "low priority"
+                        : "standard priority";
+
+    const parts: string[] = [];
+
+    // Core action
+    const res = named["res"];
+    if (res) {
+      parts.push(`${verb} ${res.replace(/_/g, " ")} from the ${domainName} domain`);
+    } else {
+      parts.push(`${verb} in the ${domainName} domain`);
+    }
+
+    // Time period
+    if (named["period"]) parts.push(`for period ${named["period"]}`);
+
+    // Filter
+    if (named["filter"]) parts.push(`filtered to ${named["filter"].replace(/=/g, ": ").replace(/_/g, " ")}`);
+
+    // Format
+    if (named["fmt"]) parts.push(`return as ${named["fmt"].toUpperCase()}`);
+
+    // Rules
+    if (named["rules"]) parts.push(`using rules ${named["rules"]}`);
+
+    // Validate
+    if (named["validate"]) parts.push(`validate against ${named["validate"].replace(/_/g, " ")}`);
+
+    // Flags
+    if (named["flags"]) parts.push(`flag: ${named["flags"].replace(/,/g, ", ")}`);
+
+    // Highlight
+    if (named["highlight"]) parts.push(`highlight: ${named["highlight"].replace(/_/g, " ")}`);
+
+    // Risk
+    if (named["risk"]) parts.push(`risk level: ${named["risk"]}`);
+
+    // Amount
+    if (named["amt"]) {
+      const ccy = named["ccy"] ?? "";
+      parts.push(`amount: ${ccy} ${named["amt"]}`.trim());
+    }
+
+    // Recipient
+    if (named["to"]) parts.push(`send to: ${named["to"].replace(/,/g, ", ")}`);
+
+    // Actor / chain
+    if (named["actor"]) parts.push(`initiated by ${named["actor"]}`);
+    if (named["chain"]) parts.push(`agent chain: ${named["chain"].replace(/,/g, " → ")}`);
+
+    // Routing
+    parts.push(`return result to ${returnTo} (${priorityLabel})`);
+
+    const english = parts.join(", ") + ".";
+
+    return {
+      english,
+      parsed: { task, domain: dom, ...named },
+      isComplete: true,
+      caveat: "Decoded output is structural. Packet is the canonical record.",
+    };
+  }
+}

package/Src/encoders/ruleBasedEncoder.ts

@@ -0,0 +1,140 @@
+/**
+ * AACP v1.1 Rule-Based Encoder
+ * Deterministic, zero-cost encoding for structured input.
+ * Everything except TASK and DOM is a named key:value pair.
+ * No empty positional slots. No LLM calls.
+ */
+
+import { AACP_VERSION, EncodeParams, EncodedPacket } from "../schema";
+import { AACPValidator } from "../validator";
+
+class EncodedPacketImpl implements EncodedPacket {
+  constructor(
+    public packet: string,
+    public domain: string,
+    public task: string,
+    public tokenEstimateEnglish: number,
+    public tokenEstimatePacket: number,
+    public compressionLoss: "none" | "minor" | "partial" | "significant",
+    public lossNote: string | null,
+    public aacpVersion: string,
+    public encoderType: "rule_based" | "llm" | "fallback",
+    public apiCostUsd: number,
+  ) {}
+
+  get compressionRatio(): number {
+    if (this.tokenEstimateEnglish === 0) return 0;
+    return 1 - this.tokenEstimatePacket / this.tokenEstimateEnglish;
+  }
+
+  get reductionPct(): string {
+    return `${(this.compressionRatio * 100).toFixed(1)}%`;
+  }
+
+  summary(): string {
+    return [
+      `PACKET [${this.domain}/${this.task}]`,
+      `  Encoder: ${this.encoderType}  Cost: $${this.apiCostUsd.toFixed(4)}`,
+      `  Loss:    ${this.compressionLoss}`,
+      "",
+      this.packet,
+    ].join("\n");
+  }
+}
+
+export class RuleBasedEncoder {
+  private validator = new AACPValidator();
+
+  encode(params: EncodeParams): EncodedPacket {
+    const {
+      task, domain, returnAgent, priority = "2",
+      res, period, filterExpr, fields, fmt,
+      src, srcPrev, rules, validate, template, dataPtr,
+      amt, ccy, supplier, match, terms, docType, party, clause,
+      issue, risk, block, flags, flagsInherit, req, highlight,
+      status, to, subj, att, flagMsg, tone, sentiment,
+      actor, chain, prog, ltv, loyalty, urgency,
+    } = params;
+
+    // Core: TASK and DOM positional, everything else named
+    const parts: string[] = [
+      task.toUpperCase(),
+      domain.toUpperCase(),
+      `return:${returnAgent}`,
+      `p:${priority}`,
+      `aacp:${AACP_VERSION}`,
+    ];
+
+    const add = (key: string, val: string | number | null | undefined) => {
+      if (val !== null && val !== undefined && String(val).trim() !== "") {
+        parts.push(`${key}:${val}`);
+      }
+    };
+
+    add("res",      res);
+    add("period",   period);
+    add("filter",   filterExpr);
+    add("fields",   fields?.join(","));
+    add("fmt",      fmt);
+    add("src",      src?.join(","));
+    add("src_prev", srcPrev);
+    add("rules",    rules);
+    add("validate", validate);
+    add("tmpl",     template);
+    add("data_ptr", dataPtr);
+    add("amt",      amt !== undefined ? String(amt) : undefined);
+    add("ccy",      ccy?.toUpperCase());
+    add("sup",      supplier?.replace(/ /g, "-"));
+    add("match",    match);
+    add("terms",    terms);
+    add("type",     docType?.toUpperCase());
+    add("party",    party?.replace(/ /g, "-"));
+    add("clause",   clause);
+    add("issue",    issue?.replace(/ /g, "_").toLowerCase());
+    add("risk",     risk?.toLowerCase());
+    add("block",    block);
+    add("flags",    flags?.join(","));
+    add("flags_inherit", flagsInherit?.join(","));
+    add("req",      req?.join(","));
+    add("highlight", highlight);
+    add("status",   status);
+    add("to",       to?.join(","));
+    add("subj",     subj?.replace(/ /g, "_"));
+    add("att",      att);
+    add("flag_msg", flagMsg?.replace(/ /g, "_"));
+    add("sentiment", sentiment?.toLowerCase());
+    add("tone",     tone?.toLowerCase());
+    add("prog",     prog !== undefined ? prog.toFixed(2) : undefined);
+    add("actor",    actor);
+    add("chain",    chain?.join(","));
+    add("ltv",      ltv !== undefined ? String(ltv) : undefined);
+    add("loyalty",  loyalty);
+    add("urgency",  urgency?.toLowerCase());
+
+    const packet = parts.join("|");
+
+    const validation = this.validator.validate(packet);
+    if (!validation.valid) {
+      throw new Error(
+        `Rule-based encoder produced invalid packet:\n` +
+        validation.errors.join("\n") + "\n" + packet
+      );
+    }
+
+    const tokenEstimatePacket  = Math.max(1, Math.floor(packet.length / 4));
+    const tokenEstimateEnglish = 15 + parts.length * 8;
+
+    return new EncodedPacketImpl(
+      packet,
+      domain.toUpperCase(),
+      task.toUpperCase(),
+      tokenEstimateEnglish,
+      tokenEstimatePacket,
+      "none",
+      null,
+      AACP_VERSION,
+      "rule_based",
+      0.0,
+    );
+  }
+}

package/Src/encoders/workflows/contractEncoder.ts

@@ -0,0 +1,68 @@
+/**
+ * AACP v1.1 Contract Review Workflow Encoder
+ * Zero-cost deterministic encoding for legal contract review workflows.
+ */
+
+import { RuleBasedEncoder } from "../ruleBasedEncoder";
+import { EncodedPacket } from "../../schema";
+
+export class ContractEncoder {
+  private enc = new RuleBasedEncoder();
+
+  flagClause(
+    docType: string,
+    party: string,
+    clause: string,
+    issue: string,
+    risk: "low" | "medium" | "high" | "critical",
+    blockAction?: string,
+    returnAgent = "LEG-Agent",
+    priority = "1",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "FLAG", domain: "LEGAL",
+      docType, party, clause, issue, risk,
+      block: blockAction,
+      returnAgent, priority,
+    });
+  }
+
+  reviewContract(
+    docType: string,
+    party: string,
+    rules: string,
+    returnAgent = "LEG-Agent",
+    priority = "1",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "FLAG", domain: "LEGAL",
+      docType, party, rules,
+      returnAgent, priority,
+    });
+  }
+
+  logReview(
+    docType: string,
+    party: string,
+    status: string,
+    returnAgent = "AUD-Agent",
+    priority = "3",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "LOG", domain: "LEGAL",
+      docType, party, status,
+      returnAgent, priority,
+    });
+  }
+
+  fullReview(
+    docType: string,
+    party: string,
+    rules: string,
+  ): EncodedPacket[] {
+    return [
+      this.reviewContract(docType, party, rules),
+      this.logReview(docType, party, "under_review"),
+    ];
+  }
+}

package/Src/encoders/workflows/invoiceEncoder.ts

@@ -0,0 +1,71 @@
+/**
+ * AACP v1.1 Invoice Processing Workflow Encoder
+ * Zero-cost deterministic encoding for AP invoice workflows.
+ */
+
+import { RuleBasedEncoder } from "../ruleBasedEncoder";
+import { EncodedPacket } from "../../schema";
+
+export class InvoiceEncoder {
+  private enc = new RuleBasedEncoder();
+
+  processInvoice(
+    supplier: string,
+    amount: number,
+    currency: string,
+    poNumber: string,
+    terms = "net30",
+    returnAgent = "FIN-Agent",
+    priority = "2",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "PROC", domain: "FIN",
+      res: "invoice",
+      supplier, amt: amount, ccy: currency,
+      match: poNumber, terms,
+      returnAgent, priority,
+    });
+  }
+
+  approvePayment(
+    poNumber: string,
+    returnAgent = "FIN-Agent",
+    priority = "1",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "PROC", domain: "FIN",
+      res: "payment",
+      match: poNumber,
+      req: ["approve"],
+      returnAgent, priority,
+    });
+  }
+
+  logInvoice(
+    poNumber: string,
+    status = "approved",
+    returnAgent = "AUD-Agent",
+    priority = "3",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "LOG", domain: "FIN",
+      res: "invoice",
+      match: poNumber,
+      status,
+      returnAgent, priority,
+    });
+  }
+
+  fullProcess(
+    supplier: string,
+    amount: number,
+    currency: string,
+    poNumber: string,
+  ): EncodedPacket[] {
+    return [
+      this.processInvoice(supplier, amount, currency, poNumber),
+      this.approvePayment(poNumber),
+      this.logInvoice(poNumber),
+    ];
+  }
+}

package/Src/encoders/workflows/itEncoder.ts

@@ -0,0 +1,95 @@
+/**
+ * AACP v1.1 IT Provisioning Workflow Encoder
+ * Zero-cost deterministic encoding for IT provisioning workflows.
+ */
+
+import { RuleBasedEncoder } from "../ruleBasedEncoder";
+import { EncodedPacket } from "../../schema";
+
+export class ITEncoder {
+  private enc = new RuleBasedEncoder();
+
+  createAccount(
+    username: string,
+    dept: string,
+    returnAgent = "IT-Agent",
+    priority = "1",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "BUILD", domain: "IT",
+      res: "ad_account",
+      filterExpr: `usr=${username}`,
+      fields: ["email", "dept", "grp", "pwd_reset"],
+      returnAgent, priority,
+    });
+  }
+
+  assignLicences(
+    username: string,
+    licences: string[],
+    returnAgent = "IT-Agent",
+    priority = "1",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "PROC", domain: "IT",
+      res: "licences",
+      filterExpr: `usr=${username}`,
+      req: licences,
+      returnAgent, priority,
+    });
+  }
+
+  configureAccess(
+    username: string,
+    systems: string[],
+    returnAgent = "IT-Agent",
+    priority = "1",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "BUILD", domain: "IT",
+      res: "access_profile",
+      filterExpr: `usr=${username}`,
+      req: systems,
+      returnAgent, priority,
+    });
+  }
+
+  sendWelcome(
+    username: string,
+    returnAgent = "IT-Agent",
+    priority = "2",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "SEND", domain: "IT",
+      to: [username],
+      subj: `welcome_${username}_onboarding`,
+      flagMsg: "onboarding_complete",
+      returnAgent, priority,
+    });
+  }
+
+  logProvisioning(
+    username: string,
+    actor = "IT-Agent",
+    returnAgent = "AUD-Agent",
+    priority = "2",
+  ): EncodedPacket {
+    return this.enc.encode({
+      task: "LOG", domain: "IT",
+      actor,
+      status: "provisioned",
+      filterExpr: `usr=${username}`,
+      returnAgent, priority,
+    });
+  }
+
+  fullProvision(username: string, dept: string, licences: string[]): EncodedPacket[] {
+    return [
+      this.createAccount(username, dept),
+      this.assignLicences(username, licences),
+      this.configureAccess(username, ["email", "vpn", "sharepoint"]),
+      this.sendWelcome(username),
+      this.logProvisioning(username),
+    ];
+  }
+}