Skip to content
10 changes: 10 additions & 0 deletions docs/development/optional-agent-packages.md
Original file line number Diff line number Diff line change
Expand Up @@ -24,6 +24,16 @@ Client capability elements receive the Engine's selected UI locale through their
English; the Engine does not translate package prompts or package-authored machine values. Locale changes reuse the
existing `marinara-capability-props` event so an installed interface can rerender without an Engine restart.

### Delivery and caching

Installed package files are served with strong validators derived from the manifest's per-file
SHA-256 hashes — the same values the Engine re-verifies the bytes against on every read. The
client bundle (`/api/capability-packages/<id>/client`) always revalidates (`no-cache` plus an
`ETag`), so an unchanged bundle answers `304 Not Modified` instead of re-downloading, while a
republished bundle is picked up immediately. Package asset requests that pin the installed
version with `?v=<version>` are content-addressed and may be cached indefinitely
(`immutable`); requests without the pin keep always-revalidate semantics.

Capability API 1.1 adds a generic runtime facade to the server activation context.
Packages can read the effective agent-debug state and write through the Engine's
Pino logger, including explicit debug-mode overrides, without importing the
Expand Down
3 changes: 2 additions & 1 deletion package.json
Original file line number Diff line number Diff line change
Expand Up @@ -57,9 +57,10 @@
"regression:mari-instructions": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/mari-instructions-memory.regression.ts",
"regression:mari-db-execution-security:run": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/mari-db-execution-security.regression.ts",
"regression:mari-db-execution-security": "pnpm build:shared && pnpm regression:mari-db-execution-security:run",
"regression:issues": "pnpm regression:card-library-search && pnpm regression:persona-client:run && pnpm regression:chat-resource-drop && pnpm regression:avatar-delete && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-html-newlines.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/open-issues.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/assigned-issue-sweep.regression.ts && pnpm regression:swarmui-timeout && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/stock-preset-protection.regression.ts && pnpm regression:mari-review-durability && pnpm regression:storage-writer-lock && pnpm regression:mari-preset-granular && pnpm regression:mari-instructions && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/bot-browser-route.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/janny-character-import.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/agent-activation.regression.ts && pnpm regression:agent-registry-hydration && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/profile-import-noodle.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/notification-sound.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/agent-catalog-kind-badges.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/file-backed-shutdown.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/autonomous-scheduler-gate.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/message-sharding.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/memory-recall-revectorize.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/env-watcher.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/extension-ipc.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-package-lifecycle.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-client-version-refresh.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/message-page-cache.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-branch-lineage.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/conversation-game-slash.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/game-metadata-race.regression.ts && pnpm regression:launcher-update && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/scene-video-range.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-prompt-context.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-documentation.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-fetch-tiers.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/entity-embedding-store.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-fetch-integration.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-relevance-names.regression.ts",
"regression:issues": "pnpm regression:card-library-search && pnpm regression:persona-client:run && pnpm regression:chat-resource-drop && pnpm regression:avatar-delete && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-html-newlines.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/open-issues.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/assigned-issue-sweep.regression.ts && pnpm regression:swarmui-timeout && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/stock-preset-protection.regression.ts && pnpm regression:mari-review-durability && pnpm regression:storage-writer-lock && pnpm regression:mari-preset-granular && pnpm regression:mari-instructions && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/bot-browser-route.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/janny-character-import.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/agent-activation.regression.ts && pnpm regression:agent-registry-hydration && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/profile-import-noodle.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/notification-sound.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/agent-catalog-kind-badges.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/file-backed-shutdown.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/autonomous-scheduler-gate.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/message-sharding.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/memory-recall-revectorize.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/env-watcher.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/extension-ipc.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-package-lifecycle.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-client-version-refresh.regression.ts && pnpm regression:capability-cache && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/message-page-cache.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-branch-lineage.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/conversation-game-slash.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/game-metadata-race.regression.ts && pnpm regression:launcher-update && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/scene-video-range.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-prompt-context.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-documentation.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-fetch-tiers.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/entity-embedding-store.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-fetch-integration.regression.ts && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/professor-mari-relevance-names.regression.ts",
"regression:launcher-update": "node ./scripts/regressions/launcher-env.regression.mjs && node ./scripts/regressions/launcher-update.regression.mjs && node ./scripts/regressions/dev-launcher-process.regression.mjs && node ./scripts/regressions/launcher-format-guard.regression.mjs && node ./scripts/check-windows-installer-layout.mjs",
"regression:card-library-search": "pnpm build:shared && pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/card-library-search.regression.ts",
"regression:capability-cache": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/capability-package-cache.regression.ts",
"regression:chat-resource-drop": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/chat-resource-drop.regression.ts",
"regression:gallery-delete": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/gallery-cascade-deletion.regression.ts",
"regression:avatar-delete": "pnpm --filter @marinara-engine/server exec tsx ../../scripts/regressions/avatar-file-deletion.regression.ts",
Expand Down
62 changes: 52 additions & 10 deletions packages/server/src/routes/capability-packages.routes.ts
Original file line number Diff line number Diff line change
Expand Up @@ -18,6 +18,20 @@
.regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/)
.max(80),
});

