Add CultCache agent transport lane
This commit is contained in:
parent
3fd655e1f2
commit
f5c9b1ef59
3 changed files with 518 additions and 0 deletions
3
.gitignore
vendored
3
.gitignore
vendored
|
|
@ -6,6 +6,9 @@
|
|||
# dotenv files
|
||||
.env
|
||||
|
||||
# Local Bifrost transport/state stores
|
||||
.bifrost/
|
||||
|
||||
# User-specific files
|
||||
*.rsuser
|
||||
*.suo
|
||||
|
|
|
|||
66
docs/agent-transport.md
Normal file
66
docs/agent-transport.md
Normal file
|
|
@ -0,0 +1,66 @@
|
|||
# Agent Transport
|
||||
|
||||
Bifrost owns the agent transport contract for GameCult work requests.
|
||||
|
||||
This is not a Postgres queue and not a VoidBot side channel. VoidBot may observe Discord and package consensus, but the shared request lane belongs here:
|
||||
|
||||
- Bifrost defines the request shape, status rules, and claim semantics.
|
||||
- CultCache stores the durable request documents.
|
||||
- CultNet carries snapshots and raw document updates between runtimes.
|
||||
- Repo agents claim only requests whose target repository matches their jurisdiction.
|
||||
|
||||
That ownership split matters. If the queue lives in VoidBot, Discord becomes the hidden source of authority. If it lives in Bifrost but stores through Entity Framework, agents cannot share the same packet through the CultCache/CultNet machinery they already use for state. The coherent machine is smaller: Bifrost says what the request means; CultCache remembers it; CultNet moves it.
|
||||
|
||||
## Document
|
||||
|
||||
Agent update requests are stored as CultCache documents with this type:
|
||||
|
||||
`bifrost.agent-transport.update-request`
|
||||
|
||||
The schema id is:
|
||||
|
||||
`bifrost.agent-transport.update-request.v0`
|
||||
|
||||
Each request has:
|
||||
|
||||
- `id`: stable request id.
|
||||
- `targetRepoName`: short repository name, such as `AetheriaLore`.
|
||||
- `targetRepositoryFullName`: optional owner/name form.
|
||||
- `targetAgentIdentity`: optional Face identity, such as `nibu`.
|
||||
- `title`: short human label.
|
||||
- `requestMarkdown`: the actual consensus or task packet.
|
||||
- `priority`: higher numbers claim first.
|
||||
- `status`: `queued`, `claimed`, `completed`, or `cancelled`.
|
||||
- `sourceKind`: where the request came from, such as `discord_consensus`.
|
||||
- `sourceChannelId`, `sourceMessageIds`, `sourcePacketPath`, `sourcePromptPath`: optional provenance.
|
||||
- `createdByAgent`, `claimedByAgent`: identity trace.
|
||||
- `closeNote`: completion/cancellation note.
|
||||
- `createdAt`, `updatedAt`, `claimedAt`, `closedAt`: ISO timestamps.
|
||||
|
||||
## CLI
|
||||
|
||||
`tools/agent-transport.mjs` is intentionally local and boring. It imports the sibling `CultCacheTS` and `CultNetTS` builds directly, writes a `.cc` store, and can emit/apply CultNet raw snapshots.
|
||||
|
||||
Default store:
|
||||
|
||||
`E:\Projects\Bifrost\.bifrost\agent-transport.cc`
|
||||
|
||||
Examples:
|
||||
|
||||
```powershell
|
||||
node .\tools\agent-transport.mjs enqueue --repo AetheriaLore --agent nibu --title "Wavecrafter consensus" --request-file E:\path\packet.md --priority 80
|
||||
node .\tools\agent-transport.mjs list --repo AetheriaLore --status queued
|
||||
node .\tools\agent-transport.mjs claim --repo AetheriaLore --agent nibu --claimed-by nibu
|
||||
node .\tools\agent-transport.mjs close --id req_... --status completed --note "Opened AetheriaLore PR."
|
||||
node .\tools\agent-transport.mjs snapshot --out E:\tmp\bifrost-agent-transport.msgpack
|
||||
node .\tools\agent-transport.mjs apply-snapshot --in E:\tmp\bifrost-agent-transport.msgpack
|
||||
```
|
||||
|
||||
The `snapshot` command writes a MessagePack-encoded `cultnet.snapshot_response_raw.v0` message. This keeps CultCache payload bytes intact for peers that share the document binding.
|
||||
|
||||
## Next Integration Points
|
||||
|
||||
- Add an MCP wrapper that calls this CLI instead of storing transport state in VoidBot.
|
||||
- Teach the VoidBot consensus feeder to enqueue Bifrost update requests after it writes a packet.
|
||||
- Let repo Faces claim by `targetRepoName`, then inject the claimed packet into Codex only when the repo matches their jurisdiction.
|
||||
- Use CultNet direct pipes when a long-running agent runtime is available; keep raw snapshot files as the dead-simple bridge until then.
|
||||
449
tools/agent-transport.mjs
Normal file
449
tools/agent-transport.mjs
Normal file
|
|
@ -0,0 +1,449 @@
|
|||
#!/usr/bin/env node
|
||||
import { createRequire } from "node:module";
|
||||
import { randomUUID } from "node:crypto";
|
||||
import { mkdir, readFile, writeFile } from "node:fs/promises";
|
||||
import { dirname, resolve } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
|
||||
const scriptDir = dirname(fileURLToPath(import.meta.url));
|
||||
const repoRoot = resolve(scriptDir, "..");
|
||||
const projectsRoot = resolve(repoRoot, "..");
|
||||
const defaultStorePath = resolve(repoRoot, ".bifrost", "agent-transport.cc");
|
||||
|
||||
const cultCacheRequire = createRequire(resolve(projectsRoot, "CultCacheTS", "package.json"));
|
||||
const cultNetRequire = createRequire(resolve(projectsRoot, "CultNetTS", "package.json"));
|
||||
|
||||
const {
|
||||
CultCache,
|
||||
SingleFileMessagePackBackingStore,
|
||||
defineDocumentType,
|
||||
} = cultCacheRequire(resolve(projectsRoot, "CultCacheTS", "dist", "index.js"));
|
||||
const {
|
||||
CultNetDocumentRegistry,
|
||||
defineCultNetDocumentBinding,
|
||||
} = cultNetRequire(resolve(projectsRoot, "CultNetTS", "dist", "index.js"));
|
||||
const { encode, decode } = cultNetRequire("@msgpack/msgpack");
|
||||
|
||||
const documentType = "bifrost.agent-transport.update-request";
|
||||
const schemaId = "bifrost.agent-transport.update-request.v0";
|
||||
const validStatuses = new Set(["queued", "claimed", "completed", "cancelled"]);
|
||||
const validCloseStatuses = new Set(["completed", "cancelled"]);
|
||||
|
||||
const updateRequestDefinition = defineDocumentType({
|
||||
type: documentType,
|
||||
schemaId,
|
||||
schemaName: documentType,
|
||||
schemaVersion: "bifrost.agent_transport.update_request.v0",
|
||||
schema: {
|
||||
parse: parseUpdateRequest,
|
||||
},
|
||||
name: "id",
|
||||
indexes: {
|
||||
targetRepoName: "targetRepoName",
|
||||
targetAgentIdentity: "targetAgentIdentity",
|
||||
status: "status",
|
||||
},
|
||||
members: [
|
||||
{ slot: 1, memberName: "id", typeName: "string", isName: true },
|
||||
{ slot: 2, memberName: "targetRepoName", typeName: "string", indexAlias: "targetRepoName" },
|
||||
{ slot: 3, memberName: "targetRepositoryFullName", typeName: "string" },
|
||||
{ slot: 4, memberName: "targetAgentIdentity", typeName: "string", indexAlias: "targetAgentIdentity" },
|
||||
{ slot: 5, memberName: "title", typeName: "string" },
|
||||
{ slot: 6, memberName: "requestMarkdown", typeName: "string" },
|
||||
{ slot: 7, memberName: "priority", typeName: "number" },
|
||||
{ slot: 8, memberName: "status", typeName: "string", indexAlias: "status" },
|
||||
{ slot: 9, memberName: "sourceKind", typeName: "string" },
|
||||
{ slot: 10, memberName: "sourceChannelId", typeName: "string" },
|
||||
{ slot: 11, memberName: "sourceMessageIds", typeName: "string", isMany: true },
|
||||
{ slot: 12, memberName: "sourcePacketPath", typeName: "string" },
|
||||
{ slot: 13, memberName: "sourcePromptPath", typeName: "string" },
|
||||
{ slot: 14, memberName: "createdByAgent", typeName: "string" },
|
||||
{ slot: 15, memberName: "claimedByAgent", typeName: "string" },
|
||||
{ slot: 16, memberName: "closeNote", typeName: "string" },
|
||||
{ slot: 17, memberName: "createdAt", typeName: "string" },
|
||||
{ slot: 18, memberName: "updatedAt", typeName: "string" },
|
||||
{ slot: 19, memberName: "claimedAt", typeName: "string" },
|
||||
{ slot: 20, memberName: "closedAt", typeName: "string" },
|
||||
],
|
||||
});
|
||||
|
||||
const cultNetRegistry = new CultNetDocumentRegistry([
|
||||
defineCultNetDocumentBinding({
|
||||
definition: updateRequestDefinition,
|
||||
payloadSchemaVersion: "bifrost.agent_transport.update_request.v0",
|
||||
}),
|
||||
]);
|
||||
|
||||
async function main() {
|
||||
const [command, ...rawArgs] = process.argv.slice(2);
|
||||
const options = parseArgs(rawArgs);
|
||||
|
||||
if (!command || command === "help" || command === "--help" || command === "-h") {
|
||||
printHelp();
|
||||
return;
|
||||
}
|
||||
|
||||
const storePath = resolveOptionPath(options.store ?? defaultStorePath);
|
||||
const cache = await openCache(storePath);
|
||||
|
||||
switch (command) {
|
||||
case "enqueue":
|
||||
await enqueue(cache, options);
|
||||
return;
|
||||
case "list":
|
||||
listRequests(cache, options);
|
||||
return;
|
||||
case "claim":
|
||||
await claim(cache, options);
|
||||
return;
|
||||
case "close":
|
||||
await closeRequest(cache, options);
|
||||
return;
|
||||
case "snapshot":
|
||||
await writeSnapshot(cache, options);
|
||||
return;
|
||||
case "apply-snapshot":
|
||||
await applySnapshot(cache, options);
|
||||
return;
|
||||
case "schema":
|
||||
printJson({ documentType, schemaId });
|
||||
return;
|
||||
default:
|
||||
throw new Error(`Unknown command "${command}". Run "node tools/agent-transport.mjs help".`);
|
||||
}
|
||||
}
|
||||
|
||||
async function openCache(storePath) {
|
||||
const cache = CultCache.builder()
|
||||
.withDocumentType(updateRequestDefinition)
|
||||
.withGenericStore(new SingleFileMessagePackBackingStore(storePath))
|
||||
.build();
|
||||
|
||||
await cache.pullAllBackingStores();
|
||||
return cache;
|
||||
}
|
||||
|
||||
async function enqueue(cache, options) {
|
||||
const now = new Date().toISOString();
|
||||
const requestMarkdown = await readRequestMarkdown(options);
|
||||
const request = parseUpdateRequest({
|
||||
id: options.id ?? `req_${randomUUID()}`,
|
||||
targetRepoName: requireOption(options, "repo"),
|
||||
targetRepositoryFullName: optionalString(options["repo-full-name"]),
|
||||
targetAgentIdentity: optionalString(options.agent),
|
||||
title: requireOption(options, "title"),
|
||||
requestMarkdown,
|
||||
priority: parseInteger(options.priority ?? "50", "priority"),
|
||||
status: "queued",
|
||||
sourceKind: optionalString(options["source-kind"]) ?? "manual",
|
||||
sourceChannelId: optionalString(options["source-channel-id"]),
|
||||
sourceMessageIds: parseCsv(options["source-message-ids"]),
|
||||
sourcePacketPath: optionalString(options["packet-path"]),
|
||||
sourcePromptPath: optionalString(options["prompt-path"]),
|
||||
createdByAgent: optionalString(options["created-by"]),
|
||||
claimedByAgent: undefined,
|
||||
closeNote: undefined,
|
||||
createdAt: now,
|
||||
updatedAt: now,
|
||||
claimedAt: undefined,
|
||||
closedAt: undefined,
|
||||
});
|
||||
|
||||
await cache.put(updateRequestDefinition, request.id, request);
|
||||
printJson(request);
|
||||
}
|
||||
|
||||
function listRequests(cache, options) {
|
||||
const requests = filteredRequests(cache, options)
|
||||
.sort(compareRequests);
|
||||
|
||||
printJson(requests);
|
||||
}
|
||||
|
||||
async function claim(cache, options) {
|
||||
const repo = optionalString(options.repo);
|
||||
if (!repo) {
|
||||
throw new Error("claim requires --repo so an agent cannot grab work outside its jurisdiction.");
|
||||
}
|
||||
|
||||
const agent = optionalString(options.agent);
|
||||
const claimedBy = optionalString(options["claimed-by"]) ?? agent ?? "codex";
|
||||
const request = filteredRequests(cache, {
|
||||
...options,
|
||||
status: "queued",
|
||||
})
|
||||
.filter((candidate) => equalsIgnoreCase(candidate.targetRepoName, repo))
|
||||
.filter((candidate) => !agent || equalsIgnoreCase(candidate.targetAgentIdentity, agent) || !candidate.targetAgentIdentity)
|
||||
.sort(compareRequests)[0];
|
||||
|
||||
if (!request) {
|
||||
printJson(null);
|
||||
return;
|
||||
}
|
||||
|
||||
const now = new Date().toISOString();
|
||||
const claimed = parseUpdateRequest({
|
||||
...request,
|
||||
status: "claimed",
|
||||
claimedByAgent: claimedBy,
|
||||
claimedAt: now,
|
||||
updatedAt: now,
|
||||
});
|
||||
await cache.put(updateRequestDefinition, claimed.id, claimed);
|
||||
printJson(claimed);
|
||||
}
|
||||
|
||||
async function closeRequest(cache, options) {
|
||||
const id = requireOption(options, "id");
|
||||
const status = requireOption(options, "status");
|
||||
if (!validCloseStatuses.has(status)) {
|
||||
throw new Error("--status for close must be completed or cancelled.");
|
||||
}
|
||||
|
||||
const current = cache.get(updateRequestDefinition, id);
|
||||
if (!current) {
|
||||
throw new Error(`No update request found for id "${id}".`);
|
||||
}
|
||||
|
||||
const now = new Date().toISOString();
|
||||
const closed = parseUpdateRequest({
|
||||
...current,
|
||||
status,
|
||||
closeNote: optionalString(options.note),
|
||||
closedAt: now,
|
||||
updatedAt: now,
|
||||
});
|
||||
await cache.put(updateRequestDefinition, closed.id, closed);
|
||||
printJson(closed);
|
||||
}
|
||||
|
||||
async function writeSnapshot(cache, options) {
|
||||
const message = cultNetRegistry.createRawSnapshotResponse(
|
||||
cache,
|
||||
options["message-id"] ?? `snapshot_${randomUUID()}`,
|
||||
);
|
||||
|
||||
if (options.out) {
|
||||
const outPath = resolveOptionPath(options.out);
|
||||
await mkdir(dirname(outPath), { recursive: true });
|
||||
await writeFile(outPath, encode(message));
|
||||
printJson({
|
||||
schemaVersion: message.schemaVersion,
|
||||
messageId: message.messageId,
|
||||
documentCount: message.documents.length,
|
||||
out: outPath,
|
||||
});
|
||||
return;
|
||||
}
|
||||
|
||||
printJson({
|
||||
...message,
|
||||
documents: message.documents.map((document) => ({
|
||||
...document,
|
||||
payload: Buffer.from(document.payload).toString("base64url"),
|
||||
payloadEncoding: "messagepack+base64url",
|
||||
})),
|
||||
});
|
||||
}
|
||||
|
||||
async function applySnapshot(cache, options) {
|
||||
const inPath = resolveOptionPath(requireOption(options, "in"));
|
||||
const message = decode(await readFile(inPath));
|
||||
await cultNetRegistry.applyRawSnapshotResponse(cache, message);
|
||||
printJson({
|
||||
applied: true,
|
||||
schemaVersion: message.schemaVersion,
|
||||
messageId: message.messageId,
|
||||
documentCount: message.documents?.length ?? 0,
|
||||
in: inPath,
|
||||
});
|
||||
}
|
||||
|
||||
function filteredRequests(cache, options) {
|
||||
return cache.getAll(updateRequestDefinition)
|
||||
.filter((request) => !options.status || request.status === options.status)
|
||||
.filter((request) => !options.repo || equalsIgnoreCase(request.targetRepoName, options.repo))
|
||||
.filter((request) => !options.agent || equalsIgnoreCase(request.targetAgentIdentity, options.agent));
|
||||
}
|
||||
|
||||
function compareRequests(left, right) {
|
||||
if (right.priority !== left.priority) {
|
||||
return right.priority - left.priority;
|
||||
}
|
||||
|
||||
return left.createdAt.localeCompare(right.createdAt);
|
||||
}
|
||||
|
||||
async function readRequestMarkdown(options) {
|
||||
if (options["request-file"]) {
|
||||
return readFile(resolveOptionPath(options["request-file"]), "utf8");
|
||||
}
|
||||
|
||||
return requireOption(options, "request");
|
||||
}
|
||||
|
||||
function parseUpdateRequest(input) {
|
||||
if (!input || typeof input !== "object") {
|
||||
throw new Error("Update request must be an object.");
|
||||
}
|
||||
|
||||
const request = {
|
||||
id: requireString(input.id, "id"),
|
||||
targetRepoName: requireString(input.targetRepoName, "targetRepoName"),
|
||||
targetRepositoryFullName: optionalString(input.targetRepositoryFullName),
|
||||
targetAgentIdentity: optionalString(input.targetAgentIdentity),
|
||||
title: requireString(input.title, "title"),
|
||||
requestMarkdown: requireString(input.requestMarkdown, "requestMarkdown"),
|
||||
priority: requireNumber(input.priority, "priority"),
|
||||
status: requireString(input.status, "status"),
|
||||
sourceKind: optionalString(input.sourceKind) ?? "manual",
|
||||
sourceChannelId: optionalString(input.sourceChannelId),
|
||||
sourceMessageIds: normalizeStringArray(input.sourceMessageIds, "sourceMessageIds"),
|
||||
sourcePacketPath: optionalString(input.sourcePacketPath),
|
||||
sourcePromptPath: optionalString(input.sourcePromptPath),
|
||||
createdByAgent: optionalString(input.createdByAgent),
|
||||
claimedByAgent: optionalString(input.claimedByAgent),
|
||||
closeNote: optionalString(input.closeNote),
|
||||
createdAt: requireString(input.createdAt, "createdAt"),
|
||||
updatedAt: requireString(input.updatedAt, "updatedAt"),
|
||||
claimedAt: optionalString(input.claimedAt),
|
||||
closedAt: optionalString(input.closedAt),
|
||||
};
|
||||
|
||||
if (!validStatuses.has(request.status)) {
|
||||
throw new Error(`Update request status "${request.status}" is not valid.`);
|
||||
}
|
||||
|
||||
return request;
|
||||
}
|
||||
|
||||
function parseArgs(args) {
|
||||
const options = {};
|
||||
for (let index = 0; index < args.length; index += 1) {
|
||||
const token = args[index];
|
||||
if (!token.startsWith("--")) {
|
||||
throw new Error(`Unexpected argument "${token}".`);
|
||||
}
|
||||
|
||||
const key = token.slice(2);
|
||||
const next = args[index + 1];
|
||||
if (!next || next.startsWith("--")) {
|
||||
options[key] = "true";
|
||||
continue;
|
||||
}
|
||||
|
||||
options[key] = next;
|
||||
index += 1;
|
||||
}
|
||||
|
||||
return options;
|
||||
}
|
||||
|
||||
function requireOption(options, name) {
|
||||
const value = options[name];
|
||||
if (typeof value !== "string" || value.trim().length === 0) {
|
||||
throw new Error(`Missing required option --${name}.`);
|
||||
}
|
||||
|
||||
return value.trim();
|
||||
}
|
||||
|
||||
function optionalString(value) {
|
||||
if (typeof value !== "string") {
|
||||
return undefined;
|
||||
}
|
||||
|
||||
const trimmed = value.trim();
|
||||
return trimmed.length > 0 ? trimmed : undefined;
|
||||
}
|
||||
|
||||
function requireString(value, field) {
|
||||
const normalized = optionalString(value);
|
||||
if (!normalized) {
|
||||
throw new Error(`Update request field "${field}" must be a non-empty string.`);
|
||||
}
|
||||
|
||||
return normalized;
|
||||
}
|
||||
|
||||
function requireNumber(value, field) {
|
||||
const number = typeof value === "number" ? value : Number(value);
|
||||
if (!Number.isFinite(number)) {
|
||||
throw new Error(`Update request field "${field}" must be a finite number.`);
|
||||
}
|
||||
|
||||
return number;
|
||||
}
|
||||
|
||||
function parseInteger(value, field) {
|
||||
const number = Number(value);
|
||||
if (!Number.isInteger(number)) {
|
||||
throw new Error(`--${field} must be an integer.`);
|
||||
}
|
||||
|
||||
return number;
|
||||
}
|
||||
|
||||
function parseCsv(value) {
|
||||
if (typeof value !== "string" || value.trim().length === 0) {
|
||||
return [];
|
||||
}
|
||||
|
||||
return value
|
||||
.split(",")
|
||||
.map((item) => item.trim())
|
||||
.filter((item) => item.length > 0);
|
||||
}
|
||||
|
||||
function normalizeStringArray(value, field) {
|
||||
if (value === undefined || value === null) {
|
||||
return [];
|
||||
}
|
||||
|
||||
if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
|
||||
throw new Error(`Update request field "${field}" must be an array of strings.`);
|
||||
}
|
||||
|
||||
return value;
|
||||
}
|
||||
|
||||
function equalsIgnoreCase(left, right) {
|
||||
return typeof left === "string"
|
||||
&& typeof right === "string"
|
||||
&& left.toLowerCase() === right.toLowerCase();
|
||||
}
|
||||
|
||||
function resolveOptionPath(path) {
|
||||
return resolve(process.cwd(), path);
|
||||
}
|
||||
|
||||
function printJson(value) {
|
||||
process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
|
||||
}
|
||||
|
||||
function printHelp() {
|
||||
process.stdout.write(`Bifrost agent transport
|
||||
|
||||
Commands:
|
||||
enqueue Store a queued update request in CultCache
|
||||
list List requests, optionally filtered by --repo, --agent, --status
|
||||
claim Claim the highest-priority queued request for --repo
|
||||
close Mark a request completed or cancelled
|
||||
snapshot Write or print a CultNet raw snapshot response
|
||||
apply-snapshot Apply a CultNet raw snapshot response from --in
|
||||
schema Print the document type and schema id
|
||||
|
||||
Common options:
|
||||
--store <path> Override the .cc store path
|
||||
|
||||
Examples:
|
||||
node tools/agent-transport.mjs enqueue --repo AetheriaLore --agent nibu --title "Wavecrafters" --request-file packet.md --priority 80
|
||||
node tools/agent-transport.mjs claim --repo AetheriaLore --agent nibu --claimed-by nibu
|
||||
node tools/agent-transport.mjs snapshot --out transport.msgpack
|
||||
`);
|
||||
}
|
||||
|
||||
main().catch((error) => {
|
||||
process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
|
||||
process.exitCode = 1;
|
||||
});
|
||||
Loading…
Reference in a new issue