@pikku/core 0.12.24 → 0.12.26

package/CHANGELOG.md

@@ -1,3 +1,27 @@
+## 0.12.26
+
+### Patch Changes
+
+- 909eb25: Add audit logging support for function invocations and database queries.
+
+  Introduces `AuditService` and `createAuditedKysely` — configurable audit capture with best-effort and transactional durability modes. Audit logs capture session metadata (user, org), RPC call details, and Kysely query operations (type, tables, changes). Audit context is scoped per-invocation so nested RPC calls are correctly attributed.
+
+## 0.12.25
+
+### Patch Changes
+
+- 665bdb0: Add end-to-end data classification for SQLite and Postgres projects.
+
+  **Core (`@pikku/core`):** New `Private<T>` and `Secret<T>` intersection brands, `ClassificationManifest`, `ColumnClassification`, and `AnonymizeStrategy` types exported from `data-classification.ts`.
+
+  **CLI (`@pikku/cli`):**
+  - SQL comment annotations: `-- @public`, `-- @private[:strategy]`, `-- @secret[:strategy]` on `CREATE TABLE` columns and `ALTER TABLE ... ADD COLUMN` statements. Unannotated columns default to `private`.
+  - `pikku db migrate` now emits a `classification.gen.ts` manifest alongside `schema.d.ts`.
+  - New `pikku db audit` command — prints a per-column classification summary and warns on `private`/`secret` columns with no anonymize strategy.
+  - Postgres dialect support in `resolveDb`, `PostgresMigrationExecutor`, and `PostgresIntrospector`.
+
+  **Inspector (`@pikku/inspector`):** New PKU910 check — `findPiiPaths()` walks inferred function return types looking for `__pii__` brands (including inside `Array<T>`, `Record<K,V>`, and index signatures) and fails the build if a function exposes branded fields in its output.
+
 ## 0.12.24
 
 ### Patch Changes

package/dist/data-classification.d.ts

@@ -0,0 +1,16 @@
+export type Private<T> = T & {
+    readonly __pii__: 'private';
+};
+export type Secret<T> = T & {
+    readonly __pii__: 'secret';
+};
+export type Classification = 'public' | 'private' | 'secret';
+export type AnonymizeStrategy = 'fake:email' | 'fake:name' | 'hash' | 'keep' | null;
+export interface ColumnClassification {
+    classification: Classification;
+    anonymize_strategy: AnonymizeStrategy;
+}
+export type ClassificationManifest = {
+    version: 1;
+    tables: Record<string, Record<string, ColumnClassification>>;
+};

package/dist/data-classification.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

@@ -50,3 +50,4 @@ export { isSerializable, stopSingletonServices } from './utils.js';
 export { getSingletonServices, getCreateWireServices } from './pikku-state.js';
 export { type ScheduledTaskInfo, type ScheduledTaskSummary, } from './services/scheduler-service.js';
 export { SchedulerService } from './services/scheduler-service.js';
+export type { Private, Secret, Classification, AnonymizeStrategy, ColumnClassification, ClassificationManifest, } from './data-classification.js';

package/dist/services/gopass-secrets.d.ts

