@cosmicdrift/kumiko-framework 0.385.0 → 0.386.0

package/dist/api/request-context.d.ts

@@ -21,6 +21,7 @@ export type RequestContextData = {
         readonly risk: AgentRisk;
     };
     readonly chargedRateLimitBuckets?: Set<string>;
+    readonly agentToolCall?: true;
 };
 export declare const requestContext: {
     run<T>(data: RequestContextData, fn: () => T): T;
@@ -41,4 +42,5 @@ export declare function runWithOrigin<T>(origin: {
     };
 }, fn: () => T): T;
 export declare function runAsDirectCallEntry<T>(fn: () => T): T;
+export declare function isAgentToolCallScope(): boolean;
 export declare function runWithWriteOrigin<T>(origin: WriteOrigin, fn: () => T): T;

package/dist/api/request-context.js

@@ -48,15 +48,24 @@ export function runWithOrigin(origin, fn) {
             : new Set(),
     }, fn);
 }
-// Clears entryHandler so the next dispatch inside fn becomes the new entry —
-// used by dispatchToolCall so the invoked tool handler, not the surrounding
-// turn/approve handler, is what the irreversible-operation gate sees.
+// Clears entryHandler so the next dispatch inside fn becomes the new entry, letting
+// the irreversible-operation gate see the invoked tool handler instead of the
+// surrounding turn/approve handler. Reserved for dispatchToolCall, so it also marks
+// the scope as an agent tool call; it always mints a scope, because an agent loop
+// running outside any request must still carry that marker.
 export function runAsDirectCallEntry(fn) {
     const current = requestContext.get();
-    if (!current)
-        return fn();
-    const { entryHandler: _entryHandler, ...rest } = current;
-    return requestContext.run(rest, fn);
+    const requestId = current?.requestId ?? requestContext.generateId();
+    const { entryHandler: _entryHandler, ...rest } = current ?? {};
+    return requestContext.run({
+        ...rest,
+        requestId,
+        correlationId: current?.correlationId ?? requestId,
+        agentToolCall: true,
+    }, fn);
+}
+export function isAgentToolCallScope() {
+    return requestContext.get()?.agentToolCall === true;
 }
 // An ungated origin never mints a scope: seeds and boot writes keep their missing context.
 export function runWithWriteOrigin(origin, fn) {

package/dist/db/cross-tenant-reads.d.ts

@@ -0,0 +1,8 @@
+import type { CrossTenantReads } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import type { EscapeHatchReporter } from "../engine/types/index.ts";
+import { type CreateTenantDbOptions, type TenantDb } from "./tenant-db.ts";
+export declare function createCrossTenantReads(systemModeDb: TenantDb, reason: string, report: EscapeHatchReporter): CrossTenantReads;
+export declare function createHandlerCrossTenantReads(options: Omit<CreateTenantDbOptions, "mode"> & {
+    readonly reason: string;
+    readonly report: EscapeHatchReporter;
+}): CrossTenantReads;

package/dist/db/cross-tenant-reads.js

@@ -0,0 +1,23 @@
+import { createTenantDb } from "./tenant-db.js";
+export function createCrossTenantReads(systemModeDb, reason, report) {
+    return {
+        selectMany(table, where, options) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.selectMany(table, where, options);
+        },
+        fetchOne(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.fetchOne(table, where);
+        },
+        count(table, where) {
+            report("cross-tenant-read", reason);
+            return systemModeDb.count(table, where);
+        },
+    };
+}
+// Own system-mode TenantDb without unsafeRaw/globalWrites: the handler gets the read surface only.
+export function createHandlerCrossTenantReads(options) {
+    const { reason, report, ...dbOptions } = options;
+    const systemModeDb = createTenantDb({ ...dbOptions, mode: "system" });
+    return createCrossTenantReads(systemModeDb, reason, report);
+}

package/dist/db/queries/test-stack.d.ts

@@ -2,5 +2,8 @@ import type { AnyDb } from "../query.ts";
 export { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement } from "./ddl.ts";
 export declare function truncateTablesRestartIdentity(db: AnyDb, tableNames: readonly string[]): Promise<void>;
 export declare function databaseExists(db: AnyDb, dbName: string): Promise<boolean>;