/** Strong ETag from the manifest-recorded sha256 — the same value the serve
* path re-verifies the bytes against, so the validator can never drift. */
function packageFileEtag(sha256Hex: string): string {
return `"${sha256Hex}"`;
}

function ifNoneMatchSatisfied(headerValue: string | undefined, etag: string): boolean {
if (!headerValue) return false;
if (headerValue.trim() === "*") return true;
// Weak comparison is fine for 304s: a W/-prefixed candidate with the same
// hash still identifies the same bytes here.
return headerValue.split(",").some((candidate) => candidate.trim().replace(/^W\//, "") === etag);
}
const packageAssetParams = packageParams.extend({ "*": z.string().min(1).max(240) });
const packageVersion = z
.string()
Expand Down Expand Up @@ -75,20 +89,48 @@
const { id } = packageParams.parse(request.params);
const entrypoint = await capabilityPackageManager.clientEntrypoint(id);
if (!entrypoint) return reply.status(404).send({ error: "Active client package not found" });
reply.header("Content-Type", "text/javascript; charset=utf-8");
// Deliberately NOT immutable, even though the URL carries ?v=: a package
// author (or the catalog) can republish the same version string with
// different bytes during development, and an immutable client bundle would
// pin the stale copy with no way to evict it short of a hard reload.
// no-cache + a strong ETag keeps "always revalidate" semantics while
// letting the revalidation answer 304 instead of re-sending the body.
const etag = packageFileEtag(entrypoint.sha256);
reply.header("Cache-Control", "no-cache, must-revalidate");
reply.header("ETag", etag);
reply.header("X-Content-Type-Options", "nosniff");
if (ifNoneMatchSatisfied(request.headers["if-none-match"], etag)) {
return reply.status(304).send();
}
reply.header("Content-Type", "text/javascript; charset=utf-8");
return reply.send(await readFile(entrypoint.file));
});
app.get<{ Params: { id: string; "*": string } }>("/:id/assets/*", async (request, reply) => {
const { id, "*": assetPath } = packageAssetParams.parse(request.params);
const asset = await capabilityPackageManager.browserTabAsset(id, assetPath);
if (!asset) return reply.status(404).send({ error: "Active package asset not found" });
reply.header("Content-Type", asset.contentType);
reply.header("Cache-Control", "private, no-cache, must-revalidate");
reply.header("X-Content-Type-Options", "nosniff");
return reply.send(await readFile(asset.file));
});
app.get<{ Params: { id: string; "*": string }; Querystring: { v?: string } }>(
"/:id/assets/*",
async (request, reply) => {
const { id, "*": assetPath } = packageAssetParams.parse(request.params);
const asset = await capabilityPackageManager.browserTabAsset(id, assetPath);
if (!asset) return reply.status(404).send({ error: "Active package asset not found" });
const etag = packageFileEtag(asset.sha256);
// A request that pins the installed version may cache the bytes forever:
// path + version + manifest hash identify them exactly. Any other request
// keeps today's always-revalidate behaviour byte-for-byte.
const requestedVersion = typeof request.query?.v === "string" ? request.query.v : null;
reply.header(
"Cache-Control",
requestedVersion === asset.installed.version
? "public, max-age=31536000, immutable"
: "private, no-cache, must-revalidate",
);
reply.header("ETag", etag);
reply.header("X-Content-Type-Options", "nosniff");
if (ifNoneMatchSatisfied(request.headers["if-none-match"], etag)) {
return reply.status(304).send();
}
reply.header("Content-Type", asset.contentType);
return reply.send(await readFile(asset.file));
},
Comment thread
kolacheee marked this conversation as resolved.
Dismissed
);
app.post<{ Params: { id: string }; Body: { expectedVersion: string; expectedArtifactSha256: string } }>(
"/:id/install",
async (request, reply) => {
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -818,8 +818,15 @@ export const capabilityPackageManager = {
if (!installed || !isInstalledCapabilityReady(installed)) return null;
const entrypoint = installed.manifest.entrypoints.client;
if (!entrypoint) return null;
// The manifest-recorded hash doubles as a strong HTTP validator (ETag): it
// is the same value the read below re-verifies the bytes against.
const declaration = installed.manifest.files.find(
(item) => normalizeArchivePath(item.path) === normalizeArchivePath(entrypoint),
);
if (!declaration) return null;
return {
installed,
sha256: declaration.sha256,
file: await verifyInstalledPackageFile(installed, entrypoint),
};
},
Expand All @@ -835,12 +842,14 @@ export const capabilityPackageManager = {
}
const iconPaths = installed.manifest.contributions?.homeBrowserTab?.iconPaths ?? [];
if (!iconPaths.some((path) => normalizeArchivePath(path) === normalizedPath)) return null;
if (!installed.manifest.files.some((item) => normalizeArchivePath(item.path) === normalizedPath)) return null;
const declaration = installed.manifest.files.find((item) => normalizeArchivePath(item.path) === normalizedPath);
if (!declaration) return null;
const contentType = BROWSER_TAB_ASSET_CONTENT_TYPES.get(extname(normalizedPath).toLowerCase());
if (!contentType) return null;
return {
installed,
contentType,
sha256: declaration.sha256,
file: await verifyBrowserTabAsset(installed, normalizedPath),
};
},
Expand Down
Loading