@desplega.ai/agent-swarm 2.7.9 → 2.8.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.
- package/dist/acp-adapter-t949vbbp.js +15 -0
- package/dist/{actions-g563mbn2.js → actions-7e9czc7s.js} +19 -19
- package/dist/{amp-adapter-q61w05eb.js → amp-adapter-gv6cbb7d.js} +2 -3
- package/dist/app-b9fbkp9v.js +20 -0
- package/dist/{assistant-p477rjwj.js → assistant-wjb7v4c7.js} +22 -22
- package/dist/{boot-args-schema-h4qj462e.js → boot-args-schema-2t37e0fe.js} +1 -1
- package/dist/{boot-reembed-n1ehfbsw.js → boot-reembed-a35nkyr1.js} +1 -1
- package/dist/{boot-reembed-qw4mc0pt.js → boot-reembed-gka3zas7.js} +1 -1
- package/dist/{boot-scrub-sweep-9w9jp4sm.js → boot-scrub-sweep-65sdnp6c.js} +3 -3
- package/dist/{boot-seeds-qdaf3sdy.js → boot-seeds-x42tzytw.js} +4 -5
- package/dist/{claude-adapter-348p5hx9.js → claude-adapter-v221b2fd.js} +7 -8
- package/dist/{claude-managed-adapter-h74d06yz.js → claude-managed-adapter-29eq09wd.js} +2 -2
- package/dist/{claude-managed-setup-7787fxtp.js → claude-managed-setup-9m6450zk.js} +2 -2
- package/dist/{claude-sdk-session-hbszbt8a.js → claude-sdk-session-0q0ptaba.js} +9066 -8818
- package/dist/{cli-n5yexkdg.js → cli-0b4zam62.js} +1 -0
- package/dist/{cli-21159vea.js → cli-0jzra9ad.js} +2 -2
- package/dist/{cli-eqtfgfr6.js → cli-2gxeg5gr.js} +1 -1
- package/dist/{cli-k70e3x9e.js → cli-2wnq8jkz.js} +9 -9
- package/dist/{cli-cvs2r2vq.js → cli-2zp0et3v.js} +59 -6
- package/dist/{cli-650zv9q9.js → cli-334z18y3.js} +4 -4
- package/dist/{cli-12xyjhws.js → cli-3rkdne1h.js} +2 -2
- package/dist/{cli-2a8py3sx.js → cli-4txa0ter.js} +5 -7
- package/dist/{cli-jc1g9ndz.js → cli-5j88qqa8.js} +10 -5
- package/dist/{cli-xfjrc279.js → cli-5mrq3ake.js} +48 -14
- package/dist/{cli-v3cf1ts9.js → cli-6t09sdhy.js} +3 -3
- package/dist/{cli-qzt90yze.js → cli-6wxjceza.js} +8 -8
- package/dist/{cli-9aezs55w.js → cli-7b8sbmag.js} +8 -8
- package/dist/{cli-3xj33nrx.js → cli-7cp6aa1q.js} +10 -3
- package/dist/{cli-jfx48xrj.js → cli-7p1kvkck.js} +6 -6
- package/dist/{cli-b932gexn.js → cli-8aes17e4.js} +2 -2
- package/dist/{cli-3tqcamp6.js → cli-8fknbnhw.js} +14 -13
- package/dist/{cli-587857ys.js → cli-8kzasymh.js} +3 -3
- package/dist/{cli-sgs5k6yd.js → cli-a7wvp2km.js} +1 -1
- package/dist/{cli-varqt4d1.js → cli-abejgen1.js} +69 -22
- package/dist/{cli-rwymrnaz.js → cli-bsywb58a.js} +8 -8
- package/dist/{cli-btc9cb4c.js → cli-c55z5chy.js} +4 -6
- package/dist/{cli-ms5m5r1y.js → cli-deefvewm.js} +1 -1
- package/dist/{cli-p17970qv.js → cli-ee0b971j.js} +3 -3
- package/dist/cli-f3vq58d2.js +242 -0
- package/dist/{cli-3xcwp3z8.js → cli-ffhtssbp.js} +2 -2
- package/dist/{cli-hwprv9e4.js → cli-g70vxtjh.js} +2 -2
- package/dist/{cli-4t0fmf3z.js → cli-gxkx0zzp.js} +1 -1
- package/dist/{cli-neyag5p6.js → cli-h38x262p.js} +3365 -429
- package/dist/{cli-2ccpqyyf.js → cli-j790gp2w.js} +105 -22
- package/dist/{cli-f2zenhja.js → cli-kc7v1nfv.js} +1 -1
- package/dist/{cli-vxh6acp7.js → cli-m23zjcy2.js} +10 -10
- package/dist/{cli-y8nbefpb.js → cli-m28atx8q.js} +12 -10
- package/dist/{cli-serm8zrx.js → cli-m4dqmnbp.js} +1 -1
- package/dist/{cli-ybjdc978.js → cli-mrt48bx7.js} +7 -4
- package/dist/{cli-y5rbvxhc.js → cli-n515ex5z.js} +14 -14
- package/dist/{cli-ypff1qwp.js → cli-n9ftpys4.js} +7 -7
- package/dist/{cli-605nn699.js → cli-p1bq50aa.js} +894 -226
- package/dist/{cli-qkdmz8c8.js → cli-p1w18yhx.js} +1 -1
- package/dist/{cli-xk879m3k.js → cli-p2gfst4m.js} +52 -43
- package/dist/{cli-sya22y84.js → cli-pasjcnmj.js} +12 -12
- package/dist/{cli-0whpms1z.js → cli-qa4wdgsy.js} +5 -5
- package/dist/{cli-ejkvvqbe.js → cli-qfedvmcr.js} +50 -24
- package/dist/{cli-tqq0hspb.js → cli-qmqk2yc2.js} +1 -1
- package/dist/{cli-qmd3mse0.js → cli-qsnnd04k.js} +1 -1
- package/dist/{cli-agyaeef4.js → cli-qwca7s44.js} +3 -3
- package/dist/{cli-fayav105.js → cli-rfywm85n.js} +724 -792
- package/dist/{cli-zgv8gxgs.js → cli-rmmpt0wm.js} +6 -6
- package/dist/{cli-hae9j8sv.js → cli-rzsy6nc6.js} +12 -8
- package/dist/{cli-btf6fw39.js → cli-s7t6p9my.js} +1 -1
- package/dist/{cli-cseh6f8w.js → cli-sdtt3men.js} +1 -1
- package/dist/{cli-9r5gtwjr.js → cli-tk7cjj8h.js} +197 -2
- package/dist/{cli-q26b9wre.js → cli-tph5wt3y.js} +4 -4
- package/dist/{cli-gce09r66.js → cli-tqegb8eq.js} +3 -3
- package/dist/{cli-kf3pxxdg.js → cli-v1dv1r37.js} +1 -1
- package/dist/{cli-09kmfkmq.js → cli-wcg8x116.js} +1 -1
- package/dist/{cli-mnrkgg60.js → cli-wk18cm92.js} +5 -5
- package/dist/{cli-p0m0p34z.js → cli-x1wa213s.js} +3 -3
- package/dist/{cli-jrp1dt73.js → cli-xzm9vcfg.js} +1 -1
- package/dist/{cli-715t1gx6.js → cli-y97qxcfx.js} +9 -9
- package/dist/{cli-bc779n4v.js → cli-yq3zak69.js} +1 -1
- package/dist/cli.js +17 -17
- package/dist/{codex-adapter-ysq6bzha.js → codex-adapter-30j9bpzd.js} +5 -6
- package/dist/{codex-hook-fac6175r.js → codex-hook-h3vk6xzr.js} +1 -1
- package/dist/{codex-session-runner-qakzfx93.js → codex-session-runner-8vp57v8w.js} +5 -6
- package/dist/{commands-rs7hkv9r.js → commands-bngnz9g7.js} +3 -3
- package/dist/{controller-r5x9bg6e.js → controller-hxx8wwy1.js} +2 -2
- package/dist/{controllers-connect-498hrxvk.js → controllers-connect-e2b4gyxc.js} +20 -20
- package/dist/{cursor-adapter-d46qszer.js → cursor-adapter-n5nc3mfe.js} +1 -2
- package/dist/{db-s13dqhr6.js → db-bgm7vkc0.js} +3 -3
- package/dist/{db-pm96nhdb.js → db-c6np41ca.js} +12 -2
- package/dist/{devin-adapter-z46ep5ph.js → devin-adapter-xedz98zv.js} +1 -1
- package/dist/{dispatcher-j3h81t7m.js → dispatcher-jnybck15.js} +18 -18
- package/dist/{dsh-adapter-rw0d5rc4.js → dsh-adapter-nrhbrjz8.js} +1 -2
- package/dist/{easter-egg-3d-qtgfxgze.js → easter-egg-3d-533knw22.js} +1 -1
- package/dist/{embedding-space-xh8p4q4x.js → embedding-space-crsm2zp0.js} +6 -6
- package/dist/{embeddings-wp745m91.js → embeddings-e7z3f27f.js} +1 -1
- package/dist/{execute-2fzb9z74.js → execute-b3mrb1mv.js} +1 -1
- package/dist/{external-channel-ys21h3sy.js → external-channel-m77wf5z3.js} +2 -2
- package/dist/{fx-adapter-vz0b9z3g.js → fx-adapter-b6w0kf56.js} +7 -8
- package/dist/{google-generative-ai-ytpgncx9.js → google-generative-ai-h7s3e9kk.js} +1 -1
- package/dist/{google-vertex-tqhze5j7.js → google-vertex-fhxaafzw.js} +1 -1
- package/dist/{grok-adapter-spea7zkj.js → grok-adapter-4sqtebdk.js} +7 -8
- package/dist/handlers-kdjcyzdj.js +32 -0
- package/dist/heartbeat-xgb036sx.js +43 -0
- package/dist/{hook-amcj4s10.js → hook-5h02c9ga.js} +6 -6
- package/dist/{hook-bc6n49qn.js → hook-xsk1jbha.js} +5 -5
- package/dist/{http-7374brv5.js → http-txe7qhvn.js} +448 -165
- package/dist/{index-pxn30mse.js → index-0eny15vj.js} +8 -8
- package/dist/{index-5a9jtqde.js → index-0rvk3vd4.js} +46 -46
- package/dist/{index-fvzke5kx.js → index-1qw6f2dc.js} +10 -10
- package/dist/{index-q5cmtbz5.js → index-4a0670yh.js} +15939 -14244
- package/dist/index-835xdgnm.js +33 -0
- package/dist/index-d469300x.js +37 -0
- package/dist/{index-h7f61sy9.js → index-e5pfbsys.js} +3 -3
- package/dist/{index-hsad2t3r.js → index-m5gx1xd6.js} +38 -38
- package/dist/{index-5fx3b3kw.js → index-rvccek1w.js} +9 -9
- package/dist/index-rzqwp11g.js +32 -0
- package/dist/{index-w4m9z29z.js → index-tvfafeyy.js} +1 -1
- package/dist/{index-c9y31ytf.js → index-vk63emp7.js} +979 -35
- package/dist/{index-514d9pf6.js → index-w7em4ktq.js} +8 -8
- package/dist/{index-p4hjwbvw.js → index-ysvbhg5m.js} +1 -1
- package/dist/{keepalive-wy29kbrg.js → keepalive-4zsrce78.js} +3 -3
- package/dist/lead-yqt47dkr.js +70 -0
- package/dist/{maintenance-h2ds9w6c.js → maintenance-86jvartk.js} +1 -1
- package/dist/{oauth-refresh-sweep-q7mtbyp3.js → oauth-refresh-sweep-j52kg9pr.js} +2 -2
- package/dist/{onboard-vw8r2fdw.js → onboard-c2aj5p8q.js} +3 -3
- package/dist/{opencode-adapter-mtb0953j.js → opencode-adapter-dsagkhtw.js} +5 -6
- package/dist/{otel-impl-j42czw3r.js → otel-impl-yyy203z8.js} +1 -1
- package/dist/{pi-mono-adapter-zk8pg9jr.js → pi-mono-adapter-546cd1cc.js} +9 -9
- package/dist/{pricing-refresh-x7nhv23d.js → pricing-refresh-1rgzqyzz.js} +2 -3
- package/dist/{rbac-roles-9044425x.js → rbac-roles-e70xfeyj.js} +4 -6
- package/dist/{rbac-roles-bzvee6cf.js → rbac-roles-q89qe8er.js} +3 -3
- package/dist/{registry-hpjfmcfz.js → registry-32b1mft6.js} +1 -1
- package/dist/{render-v2-t7bn4skz.js → render-v2-k6tt107q.js} +9 -4
- package/dist/{resume-x94gemep.js → resume-cnnrjfxa.js} +6 -6
- package/dist/{runtime-breq6fmv.js → runtime-1hv06jsn.js} +1 -1
- package/dist/{session-access-q7dmqjvt.js → session-access-xkxkjw3n.js} +4 -4
- package/dist/{session-source-backfill-440ysamr.js → session-source-backfill-1d5pdwww.js} +2 -2
- package/dist/{setup-07n4727s.js → setup-se8q7gkc.js} +1 -1
- package/dist/{virtual-modules-z5h6mcyf.js → virtual-modules-gazyapte.js} +3 -3
- package/dist/{work-objects-pnq5y534.js → work-objects-1kxnbzy5.js} +22 -22
- package/dist/{worker-follow-up-7z1gfkr8.js → worker-follow-up-zqm8apt4.js} +18 -18
- package/dist/worker-j6xxtq7p.js +70 -0
- package/openapi.json +334 -7
- package/package.json +4 -4
- package/src/apps/catalog.generated.json +55 -0
- package/src/apps/definition.ts +11 -0
- package/src/apps/page-validator.ts +19 -0
- package/src/apps/store.ts +28 -8
- package/src/assets/key.ts +77 -4
- package/src/be/db/model-profiles.ts +147 -38
- package/src/be/db/session-labels.ts +57 -0
- package/src/be/db/session-tree.ts +51 -7
- package/src/be/db/slack-trees.ts +146 -0
- package/src/be/db/tasks/read.ts +107 -8
- package/src/be/db/workflow-run-definitions.ts +117 -0
- package/src/be/db-client.ts +8 -2
- package/src/be/db.ts +119 -87
- package/src/be/event-loop-lag.ts +146 -0
- package/src/be/mcp-overflow-sweep.ts +2 -1
- package/src/be/memory/constants.ts +14 -1
- package/src/be/memory/key-paths.ts +8 -0
- package/src/be/memory/providers/sqlite-store.ts +199 -18
- package/src/be/memory/task-learning.ts +79 -14
- package/src/be/memory/types.ts +24 -1
- package/src/be/migrations/278_slack_render_v2_reconcile.sql +108 -0
- package/src/be/migrations/279_backfill_learning_expiry.sql +15 -0
- package/src/be/migrations/281_model_profiles_pr2.sql +28 -0
- package/src/be/migrations/283_workflow_run_definitions.sql +14 -0
- package/src/be/model-profile-check.ts +284 -0
- package/src/be/model-tier-resolution.ts +112 -12
- package/src/be/multi-runtime.ts +27 -0
- package/src/be/runtime-pools/routing.ts +52 -4
- package/src/be/scripts/typecheck.ts +1 -0
- package/src/be/seed-scripts/catalog/dreaming-learnings.ts +552 -0
- package/src/be/seed-scripts/catalog/dreaming-memtax-create.ts +389 -14
- package/src/be/seed-scripts/catalog/dreaming-memtax.ts +6 -3
- package/src/be/seed-scripts/index.ts +9 -0
- package/src/be/steering.ts +8 -2
- package/src/be/swarm-config-guard.ts +2 -0
- package/src/commands/context-preamble.ts +258 -0
- package/src/commands/onboard/agent-fs-version.ts +1 -1
- package/src/commands/runner.ts +32 -1
- package/src/extensions/catalog.generated.json +3 -3
- package/src/fs/provider.ts +17 -3
- package/src/heartbeat/heartbeat.ts +17 -5
- package/src/heartbeat/index.ts +1 -0
- package/src/http/agents.ts +56 -4
- package/src/http/apps.ts +3 -1
- package/src/http/config.ts +2 -6
- package/src/http/core.ts +9 -3
- package/src/http/index.ts +12 -9
- package/src/http/memory.ts +9 -4
- package/src/http/model-profiles.ts +58 -10
- package/src/http/poll.ts +36 -3
- package/src/http/schedules.ts +42 -3
- package/src/http/sessions.ts +16 -3
- package/src/http/tasks.ts +37 -12
- package/src/http/utils.ts +18 -0
- package/src/http/webhooks.ts +48 -0
- package/src/http/workflows.ts +15 -2
- package/src/integrations/chat-sdk/commands.ts +167 -31
- package/src/integrations/chat-sdk/inbound.ts +10 -8
- package/src/integrations/chat-sdk/message-text.ts +117 -0
- package/src/prompts/session-templates.ts +1 -1
- package/src/providers/acp-targets.ts +11 -6
- package/src/providers/amp-adapter.ts +1 -1
- package/src/providers/claude-sdk-session.ts +132 -23
- package/src/providers/codex-skill-resolver.ts +10 -4
- package/src/providers/cursor-adapter.ts +1 -1
- package/src/providers/devin-skill-resolver.ts +5 -5
- package/src/providers/dsh-adapter.ts +1 -1
- package/src/scheduler/schedule-task.ts +1 -0
- package/src/scheduler/scheduler.ts +4 -1
- package/src/scripts-runtime/executors/quickjs-runner.ts +2 -0
- package/src/scripts-runtime/executors/quickjs-structured-clone.ts +180 -0
- package/src/scripts-runtime/quickjs-compat.ts +0 -1
- package/src/scripts-runtime/sdk-allowlist.ts +1 -0
- package/src/scripts-runtime/swarm-sdk.ts +18 -1
- package/src/scripts-runtime/types/stdlib.d.ts +1 -0
- package/src/scripts-runtime/types/swarm-sdk.d.ts +1 -0
- package/src/server.ts +2 -0
- package/src/slack/app.ts +425 -10
- package/src/slack/handlers.ts +9 -2
- package/src/slack/inbound-dispatch.ts +18 -1
- package/src/slack/index.ts +7 -1
- package/src/slack/lifecycle-lock.ts +29 -0
- package/src/slack/render-v2.ts +424 -212
- package/src/slack/socket-fence.ts +64 -0
- package/src/slack/watcher.ts +42 -8
- package/src/slack/workspace-guard.ts +345 -0
- package/src/tasks/task-terminal-effects.ts +4 -0
- package/src/tasks/worker-follow-up.ts +102 -2
- package/src/tests/acp-adapter.test.ts +82 -0
- package/src/tests/apps-icon.test.ts +120 -0
- package/src/tests/apps-schema-form.test.ts +151 -0
- package/src/tests/chained-task-follow-up.test.ts +248 -0
- package/src/tests/chat-sdk-commands.test.ts +359 -2
- package/src/tests/chat-sdk-inbound.test.ts +20 -0
- package/src/tests/chat-sdk-slack.test.ts +189 -1
- package/src/tests/check-pr-body.test.ts +40 -0
- package/src/tests/claude-sdk-lifecycle.test.ts +216 -1
- package/src/tests/claude-sdk-process.fixture.ts +57 -0
- package/src/tests/codex-skill-resolver.test.ts +31 -0
- package/src/tests/credentials-allowlist.test.ts +470 -0
- package/src/tests/db-client-busy-retry.test.ts +69 -18
- package/src/tests/db-client.test.ts +26 -1
- package/src/tests/db-task-read-contract.test.ts +7 -0
- package/src/tests/db-task-write-contract.test.ts +6 -0
- package/src/tests/deferred-wake-follow-up.test.ts +47 -0
- package/src/tests/docs-index-footprint.test.js +3 -3
- package/src/tests/dreaming-learnings.test.ts +1395 -0
- package/src/tests/dsh-adapter.test.ts +1 -1
- package/src/tests/event-loop-lag.test.ts +184 -0
- package/src/tests/explicit-model-validation.test.ts +2 -0
- package/src/tests/extensions-example-comms-adherence-gate.test.ts +115 -0
- package/src/tests/fs-provider.test.ts +42 -0
- package/src/tests/github-webhook-early-ack.test.ts +144 -0
- package/src/tests/heartbeat.test.ts +28 -1
- package/src/tests/http-api-integration.test.ts +2 -0
- package/src/tests/http-log-scrubbing.test.ts +68 -2
- package/src/tests/human-free-reclassify.test.ts +5 -1
- package/src/tests/kv-storage.test.ts +92 -1
- package/src/tests/list-endpoint-slimming.test.ts +17 -0
- package/src/tests/memory-key-paths.test.ts +57 -0
- package/src/tests/memory-retrieval-purge.test.ts +19 -0
- package/src/tests/migration-283-workflow-run-definitions.test.ts +69 -0
- package/src/tests/model-profile-check.test.ts +387 -0
- package/src/tests/model-profiles-api.test.ts +528 -1
- package/src/tests/profile-claim.test.ts +415 -3
- package/src/tests/profile-tier-alias.test.ts +382 -0
- package/src/tests/quickjs-compat.test.ts +1 -1
- package/src/tests/runner-context-preamble.test.ts +552 -0
- package/src/tests/schedule-profile.test.ts +359 -0
- package/src/tests/script-connections.test.ts +9 -0
- package/src/tests/script-executor-conformance.test.ts +188 -0
- package/src/tests/script-per-script-executor.test.ts +1 -0
- package/src/tests/scripts-sdk-bridge-tool-failure.test.ts +141 -0
- package/src/tests/seed-scripts.test.ts +2 -2
- package/src/tests/sessions-tree.test.ts +133 -2
- package/src/tests/slack-app-icon.test.ts +4 -0
- package/src/tests/slack-dm-implicit-mention.test.ts +236 -0
- package/src/tests/slack-file-tools-attachments.test.ts +1 -0
- package/src/tests/slack-inbound-receipts.test.ts +22 -2
- package/src/tests/slack-read-boundaries.test.ts +4 -3
- package/src/tests/slack-render-v2-query-plans.test.ts +262 -3
- package/src/tests/slack-render-v2-reconcile.test.ts +201 -0
- package/src/tests/slack-socket-ack.test.ts +16 -1
- package/src/tests/slack-socket-watchdog.test.ts +748 -0
- package/src/tests/slack-workspace-guard.test.ts +905 -0
- package/src/tests/steering-core.test.ts +40 -0
- package/src/tests/store-progress-learning.test.ts +605 -20
- package/src/tests/tool-annotations.test.ts +1 -1
- package/src/tests/vcs-identity-inheritance.test.ts +85 -0
- package/src/tests/workflow-convergence.test.ts +46 -40
- package/src/tests/workflow-definition-pinning-recovery.test.ts +552 -0
- package/src/tests/workflow-definition-pinning.test.ts +645 -0
- package/src/tests/workflow-executors.test.ts +16 -7
- package/src/tests/workflow-foreach.test.ts +43 -20
- package/src/tests/workflow-notify-slack-ready.test.ts +161 -0
- package/src/tests/workflow-profile.test.ts +328 -0
- package/src/tools/app-upsert.ts +1 -1
- package/src/tools/memory-edit.ts +2 -1
- package/src/tools/model-profiles/check-model-profile.ts +63 -0
- package/src/tools/schedules/create-schedule.ts +45 -4
- package/src/tools/schedules/patch-schedule.ts +50 -4
- package/src/tools/schedules/update-schedule.ts +50 -4
- package/src/tools/send-task.ts +17 -2
- package/src/tools/store-progress.ts +15 -3
- package/src/tools/task-action.ts +9 -1
- package/src/tools/templates.ts +13 -0
- package/src/tools/tool-config.ts +2 -1
- package/src/tools/utils.ts +77 -11
- package/src/tools/workflows/create-workflow.ts +1 -1
- package/src/tools/workflows/retry-workflow-run.ts +1 -1
- package/src/tools/workflows/update-workflow.ts +10 -1
- package/src/types.ts +56 -1
- package/src/utils/credentials.ts +89 -12
- package/src/workflows/engine.ts +10 -1
- package/src/workflows/executors/agent-task.ts +21 -2
- package/src/workflows/executors/foreach.ts +4 -1
- package/src/workflows/executors/notify.ts +62 -6
- package/src/workflows/executors/sub-workflow.ts +1 -1
- package/src/workflows/executors/swarm-script.ts +4 -1
- package/src/workflows/foreach-driver.ts +8 -5
- package/src/workflows/limits.ts +2 -1
- package/src/workflows/model-validation.ts +27 -2
- package/src/workflows/patch-definition.ts +3 -1
- package/src/workflows/recovery.ts +6 -6
- package/src/workflows/resume.ts +9 -9
- package/src/workflows/retry-poller.ts +2 -2
- package/templates/extensions/comms-adherence-gate/README.md +25 -0
- package/templates/extensions/comms-adherence-gate/hooks.ts +100 -11
- package/templates/extensions/comms-adherence-gate/manifest.json +1 -1
- package/templates/skills/apps/SKILL.md +9 -0
- package/templates/skills/apps/content.md +9 -0
- package/templates/skills/code-quality/content.md +12 -0
- package/templates/skills/memory/content.md +8 -0
- package/templates/skills/scheduling/config.json +1 -1
- package/templates/skills/scheduling/content.md +2 -2
- package/templates/skills/swarm-docs/content.md +4 -0
- package/templates/skills/swarm-extensions/content.md +1 -1
- package/templates/skills/swarm-scripts/SKILL.md +1 -1
- package/templates/skills/swarm-scripts/content.md +1 -1
- package/templates/skills/work-on-task/SKILL.md +2 -0
- package/templates/skills/work-on-task/content.md +2 -0
- package/templates/workflows/dreaming/content.md +174 -7
- package/dist/acp-adapter-dn4gdsgr.js +0 -16
- package/dist/app-a66ssc4k.js +0 -17
- package/dist/cli-530hkwdy.js +0 -779
- package/dist/cli-a0657jmf.js +0 -339
- package/dist/cli-cyn9v8zr.js +0 -748
- package/dist/handlers-crckt5dq.js +0 -32
- package/dist/heartbeat-8phn1kdq.js +0 -41
- package/dist/index-4x08sjtk.js +0 -30
- package/dist/index-8ybffts4.js +0 -37
- package/dist/index-nfy4kkg5.js +0 -33
- package/dist/lead-zdqxsvjn.js +0 -71
- package/dist/worker-y62rvvq3.js +0 -71
- package/dist/{cli-gxy8y1dt.js → cli-8bpgbr8k.js} +3 -3
package/src/be/steering.ts
CHANGED
|
@@ -83,11 +83,17 @@ export interface TaskSteeringFields {
|
|
|
83
83
|
|
|
84
84
|
type SteeringAgent = Pick<Agent, "isLead" | "provider" | "harnessProvider">;
|
|
85
85
|
|
|
86
|
+
function supportedModesForTask(task: AgentTask, provider: ProviderName): SteerMode[] {
|
|
87
|
+
return provider === "claude" && task.providerMeta?.transport === "sdk"
|
|
88
|
+
? ["steer", "queue"]
|
|
89
|
+
: PROVIDER_STEER_CAPABILITIES[provider];
|
|
90
|
+
}
|
|
91
|
+
|
|
86
92
|
function steeringFieldsFor(task: AgentTask, agent: SteeringAgent | null): TaskSteeringFields {
|
|
87
93
|
const provider = agent?.harnessProvider ?? agent?.provider ?? task.provider;
|
|
88
94
|
return {
|
|
89
95
|
isLeadTask: agent?.isLead ?? false,
|
|
90
|
-
supportedSteerModes: provider ?
|
|
96
|
+
supportedSteerModes: provider ? supportedModesForTask(task, provider) : [],
|
|
91
97
|
};
|
|
92
98
|
}
|
|
93
99
|
|
|
@@ -339,7 +345,7 @@ export async function requestSteering(args: RequestSteeringArgs): Promise<SteerR
|
|
|
339
345
|
const currentTask = await getTaskById(args.taskId);
|
|
340
346
|
if (!currentTask) throw new SteeringRequestError("Task not found", 404);
|
|
341
347
|
const provider = await providerForTask(currentTask);
|
|
342
|
-
const supportedModes =
|
|
348
|
+
const supportedModes = supportedModesForTask(currentTask, provider);
|
|
343
349
|
|
|
344
350
|
if (onUnsupported === "fail" && !supportedModes.includes(requestedMode)) {
|
|
345
351
|
const supported = supportedModes.length > 0 ? supportedModes.join(", ") : "none";
|
|
@@ -598,6 +598,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
|
|
|
598
598
|
"SCRIPT_RUN_CONCURRENCY_CAP",
|
|
599
599
|
"WORKER_API_READY_TIMEOUT_SECONDS",
|
|
600
600
|
"DB_QUERY_HTTP_BUDGET_MS",
|
|
601
|
+
"EVENT_LOOP_STALL_WARN_MS",
|
|
601
602
|
"DB_QUERY_HTTP_MAX_ROWS",
|
|
602
603
|
"DB_QUERY_MCP_BUDGET_MS",
|
|
603
604
|
"DB_QUERY_MCP_MAX_ROWS",
|
|
@@ -605,6 +606,7 @@ const VALIDATED_KEYS: Record<string, ConfigValidator> = {
|
|
|
605
606
|
"SLACK_CONCLUSION_SETTLE_SEC",
|
|
606
607
|
"SLACK_CONCLUSION_TIMEOUT_MIN",
|
|
607
608
|
"SLACK_TREE_STALL_MIN",
|
|
609
|
+
"SLACK_TASK_WATCHER_INTERVAL_MS",
|
|
608
610
|
],
|
|
609
611
|
1,
|
|
610
612
|
),
|
|
@@ -316,6 +316,247 @@ function summarizeSessionLogLine(line: SessionLogForPreamble): string | null {
|
|
|
316
316
|
return snippet ? `[${ts}] ${snippet}` : null;
|
|
317
317
|
}
|
|
318
318
|
|
|
319
|
+
/**
|
|
320
|
+
* Tools with no side effect: an unanswered call to one of them is safe to
|
|
321
|
+
* repeat. Compared lowercased, so one entry covers Claude's `Read` and the
|
|
322
|
+
* `read` of pi, opencode, ACP, dsh and cursor.
|
|
323
|
+
*/
|
|
324
|
+
const READ_ONLY_TOOLS = new Set([
|
|
325
|
+
"read",
|
|
326
|
+
"grep",
|
|
327
|
+
"glob",
|
|
328
|
+
"ls",
|
|
329
|
+
"list",
|
|
330
|
+
"find",
|
|
331
|
+
"webfetch",
|
|
332
|
+
"websearch",
|
|
333
|
+
"web_search",
|
|
334
|
+
"toolsearch",
|
|
335
|
+
"tool_search",
|
|
336
|
+
"skill",
|
|
337
|
+
"todowrite",
|
|
338
|
+
"todoread",
|
|
339
|
+
"todo_list",
|
|
340
|
+
"shell_command_status",
|
|
341
|
+
]);
|
|
342
|
+
|
|
343
|
+
type ToolInput = Record<string, unknown> | undefined;
|
|
344
|
+
|
|
345
|
+
type ToolLogEvent =
|
|
346
|
+
| { kind: "use"; id: string | null; name: string; input: ToolInput }
|
|
347
|
+
| { kind: "input"; id: string; input: ToolInput }
|
|
348
|
+
| { kind: "result"; id: string };
|
|
349
|
+
|
|
350
|
+
function firstString(...values: unknown[]): string | null {
|
|
351
|
+
for (const v of values) if (typeof v === "string" && v) return v;
|
|
352
|
+
return null;
|
|
353
|
+
}
|
|
354
|
+
|
|
355
|
+
function asRecord(value: unknown): Record<string, unknown> | undefined {
|
|
356
|
+
return value && typeof value === "object" && !Array.isArray(value)
|
|
357
|
+
? (value as Record<string, unknown>)
|
|
358
|
+
: undefined;
|
|
359
|
+
}
|
|
360
|
+
|
|
361
|
+
/** Codex item types that are tool calls (mirrors the UI logs-parser codex adapter). */
|
|
362
|
+
const CODEX_TOOL_ITEMS = new Set([
|
|
363
|
+
"command_execution",
|
|
364
|
+
"mcp_tool_call",
|
|
365
|
+
"collab_tool_call",
|
|
366
|
+
"web_search",
|
|
367
|
+
"todo_list",
|
|
368
|
+
"file_change",
|
|
369
|
+
]);
|
|
370
|
+
|
|
371
|
+
function codexToolUse(item: Record<string, unknown>): ToolLogEvent {
|
|
372
|
+
const id = firstString(item.id);
|
|
373
|
+
if (item.type === "command_execution") {
|
|
374
|
+
const command = Array.isArray(item.command) ? item.command.join(" ") : item.command;
|
|
375
|
+
return { kind: "use", id, name: "bash", input: { command } };
|
|
376
|
+
}
|
|
377
|
+
if (item.type === "mcp_tool_call") {
|
|
378
|
+
return {
|
|
379
|
+
kind: "use",
|
|
380
|
+
id,
|
|
381
|
+
name: `${item.server ?? "mcp"}.${item.tool ?? "unknown"}`,
|
|
382
|
+
input: asRecord(item.arguments),
|
|
383
|
+
};
|
|
384
|
+
}
|
|
385
|
+
return { kind: "use", id, name: String(item.type), input: undefined };
|
|
386
|
+
}
|
|
387
|
+
|
|
388
|
+
/**
|
|
389
|
+
* Extract tool call / result events from one session_log line, in order.
|
|
390
|
+
* Each harness stores its own shape; every branch pairs on a call id:
|
|
391
|
+
* - claude, pi, amp: `message.content[]` `tool_use.id` / `tool_result.tool_use_id`
|
|
392
|
+
* - codex: `item.started` / `item.completed` on `item.id`
|
|
393
|
+
* - opencode, acp, grok, fx: `tool_start` / `tool_end` on `toolCallId`
|
|
394
|
+
* (ACP fills the real args in a later raw `tool_call_update.rawInput`)
|
|
395
|
+
* - claude-managed: `agent.{mcp_,}tool_use.id` / `agent.tool_result.tool_use_id`,
|
|
396
|
+
* `agent.mcp_tool_result.mcp_tool_use_id`
|
|
397
|
+
* - cursor: `tool_call` on `call_id`, `status: "running"` until it completes
|
|
398
|
+
* - dsh: `tool_call` / `tool_result` on `callId`
|
|
399
|
+
* A call without an id gets `id: null` and is never flagged.
|
|
400
|
+
*/
|
|
401
|
+
function extractToolLogEvents(line: SessionLogForPreamble): ToolLogEvent[] {
|
|
402
|
+
let parsed: unknown;
|
|
403
|
+
try {
|
|
404
|
+
parsed = JSON.parse(line.content);
|
|
405
|
+
} catch {
|
|
406
|
+
return [];
|
|
407
|
+
}
|
|
408
|
+
const obj = asRecord(parsed);
|
|
409
|
+
if (!obj) return [];
|
|
410
|
+
|
|
411
|
+
const content = asRecord(obj.message)?.content;
|
|
412
|
+
if (Array.isArray(content)) {
|
|
413
|
+
const events: ToolLogEvent[] = [];
|
|
414
|
+
for (const block of content) {
|
|
415
|
+
const b = asRecord(block);
|
|
416
|
+
if (!b) continue;
|
|
417
|
+
if (b.type === "tool_use" && typeof b.name === "string") {
|
|
418
|
+
events.push({ kind: "use", id: firstString(b.id), name: b.name, input: asRecord(b.input) });
|
|
419
|
+
} else if (b.type === "tool_result") {
|
|
420
|
+
const id = firstString(b.tool_use_id);
|
|
421
|
+
if (id) events.push({ kind: "result", id });
|
|
422
|
+
}
|
|
423
|
+
}
|
|
424
|
+
return events;
|
|
425
|
+
}
|
|
426
|
+
|
|
427
|
+
const update = asRecord(obj.update);
|
|
428
|
+
if (update?.sessionUpdate === "tool_call_update") {
|
|
429
|
+
const id = firstString(update.toolCallId);
|
|
430
|
+
const input = asRecord(update.rawInput);
|
|
431
|
+
return id && input ? [{ kind: "input", id, input }] : [];
|
|
432
|
+
}
|
|
433
|
+
|
|
434
|
+
const item = asRecord(obj.item);
|
|
435
|
+
const result = (...ids: unknown[]): ToolLogEvent[] => {
|
|
436
|
+
const id = firstString(...ids);
|
|
437
|
+
return id ? [{ kind: "result", id }] : [];
|
|
438
|
+
};
|
|
439
|
+
|
|
440
|
+
switch (obj.type) {
|
|
441
|
+
case "item.started": {
|
|
442
|
+
return item && CODEX_TOOL_ITEMS.has(String(item.type)) ? [codexToolUse(item)] : [];
|
|
443
|
+
}
|
|
444
|
+
case "item.completed":
|
|
445
|
+
return item && CODEX_TOOL_ITEMS.has(String(item.type)) ? result(item.id) : [];
|
|
446
|
+
case "tool_start":
|
|
447
|
+
return [
|
|
448
|
+
{
|
|
449
|
+
kind: "use",
|
|
450
|
+
id: firstString(obj.toolCallId),
|
|
451
|
+
name: firstString(obj.toolName) ?? "tool",
|
|
452
|
+
input: asRecord(obj.args),
|
|
453
|
+
},
|
|
454
|
+
];
|
|
455
|
+
case "tool_end":
|
|
456
|
+
return result(obj.toolCallId);
|
|
457
|
+
case "agent.tool_use":
|
|
458
|
+
case "agent.mcp_tool_use": {
|
|
459
|
+
const name = firstString(obj.name) ?? "tool";
|
|
460
|
+
const server = firstString(obj.mcp_server_name);
|
|
461
|
+
return [
|
|
462
|
+
{
|
|
463
|
+
kind: "use",
|
|
464
|
+
id: firstString(obj.id),
|
|
465
|
+
name: obj.type === "agent.mcp_tool_use" && server ? `${server}.${name}` : name,
|
|
466
|
+
input: asRecord(obj.input),
|
|
467
|
+
},
|
|
468
|
+
];
|
|
469
|
+
}
|
|
470
|
+
case "agent.tool_result":
|
|
471
|
+
return result(obj.tool_use_id);
|
|
472
|
+
case "agent.mcp_tool_result":
|
|
473
|
+
return result(obj.mcp_tool_use_id);
|
|
474
|
+
case "tool_call": {
|
|
475
|
+
// cursor: one `tool_call` row per state change on the same call_id.
|
|
476
|
+
if (typeof obj.status === "string" && obj.call_id !== undefined) {
|
|
477
|
+
if (obj.status !== "running") return result(obj.call_id);
|
|
478
|
+
const args = asRecord(obj.args);
|
|
479
|
+
const mcpTool = obj.name === "mcp" ? firstString(args?.toolName) : null;
|
|
480
|
+
return [
|
|
481
|
+
{
|
|
482
|
+
kind: "use",
|
|
483
|
+
id: firstString(obj.call_id),
|
|
484
|
+
name: mcpTool
|
|
485
|
+
? `mcp__${firstString(args?.providerIdentifier) ?? "mcp"}__${mcpTool}`
|
|
486
|
+
: (firstString(obj.name) ?? "tool"),
|
|
487
|
+
input: mcpTool ? asRecord(args?.args) : args,
|
|
488
|
+
},
|
|
489
|
+
];
|
|
490
|
+
}
|
|
491
|
+
// dsh
|
|
492
|
+
return [
|
|
493
|
+
{
|
|
494
|
+
kind: "use",
|
|
495
|
+
id: firstString(obj.callId),
|
|
496
|
+
name: firstString(obj.tool, obj.name) ?? "tool",
|
|
497
|
+
input: asRecord(obj.input),
|
|
498
|
+
},
|
|
499
|
+
];
|
|
500
|
+
}
|
|
501
|
+
case "tool_use":
|
|
502
|
+
return typeof obj.name === "string"
|
|
503
|
+
? [
|
|
504
|
+
{
|
|
505
|
+
kind: "use",
|
|
506
|
+
id: firstString(obj.id, obj.tool_use_id, obj.call_id, obj.callId, obj.toolCallId),
|
|
507
|
+
name: obj.name,
|
|
508
|
+
input: asRecord(obj.input),
|
|
509
|
+
},
|
|
510
|
+
]
|
|
511
|
+
: [];
|
|
512
|
+
case "tool_result":
|
|
513
|
+
return result(obj.tool_use_id, obj.call_id, obj.callId, obj.toolCallId, obj.id);
|
|
514
|
+
default:
|
|
515
|
+
return [];
|
|
516
|
+
}
|
|
517
|
+
}
|
|
518
|
+
|
|
519
|
+
/** Most unanswered calls named in the preamble line. */
|
|
520
|
+
const MAX_INTERRUPTED_CALLS = 3;
|
|
521
|
+
|
|
522
|
+
/**
|
|
523
|
+
* Find the tool calls the interrupted session was waiting on: every call
|
|
524
|
+
* with an id that never got its result, in start order, so a parallel batch
|
|
525
|
+
* whose later call answered first still flags the earlier one (Codex: start
|
|
526
|
+
* push, start search, complete search). Read-only calls are skipped. Returns
|
|
527
|
+
* the newest `MAX_INTERRUPTED_CALLS` as `<tool> <arg summary>` joined by
|
|
528
|
+
* `; `, or null when nothing is open. A call without an id cannot be paired
|
|
529
|
+
* and is never flagged. The caller scrubs the result.
|
|
530
|
+
*/
|
|
531
|
+
function findInterruptedToolCall(logs: SessionLogForPreamble[]): string | null {
|
|
532
|
+
const open = new Map<string, Extract<ToolLogEvent, { kind: "use" }>>();
|
|
533
|
+
const answered = new Set<string>();
|
|
534
|
+
const lateInput = new Map<string, ToolInput>();
|
|
535
|
+
for (const line of logs) {
|
|
536
|
+
for (const event of extractToolLogEvents(line)) {
|
|
537
|
+
if (event.kind === "use") {
|
|
538
|
+
// cursor repeats a `running` row per state change on one call_id.
|
|
539
|
+
if (event.id && !answered.has(event.id) && !open.has(event.id)) open.set(event.id, event);
|
|
540
|
+
} else if (event.kind === "input") {
|
|
541
|
+
lateInput.set(event.id, event.input);
|
|
542
|
+
} else {
|
|
543
|
+
answered.add(event.id);
|
|
544
|
+
open.delete(event.id);
|
|
545
|
+
}
|
|
546
|
+
}
|
|
547
|
+
}
|
|
548
|
+
const calls: string[] = [];
|
|
549
|
+
for (const use of open.values()) {
|
|
550
|
+
if (READ_ONLY_TOOLS.has(use.name.toLowerCase())) continue;
|
|
551
|
+
const input = { ...use.input, ...(use.id ? lateInput.get(use.id) : undefined) };
|
|
552
|
+
const primary = firstString(input?.file_path, input?.path, input?.command);
|
|
553
|
+
const raw = primary ?? (Object.keys(input).length > 0 ? JSON.stringify(input) : "");
|
|
554
|
+
const args = raw.replace(/\s+/g, " ").trim().slice(0, 200);
|
|
555
|
+
calls.push(args ? `${use.name} ${args}` : use.name);
|
|
556
|
+
}
|
|
557
|
+
return calls.length > 0 ? calls.slice(-MAX_INTERRUPTED_CALLS).join("; ") : null;
|
|
558
|
+
}
|
|
559
|
+
|
|
319
560
|
/**
|
|
320
561
|
* Build a resume-task preamble.
|
|
321
562
|
*
|
|
@@ -402,6 +643,22 @@ export async function buildResumeContextPreamble(
|
|
|
402
643
|
let artBudget = Math.floor(CONTEXT_PREAMBLE_RESUME_MAX_CHARS * 0.1);
|
|
403
644
|
const steeringBudget = Math.floor(CONTEXT_PREAMBLE_RESUME_MAX_CHARS * 0.1);
|
|
404
645
|
|
|
646
|
+
// An unanswered side-effecting call may have landed before the cut-off
|
|
647
|
+
// (git push, PR comment, message send). Flag it so the agent checks first.
|
|
648
|
+
// Only the newest attempt's session was cut; an earlier attempt's open call
|
|
649
|
+
// was already the previous resume's to check.
|
|
650
|
+
const interruptedSession = logsBatches.find((batch) => batch.length > 0) ?? [];
|
|
651
|
+
const interrupted = findInterruptedToolCall(
|
|
652
|
+
[...interruptedSession]
|
|
653
|
+
.sort((a, b) => a.createdAt.localeCompare(b.createdAt))
|
|
654
|
+
.slice(-CONTEXT_PREAMBLE_RESUME_SESSION_LOG_LIMIT),
|
|
655
|
+
);
|
|
656
|
+
const interruptedLine = interrupted
|
|
657
|
+
? scrubSecrets(
|
|
658
|
+
`Interrupted: ${interrupted} may have landed. Check its effect before calling it again.`,
|
|
659
|
+
)
|
|
660
|
+
: "";
|
|
661
|
+
|
|
405
662
|
const header = [
|
|
406
663
|
"\n---",
|
|
407
664
|
"## Resuming Interrupted Task",
|
|
@@ -418,6 +675,7 @@ export async function buildResumeContextPreamble(
|
|
|
418
675
|
chain.length === 2 ? "2nd" : chain.length === 3 ? "3rd" : `${chain.length}th`
|
|
419
676
|
} resume attempt).`
|
|
420
677
|
: "",
|
|
678
|
+
interruptedLine,
|
|
421
679
|
"",
|
|
422
680
|
"---",
|
|
423
681
|
"",
|
package/src/commands/runner.ts
CHANGED
|
@@ -83,6 +83,7 @@ import { MASKED_SECRET_VALUE } from "../utils/config-secrets.ts";
|
|
|
83
83
|
import { getMcpBaseUrl } from "../utils/constants.ts";
|
|
84
84
|
import { getContextWindowSize } from "../utils/context-window.ts";
|
|
85
85
|
import {
|
|
86
|
+
CredentialAllowlistError,
|
|
86
87
|
type CredentialSelection,
|
|
87
88
|
ModelWindowExhaustedError,
|
|
88
89
|
normalizeProviderKeyAliases,
|
|
@@ -911,6 +912,14 @@ export async function fetchResolvedEnv(
|
|
|
911
912
|
* unset so an exhausted default model never blocks configuration loading.
|
|
912
913
|
*/
|
|
913
914
|
enforceModelCapacity?: boolean;
|
|
915
|
+
/**
|
|
916
|
+
* The claimed profile's pooled-key allowlist (trigger `credentialAllowlist`).
|
|
917
|
+
* Forwarded to `resolveCredentialPools`, which throws
|
|
918
|
+
* `CredentialAllowlistError` when it matches no key.
|
|
919
|
+
*/
|
|
920
|
+
credentialAllowlist?: Record<string, string[]>;
|
|
921
|
+
/** The profile that carries `credentialAllowlist`, for the error message. */
|
|
922
|
+
resolvedProfile?: string;
|
|
914
923
|
},
|
|
915
924
|
): Promise<ResolvedEnvResult> {
|
|
916
925
|
const env: Record<string, string | undefined> = { ...baseEnv };
|
|
@@ -1080,6 +1089,8 @@ export async function fetchResolvedEnv(
|
|
|
1080
1089
|
model: effectiveModel,
|
|
1081
1090
|
localBlocks: sessionContext?.localBlocks,
|
|
1082
1091
|
enforceModelCapacity: sessionContext?.enforceModelCapacity,
|
|
1092
|
+
allowedKeySuffixes: sessionContext?.credentialAllowlist,
|
|
1093
|
+
allowlistProfile: sessionContext?.resolvedProfile,
|
|
1083
1094
|
});
|
|
1084
1095
|
|
|
1085
1096
|
return { env, credentialEnv, credentialSelections, resolvedProvider, scriptsOnlyConfigValue };
|
|
@@ -2471,6 +2482,9 @@ export async function getPausedTasksFromAPI(config: ApiConfig): Promise<
|
|
|
2471
2482
|
status?: string;
|
|
2472
2483
|
contextKey?: string;
|
|
2473
2484
|
requestedBy?: Trigger["requestedBy"];
|
|
2485
|
+
/** The profile claim applied, and its pooled-key allowlist read again at fetch. */
|
|
2486
|
+
resolvedProfile?: string;
|
|
2487
|
+
credentialAllowlist?: Record<string, string[]>;
|
|
2474
2488
|
}>
|
|
2475
2489
|
> {
|
|
2476
2490
|
const headers: Record<string, string> = {
|
|
@@ -2508,6 +2522,8 @@ export async function getPausedTasksFromAPI(config: ApiConfig): Promise<
|
|
|
2508
2522
|
output?: string;
|
|
2509
2523
|
status?: string;
|
|
2510
2524
|
requestedBy?: Trigger["requestedBy"];
|
|
2525
|
+
resolvedProfile?: string;
|
|
2526
|
+
credentialAllowlist?: Record<string, string[]>;
|
|
2511
2527
|
}>;
|
|
2512
2528
|
};
|
|
2513
2529
|
return data.tasks || [];
|
|
@@ -4254,6 +4270,9 @@ export async function spawnProviderProcess(
|
|
|
4254
4270
|
contextKey?: string;
|
|
4255
4271
|
/** Forwarded to fetchResolvedEnv → resolveCredentialPools — see RunnerState.modelWindowBlocks. */
|
|
4256
4272
|
localBlocks?: Map<string, number>;
|
|
4273
|
+
/** Claim-time profile (task.resolvedProfile) and its pooled-key allowlist. */
|
|
4274
|
+
resolvedProfile?: string;
|
|
4275
|
+
credentialAllowlist?: Record<string, string[]>;
|
|
4257
4276
|
},
|
|
4258
4277
|
logDir: string,
|
|
4259
4278
|
): Promise<RunningTask> {
|
|
@@ -4288,10 +4307,15 @@ export async function spawnProviderProcess(
|
|
|
4288
4307
|
modelTier: opts.modelTier,
|
|
4289
4308
|
localBlocks: opts.localBlocks,
|
|
4290
4309
|
enforceModelCapacity: true,
|
|
4310
|
+
credentialAllowlist: opts.credentialAllowlist,
|
|
4311
|
+
resolvedProfile: opts.resolvedProfile,
|
|
4291
4312
|
},
|
|
4292
4313
|
));
|
|
4293
4314
|
} catch (err) {
|
|
4294
|
-
if (
|
|
4315
|
+
if (
|
|
4316
|
+
(err instanceof ModelWindowExhaustedError || err instanceof CredentialAllowlistError) &&
|
|
4317
|
+
realTaskId
|
|
4318
|
+
) {
|
|
4295
4319
|
const reason = err.message;
|
|
4296
4320
|
console.warn(`[${opts.role}] ${reason}`);
|
|
4297
4321
|
await ensureTaskFinished(
|
|
@@ -7081,6 +7105,8 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
|
|
|
7081
7105
|
vcsRepo: task.vcsRepo,
|
|
7082
7106
|
contextKey: (task as { contextKey?: string }).contextKey,
|
|
7083
7107
|
localBlocks: state.modelWindowBlocks,
|
|
7108
|
+
resolvedProfile: task.resolvedProfile,
|
|
7109
|
+
credentialAllowlist: task.credentialAllowlist,
|
|
7084
7110
|
},
|
|
7085
7111
|
logDir,
|
|
7086
7112
|
);
|
|
@@ -7703,6 +7729,11 @@ export async function runAgent(config: RunnerConfig, opts: RunnerOptions) {
|
|
|
7703
7729
|
vcsRepo: taskVcsRepo,
|
|
7704
7730
|
contextKey: taskContextKey,
|
|
7705
7731
|
localBlocks: state.modelWindowBlocks,
|
|
7732
|
+
resolvedProfile: (trigger.task as { resolvedProfile?: string } | undefined)
|
|
7733
|
+
?.resolvedProfile,
|
|
7734
|
+
credentialAllowlist: (
|
|
7735
|
+
trigger.task as { credentialAllowlist?: Record<string, string[]> } | undefined
|
|
7736
|
+
)?.credentialAllowlist,
|
|
7706
7737
|
},
|
|
7707
7738
|
logDir,
|
|
7708
7739
|
);
|
|
@@ -5,16 +5,16 @@
|
|
|
5
5
|
"$schema": "../manifest.schema.json",
|
|
6
6
|
"name": "comms-adherence-gate",
|
|
7
7
|
"description": "Judges every Slack-facing store-progress completion and agent Slack post against the comms preferences of the requester, or of the person it @-mentions, their latest request and a plain-language rubric with Jev (TypeSafe or OpenRouter), and in enforce blocks a failing call once per task",
|
|
8
|
-
"version": "1.
|
|
8
|
+
"version": "1.8.0",
|
|
9
9
|
"runtime": "api",
|
|
10
10
|
"assets": {
|
|
11
11
|
"hooks": "hooks.ts"
|
|
12
12
|
}
|
|
13
13
|
},
|
|
14
14
|
"files": {
|
|
15
|
-
"hooks.ts": "import { type ApiCtx, block, type SwarmExtension } from \"swarm-extension\";\nimport { z } from \"zod\";\n\n/**\n * comms-adherence-gate\n *\n * When an agent calls `store-progress` with status \"completed\" on a task that\n * reaches a human in Slack, or posts to Slack itself (`slack-reply`,\n * `slack-post`, `slack-start-thread`, `slack-update`), judge the text with Jev:\n * against the requesting user's stored comms preferences\n * (users.metadata.$.comms) and what that user actually asked for in their\n * latest message, and against a plain-language rubric that applies to every\n * message whatever preferences exist. An explicit request (\"tell me a long\n * joke\", \"explain in detail\") outranks the stored default, so a requested long\n * answer is not a verbosity failure.\n *\n * Threads with several people: a message that @-mentions someone is judged\n * against the first mentioned person with stored preferences, skipping a\n * requester without preferences; otherwise against the requester. `plain` applies to everyone.\n *\n * Transport (config.provider): Jev is served by TypeSafe directly and by\n * OpenRouter's Decisions endpoint. Both take the same {model, state, questions}\n * body and return the same `answers` shape. `auto` uses TYPESAFE_API_KEY when\n * set, else OPENROUTER_API_KEY.\n *\n * modes (config.mode for the preference dimensions, config.plainMode for `plain`):\n * off -> never evaluate\n * shadow -> evaluate + record, never block (default)\n * enforce -> record, and block the call up to maxBlocksPerTask times per task\n * with actionable feedback. The budget is shared by both modes and\n * by every gated tool.\n *\n * Fails OPEN on every error: a judge outage must never wall the swarm.\n * Every verdict lands in KV namespace `ext:comms-gate`.\n */\n\nexport const config = z.object({\n mode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n /** A preference dimension scoring below this fails. */\n threshold: z.number().min(0).max(1).default(0.5),\n /** The `plain` dimension, judged on every message. Independent of `mode`. */\n plainMode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n /**\n * `plain` scoring below this fails. Jev scores dense status text low and\n * plain text high with little in between, so this sits far below `threshold`.\n */\n plainThreshold: z.number().min(0).max(1).default(0.25),\n timeoutMs: z.number().int().positive().default(4000),\n maxBlocksPerTask: z.number().int().min(0).default(1),\n provider: z.enum([\"auto\", \"typesafe\", \"openrouter\"]).default(\"auto\"),\n /** Jev model on the TypeSafe transport. */\n model: z.string().default(\"jev-latest\"),\n /** Jev model on the OpenRouter transport. */\n openrouterModel: z.string().default(\"typesafe/jev-1.13\"),\n /** Explicit TypeSafe key; otherwise TYPESAFE_API_KEY from the API process env. */\n apiKey: z.string().optional(),\n});\n\ntype Cfg = z.infer<typeof config>;\ntype Swarm = ApiCtx[\"swarm\"];\n\nconst NS = \"ext:comms-gate\";\nconst TYPESAFE_ENDPOINT = \"https://api.typesafe.ai/v1/systemone\";\nconst OPENROUTER_ENDPOINT = \"https://openrouter.ai/api/alpha/decisions\";\nconst UUID_RE = /^[0-9a-fA-F-]{36}$/;\n/** MCP tools that post agent-authored text to Slack, all with a `message` arg. */\nexport const SLACK_TOOLS = new Set([\n \"slack-reply\",\n \"slack-post\",\n \"slack-start-thread\",\n \"slack-update\",\n]);\n// The dispatcher cancels a handler after 5 s; leave room for the DB read and KV writes.\nconst MAX_TIMEOUT_MS = 4000;\n\nexport const cfgOf = (raw: unknown): Cfg => {\n const parsed = config.safeParse(raw ?? {});\n return parsed.success ? parsed.data : config.parse({});\n};\n\n// kv keys accept [a-zA-Z0-9._:/%-]\nconst safeKey = (raw: string | undefined | null): string =>\n (raw && raw.length > 0 ? raw : \"unknown\").replace(/[^a-zA-Z0-9._-]/g, \"_\").slice(0, 120);\n\n/** SDK envelopes: {success, data:{...}} or the bare payload. */\ntype Envelope = {\n data?: { rows?: unknown[]; value?: unknown };\n rows?: unknown[];\n value?: unknown;\n} | null;\n\nconst cell = (row: unknown, i: number, key: string): unknown =>\n Array.isArray(row) ? row[i] : (row as Record<string, unknown>)?.[key];\n\n/**\n * The newest human message sits at the END of a Slack task: the\n * `<thread_context>` blob comes first and can run to thousands of chars, so a\n * leading slice of `agent_tasks.task` shows the judge everything except the\n * actual request. Take the tail, then the part after the last `</thread_context>`.\n */\nconst CTX_END = \"</thread_context>\";\nexport const latestAsk = (tail: string): string => {\n const end = tail.lastIndexOf(CTX_END);\n let out = (end >= 0 ? tail.slice(end + CTX_END.length) : tail)\n .replace(/\\[Thread follow-up[^\\]]*\\]/g, \"\")\n .trim();\n // Some tasks end with the context block; fall back to the last messages in it.\n if (out.length < 8) out = (end >= 0 ? tail.slice(0, end) : tail).trim().slice(-800);\n return out.slice(0, 900);\n};\n\n// Preferences are the DEFAULT. A direct request outranks them.\nconst JUDGING_RULES = [\n \"The requester's explicit instruction in latest_request OUTRANKS requester_preferences. Preferences describe the DEFAULT; they never override a direct request.\",\n \"If latest_request asks for something long, detailed, creative, a story, a joke, a full explanation or a document, then length and structure serving that request are CORRECT and must NOT be penalized.\",\n \"Judge whether agent_message serves what latest_request actually asked for, written in the requester's manner. Do not judge it against the default preference when the request overrides it.\",\n];\n\ntype Prefs = { verbosity?: unknown; tone?: unknown; language?: unknown } & Record<string, unknown>;\n\n/**\n * The `plain` rubric, from the `comms` skill (Simpler and Precise modes). Jev\n * separates dense from plain text reliably only with contrasting examples; a\n * prose-only rubric scored a plain rewrite as low as the dense original.\n */\nexport const PLAIN_RULES = [\n \"Examples of NOT plain: 'p50 Δ +120ms vs baseline (n=37)', 'error rate 2.1% → 0.4% (cohort B, ±0.3 at 95%)', 'cost $-42/day', 'first-call hit ratio 0.61', 'drift unmeasured; 2 flaky'.\",\n \"Examples of plain: 'Pages load 120 ms slower than last week, across 37 runs', 'Errors dropped from 2 in 100 requests to 4 in 1,000', 'We spend $42 a day less', 'PR #123 keeps the migration reversible', 'Lead saves about $75 a week'.\",\n \"Code identifiers, task ids, PR numbers, links, file paths and version numbers are fine as they are.\",\n];\n\nexport const PLAIN_QUESTION = {\n type: \"noul\",\n instructions:\n \"Is agent_message written like the plain examples in plain_language_rules rather than like the NOT plain ones? Ignore length and tone.\",\n criteria: {\n true: \"Written like the plain examples: everyday words and numbers with units and direction.\",\n false:\n \"Written like the NOT plain examples: statistics shorthand, abbreviations, signed or cryptic numbers.\",\n },\n};\n\n/** Structured output (an outputSchema answer) is for machines; `plain` skips it. */\nexport const looksLikeJson = (text: string): boolean => {\n if (!/^[[{]/.test(text)) return false;\n try {\n JSON.parse(text);\n return true;\n } catch {\n return false;\n }\n};\n\n/** One `noul` question per stated preference the gate knows how to judge. */\nexport const buildQuestions = (prefs: Prefs): Record<string, unknown> => {\n const questions: Record<string, unknown> = {};\n if (prefs.verbosity) {\n questions.verbosity = {\n type: \"noul\",\n instructions:\n \"Does agent_message respect the requester's verbosity preference, AS OVERRIDDEN by any explicit instruction in latest_request? Apply judging_rules.\",\n criteria: {\n true: \"Length and structure fit what latest_request asked for (or the stated preference when the request does not override it), and it leads with the result.\",\n false:\n \"Too long for what was asked, or it opens with preamble, recaps the request, narrates the process, or ends with an offer to elaborate. Length explicitly requested in latest_request is NOT a failure.\",\n },\n };\n }\n if (prefs.tone) {\n questions.tone = {\n type: \"noul\",\n instructions:\n \"Does agent_message match the requester's stated tone preference, as overridden by any explicit instruction in latest_request? Apply judging_rules.\",\n criteria: {\n true: \"The tone matches what the requester asked for.\",\n false:\n \"The tone conflicts with it (for example hedging, flattery or filler when the requester asked for direct and plain). A voice appropriate to an explicitly requested creative or narrative form is NOT a failure.\",\n },\n };\n }\n if (prefs.language) {\n questions.language = {\n type: \"noul\",\n instructions: \"Is agent_message written in the requester's stated language?\",\n criteria: {\n true: \"Written in the stated language.\",\n false: \"Written in a different language.\",\n },\n };\n }\n return questions;\n};\n\nconst secretCache = new Map<string, { value: string; at: number }>();\nconst KEY_TTL_MS = 5 * 60 * 1000;\nconst usable = (v: string): boolean => Boolean(v) && !v.startsWith(\"[REDACTED\");\nconst envOf = (name: string): string => String(process.env[name] ?? \"\");\n\n/**\n * Resolve a secret: explicit value, then the API process env. The API process loads\n * global swarm_config rows into process.env at boot and on config reload.\n * ctx.swarm.config_get cannot serve it: the SDK scrubs secrets to \"[REDACTED:<name>]\".\n */\nconst secret = (name: string, explicit?: string): string => {\n const cached = secretCache.get(name);\n if (cached && Date.now() - cached.at < KEY_TTL_MS) return cached.value;\n const value = [String(explicit ?? \"\"), envOf(name)].find(usable) ?? \"\";\n if (usable(value)) secretCache.set(name, { value, at: Date.now() });\n return value;\n};\n\n/** Test hook: forget cached secrets. */\nexport const resetKeyCache = (): void => {\n secretCache.clear();\n};\n\nexport type JevTransport = {\n provider: \"typesafe\" | \"openrouter\";\n endpoint: string;\n key: string;\n model: string;\n};\n\n/**\n * Pick the Jev transport. `auto` prefers TypeSafe and falls back to OpenRouter.\n * Throws when the chosen provider has no usable key; the handler fails open.\n */\nexport const resolveTransport = (cfg: Cfg): JevTransport => {\n const typesafe = (): JevTransport | null => {\n const key = secret(\"TYPESAFE_API_KEY\", cfg.apiKey);\n return usable(key)\n ? { provider: \"typesafe\", endpoint: TYPESAFE_ENDPOINT, key, model: cfg.model }\n : null;\n };\n const openrouter = (): JevTransport | null => {\n const key = secret(\"OPENROUTER_API_KEY\");\n return usable(key)\n ? { provider: \"openrouter\", endpoint: OPENROUTER_ENDPOINT, key, model: cfg.openrouterModel }\n : null;\n };\n const transport =\n cfg.provider === \"typesafe\"\n ? typesafe()\n : cfg.provider === \"openrouter\"\n ? openrouter()\n : (typesafe() ?? openrouter());\n if (transport) return transport;\n throw new Error(\n cfg.provider === \"typesafe\"\n ? \"no TYPESAFE_API_KEY\"\n : cfg.provider === \"openrouter\"\n ? \"no OPENROUTER_API_KEY\"\n : \"no TYPESAFE_API_KEY or OPENROUTER_API_KEY\",\n );\n};\n\n/** One Jev call; returns the `noul` score per question. Throws on any failure. */\nexport const askJev = async (\n state: Record<string, unknown>,\n questions: Record<string, unknown>,\n transport: JevTransport,\n cfg: Cfg,\n outer?: AbortSignal,\n): Promise<{ scores: Record<string, number>; latencyMs: number }> => {\n const controller = new AbortController();\n const timer = setTimeout(() => controller.abort(), Math.min(cfg.timeoutMs, MAX_TIMEOUT_MS));\n const onOuterAbort = () => controller.abort();\n outer?.addEventListener(\"abort\", onOuterAbort);\n const t0 = Date.now();\n try {\n const res = await fetch(transport.endpoint, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\", Authorization: `Bearer ${transport.key}` },\n body: JSON.stringify({ state, model: transport.model, questions }),\n signal: controller.signal,\n });\n if (!res.ok) throw new Error(`${transport.provider} ${res.status}`);\n const body = (await res.json()) as { answers?: Record<string, { noul?: unknown }> } | null;\n const answers = body?.answers;\n if (!answers || typeof answers !== \"object\") throw new Error(\"no answers in response\");\n const scores: Record<string, number> = {};\n for (const [id, a] of Object.entries(answers)) {\n if (typeof a?.noul === \"number\") scores[id] = a.noul;\n }\n if (Object.keys(scores).length === 0) throw new Error(\"no scores in response\");\n return { scores, latencyMs: Date.now() - t0 };\n } finally {\n clearTimeout(timer);\n outer?.removeEventListener(\"abort\", onOuterAbort);\n }\n};\n\nconst SELFTEST = \"comms-gate-selftest\";\nconst SELFTEST_PREFS = {\n tone: \"direct, plain, no hedging\",\n language: \"English\",\n verbosity:\n \"very terse - answer in the first sentence, ~400 chars max. No preamble, no recap, no closing offer.\",\n};\nconst SELFTEST_BAD =\n \"Great question! Let me walk you through what I did here. First I looked at the task, then I reviewed the relevant files, and after careful consideration I decided to go with option B. I hope this helps - let me know if you would like me to elaborate further on any of the above!\";\nconst SELFTEST_GOOD =\n \"Went with option B: it is the only one that keeps the migration reversible. PR #123.\";\n// A real dense monitor post a requester had to ask to have rewritten, and that rewrite.\nconst SELFTEST_PLAIN_BAD =\n \"Prompt cache monitor, day 7 verdict for v2.0.0: partial. Lead first-call read median 12.4k (baseline v1.173.0, n 410) → 19.1k tokens (n 2234; expected 25.0k-40.0k). First-call saving about $75/week on Lead vs v1.173.0 (expected $129; sampling noise ±$24 at 95%, one baseline version, day-to-day drift not measured); session $ change $-167/week; fleet first-call saving $-7/week.\";\nconst SELFTEST_PLAIN_GOOD =\n \"Cheaper, but half what we hoped: Lead saves about $75 a week, not $129. Whole Lead tasks still cost $167 a week more, probably from other releases and heavier work, not this change.\";\n\nconst below = (bad: unknown, good: unknown, threshold: number): boolean =>\n typeof bad === \"number\" && typeof good === \"number\" && bad < threshold && good >= threshold;\n\n/**\n * Run the judge on known-bad (positive control, must score below threshold) and\n * known-good (negative control, must score at or above it) messages and record\n * them under `selftest:last`: one pair for verbosity, one for `plain`. Proves key,\n * egress and KV from inside the API runtime without touching real traffic.\n */\nconst selfTest = async (swarm: Swarm, cfg: Cfg, signal?: AbortSignal): Promise<void> => {\n const started = Date.now();\n try {\n const transport = resolveTransport(cfg);\n const judge = (message: string, dim: \"verbosity\" | \"plain\") =>\n askJev(\n dim === \"plain\"\n ? { plain_language_rules: PLAIN_RULES, agent_message: message }\n : { requester_preferences: SELFTEST_PREFS, agent_message: message },\n { [dim]: dim === \"plain\" ? PLAIN_QUESTION : buildQuestions(SELFTEST_PREFS).verbosity },\n transport,\n cfg,\n signal,\n ).then((r) => r.scores[dim] ?? null);\n const [bad, good, plainBad, plainGood] = await Promise.all([\n judge(SELFTEST_BAD, \"verbosity\"),\n judge(SELFTEST_GOOD, \"verbosity\"),\n judge(SELFTEST_PLAIN_BAD, \"plain\"),\n judge(SELFTEST_PLAIN_GOOD, \"plain\"),\n ]);\n await swarm.kv_set({\n namespace: NS,\n key: \"selftest:last\",\n value: {\n at: new Date().toISOString(),\n provider: transport.provider,\n threshold: cfg.threshold,\n positiveControlBadScore: bad,\n negativeControlGoodScore: good,\n controlsOk: below(bad, good, cfg.threshold),\n plainThreshold: cfg.plainThreshold,\n plainPositiveControlBadScore: plainBad,\n plainNegativeControlGoodScore: plainGood,\n plainControlsOk: below(plainBad, plainGood, cfg.plainThreshold),\n latencyMs: Date.now() - started,\n },\n });\n } catch (err) {\n await swarm\n .kv_set({\n namespace: NS,\n key: \"selftest:last\",\n value: {\n at: new Date().toISOString(),\n error: String(err).slice(0, 400),\n latencyMs: Date.now() - started,\n },\n })\n .catch(() => {});\n }\n};\n\nconst TASK_SQL = `SELECT t.source, t.slackThreadTs, t.agentId, t.requestedByUserId,\n json_extract(u.metadata, '$.comms') AS comms, u.name,\n substr(t.task, 1, 400) AS askHead,\n substr(t.task, -1400) AS askTail,\n t.creatorAgentId\nFROM agent_tasks t\nLEFT JOIN users u ON u.id = t.requestedByUserId\nWHERE t.id = ?`;\n\nconst LEAD_SQL = \"SELECT isLead FROM agents WHERE id = ?\";\n\n/** Slack user mentions in agent text: `<@U123>` or `<@U123|name>`. */\nconst MENTION_RE = /<@([UW][A-Z0-9]+)(?:\\|[^>]*)?>/g;\nconst MAX_MENTIONS = 5;\n\n/** Mentioned Slack user ids in order of first appearance, capped. */\nexport const mentionedSlackIds = (text: string): string[] => {\n const ids: string[] = [];\n for (const m of text.matchAll(MENTION_RE)) {\n if (!ids.includes(m[1]!)) ids.push(m[1]!);\n if (ids.length >= MAX_MENTIONS) break;\n }\n return ids;\n};\n\nconst addresseeSql = (n: number) => `SELECT x.externalId, u.id, u.name,\n json_extract(u.metadata, '$.comms') AS comms\nFROM user_external_ids x\nJOIN users u ON u.id = x.userId\nWHERE x.kind = 'slack' AND x.externalId IN (${Array(n).fill(\"?\").join(\", \")})`;\n\nconst parsePrefs = (raw: unknown): Prefs | null => {\n if (!raw) return null;\n const parsed = typeof raw === \"string\" ? JSON.parse(raw) : raw;\n return parsed && typeof parsed === \"object\" && Object.keys(parsed).length > 0\n ? (parsed as Prefs)\n : null;\n};\n\ntype Audience = { id: string; name: string; prefs: Prefs; via: \"mention\" | \"requester\" };\n\n/**\n * Whose preferences a message is judged against. In a thread with several\n * people, the message is for whoever it @-mentions: the first mentioned person\n * with stored preferences wins, including the requester only if they have prefs.\n * Without such a mention, the task requester (the\n * person whose message created this task). One SQL read, only when the text\n * mentions someone; no judge call.\n */\nconst resolveAudience = async (\n swarm: Swarm,\n text: string,\n requester: Audience,\n): Promise<Audience> => {\n const ids = mentionedSlackIds(text);\n if (ids.length === 0) return requester;\n const q = (await swarm.db_query({ sql: addresseeSql(ids.length), params: ids })) as Envelope;\n const rows = q?.data?.rows ?? q?.rows ?? [];\n for (const slackId of ids) {\n const row = rows.find((r) => String(cell(r, 0, \"externalId\")) === slackId);\n if (!row) continue;\n const userId = String(cell(row, 1, \"id\") ?? \"\");\n // A requester with stored preferences keeps their own task context.\n if (userId && userId === requester.id) {\n if (Object.keys(requester.prefs).length > 0) return requester;\n continue;\n }\n const prefs = parsePrefs(cell(row, 3, \"comms\"));\n if (!prefs) continue;\n return { id: userId, name: String(cell(row, 2, \"name\") ?? userId), prefs, via: \"mention\" };\n }\n return requester;\n};\n\n/**\n * Mirrors the `task.progress.write` rule store-progress enforces\n * (src/rbac/legacy-policy.ts): the caller owns the task, the task is\n * unassigned, or the caller is a lead. Lead status comes from the caller's\n * agents row, never from tool args. Extension callers return before this.\n */\nconst mayWriteProgress = async (\n swarm: Swarm,\n callerId: string | undefined,\n taskAgentId: string,\n): Promise<boolean> => {\n if (!callerId) return false;\n if (!taskAgentId || taskAgentId === callerId) return true;\n const q = (await swarm.db_query({ sql: LEAD_SQL, params: [callerId] })) as Envelope;\n const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n return Number(cell(row, 0, \"isLead\") ?? 0) === 1;\n};\n\n/** The text a gated call would put in front of a human, and the task it belongs to. */\nconst gatedText = (\n tool: string,\n args: Record<string, unknown>,\n sourceTaskId: string | undefined,\n): { text: string; taskId: string } | null => {\n if (tool === \"store-progress\") {\n if (args.status !== \"completed\") return null;\n return {\n text: typeof args.output === \"string\" ? args.output.trim() : \"\",\n taskId: String(args.taskId ?? sourceTaskId ?? \"\"),\n };\n }\n if (SLACK_TOOLS.has(tool)) {\n // slack-reply names its task; the other tools post from the caller's task context.\n const named = tool === \"slack-reply\" ? args.taskId : undefined;\n return {\n text: typeof args.message === \"string\" ? args.message.trim() : \"\",\n taskId: String(named ?? sourceTaskId ?? \"\"),\n };\n }\n return null;\n};\n\nconst extension: SwarmExtension = (api) => {\n api.on(\"pre.tool.call\", async (event, ctx) => {\n if (event.tool !== \"store-progress\" && !SLACK_TOOLS.has(event.tool)) return;\n const origin = event.requestInfo?.callOrigin;\n if (origin === \"extension\") return;\n\n const cfg = cfgOf(ctx.config);\n if (cfg.mode === \"off\" && cfg.plainMode === \"off\") return;\n\n const args = (event.args ?? {}) as Record<string, unknown>;\n\n // Self-test hatch: a progress call whose text starts with the sentinel runs\n // the controls and records them under `selftest:last`.\n if (\n event.tool === \"store-progress\" &&\n args.status !== \"completed\" &&\n typeof args.progress === \"string\" &&\n args.progress.startsWith(SELFTEST)\n ) {\n await selfTest(ctx.swarm, cfg, ctx.signal);\n return;\n }\n\n const gated = gatedText(event.tool, args, event.requestInfo?.sourceTaskId);\n if (!gated?.text) return;\n const { text, taskId } = gated;\n if (!UUID_RE.test(taskId)) return;\n\n try {\n const q = (await ctx.swarm.db_query({ sql: TASK_SQL, params: [taskId] })) as Envelope;\n const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n if (!row) return;\n\n const source = String(cell(row, 0, \"source\") ?? \"\");\n const slackThreadTs = cell(row, 1, \"slackThreadTs\");\n const agentId = String(cell(row, 2, \"agentId\") ?? \"\");\n const requesterId = String(cell(row, 3, \"requestedByUserId\") ?? \"\");\n const commsRaw = cell(row, 4, \"comms\");\n const requesterName = String(cell(row, 5, \"name\") ?? (requesterId || \"the requester\"));\n const threadOpening = String(cell(row, 6, \"askHead\") ?? \"\");\n const ask = latestAsk(String(cell(row, 7, \"askTail\") ?? \"\"));\n\n // Judge only a call the tool itself will accept, so no agent can ship another\n // task's thread and preferences to the external judge. store-progress follows\n // its write rule; the Slack tools follow slack-reply's: the caller is the\n // task's assignee or its creator.\n const callerId = event.requestInfo?.agentId;\n const creatorAgentId = String(cell(row, 8, \"creatorAgentId\") ?? \"\");\n const allowed =\n event.tool === \"store-progress\"\n ? await mayWriteProgress(ctx.swarm, callerId, agentId)\n : Boolean(callerId) && (callerId === agentId || callerId === creatorAgentId);\n if (!allowed) return;\n\n // A completion reaches a human only on a Slack task; a Slack tool always does.\n if (event.tool === \"store-progress\" && source !== \"slack\" && !slackThreadTs) return;\n\n const requester: Audience = {\n id: requesterId,\n name: requesterName,\n prefs: parsePrefs(commsRaw) ?? {},\n via: \"requester\",\n };\n // `plain` alone judges no one's preferences, so it skips the lookup.\n const audience =\n cfg.mode === \"off\" ? requester : await resolveAudience(ctx.swarm, text, requester);\n const { prefs, name: audienceName } = audience;\n\n const questions: Record<string, unknown> = cfg.mode === \"off\" ? {} : buildQuestions(prefs);\n // Only a store-progress outputSchema answer is machine JSON; a Slack post is\n // always read by a human, JSON or not.\n if (cfg.plainMode !== \"off\" && (event.tool !== \"store-progress\" || !looksLikeJson(text)))\n questions.plain = PLAIN_QUESTION;\n if (Object.keys(questions).length === 0) return;\n\n const transport = resolveTransport(cfg);\n const { scores, latencyMs } = await askJev(\n {\n role: \"You audit an AI agent's message to the human who requested the work.\",\n requester: audienceName,\n requester_preferences: prefs,\n latest_request: ask,\n thread_opening: threadOpening,\n judging_rules: JUDGING_RULES,\n plain_language_rules: PLAIN_RULES,\n agent_message: text,\n },\n questions,\n transport,\n cfg,\n ctx.signal,\n );\n\n const limitOf = (dim: string) => (dim === \"plain\" ? cfg.plainThreshold : cfg.threshold);\n const failed = Object.entries(scores)\n .filter(([k, v]) => v < limitOf(k))\n .map(([k]) => k);\n // Script SDK calls never reach pre.tool.call today; if one does, record it only.\n const blocking =\n origin === \"script-sdk\"\n ? []\n : failed.filter((d) => (d === \"plain\" ? cfg.plainMode : cfg.mode) === \"enforce\");\n\n const verdict = {\n at: new Date().toISOString(),\n tool: event.tool,\n taskId,\n agentId,\n source,\n requester: requesterName,\n requesterId,\n judgedFor: audience.via,\n audienceId: audience.id,\n audience: audienceName,\n provider: transport.provider,\n scores,\n failed,\n threshold: cfg.threshold,\n plainThreshold: cfg.plainThreshold,\n mode: cfg.mode,\n plainMode: cfg.plainMode,\n latencyMs,\n preferences: prefs,\n askPreview: ask.slice(0, 400),\n outputPreview: text.slice(0, 700),\n };\n\n await ctx.swarm.kv_incr({ namespace: NS, key: \"total\" });\n await ctx.swarm.kv_set({ namespace: NS, key: \"last\", value: verdict });\n\n if (failed.length === 0) {\n await ctx.swarm.kv_incr({ namespace: NS, key: \"pass\" });\n return;\n }\n\n await ctx.swarm.kv_incr({ namespace: NS, key: \"fail\" });\n for (const dim of failed) {\n await ctx.swarm.kv_incr({ namespace: NS, key: `dim:${safeKey(dim)}` });\n }\n\n const blocksKey = `blocks:${safeKey(taskId)}`;\n // kv_get answers {success, data:{value}}, and {success:false} when absent.\n const prior = (await ctx.swarm.kv_get({ namespace: NS, key: blocksKey })) as Envelope;\n const priorBlocks = Number(prior?.data?.value ?? prior?.value ?? 0) || 0;\n const willBlock = blocking.length > 0 && priorBlocks < cfg.maxBlocksPerTask;\n\n await ctx.swarm.kv_set({\n namespace: NS,\n key: `fail:${Date.now()}:${safeKey(taskId)}`,\n value: { ...verdict, action: willBlock ? \"blocked\" : \"recorded\" },\n });\n\n if (!willBlock) {\n await ctx.swarm.kv_incr({\n namespace: NS,\n key: blocking.length > 0 ? \"escaped\" : \"shadowed\",\n });\n return;\n }\n\n await ctx.swarm.kv_incr({ namespace: NS, key: \"blocked\" });\n await ctx.swarm.kv_incr({ namespace: NS, key: blocksKey });\n\n const lines = [\n blocking.includes(\"plain\")\n ? `Comms gate: this message is not in plain words for ${audienceName}.`\n : `Comms gate: this output does not match ${audienceName}'s stated preferences.`,\n ];\n for (const d of blocking) {\n const score = `${d} (${scores[d]!.toFixed(2)} vs ${limitOf(d)})`;\n lines.push(\n d === \"plain\"\n ? `${score}: a reader outside the swarm cannot follow it on first read.`\n : `${score}: requested ${String(prefs[d] ?? \"\").slice(0, 220)}`,\n );\n }\n lines.push(\n blocking.includes(\"plain\")\n ? `Rewrite the message with the \\`comms\\` skill (Simpler mode): common words, one idea per sentence, every number with a unit and a direction word, shorthand explained or replaced. Keep every number, name, link and hedge verbatim, then call ${event.tool} again.`\n : `Rewrite the message to match and call ${event.tool} again. Do not change the facts, only how they are said.`,\n );\n return block(lines.join(\"\\n\"));\n } catch (err) {\n // Fail open, always.\n try {\n await ctx.swarm.kv_incr({ namespace: NS, key: \"error\" });\n await ctx.swarm.kv_set({\n namespace: NS,\n key: \"error:last\",\n value: {\n at: new Date().toISOString(),\n tool: event.tool,\n taskId,\n error: String(err).slice(0, 400),\n },\n });\n } catch {\n /* ignore */\n }\n ctx.log.warn(\"comms-adherence-gate: failing open\", { error: String(err) });\n return;\n }\n });\n};\n\nexport default extension;\n"
|
|
15
|
+
"hooks.ts": "import { type ApiCtx, block, type SwarmExtension } from \"swarm-extension\";\nimport { z } from \"zod\";\n\n/**\n * comms-adherence-gate\n *\n * When an agent calls `store-progress` with status \"completed\" on a task that\n * reaches a human in Slack, or posts to Slack itself (`slack-reply`,\n * `slack-post`, `slack-start-thread`, `slack-update`), judge the text with Jev:\n * against the requesting user's stored comms preferences\n * (users.metadata.$.comms) and what that user actually asked for in their\n * latest message, and against a plain-language rubric that applies to every\n * message whatever preferences exist. An explicit request (\"tell me a long\n * joke\", \"explain in detail\") outranks the stored default, so a requested long\n * answer is not a verbosity failure.\n *\n * Threads with several people: a message that @-mentions someone is judged\n * against the first mentioned person with stored preferences, skipping a\n * requester without preferences; otherwise against the requester. `plain` applies to everyone.\n *\n * Transport (config.provider): Jev is served by TypeSafe directly and by\n * OpenRouter's Decisions endpoint. Both take the same {model, state, questions}\n * body and return the same `answers` shape. `auto` uses TYPESAFE_API_KEY when\n * set, else OPENROUTER_API_KEY.\n *\n * modes (config.mode for the preference dimensions, config.plainMode for `plain`):\n * off -> never evaluate\n * shadow -> evaluate + record, never block (default)\n * enforce -> record, and block the call up to maxBlocksPerTask times per task\n * with actionable feedback. The budget is shared by both modes and\n * by every gated tool.\n *\n * Fails OPEN on every error: a judge outage must never wall the swarm.\n * Every verdict lands in KV namespace `ext:comms-gate`.\n */\n\nexport const config = z.object({\n mode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n /** A preference dimension scoring below this fails. */\n threshold: z.number().min(0).max(1).default(0.5),\n /** The `plain` dimension, judged on every message. Independent of `mode`. */\n plainMode: z.enum([\"off\", \"shadow\", \"enforce\"]).default(\"shadow\"),\n /**\n * `plain` scoring below this fails. Jev scores dense status text low and\n * plain text high with little in between, so this sits far below `threshold`.\n */\n plainThreshold: z.number().min(0).max(1).default(0.25),\n timeoutMs: z.number().int().positive().default(4000),\n maxBlocksPerTask: z.number().int().min(0).default(1),\n provider: z.enum([\"auto\", \"typesafe\", \"openrouter\"]).default(\"auto\"),\n /** Jev model on the TypeSafe transport. */\n model: z.string().default(\"jev-latest\"),\n /** Jev model on the OpenRouter transport. */\n openrouterModel: z.string().default(\"typesafe/jev-1.13\"),\n /** Explicit TypeSafe key; otherwise TYPESAFE_API_KEY from the API process env. */\n apiKey: z.string().optional(),\n /**\n * Fixed text the operator's own templates mandate, judged by the self-test and\n * expected to pass. Kept loose here and parsed per entry by `fixturesOf`, so one\n * bad entry cannot fail the whole config and drop `mode` back to its default.\n */\n fixtures: z.unknown().optional(),\n});\n\ntype Cfg = z.infer<typeof config>;\ntype Swarm = ApiCtx[\"swarm\"];\n\nconst NS = \"ext:comms-gate\";\nconst TYPESAFE_ENDPOINT = \"https://api.typesafe.ai/v1/systemone\";\nconst OPENROUTER_ENDPOINT = \"https://openrouter.ai/api/alpha/decisions\";\nconst UUID_RE = /^[0-9a-fA-F-]{36}$/;\n/** MCP tools that post agent-authored text to Slack, all with a `message` arg. */\nexport const SLACK_TOOLS = new Set([\n \"slack-reply\",\n \"slack-post\",\n \"slack-start-thread\",\n \"slack-update\",\n]);\n// The dispatcher cancels a handler after 5 s; leave room for the DB read and KV writes.\nconst MAX_TIMEOUT_MS = 4000;\n\nexport const cfgOf = (raw: unknown): Cfg => {\n const parsed = config.safeParse(raw ?? {});\n return parsed.success ? parsed.data : config.parse({});\n};\n\n// kv keys accept [a-zA-Z0-9._:/%-]\nconst safeKey = (raw: string | undefined | null): string =>\n (raw && raw.length > 0 ? raw : \"unknown\").replace(/[^a-zA-Z0-9._-]/g, \"_\").slice(0, 120);\n\n/** SDK envelopes: {success, data:{...}} or the bare payload. */\ntype Envelope = {\n data?: { rows?: unknown[]; value?: unknown };\n rows?: unknown[];\n value?: unknown;\n} | null;\n\nconst cell = (row: unknown, i: number, key: string): unknown =>\n Array.isArray(row) ? row[i] : (row as Record<string, unknown>)?.[key];\n\n/**\n * The newest human message sits at the END of a Slack task: the\n * `<thread_context>` blob comes first and can run to thousands of chars, so a\n * leading slice of `agent_tasks.task` shows the judge everything except the\n * actual request. Take the tail, then the part after the last `</thread_context>`.\n */\nconst CTX_END = \"</thread_context>\";\nexport const latestAsk = (tail: string): string => {\n const end = tail.lastIndexOf(CTX_END);\n let out = (end >= 0 ? tail.slice(end + CTX_END.length) : tail)\n .replace(/\\[Thread follow-up[^\\]]*\\]/g, \"\")\n .trim();\n // Some tasks end with the context block; fall back to the last messages in it.\n if (out.length < 8) out = (end >= 0 ? tail.slice(0, end) : tail).trim().slice(-800);\n return out.slice(0, 900);\n};\n\n// Preferences are the DEFAULT. A direct request outranks them.\nconst JUDGING_RULES = [\n \"The requester's explicit instruction in latest_request OUTRANKS requester_preferences. Preferences describe the DEFAULT; they never override a direct request.\",\n \"If latest_request asks for something long, detailed, creative, a story, a joke, a full explanation or a document, then length and structure serving that request are CORRECT and must NOT be penalized.\",\n \"Judge whether agent_message serves what latest_request actually asked for, written in the requester's manner. Do not judge it against the default preference when the request overrides it.\",\n];\n\ntype Prefs = { verbosity?: unknown; tone?: unknown; language?: unknown } & Record<string, unknown>;\n\n/**\n * The `plain` rubric, from the `comms` skill (Simpler and Precise modes). Jev\n * separates dense from plain text reliably only with contrasting examples; a\n * prose-only rubric scored a plain rewrite as low as the dense original.\n */\nexport const PLAIN_RULES = [\n \"Examples of NOT plain: 'p50 Δ +120ms vs baseline (n=37)', 'error rate 2.1% → 0.4% (cohort B, ±0.3 at 95%)', 'cost $-42/day', 'first-call hit ratio 0.61', 'drift unmeasured; 2 flaky'.\",\n \"Examples of plain: 'Pages load 120 ms slower than last week, across 37 runs', 'Errors dropped from 2 in 100 requests to 4 in 1,000', 'We spend $42 a day less', 'PR #123 keeps the migration reversible', 'Lead saves about $75 a week'.\",\n \"Code identifiers, task ids, PR numbers, links, file paths and version numbers are fine as they are.\",\n];\n\nexport const PLAIN_QUESTION = {\n type: \"noul\",\n instructions:\n \"Is agent_message written like the plain examples in plain_language_rules rather than like the NOT plain ones? Ignore length and tone.\",\n criteria: {\n true: \"Written like the plain examples: everyday words and numbers with units and direction.\",\n false:\n \"Written like the NOT plain examples: statistics shorthand, abbreviations, signed or cryptic numbers.\",\n },\n};\n\n/** Structured output (an outputSchema answer) is for machines; `plain` skips it. */\nexport const looksLikeJson = (text: string): boolean => {\n if (!/^[[{]/.test(text)) return false;\n try {\n JSON.parse(text);\n return true;\n } catch {\n return false;\n }\n};\n\n/** One `noul` question per stated preference the gate knows how to judge. */\nexport const buildQuestions = (prefs: Prefs): Record<string, unknown> => {\n const questions: Record<string, unknown> = {};\n if (prefs.verbosity) {\n questions.verbosity = {\n type: \"noul\",\n instructions:\n \"Does agent_message respect the requester's verbosity preference, AS OVERRIDDEN by any explicit instruction in latest_request? Apply judging_rules.\",\n criteria: {\n true: \"Length and structure fit what latest_request asked for (or the stated preference when the request does not override it), and it leads with the result.\",\n false:\n \"Too long for what was asked, or it opens with preamble, recaps the request, narrates the process, or ends with an offer to elaborate. Length explicitly requested in latest_request is NOT a failure.\",\n },\n };\n }\n if (prefs.tone) {\n questions.tone = {\n type: \"noul\",\n instructions:\n \"Does agent_message match the requester's stated tone preference, as overridden by any explicit instruction in latest_request? Apply judging_rules.\",\n criteria: {\n true: \"The tone matches what the requester asked for.\",\n false:\n \"The tone conflicts with it (for example hedging, flattery or filler when the requester asked for direct and plain). A voice appropriate to an explicitly requested creative or narrative form is NOT a failure.\",\n },\n };\n }\n if (prefs.language) {\n questions.language = {\n type: \"noul\",\n instructions: \"Is agent_message written in the requester's stated language?\",\n criteria: {\n true: \"Written in the stated language.\",\n false: \"Written in a different language.\",\n },\n };\n }\n return questions;\n};\n\nconst secretCache = new Map<string, { value: string; at: number }>();\nconst KEY_TTL_MS = 5 * 60 * 1000;\nconst usable = (v: string): boolean => Boolean(v) && !v.startsWith(\"[REDACTED\");\nconst envOf = (name: string): string => String(process.env[name] ?? \"\");\n\n/**\n * Resolve a secret: explicit value, then the API process env. The API process loads\n * global swarm_config rows into process.env at boot and on config reload.\n * ctx.swarm.config_get cannot serve it: the SDK scrubs secrets to \"[REDACTED:<name>]\".\n */\nconst secret = (name: string, explicit?: string): string => {\n const cached = secretCache.get(name);\n if (cached && Date.now() - cached.at < KEY_TTL_MS) return cached.value;\n const value = [String(explicit ?? \"\"), envOf(name)].find(usable) ?? \"\";\n if (usable(value)) secretCache.set(name, { value, at: Date.now() });\n return value;\n};\n\n/** Test hook: forget cached secrets. */\nexport const resetKeyCache = (): void => {\n secretCache.clear();\n};\n\nexport type JevTransport = {\n provider: \"typesafe\" | \"openrouter\";\n endpoint: string;\n key: string;\n model: string;\n};\n\n/**\n * Pick the Jev transport. `auto` prefers TypeSafe and falls back to OpenRouter.\n * Throws when the chosen provider has no usable key; the handler fails open.\n */\nexport const resolveTransport = (cfg: Cfg): JevTransport => {\n const typesafe = (): JevTransport | null => {\n const key = secret(\"TYPESAFE_API_KEY\", cfg.apiKey);\n return usable(key)\n ? { provider: \"typesafe\", endpoint: TYPESAFE_ENDPOINT, key, model: cfg.model }\n : null;\n };\n const openrouter = (): JevTransport | null => {\n const key = secret(\"OPENROUTER_API_KEY\");\n return usable(key)\n ? { provider: \"openrouter\", endpoint: OPENROUTER_ENDPOINT, key, model: cfg.openrouterModel }\n : null;\n };\n const transport =\n cfg.provider === \"typesafe\"\n ? typesafe()\n : cfg.provider === \"openrouter\"\n ? openrouter()\n : (typesafe() ?? openrouter());\n if (transport) return transport;\n throw new Error(\n cfg.provider === \"typesafe\"\n ? \"no TYPESAFE_API_KEY\"\n : cfg.provider === \"openrouter\"\n ? \"no OPENROUTER_API_KEY\"\n : \"no TYPESAFE_API_KEY or OPENROUTER_API_KEY\",\n );\n};\n\n/**\n * The judge input for one message. The live gate and the self-test fixtures build it\n * here, so a fixture is judged exactly like real traffic.\n */\nexport const gateState = (s: {\n requester: string;\n prefs: Prefs;\n ask: string;\n threadOpening: string;\n text: string;\n}): Record<string, unknown> => ({\n role: \"You audit an AI agent's message to the human who requested the work.\",\n requester: s.requester,\n requester_preferences: s.prefs,\n latest_request: s.ask,\n thread_opening: s.threadOpening,\n judging_rules: JUDGING_RULES,\n plain_language_rules: PLAIN_RULES,\n agent_message: s.text,\n});\n\n/** One Jev call; returns the `noul` score per question. Throws on any failure. */\nexport const askJev = async (\n state: Record<string, unknown>,\n questions: Record<string, unknown>,\n transport: JevTransport,\n cfg: Cfg,\n outer?: AbortSignal,\n): Promise<{ scores: Record<string, number>; latencyMs: number }> => {\n const controller = new AbortController();\n const timer = setTimeout(() => controller.abort(), Math.min(cfg.timeoutMs, MAX_TIMEOUT_MS));\n const onOuterAbort = () => controller.abort();\n outer?.addEventListener(\"abort\", onOuterAbort);\n const t0 = Date.now();\n try {\n const res = await fetch(transport.endpoint, {\n method: \"POST\",\n headers: { \"Content-Type\": \"application/json\", Authorization: `Bearer ${transport.key}` },\n body: JSON.stringify({ state, model: transport.model, questions }),\n signal: controller.signal,\n });\n if (!res.ok) throw new Error(`${transport.provider} ${res.status}`);\n const body = (await res.json()) as { answers?: Record<string, { noul?: unknown }> } | null;\n const answers = body?.answers;\n if (!answers || typeof answers !== \"object\") throw new Error(\"no answers in response\");\n const scores: Record<string, number> = {};\n for (const [id, a] of Object.entries(answers)) {\n if (typeof a?.noul === \"number\") scores[id] = a.noul;\n }\n if (Object.keys(scores).length === 0) throw new Error(\"no scores in response\");\n return { scores, latencyMs: Date.now() - t0 };\n } finally {\n clearTimeout(timer);\n outer?.removeEventListener(\"abort\", onOuterAbort);\n }\n};\n\nconst SELFTEST = \"comms-gate-selftest\";\nconst SELFTEST_PREFS = {\n tone: \"direct, plain, no hedging\",\n language: \"English\",\n verbosity:\n \"very terse - answer in the first sentence, ~400 chars max. No preamble, no recap, no closing offer.\",\n};\nconst SELFTEST_BAD =\n \"Great question! Let me walk you through what I did here. First I looked at the task, then I reviewed the relevant files, and after careful consideration I decided to go with option B. I hope this helps - let me know if you would like me to elaborate further on any of the above!\";\nconst SELFTEST_GOOD =\n \"Went with option B: it is the only one that keeps the migration reversible. PR #123.\";\n// A real dense monitor post a requester had to ask to have rewritten, and that rewrite.\nconst SELFTEST_PLAIN_BAD =\n \"Prompt cache monitor, day 7 verdict for v2.0.0: partial. Lead first-call read median 12.4k (baseline v1.173.0, n 410) → 19.1k tokens (n 2234; expected 25.0k-40.0k). First-call saving about $75/week on Lead vs v1.173.0 (expected $129; sampling noise ±$24 at 95%, one baseline version, day-to-day drift not measured); session $ change $-167/week; fleet first-call saving $-7/week.\";\nconst SELFTEST_PLAIN_GOOD =\n \"Cheaper, but half what we hoped: Lead saves about $75 a week, not $129. Whole Lead tasks still cost $167 a week more, probably from other releases and heavier work, not this change.\";\n\nconst below = (bad: unknown, good: unknown, threshold: number): boolean =>\n typeof bad === \"number\" && typeof good === \"number\" && bad < threshold && good >= threshold;\n\n/** Fixtures judged per self-test run: one Jev call each, inside the 5 s handler budget. */\nexport const MAX_FIXTURES = 8;\nconst fixture = z.object({\n name: z.string().min(1).max(80),\n /** The fixed text as it will be posted, placeholders filled with sample values. */\n text: z.string().min(1).max(4000),\n /** Audience preferences; omit to judge `plain` only. */\n prefs: z\n .object({\n verbosity: z.string().optional(),\n tone: z.string().optional(),\n language: z.string().optional(),\n })\n .optional(),\n /** The request the text answers, as `latest_request`. */\n request: z.string().max(900).optional(),\n});\nexport type Fixture = z.infer<typeof fixture>;\n\n/** Valid fixture entries, in order, capped at MAX_FIXTURES; invalid entries are skipped. */\nexport const fixturesOf = (raw: unknown): Fixture[] =>\n (Array.isArray(raw) ? raw : [])\n .map((f) => fixture.safeParse(f))\n .filter((r) => r.success)\n .map((r) => r.data)\n .slice(0, MAX_FIXTURES);\n\n/**\n * Judge each fixture with the live gate's questions and state. A fixture is fixed\n * text the operator expects to pass, so any dimension below its threshold fails it.\n */\nconst judgeFixtures = async (\n fixtures: Fixture[],\n transport: JevTransport,\n cfg: Cfg,\n signal?: AbortSignal,\n) =>\n Promise.all(\n fixtures.map(async (f) => {\n const prefs: Prefs = f.prefs ?? {};\n const questions = { ...buildQuestions(prefs), plain: PLAIN_QUESTION };\n try {\n const { scores } = await askJev(\n gateState({\n requester: \"the requester\",\n prefs,\n ask: f.request ?? \"\",\n threadOpening: \"\",\n text: f.text,\n }),\n questions,\n transport,\n cfg,\n signal,\n );\n const failed = Object.keys(questions).filter((dim) => {\n const s = scores[dim];\n return typeof s !== \"number\" || s < (dim === \"plain\" ? cfg.plainThreshold : cfg.threshold);\n });\n return { name: f.name, scores, failed, pass: failed.length === 0 };\n } catch (err) {\n return { name: f.name, error: String(err).slice(0, 200), pass: false };\n }\n }),\n );\n\n/**\n * Run the judge on known-bad (positive control, must score below threshold) and\n * known-good (negative control, must score at or above it) messages and record\n * them under `selftest:last`: one pair for verbosity, one for `plain`. Proves key,\n * egress and KV from inside the API runtime without touching real traffic.\n */\nconst selfTest = async (swarm: Swarm, cfg: Cfg, signal?: AbortSignal): Promise<void> => {\n const started = Date.now();\n try {\n const transport = resolveTransport(cfg);\n const judge = (message: string, dim: \"verbosity\" | \"plain\") =>\n askJev(\n dim === \"plain\"\n ? { plain_language_rules: PLAIN_RULES, agent_message: message }\n : { requester_preferences: SELFTEST_PREFS, agent_message: message },\n { [dim]: dim === \"plain\" ? PLAIN_QUESTION : buildQuestions(SELFTEST_PREFS).verbosity },\n transport,\n cfg,\n signal,\n ).then((r) => r.scores[dim] ?? null);\n const fixtures = fixturesOf(cfg.fixtures);\n const [bad, good, plainBad, plainGood, fixtureResults] = await Promise.all([\n judge(SELFTEST_BAD, \"verbosity\"),\n judge(SELFTEST_GOOD, \"verbosity\"),\n judge(SELFTEST_PLAIN_BAD, \"plain\"),\n judge(SELFTEST_PLAIN_GOOD, \"plain\"),\n judgeFixtures(fixtures, transport, cfg, signal),\n ]);\n await swarm.kv_set({\n namespace: NS,\n key: \"selftest:last\",\n value: {\n at: new Date().toISOString(),\n provider: transport.provider,\n threshold: cfg.threshold,\n positiveControlBadScore: bad,\n negativeControlGoodScore: good,\n controlsOk: below(bad, good, cfg.threshold),\n plainThreshold: cfg.plainThreshold,\n plainPositiveControlBadScore: plainBad,\n plainNegativeControlGoodScore: plainGood,\n plainControlsOk: below(plainBad, plainGood, cfg.plainThreshold),\n fixtures: fixtureResults,\n // null when none are configured: zero fixtures is not a pass.\n fixturesOk: fixtureResults.length === 0 ? null : fixtureResults.every((f) => f.pass),\n latencyMs: Date.now() - started,\n },\n });\n } catch (err) {\n await swarm\n .kv_set({\n namespace: NS,\n key: \"selftest:last\",\n value: {\n at: new Date().toISOString(),\n error: String(err).slice(0, 400),\n latencyMs: Date.now() - started,\n },\n })\n .catch(() => {});\n }\n};\n\nconst TASK_SQL = `SELECT t.source, t.slackThreadTs, t.agentId, t.requestedByUserId,\n json_extract(u.metadata, '$.comms') AS comms, u.name,\n substr(t.task, 1, 400) AS askHead,\n substr(t.task, -1400) AS askTail,\n t.creatorAgentId\nFROM agent_tasks t\nLEFT JOIN users u ON u.id = t.requestedByUserId\nWHERE t.id = ?`;\n\nconst LEAD_SQL = \"SELECT isLead FROM agents WHERE id = ?\";\n\n/** Slack user mentions in agent text: `<@U123>` or `<@U123|name>`. */\nconst MENTION_RE = /<@([UW][A-Z0-9]+)(?:\\|[^>]*)?>/g;\nconst MAX_MENTIONS = 5;\n\n/** Mentioned Slack user ids in order of first appearance, capped. */\nexport const mentionedSlackIds = (text: string): string[] => {\n const ids: string[] = [];\n for (const m of text.matchAll(MENTION_RE)) {\n if (!ids.includes(m[1]!)) ids.push(m[1]!);\n if (ids.length >= MAX_MENTIONS) break;\n }\n return ids;\n};\n\nconst addresseeSql = (n: number) => `SELECT x.externalId, u.id, u.name,\n json_extract(u.metadata, '$.comms') AS comms\nFROM user_external_ids x\nJOIN users u ON u.id = x.userId\nWHERE x.kind = 'slack' AND x.externalId IN (${Array(n).fill(\"?\").join(\", \")})`;\n\nconst parsePrefs = (raw: unknown): Prefs | null => {\n if (!raw) return null;\n const parsed = typeof raw === \"string\" ? JSON.parse(raw) : raw;\n return parsed && typeof parsed === \"object\" && Object.keys(parsed).length > 0\n ? (parsed as Prefs)\n : null;\n};\n\ntype Audience = { id: string; name: string; prefs: Prefs; via: \"mention\" | \"requester\" };\n\n/**\n * Whose preferences a message is judged against. In a thread with several\n * people, the message is for whoever it @-mentions: the first mentioned person\n * with stored preferences wins, including the requester only if they have prefs.\n * Without such a mention, the task requester (the\n * person whose message created this task). One SQL read, only when the text\n * mentions someone; no judge call.\n */\nconst resolveAudience = async (\n swarm: Swarm,\n text: string,\n requester: Audience,\n): Promise<Audience> => {\n const ids = mentionedSlackIds(text);\n if (ids.length === 0) return requester;\n const q = (await swarm.db_query({ sql: addresseeSql(ids.length), params: ids })) as Envelope;\n const rows = q?.data?.rows ?? q?.rows ?? [];\n for (const slackId of ids) {\n const row = rows.find((r) => String(cell(r, 0, \"externalId\")) === slackId);\n if (!row) continue;\n const userId = String(cell(row, 1, \"id\") ?? \"\");\n // A requester with stored preferences keeps their own task context.\n if (userId && userId === requester.id) {\n if (Object.keys(requester.prefs).length > 0) return requester;\n continue;\n }\n const prefs = parsePrefs(cell(row, 3, \"comms\"));\n if (!prefs) continue;\n return { id: userId, name: String(cell(row, 2, \"name\") ?? userId), prefs, via: \"mention\" };\n }\n return requester;\n};\n\n/**\n * Mirrors the `task.progress.write` rule store-progress enforces\n * (src/rbac/legacy-policy.ts): the caller owns the task, the task is\n * unassigned, or the caller is a lead. Lead status comes from the caller's\n * agents row, never from tool args. Extension callers return before this.\n */\nconst mayWriteProgress = async (\n swarm: Swarm,\n callerId: string | undefined,\n taskAgentId: string,\n): Promise<boolean> => {\n if (!callerId) return false;\n if (!taskAgentId || taskAgentId === callerId) return true;\n const q = (await swarm.db_query({ sql: LEAD_SQL, params: [callerId] })) as Envelope;\n const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n return Number(cell(row, 0, \"isLead\") ?? 0) === 1;\n};\n\n/** The text a gated call would put in front of a human, and the task it belongs to. */\nconst gatedText = (\n tool: string,\n args: Record<string, unknown>,\n sourceTaskId: string | undefined,\n): { text: string; taskId: string } | null => {\n if (tool === \"store-progress\") {\n if (args.status !== \"completed\") return null;\n return {\n text: typeof args.output === \"string\" ? args.output.trim() : \"\",\n taskId: String(args.taskId ?? sourceTaskId ?? \"\"),\n };\n }\n if (SLACK_TOOLS.has(tool)) {\n // slack-reply names its task; the other tools post from the caller's task context.\n const named = tool === \"slack-reply\" ? args.taskId : undefined;\n return {\n text: typeof args.message === \"string\" ? args.message.trim() : \"\",\n taskId: String(named ?? sourceTaskId ?? \"\"),\n };\n }\n return null;\n};\n\nconst extension: SwarmExtension = (api) => {\n api.on(\"pre.tool.call\", async (event, ctx) => {\n if (event.tool !== \"store-progress\" && !SLACK_TOOLS.has(event.tool)) return;\n const origin = event.requestInfo?.callOrigin;\n if (origin === \"extension\") return;\n\n const cfg = cfgOf(ctx.config);\n if (cfg.mode === \"off\" && cfg.plainMode === \"off\") return;\n\n const args = (event.args ?? {}) as Record<string, unknown>;\n\n // Self-test hatch: a progress call whose text starts with the sentinel runs\n // the controls and records them under `selftest:last`.\n if (\n event.tool === \"store-progress\" &&\n args.status !== \"completed\" &&\n typeof args.progress === \"string\" &&\n args.progress.startsWith(SELFTEST)\n ) {\n await selfTest(ctx.swarm, cfg, ctx.signal);\n return;\n }\n\n const gated = gatedText(event.tool, args, event.requestInfo?.sourceTaskId);\n if (!gated?.text) return;\n const { text, taskId } = gated;\n if (!UUID_RE.test(taskId)) return;\n\n try {\n const q = (await ctx.swarm.db_query({ sql: TASK_SQL, params: [taskId] })) as Envelope;\n const row = (q?.data?.rows ?? q?.rows ?? [])[0];\n if (!row) return;\n\n const source = String(cell(row, 0, \"source\") ?? \"\");\n const slackThreadTs = cell(row, 1, \"slackThreadTs\");\n const agentId = String(cell(row, 2, \"agentId\") ?? \"\");\n const requesterId = String(cell(row, 3, \"requestedByUserId\") ?? \"\");\n const commsRaw = cell(row, 4, \"comms\");\n const requesterName = String(cell(row, 5, \"name\") ?? (requesterId || \"the requester\"));\n const threadOpening = String(cell(row, 6, \"askHead\") ?? \"\");\n const ask = latestAsk(String(cell(row, 7, \"askTail\") ?? \"\"));\n\n // Judge only a call the tool itself will accept, so no agent can ship another\n // task's thread and preferences to the external judge. store-progress follows\n // its write rule; the Slack tools follow slack-reply's: the caller is the\n // task's assignee or its creator.\n const callerId = event.requestInfo?.agentId;\n const creatorAgentId = String(cell(row, 8, \"creatorAgentId\") ?? \"\");\n const allowed =\n event.tool === \"store-progress\"\n ? await mayWriteProgress(ctx.swarm, callerId, agentId)\n : Boolean(callerId) && (callerId === agentId || callerId === creatorAgentId);\n if (!allowed) return;\n\n // A completion reaches a human only on a Slack task; a Slack tool always does.\n if (event.tool === \"store-progress\" && source !== \"slack\" && !slackThreadTs) return;\n\n const requester: Audience = {\n id: requesterId,\n name: requesterName,\n prefs: parsePrefs(commsRaw) ?? {},\n via: \"requester\",\n };\n // `plain` alone judges no one's preferences, so it skips the lookup.\n const audience =\n cfg.mode === \"off\" ? requester : await resolveAudience(ctx.swarm, text, requester);\n const { prefs, name: audienceName } = audience;\n\n const questions: Record<string, unknown> = cfg.mode === \"off\" ? {} : buildQuestions(prefs);\n // Only a store-progress outputSchema answer is machine JSON; a Slack post is\n // always read by a human, JSON or not.\n if (cfg.plainMode !== \"off\" && (event.tool !== \"store-progress\" || !looksLikeJson(text)))\n questions.plain = PLAIN_QUESTION;\n if (Object.keys(questions).length === 0) return;\n\n const transport = resolveTransport(cfg);\n const { scores, latencyMs } = await askJev(\n gateState({ requester: audienceName, prefs, ask, threadOpening, text }),\n questions,\n transport,\n cfg,\n ctx.signal,\n );\n\n const limitOf = (dim: string) => (dim === \"plain\" ? cfg.plainThreshold : cfg.threshold);\n const failed = Object.entries(scores)\n .filter(([k, v]) => v < limitOf(k))\n .map(([k]) => k);\n // Script SDK calls never reach pre.tool.call today; if one does, record it only.\n const blocking =\n origin === \"script-sdk\"\n ? []\n : failed.filter((d) => (d === \"plain\" ? cfg.plainMode : cfg.mode) === \"enforce\");\n\n const verdict = {\n at: new Date().toISOString(),\n tool: event.tool,\n taskId,\n agentId,\n source,\n requester: requesterName,\n requesterId,\n judgedFor: audience.via,\n audienceId: audience.id,\n audience: audienceName,\n provider: transport.provider,\n scores,\n failed,\n threshold: cfg.threshold,\n plainThreshold: cfg.plainThreshold,\n mode: cfg.mode,\n plainMode: cfg.plainMode,\n latencyMs,\n preferences: prefs,\n askPreview: ask.slice(0, 400),\n outputPreview: text.slice(0, 700),\n };\n\n await ctx.swarm.kv_incr({ namespace: NS, key: \"total\" });\n await ctx.swarm.kv_set({ namespace: NS, key: \"last\", value: verdict });\n\n if (failed.length === 0) {\n await ctx.swarm.kv_incr({ namespace: NS, key: \"pass\" });\n return;\n }\n\n await ctx.swarm.kv_incr({ namespace: NS, key: \"fail\" });\n for (const dim of failed) {\n await ctx.swarm.kv_incr({ namespace: NS, key: `dim:${safeKey(dim)}` });\n }\n\n const blocksKey = `blocks:${safeKey(taskId)}`;\n // kv_get answers {success, data:{value}}, and {success:false} when absent.\n const prior = (await ctx.swarm.kv_get({ namespace: NS, key: blocksKey })) as Envelope;\n const priorBlocks = Number(prior?.data?.value ?? prior?.value ?? 0) || 0;\n const willBlock = blocking.length > 0 && priorBlocks < cfg.maxBlocksPerTask;\n\n await ctx.swarm.kv_set({\n namespace: NS,\n key: `fail:${Date.now()}:${safeKey(taskId)}`,\n value: { ...verdict, action: willBlock ? \"blocked\" : \"recorded\" },\n });\n\n if (!willBlock) {\n await ctx.swarm.kv_incr({\n namespace: NS,\n key: blocking.length > 0 ? \"escaped\" : \"shadowed\",\n });\n return;\n }\n\n await ctx.swarm.kv_incr({ namespace: NS, key: \"blocked\" });\n await ctx.swarm.kv_incr({ namespace: NS, key: blocksKey });\n\n const lines = [\n blocking.includes(\"plain\")\n ? `Comms gate: this message is not in plain words for ${audienceName}.`\n : `Comms gate: this output does not match ${audienceName}'s stated preferences.`,\n ];\n for (const d of blocking) {\n const score = `${d} (${scores[d]!.toFixed(2)} vs ${limitOf(d)})`;\n lines.push(\n d === \"plain\"\n ? `${score}: a reader outside the swarm cannot follow it on first read.`\n : `${score}: requested ${String(prefs[d] ?? \"\").slice(0, 220)}`,\n );\n }\n lines.push(\n blocking.includes(\"plain\")\n ? `Rewrite the message with the \\`comms\\` skill (Simpler mode): common words, one idea per sentence, every number with a unit and a direction word, shorthand explained or replaced. Keep every number, name, link and hedge verbatim, then call ${event.tool} again.`\n : `Rewrite the message to match and call ${event.tool} again. Do not change the facts, only how they are said.`,\n );\n return block(lines.join(\"\\n\"));\n } catch (err) {\n // Fail open, always.\n try {\n await ctx.swarm.kv_incr({ namespace: NS, key: \"error\" });\n await ctx.swarm.kv_set({\n namespace: NS,\n key: \"error:last\",\n value: {\n at: new Date().toISOString(),\n tool: event.tool,\n taskId,\n error: String(err).slice(0, 400),\n },\n });\n } catch {\n /* ignore */\n }\n ctx.log.warn(\"comms-adherence-gate: failing open\", { error: String(err) });\n return;\n }\n });\n};\n\nexport default extension;\n"
|
|
16
16
|
},
|
|
17
|
-
"readme": "# comms-adherence-gate\n\nAgents finish Slack tasks with a final message a human reads, and post to Slack threads directly. This extension judges that text with Jev, [TypeSafe](https://typesafe.ai)'s decision model: against the requester's stated comms preferences and their latest request, and against a plain-language rubric that applies to every message. In `enforce` it blocks a failing call once and tells the agent what to fix. A `plain` failure points the agent at the `comms` skill.\n\nInstall config:\n\n```json\n{ \"mode\": \"shadow\", \"plainMode\": \"shadow\" }\n```\n\nStart in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`. `mode` and `plainMode` move independently.\n\n## Modes\n\n| `mode` | Effect |\n|---|---|\n| `off` | Never evaluates. |\n| `shadow` (default) | Asks Jev and records the verdict. Never blocks. |\n| `enforce` | Asks Jev, records the verdict, and blocks the call when a dimension fails, at most `maxBlocksPerTask` times per task. The agent gets the failed dimensions, their scores and the stated preference, and calls again. |\n\n`mode` governs the preference dimensions (`verbosity`, `tone`, `language`). `plainMode` governs `plain`. A dimension blocks only when its own mode is `enforce`. Both share one block budget per task, across every gated tool.\n\n## What it gates\n\nHook: `pre.tool.call` on:\n\n- `store-progress` with `status: \"completed\"` and a non-empty `output`, on a task that came from Slack (`source = \"slack\"` or a `slackThreadTs`). Other completions pass without a Jev call.\n- `slack-reply`, `slack-post`, `slack-start-thread` and `slack-update`, judged on `message`. The task is `slack-reply`'s `taskId`, else the caller's task context. A post with no task context passes.\n\nOnly a call the tool itself accepts is judged, so no other task's text reaches Jev. For `store-progress` the caller must own the task, the task must be unassigned, or the caller must be a lead. For the Slack tools the caller must be the task's assignee or its creator, the rule `slack-reply` enforces. Calls made by extensions are skipped. Script SDK calls never reach `pre.tool.call` (the tool registrar dispatches it only for MCP calls); if one ever does, the gate records it and never blocks.\n\nA requester with no stated preferences in `users.metadata.comms` still gets the `plain` question. Set preferences with the `manage-user` tool.\n\nIn a thread with several people, the requester is the person whose message created the task. A message that @-mentions someone (`<@U123>`) is judged against the first mentioned person with stored preferences, resolved through their Slack identity in `user_external_ids`; otherwise against the requester. The lookup is one SQL read, only when the text mentions someone and `mode` is not `off`. The verdict records who was judged in `judgedFor` (`mention` or `requester`) and `audience`.\n\n## Decision\n\nThe gate reads the task row and asks one `noul` question per stated preference it knows: `verbosity`, `tone`, `language`. Any other key in `comms` is context only.\n\nJev sees the preferences, the requester's latest message (the text after the last `</thread_context>`, from the last 1,400 characters of the task), the first 400 characters of the task, and the output. Its judging rules say an explicit request outranks the stored default. A requested long answer, story or document is not a verbosity failure.\n\nIt also asks `plain` on every message unless `plainMode` is `off` or the text is a JSON document (structured output for an `outputSchema`). The rubric comes from the `comms` skill: everyday words, one idea per sentence, every number with a unit and a direction word, and no unexplained shorthand (n, median, p90, cohort, baseline, delta, `±X at 95%`). Code identifiers, task ids, PR numbers, links and versions are fine. Jev gets contrasting plain and dense examples in `plain_language_rules`; a prose-only rubric scored plain rewrites as low as the dense originals.\n\nAll questions go in one Jev request. A preference dimension fails below `threshold`; `plain` fails below `plainThreshold`. Any failed dimension fails the message.\n\n### Calibration of `plain`\n\nJev scores dense status text near 0 and plain text near 0.8 to 0.9, with a wide middle of compact but readable engineering notes. Measured on 400 Slack-facing completions over 7 days, at `threshold` 0.75 for preferences:\n\n| `plainThreshold` | Newly blocked (of messages that pass today) |\n|---|---|\n| 0.75 | 81% to 83% |\n| 0.3 | 9% to 13% |\n| 0.25 (default) | 5% to 7% |\n\nAt 0.25 the dense prompt-cache-monitor post scores about 0.15 and its plain rewrite about 0.81.\n\n## Jev transport\n\nJev is reachable two ways. Both take the same request and return the same answer.\n\n| `provider` | Endpoint | Key | Model |\n|---|---|---|---|\n| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |\n| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |\n| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |\n\nEach verdict row records the `provider` that answered.\n\n## Fail open\n\nEvery error lets the completion through: a missing key, an HTTP error, a network error, a timeout, a malformed answer, or a failed DB read. The handler never throws, so an outage cannot auto-disable the extension. Each failure bumps the `error` counter and overwrites `error:last`.\n\n## Self-test\n\nCall `store-progress` with a non-completed status and `progress` starting with `comms-gate-selftest`. The gate judges a known-bad and a known-good message against a terse preference, and a dense and a plain message on `plain`, then writes `selftest:last`: every score, both thresholds, the provider, `controlsOk` (verbosity: bad below `threshold`, good at or above it) and `plainControlsOk` (the same against `plainThreshold`). Real traffic is untouched.\n\n## Config\n\n| Key | Default | Notes |\n|---|---|---|\n| `mode` | `shadow` | `off`, `shadow`, or `enforce` |\n| `threshold` | `0.5` | A preference dimension scoring below this fails |\n| `plainMode` | `shadow` | `off`, `shadow`, or `enforce` for the `plain` dimension |\n| `plainThreshold` | `0.25` | `plain` scoring below this fails. See [Calibration](#calibration-of-plain) |\n| `timeoutMs` | `4000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |\n| `maxBlocksPerTask` | `1` | Blocks per task in `enforce`; after that the gate records and lets it through |\n| `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |\n| `model` | `jev-latest` | Jev model on TypeSafe |\n| `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |\n| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |\n\n## Required secrets\n\nRead from the API process environment at call time. Set them as global `swarm_config` secrets: the API process loads global rows into `process.env` at boot and on config reload.\n\n- `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`: one is required for any evaluation. Under `auto`, TypeSafe wins when both are set. Without either, every completion fails open.\n\nNo key is written to config, KV, logs, or a block reason.\n\n## KV namespace `ext:comms-gate`\n\n- `last`: the latest verdict, with `tool`, `scores`, `failed`, `mode`, `plainMode`, `provider`, `latencyMs`, the preferences, a 400-character `askPreview` and a 700-character `outputPreview`.\n- `fail:<epochMs>:<taskId>`: one row per failed verdict, with `action` (`blocked` or `recorded`).\n- `blocks:<taskId>`: blocks issued for that task.\n- `error:last`, `selftest:last`.\n- Counters: `total`, `pass`, `fail`, `blocked`, `escaped` (a blocking dimension failed, block budget spent), `shadowed` (only non-blocking dimensions failed), `error`, and `dim:<dimension>`.\n\n## Known limits\n\n- Only the last 1,400 characters of the task are searched for the latest request. A very long final message is cut to its last 900 characters.\n- The block budget is per task, so a retried call after a block goes through once the budget is spent, even if it still fails.\n- Each gated Slack post waits for one Jev call (about 0.2 s measured, capped by `timeoutMs`).\n"
|
|
17
|
+
"readme": "# comms-adherence-gate\n\nAgents finish Slack tasks with a final message a human reads, and post to Slack threads directly. This extension judges that text with Jev, [TypeSafe](https://typesafe.ai)'s decision model: against the requester's stated comms preferences and their latest request, and against a plain-language rubric that applies to every message. In `enforce` it blocks a failing call once and tells the agent what to fix. A `plain` failure points the agent at the `comms` skill.\n\nInstall config:\n\n```json\n{ \"mode\": \"shadow\", \"plainMode\": \"shadow\" }\n```\n\nStart in `shadow`, read the verdicts in KV for a few days, then switch to `enforce`. `mode` and `plainMode` move independently.\n\n## Modes\n\n| `mode` | Effect |\n|---|---|\n| `off` | Never evaluates. |\n| `shadow` (default) | Asks Jev and records the verdict. Never blocks. |\n| `enforce` | Asks Jev, records the verdict, and blocks the call when a dimension fails, at most `maxBlocksPerTask` times per task. The agent gets the failed dimensions, their scores and the stated preference, and calls again. |\n\n`mode` governs the preference dimensions (`verbosity`, `tone`, `language`). `plainMode` governs `plain`. A dimension blocks only when its own mode is `enforce`. Both share one block budget per task, across every gated tool.\n\n## What it gates\n\nHook: `pre.tool.call` on:\n\n- `store-progress` with `status: \"completed\"` and a non-empty `output`, on a task that came from Slack (`source = \"slack\"` or a `slackThreadTs`). Other completions pass without a Jev call.\n- `slack-reply`, `slack-post`, `slack-start-thread` and `slack-update`, judged on `message`. The task is `slack-reply`'s `taskId`, else the caller's task context. A post with no task context passes.\n\nOnly a call the tool itself accepts is judged, so no other task's text reaches Jev. For `store-progress` the caller must own the task, the task must be unassigned, or the caller must be a lead. For the Slack tools the caller must be the task's assignee or its creator, the rule `slack-reply` enforces. Calls made by extensions are skipped. Script SDK calls never reach `pre.tool.call` (the tool registrar dispatches it only for MCP calls); if one ever does, the gate records it and never blocks.\n\nA requester with no stated preferences in `users.metadata.comms` still gets the `plain` question. Set preferences with the `manage-user` tool.\n\nIn a thread with several people, the requester is the person whose message created the task. A message that @-mentions someone (`<@U123>`) is judged against the first mentioned person with stored preferences, resolved through their Slack identity in `user_external_ids`; otherwise against the requester. The lookup is one SQL read, only when the text mentions someone and `mode` is not `off`. The verdict records who was judged in `judgedFor` (`mention` or `requester`) and `audience`.\n\n## Decision\n\nThe gate reads the task row and asks one `noul` question per stated preference it knows: `verbosity`, `tone`, `language`. Any other key in `comms` is context only.\n\nJev sees the preferences, the requester's latest message (the text after the last `</thread_context>`, from the last 1,400 characters of the task), the first 400 characters of the task, and the output. Its judging rules say an explicit request outranks the stored default. A requested long answer, story or document is not a verbosity failure.\n\nIt also asks `plain` on every message unless `plainMode` is `off` or the text is a JSON document (structured output for an `outputSchema`). The rubric comes from the `comms` skill: everyday words, one idea per sentence, every number with a unit and a direction word, and no unexplained shorthand (n, median, p90, cohort, baseline, delta, `±X at 95%`). Code identifiers, task ids, PR numbers, links and versions are fine. Jev gets contrasting plain and dense examples in `plain_language_rules`; a prose-only rubric scored plain rewrites as low as the dense originals.\n\nAll questions go in one Jev request. A preference dimension fails below `threshold`; `plain` fails below `plainThreshold`. Any failed dimension fails the message.\n\n### Calibration of `plain`\n\nJev scores dense status text near 0 and plain text near 0.8 to 0.9, with a wide middle of compact but readable engineering notes. Measured on 400 Slack-facing completions over 7 days, at `threshold` 0.75 for preferences:\n\n| `plainThreshold` | Newly blocked (of messages that pass today) |\n|---|---|\n| 0.75 | 81% to 83% |\n| 0.3 | 9% to 13% |\n| 0.25 (default) | 5% to 7% |\n\nAt 0.25 the dense prompt-cache-monitor post scores about 0.15 and its plain rewrite about 0.81.\n\n## Jev transport\n\nJev is reachable two ways. Both take the same request and return the same answer.\n\n| `provider` | Endpoint | Key | Model |\n|---|---|---|---|\n| `typesafe` | `POST https://api.typesafe.ai/v1/systemone` | `TYPESAFE_API_KEY` (or `apiKey`) | `model`, default `jev-latest` |\n| `openrouter` | `POST https://openrouter.ai/api/alpha/decisions` | `OPENROUTER_API_KEY` | `openrouterModel`, default `typesafe/jev-1.13` |\n| `auto` (default) | TypeSafe when its key is set, else OpenRouter | | |\n\nEach verdict row records the `provider` that answered.\n\n## Fail open\n\nEvery error lets the completion through: a missing key, an HTTP error, a network error, a timeout, a malformed answer, or a failed DB read. The handler never throws, so an outage cannot auto-disable the extension. Each failure bumps the `error` counter and overwrites `error:last`.\n\n## Self-test\n\nCall `store-progress` with a non-completed status and `progress` starting with `comms-gate-selftest`. The gate judges a known-bad and a known-good message against a terse preference, and a dense and a plain message on `plain`, then writes `selftest:last`: every score, both thresholds, the provider, `controlsOk` (verbosity: bad below `threshold`, good at or above it) and `plainControlsOk` (the same against `plainThreshold`). Real traffic is untouched.\n\n### Fixtures\n\nFixed text that your own templates tell an agent to post (a daily report's all-clear line, a standard reply) should pass the gate. List it under `fixtures` and the self-test judges each entry with the same state and questions as real traffic, then records `fixtures` (per entry: `name`, `scores`, `failed`, `pass`) and `fixturesOk` in `selftest:last`. A failing fixture means the template line or the gate needs a fix before a quiet day forces an ad-hoc rewrite.\n\n```json\n{\n \"fixtures\": [\n { \"name\": \"daily-report-all-clear\", \"text\": \"📊 11-03: all clear, nothing for you. 56 of 73 workflows are turned on.\" },\n {\n \"name\": \"short-reply\",\n \"text\": \"Went with option B: it keeps the migration reversible. PR #123.\",\n \"prefs\": { \"verbosity\": \"very terse, ~400 chars max\" },\n \"request\": \"which option did you pick?\"\n }\n ]\n}\n```\n\nFill placeholders with realistic sample values. `prefs` adds the preference dimensions it names; without it only `plain` is judged. At most 8 entries run; an invalid entry is skipped, never fatal to the rest of the config.\n\n`fixturesOk` is `true` only when at least one entry ran and every entry passed. It is `null` when no valid entry ran: `fixtures` unset, an explicit `fixtures: []`, or every entry invalid. `null` means nothing was checked, so never read it as a pass. A skipped entry is missing from `fixtures` in `selftest:last`, so compare that list with your config.\n\nUnit tests mock Jev, so they cannot show that a line passes. Only the self-test, which calls the live judge, can.\n\n## Config\n\n| Key | Default | Notes |\n|---|---|---|\n| `mode` | `shadow` | `off`, `shadow`, or `enforce` |\n| `threshold` | `0.5` | A preference dimension scoring below this fails |\n| `plainMode` | `shadow` | `off`, `shadow`, or `enforce` for the `plain` dimension |\n| `plainThreshold` | `0.25` | `plain` scoring below this fails. See [Calibration](#calibration-of-plain) |\n| `timeoutMs` | `4000` | Jev call timeout, capped at 4000 (the dispatcher cancels a handler at 5 s) |\n| `maxBlocksPerTask` | `1` | Blocks per task in `enforce`; after that the gate records and lets it through |\n| `provider` | `auto` | `auto`, `typesafe`, or `openrouter`. See [Jev transport](#jev-transport) |\n| `model` | `jev-latest` | Jev model on TypeSafe |\n| `openrouterModel` | `typesafe/jev-1.13` | Jev model on OpenRouter |\n| `apiKey` | unset | Explicit TypeSafe key. Prefer the `TYPESAFE_API_KEY` secret below |\n| `fixtures` | unset | Fixed template text the self-test expects to pass. See [Fixtures](#fixtures) |\n\n## Required secrets\n\nRead from the API process environment at call time. Set them as global `swarm_config` secrets: the API process loads global rows into `process.env` at boot and on config reload.\n\n- `TYPESAFE_API_KEY` or `OPENROUTER_API_KEY`: one is required for any evaluation. Under `auto`, TypeSafe wins when both are set. Without either, every completion fails open.\n\nNo key is written to config, KV, logs, or a block reason.\n\n## KV namespace `ext:comms-gate`\n\n- `last`: the latest verdict, with `tool`, `scores`, `failed`, `mode`, `plainMode`, `provider`, `latencyMs`, the preferences, a 400-character `askPreview` and a 700-character `outputPreview`.\n- `fail:<epochMs>:<taskId>`: one row per failed verdict, with `action` (`blocked` or `recorded`).\n- `blocks:<taskId>`: blocks issued for that task.\n- `error:last`, `selftest:last`.\n- Counters: `total`, `pass`, `fail`, `blocked`, `escaped` (a blocking dimension failed, block budget spent), `shadowed` (only non-blocking dimensions failed), `error`, and `dim:<dimension>`.\n\n## Known limits\n\n- Only the last 1,400 characters of the task are searched for the latest request. A very long final message is cut to its last 900 characters.\n- The block budget is per task, so a retried call after a block goes through once the budget is spent, even if it still fails.\n- Each gated Slack post waits for one Jev call (about 0.2 s measured, capped by `timeoutMs`).\n"
|
|
18
18
|
},
|
|
19
19
|
"deploy-awareness": {
|
|
20
20
|
"manifestFile": "manifest.json",
|