-export declare function createDatabase(db: AnyDb, dbName: string): Promise<void>;
+export declare function createDatabase(db: AnyDb, dbName: string, templateDbName?: string): Promise<void>;
+export declare function renameDatabase(db: AnyDb, fromName: string, toName: string): Promise<void>;
+export declare function listDatabaseNamesWithPrefix(db: AnyDb, prefix: string): Promise<readonly string[]>;
+export declare function acquireSessionAdvisoryLock(db: AnyDb, key: string): Promise<void>;
 export declare function dropDatabaseIfExists(db: AnyDb, dbName: string): Promise<void>;

package/dist/db/queries/test-stack.js

@@ -12,8 +12,21 @@ export async function databaseExists(db, dbName) {
     const rows = await asRawClient(db).unsafe(`SELECT EXISTS (SELECT 1 FROM pg_database WHERE datname = $1) AS exists`, [dbName]);
     return rows[0]?.exists === true;
 }
-export async function createDatabase(db, dbName) {
-    await asRawClient(db).unsafe(`CREATE DATABASE ${quoteTableIdent(dbName)}`);
+export async function createDatabase(db, dbName, templateDbName) {
+    const template = templateDbName === undefined ? "" : ` TEMPLATE ${quoteTableIdent(templateDbName)}`;
+    await asRawClient(db).unsafe(`CREATE DATABASE ${quoteTableIdent(dbName)}${template}`);
+}
+export async function renameDatabase(db, fromName, toName) {
+    await asRawClient(db).unsafe(`ALTER DATABASE ${quoteTableIdent(fromName)} RENAME TO ${quoteTableIdent(toName)}`);
+}
+export async function listDatabaseNamesWithPrefix(db, prefix) {
+    const rows = await asRawClient(db).unsafe(`SELECT datname FROM pg_database WHERE starts_with(datname, $1) ORDER BY datname`, [prefix]);
+    return rows.map((row) => row.datname);
+}
+// Session-scoped: CREATE DATABASE cannot run inside a transaction, so the
+// xact-scoped variant cannot guard it. Released when the session closes.
+export async function acquireSessionAdvisoryLock(db, key) {
+    await asRawClient(db).unsafe(`SELECT pg_advisory_lock(hashtext($1))`, [key]);
 }
 export async function dropDatabaseIfExists(db, dbName) {
     await asRawClient(db).unsafe(`DROP DATABASE IF EXISTS ${quoteTableIdent(dbName)}`);

package/dist/engine/feature-ast/pattern-change-schema.d.ts

@@ -233,6 +233,7 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             reason: z.ZodString;
             grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                crossTenantReads: "crossTenantReads";
                 globalWrites: "globalWrites";
                 systemIdentity: "systemIdentity";
                 unsafeRaw: "unsafeRaw";
@@ -314,6 +315,7 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             reason: z.ZodString;
             grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                crossTenantReads: "crossTenantReads";
                 globalWrites: "globalWrites";
                 systemIdentity: "systemIdentity";
                 unsafeRaw: "unsafeRaw";
@@ -384,6 +386,7 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             reason: z.ZodString;
             grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                crossTenantReads: "crossTenantReads";
                 globalWrites: "globalWrites";
                 systemIdentity: "systemIdentity";
                 unsafeRaw: "unsafeRaw";
@@ -420,6 +423,7 @@ export declare const PATTERN_SCHEMAS_BY_KIND: {
         escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
             reason: z.ZodString;
             grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                crossTenantReads: "crossTenantReads";
                 globalWrites: "globalWrites";
                 systemIdentity: "systemIdentity";
                 unsafeRaw: "unsafeRaw";
@@ -828,6 +832,7 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         reason: z.ZodString;
         grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            crossTenantReads: "crossTenantReads";
             globalWrites: "globalWrites";
             systemIdentity: "systemIdentity";
             unsafeRaw: "unsafeRaw";
@@ -908,6 +913,7 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         reason: z.ZodString;
         grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            crossTenantReads: "crossTenantReads";
             globalWrites: "globalWrites";
             systemIdentity: "systemIdentity";
             unsafeRaw: "unsafeRaw";
@@ -977,6 +983,7 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         reason: z.ZodString;
         grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            crossTenantReads: "crossTenantReads";
             globalWrites: "globalWrites";
             systemIdentity: "systemIdentity";
             unsafeRaw: "unsafeRaw";
@@ -1012,6 +1019,7 @@ export declare const patternSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     escapeHatch: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
         reason: z.ZodString;
         grants: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+            crossTenantReads: "crossTenantReads";
             globalWrites: "globalWrites";
             systemIdentity: "systemIdentity";
             unsafeRaw: "unsafeRaw";

package/dist/internal/stack-support.d.ts

@@ -1,5 +1,5 @@
 export { createDbConnection } from "../db/connection.ts";
-export { createDatabase, databaseExists, dropDatabaseIfExists, truncateTablesRestartIdentity, } from "../db/queries/test-stack.ts";
+export { acquireSessionAdvisoryLock, createDatabase, databaseExists, dropDatabaseIfExists, listDatabaseNamesWithPrefix, renameDatabase, truncateTablesRestartIdentity, } from "../db/queries/test-stack.ts";
 export { type AnyDb, isClosedConnectionError } from "../db/query.ts";
 export { columnNamesOf } from "../db/schema-inspection.ts";
 export { schemaTableName } from "../db/table-introspection.ts";

package/dist/internal/stack-support.js

@@ -1,6 +1,6 @@
 // @runtime dev
 export { createDbConnection } from "../db/connection.js";
-export { createDatabase, databaseExists, dropDatabaseIfExists, truncateTablesRestartIdentity, } from "../db/queries/test-stack.js";
+export { acquireSessionAdvisoryLock, createDatabase, databaseExists, dropDatabaseIfExists, listDatabaseNamesWithPrefix, renameDatabase, truncateTablesRestartIdentity, } from "../db/queries/test-stack.js";
 export { isClosedConnectionError } from "../db/query.js";
 export { columnNamesOf } from "../db/schema-inspection.js";
 export { schemaTableName } from "../db/table-introspection.js";

package/dist/jobs/job-runner-helpers.d.ts

@@ -3,7 +3,7 @@ import type { ConfigAccessor } from "@cosmicdrift/kumiko-types/config";
 import type { TzContext } from "@cosmicdrift/kumiko-types/tz-context";
 import type { JobsOptions, Queue } from "bullmq";
 import type { TenantDb } from "../db/tenant-db.ts";
-import type { AppContext, EscapeHatchReporter, JobContext, JobDefinition, JobRunIn, JobTriggerEvent } from "../engine/types/index.ts";
+import type { AppContext, JobDefinition, JobRunIn, JobTriggerEvent } from "../engine/types/index.ts";
 import type { Logger } from "../logging/types.ts";
 import type { Meter, SerializedTraceContext, Tracer } from "../observability/index.ts";
 import type { JobLogEntry, JobSubjectValue } from "./job-runner-types.ts";
@@ -14,7 +14,6 @@ export declare function serializeJobSubject(subject: Readonly<Record<string, Job
 export declare function jobSubjectKey(jobName: string, payload: Record<string, unknown>, fields: readonly string[] | undefined, declaration: "tenantVisibleFailure" | "tenantVisibleRun"): string | null;
 export declare function resolveJobTz(config: ConfigAccessor | undefined, context: Pick<AppContext, "geoTzProvider" | "clock">): Promise<TzContext>;
 export declare function missingDbProxy(jobName: string): TenantDb;
-export declare function createCrossTenantReads(systemModeDb: TenantDb, reason: string, report: EscapeHatchReporter): NonNullable<JobContext["crossTenantReads"]>;
 export declare function priorAttemptsOf(data: Record<string, unknown>): number;
 export declare function tenantFailureMessageKey(err: unknown, declaration: JobDefinition["tenantVisibleFailure"]): string | null;
 export declare const TRACE_CONTEXT_KEY = "_traceContext";

package/dist/jobs/job-runner-helpers.js

@@ -103,22 +103,6 @@ export function missingDbProxy(jobName) {
         },
     });
 }
-export function createCrossTenantReads(systemModeDb, reason, report) {
-    return {
-        selectMany(table, where, options) {
-            report("cross-tenant-read", reason);
-            return systemModeDb.selectMany(table, where, options);
-        },
-        fetchOne(table, where) {
-            report("cross-tenant-read", reason);
-            return systemModeDb.fetchOne(table, where);
-        },
-        count(table, where) {
-            report("cross-tenant-read", reason);
-            return systemModeDb.count(table, where);
-        },
-    };
-}
 export function priorAttemptsOf(data) {
     const value = data["_priorAttempts"];
     return typeof value === "number" && Number.isInteger(value) && value > 0 ? value : 0;

package/dist/jobs/job-runner.js

@@ -1,8 +1,9 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
+import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
 import { DelayedError, Queue, UnrecoverableError, Worker } from "bullmq";
 import { Redis } from "ioredis";
 import { requestContext } from "../api/request-context.js";
+import { createCrossTenantReads } from "../db/cross-tenant-reads.js";
 import { createTenantDb, createUncheckedSystemDb } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { bridgeStub } from "../engine/bridge-stub.js";
@@ -19,7 +20,7 @@ import { RedisKeys } from "../pipeline/redis-keys.js";
 import { createGatedIdentitySwitch } from "../pipeline/system-identity-switch.js";
 import { buildPersonalDataGate, parseWriteOrigin } from "../pipeline/write-origin.js";
 import { cronRepeatOptions } from "./cron-repeat-options.js";
-import { BOOT_GATE_SLOW_WARN_MS, BOOT_REDIS_TIMEOUT_MS, buildRetryBullOpts, COMPLETED_JOB_RETENTION_AGE_SEC, captureTraceContext, createCrossTenantReads, createJobLogger, DEFAULT_MAX_DEFERS, DEFER_BACKOFF_MAX_DOUBLINGS, DEFER_COUNT_KEY, DEFER_DELAY_CAP_MS, FAILED_JOB_RETENTION_AGE_SEC, HANDLER_DEFER_COUNT_KEY, isJobTriggerEvent, jobSubjectKey, maxRetryWindowMs, missingDbProxy, parseRedisOpts, payloadMatchesTriggerFilter, priorAttemptsOf, readTraceContext, resolveJobTz, STOP_QUEUE_READY_TIMEOUT_MS, stampGatedWriteOrigin, startQueueDepthPolling, TRACE_CONTEXT_KEY, tenantFailureMessageKey, timeoutReject, } from "./job-runner-helpers.js";
+import { BOOT_GATE_SLOW_WARN_MS, BOOT_REDIS_TIMEOUT_MS, buildRetryBullOpts, COMPLETED_JOB_RETENTION_AGE_SEC, captureTraceContext, createJobLogger, DEFAULT_MAX_DEFERS, DEFER_BACKOFF_MAX_DOUBLINGS, DEFER_COUNT_KEY, DEFER_DELAY_CAP_MS, FAILED_JOB_RETENTION_AGE_SEC, HANDLER_DEFER_COUNT_KEY, isJobTriggerEvent, jobSubjectKey, maxRetryWindowMs, missingDbProxy, parseRedisOpts, payloadMatchesTriggerFilter, priorAttemptsOf, readTraceContext, resolveJobTz, STOP_QUEUE_READY_TIMEOUT_MS, stampGatedWriteOrigin, startQueueDepthPolling, TRACE_CONTEXT_KEY, tenantFailureMessageKey, timeoutReject, } from "./job-runner-helpers.js";
 import { ACTIVE_TENANT_IDS_QUERY_NAME, bootJobIdForJobName, DEFAULT_QUEUE_NAME_PREFIX, markSchedulersSeen, ORPHAN_SCHEDULER_GRACE_MS, perTenantChildJobId, queueNameFor, removeOrphanJobSchedulers, schedulerIdForJobName, } from "./job-runner-schedulers.js";
 import { resolveMaxPerTenant } from "./max-per-tenant.js";
 export { serializeJobSubject } from "./job-runner-helpers.js";
@@ -611,7 +612,7 @@ export function createJobRunner(options) {
                 },
             })
             : undefined;
