npm - @agentproto/agencies - Versions diffs - 0.1.0-alpha.0 - Mend

@agentproto/agencies 0.1.0-alpha.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (35) hide show

package/AGENTAGENCIES.md +39 -0
package/LICENSE +21 -0
package/README.md +90 -0
package/dist/capacity-98VwY285.d.ts +862 -0
package/dist/chunk-DYQ4A5HV.mjs +649 -0
package/dist/chunk-DYQ4A5HV.mjs.map +1 -0
package/dist/chunk-GAJQ5ZC2.mjs +149 -0
package/dist/chunk-GAJQ5ZC2.mjs.map +1 -0
package/dist/chunk-SOJ4GQR7.mjs +3 -0
package/dist/chunk-SOJ4GQR7.mjs.map +1 -0
package/dist/composition/index.d.ts +61 -0
package/dist/composition/index.mjs +75 -0
package/dist/composition/index.mjs.map +1 -0
package/dist/doctypes/index.d.ts +61 -0
package/dist/doctypes/index.mjs +4 -0
package/dist/doctypes/index.mjs.map +1 -0
package/dist/index.d.ts +32 -0
package/dist/index.mjs +17 -0
package/dist/index.mjs.map +1 -0
package/dist/renderers/index.d.ts +288 -0
package/dist/renderers/index.mjs +321 -0
package/dist/renderers/index.mjs.map +1 -0
package/dist/validators/index.d.ts +70 -0
package/dist/validators/index.mjs +4 -0
package/dist/validators/index.mjs.map +1 -0
package/package.json +94 -0
package/src/spec/canvakit-templates/agency.agency-overview/template.canvakit.html +173 -0
package/src/spec/canvakit-templates/agency.agency-profile/template.canvakit.html +121 -0
package/src/spec/canvakit-templates/agency.agreement-signing/template.canvakit.html +164 -0
package/src/spec/canvakit-templates/agency.deliverable-review/template.canvakit.html +148 -0
package/src/spec/canvakit-templates/agency.engagement-dashboard/template.canvakit.html +191 -0
package/src/spec/canvakit-templates/agency.invoice-pdf/template.canvakit.html +142 -0
package/src/spec/canvakit-templates/agency.procedure-card/template.canvakit.html +93 -0
package/src/spec/snippets/agency-overview-rollup/procedures/compute-agency-overview/PROCEDURE.md +88 -0
package/src/spec/snippets/agency-overview-rollup/routines/agency-overview-rollup/ROUTINE.md +58 -0

package/src/spec/canvakit-templates/agency.procedure-card/template.canvakit.html ADDED Viewed