@@ -5,43 +5,10 @@ import type { SecretService } from './secret-service.js';
  */
 export declare class GopassSecretService implements SecretService {
     private prefix;
-    /**
-     * Creates an instance of GopassSecretService.
-     * @param prefix - Optional prefix for all secret keys (e.g., 'pikku/' will look up 'pikku/mykey' for key 'mykey')
-     */
     constructor(prefix?: string);
     private getFullKey;
-    /**
-     * Retrieves a secret by key and parses it as JSON.
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the parsed secret value.
-     * @throws {Error} If the secret is not found or gopass fails.
-     */
-    getSecretJSON<R>(key: string): Promise<R>;
-    /**
-     * Retrieves a secret by key as a string.
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the secret value.
-     * @throws {Error} If the secret is not found or gopass fails.
-     */
-    getSecret(key: string): Promise<string>;
-    /**
-     * Checks if a secret exists without throwing.
-     * @param key - The key of the secret to check.
-     * @returns A promise that resolves to true if the secret exists.
-     */
+    getSecret<T = string>(key: string): Promise<T>;
     hasSecret(key: string): Promise<boolean>;
-    /**
-     * Stores a JSON value as a secret in gopass.
-     * @param key - The key to store the secret under.
-     * @param value - The JSON value to store.
-     * @returns A promise that resolves when the secret is stored.
-     */
-    setSecretJSON(key: string, value: unknown): Promise<void>;
-    /**
-     * Deletes a secret from gopass.
-     * @param key - The key of the secret to delete.
-     * @returns A promise that resolves when the secret is deleted.
-     */
+    setSecret(key: string, value: unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
 }

package/dist/services/gopass-secrets.js

@@ -5,10 +5,6 @@ import { execFileSync } from 'child_process';
  */
 export class GopassSecretService {
     prefix;
-    /**
-     * Creates an instance of GopassSecretService.
-     * @param prefix - Optional prefix for all secret keys (e.g., 'pikku/' will look up 'pikku/mykey' for key 'mykey')
-     */
     constructor(prefix = '') {
         this.prefix = prefix;
     }
@@ -18,38 +14,23 @@ export class GopassSecretService {
         }
         return this.prefix ? `${this.prefix}${key}` : key;
     }
-    /**
-     * Retrieves a secret by key and parses it as JSON.
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the parsed secret value.
-     * @throws {Error} If the secret is not found or gopass fails.
-     */
-    async getSecretJSON(key) {
-        const value = await this.getSecret(key);
-        return JSON.parse(value);
-    }
-    /**
-     * Retrieves a secret by key as a string.
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the secret value.
-     * @throws {Error} If the secret is not found or gopass fails.
-     */
     async getSecret(key) {
         const fullKey = this.getFullKey(key);
         try {
-            return execFileSync('gopass', ['show', '-o', fullKey], {
+            const raw = execFileSync('gopass', ['show', '-o', fullKey], {
                 encoding: 'utf8',
             }).trim();
+            try {
+                return JSON.parse(raw);
+            }
+            catch {
+                return raw;
+            }
         }
         catch (error) {
             throw new Error(`Secret Not Found: ${key}`, { cause: error });
         }
     }
-    /**
-     * Checks if a secret exists without throwing.
-     * @param key - The key of the secret to check.
-     * @returns A promise that resolves to true if the secret exists.
-     */
     async hasSecret(key) {
         const fullKey = this.getFullKey(key);
         try {
@@ -60,19 +41,13 @@ export class GopassSecretService {
             return false;
         }
     }
-    /**
-     * Stores a JSON value as a secret in gopass.
-     * @param key - The key to store the secret under.
-     * @param value - The JSON value to store.
-     * @returns A promise that resolves when the secret is stored.
-     */
-    async setSecretJSON(key, value) {
+    async setSecret(key, value) {
         const fullKey = this.getFullKey(key);
-        const jsonValue = JSON.stringify(value);
+        const encoded = typeof value === 'string' ? value : JSON.stringify(value);
         try {
             execFileSync('gopass', ['insert', '-f', fullKey], {
                 encoding: 'utf8',
-                input: jsonValue,
+                input: encoded,
                 stdio: ['pipe', 'pipe', 'pipe'],
             });
         }
@@ -80,11 +55,6 @@ export class GopassSecretService {
             throw new Error(`Failed to set secret: ${key}`, { cause: error });
         }
     }
-    /**
-     * Deletes a secret from gopass.
-     * @param key - The key of the secret to delete.
-     * @returns A promise that resolves when the secret is deleted.
-     */
     async deleteSecret(key) {
         const fullKey = this.getFullKey(key);
         try {

package/dist/services/local-secrets.d.ts

@@ -8,43 +8,9 @@ export declare class LocalSecretService implements SecretService {
     private variables;
     private localSecrets;
     private parseSecret;
-    /**
-     * Creates an instance of LocalSecretService.
-     */
     constructor(variables?: VariablesService);
-    /**
-     * Retrieves a secret by key.
-     * Checks local storage first, then falls back to environment variables.
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the secret value.
-     * @throws {Error} If the secret is not found.
-     */
-    getSecretJSON<R>(key: string): Promise<R>;
-    /**
-     * Retrieves a secret by key.
-     * Checks local storage first, then falls back to environment variables.
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the secret value.
-     * @throws {Error} If the secret is not found.
-     */
-    getSecret(key: string): Promise<string>;
-    /**
-     * Stores a JSON value as a secret in local storage.
-     * @param key - The key to store the secret under.
-     * @param value - The JSON value to store.
-     * @returns A promise that resolves when the secret is stored.
-     */
-    setSecretJSON(key: string, value: unknown): Promise<void>;
-    /**
-     * Checks if a secret exists without throwing.
-     * @param key - The key of the secret to check.
-     * @returns A promise that resolves to true if the secret exists.
-     */
+    getSecret<T = string>(key: string): Promise<T>;
+    setSecret(key: string, value: unknown): Promise<void>;
     hasSecret(key: string): Promise<boolean>;
-    /**
-     * Deletes a secret from local storage.
-     * @param key - The key of the secret to delete.
-     * @returns A promise that resolves when the secret is deleted.
-     */
     deleteSecret(key: string): Promise<void>;
 }

package/dist/services/local-secrets.js

@@ -6,7 +6,6 @@ import { LocalVariablesService } from './local-variables.js';
 export class LocalSecretService {
     variables;
     localSecrets = new Map();
-    // TODO: Drop this fallback once secrets and variables expose aligned typed/raw access paths again.
     parseSecret(raw) {
         try {
             return JSON.parse(raw);
@@ -15,66 +14,23 @@ export class LocalSecretService {
             return raw;
         }
     }
-    /**
-     * Creates an instance of LocalSecretService.
-     */
     constructor(variables = new LocalVariablesService()) {
         this.variables = variables;
     }
-    /**
-     * Retrieves a secret by key.
-     * Checks local storage first, then falls back to environment variables.
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the secret value.
-     * @throws {Error} If the secret is not found.
-     */
-    async getSecretJSON(key) {
-        // Check local storage first
+    async getSecret(key) {
         const localValue = this.localSecrets.get(key);
         if (localValue) {
             return this.parseSecret(localValue);
         }
-        // Fall back to environment variables
         const value = await this.variables.get(key);
         if (value) {
             return this.parseSecret(value);
         }
         throw new Error('Requested secret not found');
     }
-    /**
-     * Retrieves a secret by key.
-     * Checks local storage first, then falls back to environment variables.
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the secret value.
-     * @throws {Error} If the secret is not found.
-     */
-    async getSecret(key) {
-        // Check local storage first
-        const localValue = this.localSecrets.get(key);
-        if (localValue) {
-            return localValue;
-        }
-        // Fall back to environment variables
-        const value = await this.variables.get(key);
-        if (value) {
-            return value;
-        }
-        throw new Error('Requested secret not found');
-    }
-    /**
-     * Stores a JSON value as a secret in local storage.
-     * @param key - The key to store the secret under.
-     * @param value - The JSON value to store.
-     * @returns A promise that resolves when the secret is stored.
-     */
-    async setSecretJSON(key, value) {
-        this.localSecrets.set(key, JSON.stringify(value));
+    async setSecret(key, value) {
+        this.localSecrets.set(key, typeof value === 'string' ? value : JSON.stringify(value));
     }
-    /**
-     * Checks if a secret exists without throwing.
-     * @param key - The key of the secret to check.
-     * @returns A promise that resolves to true if the secret exists.
-     */
     async hasSecret(key) {
         if (this.localSecrets.has(key)) {
             return true;
@@ -82,11 +38,6 @@ export class LocalSecretService {
         const value = await this.variables.get(key);
         return value !== undefined && value !== null && value !== '';
     }
-    /**
-     * Deletes a secret from local storage.
-     * @param key - The key of the secret to delete.
-     * @returns A promise that resolves when the secret is deleted.
-     */
     async deleteSecret(key) {
         this.localSecrets.delete(key);
     }

package/dist/services/local-variables.d.ts

@@ -2,11 +2,9 @@ import type { VariablesService } from './variables-service.js';
 export declare class LocalVariablesService implements VariablesService {
     private variables;
     constructor(variables?: Record<string, string | undefined>);
-    getAll(): Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
-    get(name: string): Promise<string | undefined> | string | undefined;
-    getJSON<T = unknown>(name: string): T | undefined;
-    set(name: string, value: string): void;
-    setJSON(name: string, value: unknown): void;
+    getAll(): Record<string, string | undefined>;
+    get<T = string>(name: string): T | undefined;
+    set(name: string, value: unknown): void;
     has(name: string): boolean;
     delete(name: string): void;
 }

package/dist/services/local-variables.js

@@ -7,19 +7,19 @@ export class LocalVariablesService {
         return this.variables || {};
     }
     get(name) {
-        return this.variables[name];
-    }
-    getJSON(name) {
-        const value = this.variables[name];
-        if (value === undefined)
+        const raw = this.variables[name];
+        if (raw === undefined)
             return undefined;
-        return JSON.parse(value);
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return raw;
+        }
     }
     set(name, value) {
-        this.variables[name] = value;
-    }
-    setJSON(name, value) {
-        this.variables[name] = JSON.stringify(value);
+        this.variables[name] =
+            typeof value === 'string' ? value : JSON.stringify(value);
     }
     has(name) {
         return name in this.variables && this.variables[name] !== undefined;

package/dist/services/scoped-secret-service.d.ts

@@ -8,9 +8,8 @@ export declare class ScopedSecretService implements SecretService {
     private allowedKeys;
     constructor(secrets: SecretService, allowedKeys: Set<string>);
     private assertAllowed;
-    getSecret(key: string): Promise<string>;
-    getSecretJSON<T = {}>(key: string): Promise<T>;
+    getSecret<T = string>(key: string): Promise<T>;
     hasSecret(key: string): Promise<boolean>;
-    setSecretJSON(_key: string, _value: unknown): Promise<void>;
+    setSecret(_key: string, _value: unknown): Promise<void>;
     deleteSecret(_key: string): Promise<void>;
 }

package/dist/services/scoped-secret-service.js

@@ -18,16 +18,12 @@ export class ScopedSecretService {
         this.assertAllowed(key);
         return this.secrets.getSecret(key);
     }
-    async getSecretJSON(key) {
-        this.assertAllowed(key);
-        return this.secrets.getSecretJSON(key);
-    }
     async hasSecret(key) {
         this.assertAllowed(key);
         return this.secrets.hasSecret(key);
     }
-    async setSecretJSON(_key, _value) {
-        throw new Error('setSecretJSON is not allowed in scoped secret service');
+    async setSecret(_key, _value) {
+        throw new Error('setSecret is not allowed in scoped secret service');
     }
     async deleteSecret(_key) {
         throw new Error('deleteSecret is not allowed in scoped secret service');

package/dist/services/secret-service.d.ts

@@ -3,19 +3,12 @@
  */
 export interface SecretService {
     /**
-     * Retrieves a secret by key and parses it as JSON.
-     * @param key - The key of the secret to retrieve.
-     * @returns A promise that resolves to the parsed secret value.
-     * @throws If the secret is not found.
-     */
-    getSecretJSON<Return = {}>(key: string): Promise<Return>;
-    /**
-     * Retrieves a secret by key as a string.
+     * Retrieves a secret by key, typed as T (defaults to string).
      * @param key - The key of the secret to retrieve.
      * @returns A promise that resolves to the secret value.
      * @throws If the secret is not found.
      */
-    getSecret(key: string): Promise<string>;
+    getSecret<T = string>(key: string): Promise<T>;
     /**
      * Checks if a secret exists without throwing.
      * @param key - The key of the secret to check.
@@ -23,12 +16,12 @@ export interface SecretService {
      */
     hasSecret(key: string): Promise<boolean>;
     /**
-     * Stores a JSON value as a secret.
+     * Stores a secret value.
      * @param key - The key to store the secret under.
-     * @param value - The JSON value to store.
+     * @param value - The value to store.
      * @returns A promise that resolves when the secret is stored.
      */
-    setSecretJSON(key: string, value: unknown): Promise<void>;
+    setSecret(key: string, value: unknown): Promise<void>;
     /**
      * Deletes a secret by key.
      * @param key - The key of the secret to delete.

package/dist/services/typed-secret-service.d.ts

@@ -19,11 +19,10 @@ export declare class TypedSecretService<TMap = Record<string, unknown>> implemen
     private secrets;
     private credentialsMeta;
     constructor(secrets: SecretService, credentialsMeta: Record<string, CredentialMeta>);
-    getSecretJSON<K extends keyof TMap & string>(key: K): Promise<TMap[K]>;
-    getSecretJSON<T = unknown>(key: string): Promise<T>;
-    getSecret(key: string): Promise<string>;
+    getSecret<K extends keyof TMap & string>(key: K): Promise<TMap[K]>;
+    getSecret<T = string>(key: string): Promise<T>;
     hasSecret(key: string): Promise<boolean>;
-    setSecretJSON<K extends string>(key: K, value: K extends keyof TMap ? TMap[K] : unknown): Promise<void>;
+    setSecret<K extends string>(key: K, value: K extends keyof TMap ? TMap[K] : unknown): Promise<void>;
     deleteSecret(key: string): Promise<void>;
     getAllStatus(): Promise<CredentialStatus[]>;
     getMissing(): Promise<CredentialStatus[]>;

package/dist/services/typed-secret-service.js

@@ -5,17 +5,14 @@ export class TypedSecretService {
         this.secrets = secrets;
         this.credentialsMeta = credentialsMeta;
     }
-    async getSecretJSON(key) {
-        return this.secrets.getSecretJSON(key);
-    }
     async getSecret(key) {
         return this.secrets.getSecret(key);
     }
     async hasSecret(key) {
         return this.secrets.hasSecret(key);
     }
-    async setSecretJSON(key, value) {
-        return this.secrets.setSecretJSON(key, value);
+    async setSecret(key, value) {
+        return this.secrets.setSecret(key, value);
     }
     async deleteSecret(key) {
         return this.secrets.deleteSecret(key);

package/dist/services/typed-variables-service.d.ts

@@ -13,13 +13,10 @@ export declare class TypedVariablesService<TMap = Record<string, unknown>> imple
     private variables;
     private variablesMeta;
     constructor(variables: VariablesService, variablesMeta: Record<string, VariableMeta>);
-    get(name: keyof TMap & string): Promise<string | undefined> | string | undefined;
-    get(name: string): Promise<string | undefined> | string | undefined;
-    getJSON<K extends keyof TMap & string>(name: K): Promise<TMap[K] | undefined> | TMap[K] | undefined;
-    getJSON<T = unknown>(name: string): Promise<T | undefined> | T | undefined;
+    get<K extends keyof TMap & string>(name: K): Promise<TMap[K] | undefined> | TMap[K] | undefined;
+    get<T = string>(name: string): Promise<T | undefined> | T | undefined;
     getAll(): Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
-    set(name: string, value: string): Promise<void> | void;
-    setJSON(name: string, value: unknown): Promise<void> | void;
+    set(name: string, value: unknown): Promise<void> | void;
     has(name: string): Promise<boolean> | boolean;
     delete(name: string): Promise<void> | void;
     getAllStatus(): Promise<VariableStatus[]>;

package/dist/services/typed-variables-service.js

@@ -8,18 +8,12 @@ export class TypedVariablesService {
     get(name) {
         return this.variables.get(name);
     }
-    getJSON(name) {
-        return this.variables.getJSON(name);
-    }
     getAll() {
         return this.variables.getAll();
     }
     set(name, value) {
         return this.variables.set(name, value);
     }
-    setJSON(name, value) {
-        return this.variables.setJSON(name, value);
-    }
     has(name) {
         return this.variables.has(name);
     }

package/dist/services/variables-service.d.ts

@@ -1,9 +1,7 @@
 export interface VariablesService {
-    get: (name: string) => Promise<string | undefined> | string | undefined;
-    getJSON: <T = unknown>(name: string) => Promise<T | undefined> | T | undefined;
+    get<T = string>(name: string): Promise<T | undefined> | T | undefined;
     getAll: () => Promise<Record<string, string | undefined>> | Record<string, string | undefined>;
-    set: (name: string, value: string) => Promise<void> | void;
-    setJSON: (name: string, value: unknown) => Promise<void> | void;
+    set: (name: string, value: unknown) => Promise<void> | void;
     has: (name: string) => Promise<boolean> | boolean;
     delete: (name: string) => Promise<void> | void;
 }

package/dist/testing/service-tests.js

@@ -517,13 +517,13 @@ export function defineServiceTests(config) {
         const factory = services.secretService;
         const kek = 'test-key-encryption-key-32chars!';
         describe(`SecretService [${name}]`, () => {
-            test('setSecretJSON and getSecretJSON', async () => {
+            test('setSecret and getSecret', async () => {
                 const service = await factory({ key: kek });
-                await service.setSecretJSON('api-key', {
+                await service.setSecret('api-key', {
                     token: 'sk-123',
                     endpoint: 'https://api.example.com',
                 });
-                const result = await service.getSecretJSON('api-key');
+                const result = await service.getSecret('api-key');
                 assert.deepEqual(result, {
                     token: 'sk-123',
                     endpoint: 'https://api.example.com',
@@ -531,9 +531,9 @@ export function defineServiceTests(config) {
             });
             test('getSecret returns raw string', async () => {
                 const service = await factory({ key: kek });
-                await service.setSecretJSON('string-secret', 'plain-value');
+                await service.setSecret('string-secret', 'plain-value');
                 const result = await service.getSecret('string-secret');
-                assert.strictEqual(result, '"plain-value"');
+                assert.strictEqual(result, 'plain-value');
             });
             test('hasSecret returns true/false', async () => {
                 const service = await factory({ key: kek });
@@ -546,16 +546,16 @@ export function defineServiceTests(config) {
                     message: 'Requested secret not found',
                 });
             });
-            test('setSecretJSON upserts existing key', async () => {
+            test('setSecret upserts existing key', async () => {
                 const service = await factory({ key: kek });
-                await service.setSecretJSON('upsert-key', { v: 1 });
-                await service.setSecretJSON('upsert-key', { v: 2 });
-                const result = await service.getSecretJSON('upsert-key');
+                await service.setSecret('upsert-key', { v: 1 });
+                await service.setSecret('upsert-key', { v: 2 });
+                const result = await service.getSecret('upsert-key');
                 assert.deepEqual(result, { v: 2 });
             });
             test('deleteSecret removes the key', async () => {
                 const service = await factory({ key: kek });
-                await service.setSecretJSON('to-delete', 'bye');
+                await service.setSecret('to-delete', 'bye');
                 assert.strictEqual(await service.hasSecret('to-delete'), true);
                 await service.deleteSecret('to-delete');
                 assert.strictEqual(await service.hasSecret('to-delete'), false);
@@ -563,13 +563,13 @@ export function defineServiceTests(config) {
             test('rotateKEK re-wraps all secrets', async () => {
                 const newKEK = 'new-key-encryption-key-rotated!';
                 const oldService = await factory({ key: kek });
-                await oldService.setSecretJSON('rotate-test', { important: 'data' });
+                await oldService.setSecret('rotate-test', { important: 'data' });
                 const rotatedService = await factory({
                     key: newKEK,
                     keyVersion: 2,
                     previousKey: kek,
                 });
-                const before = await rotatedService.getSecretJSON('rotate-test');
+                const before = await rotatedService.getSecret('rotate-test');
                 assert.deepEqual(before, { important: 'data' });
                 assert.ok(rotatedService.rotateKEK);
                 const count = await rotatedService.rotateKEK();
@@ -578,7 +578,7 @@ export function defineServiceTests(config) {
                     key: newKEK,
                     keyVersion: 2,
                 });
-                const after = await newOnlyService.getSecretJSON('rotate-test');
+                const after = await newOnlyService.getSecret('rotate-test');
                 assert.deepEqual(after, { important: 'data' });
             });
             test('rotateKEK throws without previousKey', async () => {

package/dist/wirings/ai-agent/ai-agent-prepare.js

@@ -494,7 +494,10 @@ export async function prepareAgentRun(agentName, input, params, agentSessionMap,
     const trimmedMessages = trimMessages(allMessages);
     const aiMiddlewares = agent.aiMiddleware ?? [];
     const { tools, missingRpcs } = await buildToolDefs(params, agentSessionMap, input.resourceId, resolvedName, packageName, streamContext, aiMiddlewares, agent.agentMode);
-    const instructions = await buildInstructions(resolvedName, packageName);
+    let instructions = await buildInstructions(resolvedName, packageName);
+    if (input.context) {
+        instructions = `${instructions}\n\nCurrent context (use these identifiers directly in tool calls — do not ask the user for them):\n${input.context}`;
+    }
     const resolved = resolveModelConfig(resolvedName, agent);
     // Per-request overrides
     if (input.model) {

package/dist/wirings/ai-agent/ai-agent.types.d.ts

@@ -76,6 +76,10 @@ export interface AIAgentInput {
     attachments?: AIAgentInputAttachment[];
     model?: string;
     temperature?: number;
+    /** Structured context injected into the system instructions for this request.
+     *  Use to provide upfront state (e.g. current org/project/branch/deployment)
+     *  so the agent can call tools without asking the user for identifiers. */
+    context?: string;
 }
 export interface AIAgentOutput {
     runId: string;