-        const crossTenantReadsReason = escapeHatchFor(jobDef.escapeHatch, "unsafeRaw")?.reason;
+        const crossTenantReadsReason = crossTenantReadsGrantFor(jobDef.escapeHatch)?.reason;
         const crossTenantReads = tenantScopedDb && crossTenantReadsReason !== undefined
             ? createCrossTenantReads(tenantScopedDb, crossTenantReadsReason, reportEscapeHatch)
             : undefined;

package/dist/pipeline/dispatch-shared.js

@@ -1,5 +1,6 @@
-import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
-import { requestContext, runWithOrigin } from "../api/request-context.js";
+import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
+import { isAgentToolCallScope, requestContext, runWithOrigin } from "../api/request-context.js";
+import { createHandlerCrossTenantReads } from "../db/cross-tenant-reads.js";
 import { runInSavepoint, selectMany } from "../db/query.js";
 import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
@@ -186,6 +187,7 @@ export function applyMemberResolutionReadOnly(handlerContext) {
         // A read as a member gets no system-scope DB, preSave pipeline or file storage.
         runPreSave: undefined,
         systemDb: undefined,
+        crossTenantReads: undefined,
         files: undefined,
         derivatives: undefined,
         ...(handlerContext.jobRunner && { jobRunner: denyingJobRunnerProxy() }),
@@ -326,6 +328,28 @@ readOnlyForTenant = false) {
     const systemDb = isSystem && db
         ? createUncheckedSystemDb(db, rawDbOutsideTransaction, reportEscapeHatch)
         : undefined;
+    // An agent tool call runs with the user's session but feeds the LLM context, so
+    // cross-tenant rows must never reach it, even when unsafeRaw implies the grant.
+    const crossTenantReadsReason = isAgentToolCallScope()
+        ? undefined
+        : crossTenantReadsGrantFor(handlerEscapeHatch)?.reason;
+    const crossTenantReads = dbSource && crossTenantReadsReason !== undefined
+        ? createHandlerCrossTenantReads({
+            db: dbSource,
+            tenantId: user.tenantId,
+            tracer: context.tracer,
+            meter: context.meter,
+            signal: reqCtx?.signal,
+            reason: crossTenantReadsReason,
+            report: reportEscapeHatch,
+            grants: {
+                report: reportEscapeHatch,
+                memberReadOnly: isMemberResolutionPrincipal(user),
+                personalDataGate: buildPersonalDataGate(registry, origin),
+                projectionRegistry: registry,
+            },
+        })
+        : undefined;
     // Exposed as ctx.db below — the internal `db` above stays the real,
     // working TenantDb for this function's own use (config/derivatives
     // accessors, systemDb construction).
@@ -855,6 +879,7 @@ readOnlyForTenant = false) {
         db: exposedDb,
         dbOutsideTransaction,
         ...(systemDb && { systemDb }),
+        ...(crossTenantReads && { crossTenantReads }),
         log,
         notify,
         ...(config && { config }),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-framework",
-  "version": "0.385.0",
+  "version": "0.386.0",
   "description": "Framework core — engine, pipeline, API, DB, and every other bit that makes Kumiko go.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -199,7 +199,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-types": "0.385.0",
+    "@cosmicdrift/kumiko-types": "0.386.0",
     "bullmq": "^5.76.7",
     "bun-types": "^1.3.13",
     "hono": "^4.13.1",
@@ -215,7 +215,7 @@
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-testing": "0.385.0",
+    "@cosmicdrift/kumiko-testing": "0.386.0",
     "bun-types": "^1.3.13",
     "pino-pretty": "^13.1.3"
   },

package/src/changes.json

@@ -1,4 +1,10 @@
 [
+  {
+    "version": "0.386.0",
+    "type": "improvement",
+    "title": "ctx.crossTenantReads for handlers with the crossTenantReads grant",
+    "detail": "A handler whose `escapeHatch` lists `grants: [\"crossTenantReads\"]` (or `unsafeRaw`, which implies it) gets `ctx.crossTenantReads` with `selectMany`, `fetchOne` and `count`, unfiltered by tenant and including the events table. Every call is audited as `cross-tenant-read`; `ctx.db.unsafeRaw()` stays denied for the read-only grant, and neither a member-resolution read nor an agent tool call (`dispatchToolCall`, including handlers it reaches through nested `ctx.query`/`ctx.write`) ever receives the surface, so cross-tenant rows cannot reach an LLM context. Jobs use the same grant. The internal `runAsDirectCallEntry` (`/internal/request-context`) now also marks its scope as an agent tool call. Without the grant nothing changes."
+  },
   {
     "version": "0.385.0",
     "type": "improvement",