@@ -0,0 +1,93 @@
+---
+template: true
+name: agency.procedure-card
+version: 1.0.0-alpha
+description: |
+  Narrative card view of a PROCEDURE.md — what it does, who triggers it,
+  what skills it requires, and the step list. Doubles as an in-product help
+  surface ("how does this engagement work?") and a published preview on
+  agencies.sh template registry pages.
+  Reads the source PROCEDURE.md by path; the host is responsible for
+  computing `currentStepId` if rendered inside an active engagement context
+  (so the card can highlight progress).
+author: agencies.sh
+refreshEvery: 5m
+variables:
+  agencyName: ""
+  procedurePath: "procedures/example/PROCEDURE.md"
+  currentStepId: ""
+sources:
+  procedure:
+    kind: file
+    path: "{{procedurePath}}"
+---
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{{procedure.name}} · procedure</title>
+    <style>
+      :root { --fg: #1a1a1a; --muted: #666; --bg: #faf9f7; --panel: #fff; --border: #e5e5e5; --accent: #1a1a1a; --done: #0a7d30; --active: #2563eb; }
+      body { font: 15px/1.55 ui-sans-serif, system-ui, sans-serif; max-width: 44rem; margin: 0 auto; padding: 2.5rem 1.5rem; color: var(--fg); background: var(--bg); }
+      header { margin-bottom: 1.5rem; }
+      .lead { color: var(--muted); margin: 0 0 0.25rem; font-size: 0.875rem; text-transform: uppercase; letter-spacing: 0.06em; }
+      h1 { font-size: 1.625rem; letter-spacing: -0.01em; margin: 0; }
+      .description { color: #333; margin: 0.5rem 0 1.5rem; font-size: 1rem; line-height: 1.55; }
+      .panel { background: var(--panel); border: 1px solid var(--border); border-radius: 8px; padding: 1.25rem 1.5rem; margin-bottom: 1.25rem; }
+      .panel h2 { font-size: 0.8125rem; text-transform: uppercase; letter-spacing: 0.08em; color: #666; margin: 0 0 0.875rem; }
+      .meta { display: grid; grid-template-columns: max-content 1fr; gap: 0.4rem 1rem; font-size: 0.875rem; }
+      .meta dt { font-weight: 500; color: #444; }
+      .meta dd { margin: 0; }
+      .pill { display: inline-block; padding: 0.125rem 0.5rem; border-radius: 999px; font-size: 0.75rem; background: #f0eee5; color: #444; margin-right: 0.25rem; margin-bottom: 0.25rem; }
+      .steps { list-style: none; padding: 0; margin: 0; counter-reset: step; }
+      .step { position: relative; padding: 0.875rem 0 0.875rem 2.75rem; border-bottom: 1px solid #efece5; }
+      .step:last-child { border-bottom: 0; }
+      .step::before { content: counter(step); counter-increment: step; position: absolute; left: 0; top: 0.875rem; width: 1.875rem; height: 1.875rem; border-radius: 999px; background: #f0eee5; color: #555; font-weight: 600; font-size: 0.875rem; display: flex; align-items: center; justify-content: center; }
+      .step.active::before { background: var(--active); color: #fff; }
+      .step.done::before { background: var(--done); color: #fff; content: "✓"; counter-increment: step; }
+      .step .name { font-weight: 500; font-size: 0.9375rem; }
+      .step .name .marker { display: none; }
+      .step.active .name .marker { display: inline-block; padding: 0.125rem 0.5rem; border-radius: 999px; font-size: 0.6875rem; background: var(--active); color: #fff; margin-left: 0.5rem; }
+      .step .desc { color: var(--muted); font-size: 0.875rem; margin-top: 0.25rem; line-height: 1.55; }
+      .step .skill { font-size: 0.75rem; color: #777; margin-top: 0.25rem; }
+    </style>
+  </head>
+  <body>
+    <header>
+      <p class="lead">{{#agencyName}}{{agencyName}} · {{/agencyName}}procedure</p>
+      <h1>{{procedure.name}}</h1>
+      <p class="description">{{procedure.description}}</p>
+    </header>
+    <section class="panel">
+      <h2>Overview</h2>
+      <dl class="meta">
+        <dt>Estimated duration</dt><dd>{{procedure.estimatedDuration}}</dd>
+        <dt>Required skills</dt><dd>
+          {{#procedure.requiredSkills}}<span class="pill">{{.}}</span>{{/procedure.requiredSkills}}
+        </dd>
+        <dt>Triggers</dt><dd>
+          {{#procedure.triggerLabels}}<span class="pill">{{.}}</span>{{/procedure.triggerLabels}}
+        </dd>
+        {{#procedure.autonomyPolicy}}
+        <dt>Autonomy policy</dt><dd><code>{{.}}</code></dd>
+        {{/procedure.autonomyPolicy}}
+      </dl>
+    </section>
+    <section class="panel">
+      <h2>Steps</h2>
+      <ol class="steps">
+        {{#procedure.steps}}
+        <li class="step {{stateClass}}">
+          <div class="name">{{name}}<span class="marker">In progress</span></div>
+          <div class="desc">{{description}}</div>
+          {{#requiredSkill}}<div class="skill">requires <code>{{.}}</code></div>{{/requiredSkill}}
+        </li>
+        {{/procedure.steps}}
+      </ol>
+    </section>
+  </body>
+</html>

package/src/spec/snippets/agency-overview-rollup/procedures/compute-agency-overview/PROCEDURE.md ADDED Viewed

@@ -0,0 +1,88 @@
+---
+schema: agentagencies/v1
+doctype: procedure
+slug: compute-agency-overview
+name: Compute agency overview snapshot
+description: |
+  Walk the workspace and emit a fresh agency-overview snapshot. Vendor-neutral
+  playbook — any orchestration runtime can follow these steps (the canonical
+  implementation lives in `@agencies/spec/runtime` as
+  `computeAgencyOverview(config)`).
+triggers:
+  - routine: agency-overview-rollup
+requiredSkills:
+  - workspace.read
+estimatedDuration: PT30S
+steps:
+  - id: walk-counterparties
+    description: |
+      List counterparties/*/COUNTERPARTY.md and project the active subset
+      (mergedIntoId == null, status != "archived"). Used to count distinct
+      counterparties in the snapshot.
+    output: in-memory list
+  - id: walk-engagements
+    description: |
+      List engagements/*/ENGAGEMENT.md and parse frontmatter for status,
+      activeStep, expected value (sum of AGREEMENT.md line items), and
+      requiredSignatures. Group by status to fill `byStatus`. Compute
+      `pipelineValueFormatted` = sum of expected value where status ∈
+      {`scoping`, `proposed`, `negotiating`}.
+  - id: walk-invoices
+    description: |
+      Scan engagements/*/invoices/*/INVOICE.md. Sum paidAmount per month for
+      MRR; collect the top-N most-recent paid invoices for `recentPayments`.
+  - id: walk-pending-signatures
+    description: |
+      Read `_index/pending-signatures.json` (regeneratable; rebuild from
+      a directory walk if missing). Group by engagement, compute oldest
+      pending age. Tag staleness label per (oldest, threshold).
+  - id: project-snapshot
+    description: |
+      Assemble the result against `AgencyOverviewSnapshot` shape from
+      `@agencies/spec/renderers`. Stamp `generatedAt = now`. Validate
+      against `agencyOverviewSnapshotSchema` before writing.
+  - id: write-snapshot
+    description: |
+      Atomically write `_snapshots/agency-overview.json`. The dashboard
+      reads this file on its next refresh tick.
+    output: _snapshots/agency-overview.json
+  - id: record-audit
+    description: |
+      Append a `snapshot.refreshed` entry to `audit/audit-log.jsonl` with
+      the row counts as payload (counterparties, engagements, invoices).
+      Lets operators see "did the rollup actually run?" in the dashboard's
+      audit feed.
+    output: audit/audit-log.jsonl (one line)
+---
+# Compute agency overview snapshot
+The vendor-neutral playbook for the agency-overview rollup. The agencies/v1
+runtime ships a Node implementation as `computeAgencyOverview()` from
+`@agencies/spec/runtime`. Other runtimes (Temporal, n8n, hand-rolled) can follow
+the steps above — every step has a deterministic input/output described in the
+workspace contract.
+## Performance notes
+The walk is O(N) over engagements + invoices. For an agency with 500 engagements
+and 50 invoices each, expect ~0.5–1s on cold cache. Most cost is in YAML
+frontmatter parsing — if that becomes a bottleneck, cache parsed frontmatter
+keyed by `(path, mtime)` between invocations.
+## Failure modes
+- **Corrupted ENGAGEMENT.md** — the walker logs the path + skips the row. The
+  audit-log entry includes a `skipped` count so operators see drift.
+- **Missing `_index/pending-signatures.json`** — falls back to a fresh walk of
+  `signatures/` directories. Slower but correct.
+- **Concurrent writes during walk** — the snapshot is a best-effort
+  point-in-time view. The next tick (10m) reconciles.

package/src/spec/snippets/agency-overview-rollup/routines/agency-overview-rollup/ROUTINE.md ADDED Viewed

@@ -0,0 +1,58 @@
+---
+schema: agentagencies/v1
+doctype: routine
+slug: agency-overview-rollup
+name: Agency overview rollup
+description: |
+  Recompute the agency-wide overview snapshot every 10 minutes. The procedure
+  walks counterparties/, engagements/, invoices/ and writes a JSON file at
+  `_snapshots/agency-overview.json` for the agency.agency-overview canvakit
+  template to read.
+  Cheap to recompute (a directory walk + frontmatter parse), so the cadence
+  errs on the side of fresh. Bump down to 5 minutes if operators complain
+  about staleness; bump up to 30 minutes if the agency has hundreds of
+  engagements and the walk becomes expensive.
+runs: compute-agency-overview
+trigger:
+  kind: schedule
+  cronExpression: "*/10 * * * *"
+  timezone: UTC
+escalation:
+  ifPendingAfter: PT2H
+  escalateTo:
+    - operator:founder
+metadata:
+  agency:
+    canonical: true
+---
+# Agency overview rollup
+Schedules the **`compute-agency-overview`** procedure every 10 minutes. The
+procedure does a single-pass walk of the workspace, projects the aggregate into
+a JSON snapshot, and writes it to `_snapshots/agency-overview.json`.
+The agency dashboard (canvakit template `agency.agency-overview`) reads the
+snapshot via a `kind: file` data source — no live globs at render time, so the
+page stays cheap regardless of engagement count.
+## When to override this routine
+Fork this ROUTINE.md if you need:
+- **A different cadence** — change `cronExpression`. Match it to your operators'
+  working hours if you don't need 24/7 freshness.
+- **An additional snapshot** — copy this routine, change `runs` to a sibling
+  procedure that writes a different snapshot file (e.g.,
+  `_snapshots/cashflow.json` for a cashflow widget).
+- **Per-vertical aggregations** — your `compute-agency-overview` procedure can
+  branch on `AGENCY.md.verticals[]` and emit verticalized stats.
+## How to disable
+Delete this file. The procedure can still be invoked ad-hoc via
+`runProcedureTool({ slug: "compute-agency-overview" })`, and the dashboard will
+simply show whatever snapshot is on disk (or render the staleness banner if
+none).