@synapsor/runner 0.1.0-alpha.10 → 0.1.0-alpha.13

package/examples/mcp-postgres-billing-app-handler/synapsor-handler.mjs

@@ -0,0 +1,437 @@
+import crypto from "node:crypto";
+import { Pool } from "pg";
+import { z } from "zod";
+const safeIdentifier = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const scalarSchema = z.union([z.string(), z.number(), z.boolean(), z.null()]);
+export const appHandlerRequestV1Schema = z.object({
+    protocol_version: z.string().optional(),
+    schema_version: z.string().optional(),
+    proposal_id: z.string().min(1),
+    idempotency_key: z.string().min(1),
+    issued_at: z.string().optional(),
+    signature: z.string().optional(),
+}).passthrough();
+export const appHandlerReceiptV1Schema = z.object({
+    status: z.enum(["applied", "already_applied", "conflict", "failed"]),
+    rows_affected: z.number().int().nonnegative().default(0),
+    source_database_mutated: z.boolean().default(false),
+    previous_version: scalarSchema.optional(),
+    new_version: scalarSchema.optional(),
+    safe_error_code: z.string().nullable().optional(),
+    details: z.record(z.unknown()).optional(),
+});
+export function createWritebackHandler(options) {
+    const database = options.database ?? createConfiguredDatabase(options);
+    return async (request, response) => {
+        const result = await handleWritebackHttpRequest(request, options, database);
+        response.statusCode = result.statusCode;
+        response.setHeader("content-type", "application/json; charset=utf-8");
+        response.end(`${JSON.stringify(result.receipt, null, 2)}\n`);
+    };
+}
+export async function handleWritebackHttpRequest(request, options, database = options.database ?? createConfiguredDatabase(options)) {
+    try {
+        if (request.method && request.method !== "POST") {
+            return { statusCode: 405, receipt: failedReceipt("METHOD_NOT_ALLOWED") };
+        }
+        const rawBody = await readRawBody(request);
+        const auth = verifyRequestAuth({
+            headers: request.headers,
+            rawBody,
+            options,
+        });
+        if (!auth.ok)
+            return auth;
+        let body;
+        try {
+            body = JSON.parse(rawBody || "{}");
+        }
+        catch {
+            return { statusCode: 400, receipt: failedReceipt("BAD_JSON") };
+        }
+        const parsed = appHandlerRequestV1Schema.safeParse(body);
+        if (!parsed.success) {
+            return { statusCode: 400, receipt: failedReceipt("BAD_WRITEBACK_REQUEST") };
+        }
+        let baseJob;
+        try {
+            baseJob = normalizeHandlerJob(parsed.data);
+            if (!supportedProtocolVersion(baseJob.protocolVersion)) {
+                return { statusCode: 400, receipt: failedReceipt("UNSUPPORTED_PROTOCOL_VERSION") };
+            }
+        }
+        catch {
+            return { statusCode: 400, receipt: failedReceipt("BAD_WRITEBACK_REQUEST") };
+        }
+        const apply = options.capabilities[baseJob.action];
+        if (!apply) {
+            return { statusCode: 400, receipt: failedReceipt("UNSUPPORTED_ACTION") };
+        }
+        const receipt = await database.withTransaction(async (tx) => {
+            const duplicate = await tx.findReceipt(baseJob.idempotencyKey);
+            if (duplicate?.status === "applied" || duplicate?.status === "already_applied") {
+                return {
+                    ...duplicate,
+                    status: "already_applied",
+                    rows_affected: 0,
+                    source_database_mutated: false,
+                };
+            }
+            const row = await tx.lockTarget(baseJob);
+            if (!row) {
+                const conflict = conflictReceipt("ROW_NOT_FOUND_OR_WRONG_TENANT");
+                await tx.recordReceipt(baseJob, conflict);
+                return conflict;
+            }
+            const currentVersion = row[baseJob.expectedVersion.column];
+            if (!versionValuesMatch(currentVersion, baseJob.expectedVersion.value)) {
+                const conflict = conflictReceipt("ROW_CHANGED_AFTER_PROPOSAL", scalarOrNull(currentVersion));
+                await tx.recordReceipt(baseJob, conflict);
+                return conflict;
+            }
+            const job = { ...baseJob, row };
+            const effects = await apply(job, tx).catch(() => {
+                throw new SafeHandlerError("HANDLER_BUSINESS_ERROR");
+            });
+            const receipt = appliedReceipt(job, effects);
+            await tx.recordReceipt(job, receipt);
+            return receipt;
+        });
+        return { statusCode: receipt.status === "failed" ? 500 : 200, receipt };
+    }
+    catch (error) {
+        return {
+            statusCode: 500,
+            receipt: failedReceipt(error instanceof SafeHandlerError ? error.code : "HANDLER_EXCEPTION"),
+        };
+    }
+}
+class SafeHandlerError extends Error {
+    code;
+    constructor(code) {
+        super(code);
+        this.code = code;
+    }
+}
+function supportedProtocolVersion(value) {
+    return value === "1.0" || value === "synapsor.handler-writeback.v1";
+}
+function createConfiguredDatabase(options) {
+    if (!options.source)
+        throw new Error("createWritebackHandler requires source or database");
+    if (options.source.engine !== "postgres")
+        throw new Error("Only postgres app-owned handler helper source is implemented in this alpha");
+    const env = options.env ?? process.env;
+    const writeUrl = env[options.source.writeUrlEnv];
+    if (!writeUrl)
+        throw new Error(`${options.source.writeUrlEnv} is not set`);
+    return new PostgresWritebackHandlerDatabase(writeUrl, options.source.receiptTable);
+}
+export class PostgresWritebackHandlerDatabase {
+    pool;
+    receiptSchema;
+    receiptTable;
+    constructor(connectionString, receiptTable) {
+        this.pool = new Pool({ connectionString });
+        this.receiptSchema = receiptTable?.schema ?? "public";
+        this.receiptTable = receiptTable?.table ?? "synapsor_handler_receipts";
+    }
+    async withTransaction(fn) {
+        const client = await this.pool.connect();
+        try {
+            await client.query("BEGIN");
+            const tx = new PostgresWritebackHandlerTransaction(client, this.receiptSchema, this.receiptTable);
+            await tx.ensureReceiptTable();
+            const result = await fn(tx);
+            await client.query("COMMIT");
+            return result;
+        }
+        catch (error) {
+            await client.query("ROLLBACK").catch(() => undefined);
+            throw error;
+        }
+        finally {
+            client.release();
+        }
+    }
+    async close() {
+        await this.pool.end();
+    }
+}
+class PostgresWritebackHandlerTransaction {
+    client;
+    receiptSchema;
+    receiptTable;
+    constructor(client, receiptSchema, receiptTable) {
+        this.client = client;
+        this.receiptSchema = receiptSchema;
+        this.receiptTable = receiptTable;
+    }
+    async ensureReceiptTable() {
+        await this.client.query(`
+      CREATE TABLE IF NOT EXISTS ${this.receiptTableName()} (
+        idempotency_key text PRIMARY KEY,
+        proposal_id text NOT NULL,
+        action text NOT NULL,
+        status text NOT NULL,
+        receipt_json jsonb NOT NULL,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        completed_at timestamptz
+      )
+    `);
+    }
+    async query(sql, values = []) {
+        const result = await this.client.query(sql, values);
+        return { rows: result.rows, rowCount: result.rowCount ?? 0 };
+    }
+    async insert(table, values, options = {}) {
+        const entries = Object.entries(values);
+        if (!entries.length)
+            throw new Error("insert values must not be empty");
+        const columns = entries.map(([column]) => quoteIdentifier(column));
+        const params = entries.map((_, index) => `$${index + 1}`);
+        const returning = options.returning?.length ? ` RETURNING ${options.returning.map(quoteIdentifier).join(", ")}` : "";
+        const result = await this.client.query(`INSERT INTO ${qualifiedName(options.schema ?? "public", table)} (${columns.join(", ")}) VALUES (${params.join(", ")})${returning}`, entries.map(([, value]) => value));
+        return { rows: result.rows, rowCount: result.rowCount ?? 0 };
+    }
+    async update(table, where, values, options = {}) {
+        const valueEntries = Object.entries(values);
+        const whereEntries = Object.entries(where);
+        if (!valueEntries.length)
+            throw new Error("update values must not be empty");
+        if (!whereEntries.length)
+            throw new Error("update where must not be empty");
+        const params = [];
+        const set = valueEntries.map(([column, value]) => {
+            params.push(value);
+            return `${quoteIdentifier(column)} = $${params.length}`;
+        });
+        const clauses = whereEntries.map(([column, value]) => {
+            params.push(value);
+            return `${quoteIdentifier(column)} = $${params.length}`;
+        });
+        const returning = options.returning?.length ? ` RETURNING ${options.returning.map(quoteIdentifier).join(", ")}` : "";
+        const result = await this.client.query(`UPDATE ${qualifiedName(options.schema ?? "public", table)} SET ${set.join(", ")} WHERE ${clauses.join(" AND ")}${returning}`, params);
+        return { rows: result.rows, rowCount: result.rowCount ?? 0 };
+    }
+    async findReceipt(idempotencyKey) {
+        const result = await this.client.query(`SELECT receipt_json FROM ${this.receiptTableName()} WHERE idempotency_key = $1 FOR UPDATE`, [idempotencyKey]);
+        const raw = result.rows[0]?.receipt_json;
+        return isRecord(raw) ? coerceReceipt(raw) : undefined;
+    }
+    async lockTarget(job) {
+        const result = await this.client.query(`SELECT * FROM ${qualifiedName(job.target.schema, job.target.table)}
+       WHERE ${quoteIdentifier(job.target.primaryKey.column)} = $1
+         AND ${quoteIdentifier(job.tenantGuard.column)} = $2
+       FOR UPDATE`, [job.target.primaryKey.value, job.tenantGuard.value]);
+        return result.rows[0];
+    }
+    async recordReceipt(job, receipt) {
+        await this.client.query(`INSERT INTO ${this.receiptTableName()} (idempotency_key, proposal_id, action, status, receipt_json, completed_at)
+       VALUES ($1, $2, $3, $4, $5::jsonb, now())
+       ON CONFLICT (idempotency_key)
+       DO UPDATE SET status = EXCLUDED.status, receipt_json = EXCLUDED.receipt_json, completed_at = EXCLUDED.completed_at`, [job.idempotencyKey, job.proposalId, job.action, receipt.status, JSON.stringify(receipt)]);
+    }
+    receiptTableName() {
+        return qualifiedName(this.receiptSchema, this.receiptTable);
+    }
+}
+function normalizeHandlerJob(request) {
+    const changeSet = isRecord(request.change_set) ? request.change_set : request;
+    const source = isRecord(changeSet.source) ? changeSet.source : {};
+    const target = isRecord(changeSet.target) ? changeSet.target : source;
+    const guards = isRecord(changeSet.guards) ? changeSet.guards : {};
+    const scope = isRecord(changeSet.scope) ? changeSet.scope : {};
+    const principal = isRecord(changeSet.principal) ? changeSet.principal : {};
+    const primaryKey = isRecord(target.primary_key) ? target.primary_key : isRecord(source.primary_key) ? source.primary_key : {};
+    const tenantGuard = isRecord(guards.tenant) ? guards.tenant : isRecord(changeSet.tenant_guard) ? changeSet.tenant_guard : {};
+    const expectedVersion = isRecord(guards.expected_version) ? guards.expected_version : {};
+    const patch = scalarRecord(changeSet.patch);
+    const action = stringValue(changeSet.action ?? request.action, "action");
+    const schema = safeIdentifierValue(target.schema ?? source.schema, "target.schema");
+    const table = safeIdentifierValue(target.table ?? source.table, "target.table");
+    const primaryKeyColumn = safeIdentifierValue(primaryKey.column, "target.primary_key.column");
+    const primaryKeyValue = scalarValue(primaryKey.value ?? scope.object_id, "target.primary_key.value");
+    const tenantColumn = safeIdentifierValue(tenantGuard.column, "guards.tenant.column");
+    const tenantValue = scalarValue(tenantGuard.value ?? scope.tenant_id, "guards.tenant.value");
+    const expectedColumn = safeIdentifierValue(expectedVersion.column, "guards.expected_version.column");
+    const expectedValue = scalarValue(expectedVersion.value, "guards.expected_version.value");
+    return {
+        protocolVersion: String(request.protocol_version ?? request.schema_version ?? "1.0"),
+        proposalId: stringValue(request.proposal_id, "proposal_id"),
+        idempotencyKey: stringValue(request.idempotency_key, "idempotency_key"),
+        issuedAt: typeof request.issued_at === "string" ? request.issued_at : undefined,
+        action,
+        tenantId: String(tenantValue),
+        objectId: String(primaryKeyValue),
+        principal: String(principal.id ?? changeSet.runner_hint ?? "approved_operator"),
+        target: {
+            schema,
+            table,
+            primaryKey: { column: primaryKeyColumn, value: primaryKeyValue },
+        },
+        tenantGuard: { column: tenantColumn, value: tenantValue },
+        expectedVersion: { column: expectedColumn, value: expectedValue },
+        patch,
+        raw: request,
+    };
+}
+function verifyRequestAuth(input) {
+    const env = input.options.env ?? process.env;
+    const tokenEnv = input.options.tokenEnv;
+    if (tokenEnv) {
+        const expected = env[tokenEnv];
+        if (!expected)
+            return { ok: false, statusCode: 500, receipt: failedReceipt("HANDLER_TOKEN_MISSING") };
+        if (!validBearer(input.headers.authorization, expected)) {
+            return { ok: false, statusCode: 401, receipt: failedReceipt("UNAUTHORIZED") };
+        }
+    }
+    const signingSecretEnv = input.options.signingSecretEnv;
+    if (signingSecretEnv) {
+        const secret = env[signingSecretEnv];
+        if (!secret)
+            return { ok: false, statusCode: 500, receipt: failedReceipt("HANDLER_SIGNING_SECRET_MISSING") };
+        const signature = headerValue(input.headers["x-synapsor-signature"]);
+        const issuedAt = headerValue(input.headers["x-synapsor-issued-at"]);
+        if (!signature || !validSignature(input.rawBody, secret, signature)) {
+            return { ok: false, statusCode: 401, receipt: failedReceipt("INVALID_SIGNATURE") };
+        }
+        if (!issuedAt || !issuedAtWithinSkew(issuedAt, input.options.issuedAtSkewMs ?? 5 * 60 * 1000)) {
+            return { ok: false, statusCode: 401, receipt: failedReceipt("INVALID_ISSUED_AT") };
+        }
+    }
+    return { ok: true };
+}
+function appliedReceipt(job, effects) {
+    const details = {
+        ...(effects?.details ?? {}),
+        ...(effects?.effects ? { effects: effects.effects } : {}),
+    };
+    return {
+        status: "applied",
+        rows_affected: Math.max(1, Number(effects?.rowsAffected ?? effects?.effects?.length ?? 1)),
+        previous_version: scalarOrNull(job.row[job.expectedVersion.column]),
+        new_version: effects?.newVersion ?? scalarOrNull(job.row[job.expectedVersion.column]),
+        source_database_mutated: true,
+        safe_error_code: null,
+        ...(Object.keys(details).length ? { details } : {}),
+    };
+}
+function conflictReceipt(code, previousVersion) {
+    return {
+        status: "conflict",
+        rows_affected: 0,
+        source_database_mutated: false,
+        safe_error_code: code,
+        ...(previousVersion !== undefined ? { previous_version: previousVersion } : {}),
+    };
+}
+function failedReceipt(code) {
+    return {
+        status: "failed",
+        rows_affected: 0,
+        source_database_mutated: false,
+        safe_error_code: code,
+    };
+}
+function coerceReceipt(value) {
+    const parsed = appHandlerReceiptV1Schema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
+function validBearer(header, expected) {
+    const value = headerValue(header);
+    if (!value?.startsWith("Bearer "))
+        return false;
+    const actual = Buffer.from(value.slice("Bearer ".length));
+    const wanted = Buffer.from(expected);
+    return actual.length === wanted.length && crypto.timingSafeEqual(actual, wanted);
+}
+export function signHandlerRequest(rawBody, secret) {
+    return `sha256=${crypto.createHmac("sha256", secret).update(rawBody).digest("hex")}`;
+}
+function validSignature(rawBody, secret, signature) {
+    const expected = Buffer.from(signHandlerRequest(rawBody, secret));
+    const actual = Buffer.from(signature);
+    return actual.length === expected.length && crypto.timingSafeEqual(actual, expected);
+}
+function issuedAtWithinSkew(value, skewMs) {
+    const time = new Date(value).getTime();
+    if (Number.isNaN(time))
+        return false;
+    return Math.abs(Date.now() - time) <= skewMs;
+}
+function headerValue(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+async function readRawBody(request) {
+    const chunks = [];
+    let bytes = 0;
+    for await (const chunk of request) {
+        const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+        bytes += buffer.length;
+        if (bytes > 1024 * 1024)
+            throw new Error("handler body exceeds 1 MiB");
+        chunks.push(buffer);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+function scalarRecord(input) {
+    if (!isRecord(input))
+        throw new Error("patch must be an object");
+    const result = {};
+    for (const [key, value] of Object.entries(input)) {
+        if (!safeIdentifier.test(key))
+            throw new Error(`unsafe patch column: ${key}`);
+        result[key] = scalarValue(value, `patch.${key}`);
+    }
+    if (!Object.keys(result).length)
+        throw new Error("patch must not be empty");
+    return result;
+}
+function scalarValue(value, name) {
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return value;
+    throw new Error(`${name} must be a scalar`);
+}
+function scalarOrNull(value) {
+    if (value instanceof Date)
+        return value.toISOString();
+    if (value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean")
+        return value;
+    if (value === undefined)
+        return null;
+    return String(value);
+}
+function stringValue(value, name) {
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    throw new Error(`${name} must be a non-empty string`);
+}
+function safeIdentifierValue(value, name) {
+    const text = stringValue(value, name);
+    if (!safeIdentifier.test(text))
+        throw new Error(`${name} must be a safe identifier`);
+    return text;
+}
+function versionValuesMatch(actual, expected) {
+    if (actual instanceof Date)
+        return versionValuesMatch(actual.toISOString(), expected);
+    const actualDate = new Date(String(actual));
+    const expectedDate = new Date(String(expected));
+    if (!Number.isNaN(actualDate.getTime()) && !Number.isNaN(expectedDate.getTime())) {
+        return actualDate.getTime() === expectedDate.getTime();
+    }
+    return String(actual) === String(expected);
+}
+function quoteIdentifier(identifier) {
+    if (!safeIdentifier.test(identifier))
+        throw new Error(`unsafe postgres identifier: ${identifier}`);
+    return `"${identifier}"`;
+}
+function qualifiedName(schema, table) {
+    return `${quoteIdentifier(schema)}.${quoteIdentifier(table)}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/examples/mcp-postgres-billing-app-handler/synapsor.runner.json

@@ -0,0 +1,158 @@
+{
+  "version": 1,
+  "mode": "review",
+  "storage": {
+    "sqlite_path": "./tmp/billing-app-handler/local.db"
+  },
+  "sources": {
+    "billing_postgres": {
+      "engine": "postgres",
+      "read_url_env": "BILLING_APP_READ_URL",
+      "write_url_env": "BILLING_APP_WRITE_URL",
+      "statement_timeout_ms": 3000
+    }
+  },
+  "trusted_context": {
+    "provider": "environment",
+    "values": {
+      "tenant_id_env": "SYNAPSOR_TENANT_ID",
+      "principal_env": "SYNAPSOR_PRINCIPAL"
+    }
+  },
+  "contexts": {
+    "local_operator": {
+      "provider": "environment",
+      "values": {
+        "tenant_id_env": "SYNAPSOR_TENANT_ID",
+        "principal_env": "SYNAPSOR_PRINCIPAL"
+      }
+    }
+  },
+  "executors": {
+    "billing_app_handler": {
+      "type": "http_handler",
+      "url_env": "BILLING_APP_HANDLER_URL",
+      "method": "POST",
+      "auth": {
+        "type": "bearer_env",
+        "token_env": "BILLING_APP_HANDLER_TOKEN"
+      },
+      "signing_secret_env": "BILLING_APP_HANDLER_SIGNING_SECRET",
+      "timeout_ms": 5000
+    }
+  },
+  "capabilities": [
+    {
+      "name": "billing.inspect_invoice",
+      "kind": "read",
+      "source": "billing_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "late_fee_cents",
+        "waiver_reason",
+        "credit_requested_cents",
+        "credit_reason",
+        "credited_cents",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1
+    },
+    {
+      "name": "billing.propose_late_fee_waiver",
+      "kind": "proposal",
+      "source": "billing_postgres",
+      "context": "local_operator",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 },
+        "reason": { "type": "string", "required": true, "max_length": 500 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "late_fee_cents",
+        "waiver_reason",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "late_fee_cents": { "fixed": 0 },
+        "waiver_reason": { "from_arg": "reason" }
+      },
+      "allowed_columns": ["late_fee_cents", "waiver_reason"],
+      "numeric_bounds": {
+        "late_fee_cents": { "minimum": 0, "maximum": 10000 }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "billing_lead" }
+    },
+    {
+      "name": "billing.propose_account_credit",
+      "kind": "proposal",
+      "source": "billing_postgres",
+      "context": "local_operator",
+      "executor": "billing_app_handler",
+      "target": {
+        "schema": "public",
+        "table": "invoices",
+        "primary_key": "id",
+        "tenant_key": "tenant_id"
+      },
+      "args": {
+        "invoice_id": { "type": "string", "required": true, "max_length": 128 },
+        "amount_cents": { "type": "number", "required": true, "minimum": 1, "maximum": 10000 },
+        "reason": { "type": "string", "required": true, "max_length": 500 }
+      },
+      "lookup": { "id_from_arg": "invoice_id" },
+      "visible_columns": [
+        "id",
+        "tenant_id",
+        "customer_id",
+        "status",
+        "balance_cents",
+        "credited_cents",
+        "credit_requested_cents",
+        "credit_reason",
+        "updated_at"
+      ],
+      "evidence": "required",
+      "max_rows": 1,
+      "patch": {
+        "credit_requested_cents": { "from_arg": "amount_cents" },
+        "credit_reason": { "from_arg": "reason" }
+      },
+      "allowed_columns": ["credit_requested_cents", "credit_reason"],
+      "numeric_bounds": {
+        "credit_requested_cents": { "minimum": 1, "maximum": 10000 }
+      },
+      "conflict_guard": { "column": "updated_at" },
+      "approval": { "mode": "human", "required_role": "billing_lead" }
+    }
+  ]
+}

package/examples/openai-agents-http/README.md

@@ -12,6 +12,11 @@ spec-compatible HTTP MCP transport with `initialize` and session behavior. Use
 `synapsor-runner mcp serve-http` only when you intentionally want the smaller
 JSON-RPC bridge and an app-owned wrapper.
 
+OpenAI function names cannot contain dots, so start Runner with
+`--alias-mode openai`. The model sees aliases such as
+`billing__inspect_invoice`; Runner keeps `billing.inspect_invoice` in MCP
+metadata and maps calls back to the canonical Synapsor capability.
+
 The model still sees a semantic action. It does not receive raw SQL, database
 URLs, write credentials, approval tools, or commit tools.
 
@@ -26,7 +31,8 @@ export SYNAPSOR_RUNNER_HTTP_TOKEN="dev-token"
 npx -y -p @synapsor/runner@alpha synapsor-runner mcp serve-streamable-http \
   --config ./synapsor.runner.json \
   --store ./.synapsor/local.db \
-  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN
+  --auth-token-env SYNAPSOR_RUNNER_HTTP_TOKEN \
+  --alias-mode openai
 ```
 
 ## Terminal 2: Run The Agent
@@ -46,7 +52,9 @@ python agent.py
 
 Expected behavior:
 
-- the agent calls `billing.inspect_invoice` through Synapsor HTTP MCP;
+- the agent calls the OpenAI-safe alias `billing__inspect_invoice` through
+  Synapsor HTTP MCP;
+- Runner maps that alias back to canonical `billing.inspect_invoice`;
 - Synapsor applies trusted tenant/principal context from the server process;
 - the response includes scoped data and evidence handles;
 - no SQL/write/approval tool is exposed to the model;

package/examples/openai-agents-stdio/README.md

@@ -4,7 +4,10 @@ This example shows an OpenAI Agents SDK app launching Synapsor Runner as a
 local stdio MCP server.
 
 Use stdio when the agent process can start the MCP server on the same machine.
-The model sees Synapsor semantic tools such as `billing.inspect_invoice`. It
+The model sees Synapsor semantic tools through OpenAI-safe aliases such as
+`billing__inspect_invoice`. Runner keeps the canonical Synapsor capability
+name, such as `billing.inspect_invoice`, in MCP metadata and maps calls back to
+it. The model
 does not receive raw SQL, database URLs, write credentials, approval tools, or
 commit tools.
 
@@ -52,11 +55,12 @@ export SYNAPSOR_INVOICE_ID="INV-3001"
 
 Expected behavior:
 
-- the agent can inspect the scoped invoice through Synapsor;
+- the agent can inspect the scoped invoice through Synapsor using an
+  OpenAI-safe tool alias;
+- Runner maps the alias back to the canonical Synapsor capability;
 - the agent cannot run SQL;
 - the agent cannot approve or commit writes;
 - evidence/query audit are saved in the local Runner store.
 
 If your installed OpenAI Agents SDK does not expose `MCPServerStdio`, update the
-SDK or use the HTTP example, which wraps Synapsor HTTP MCP with a small JSON-RPC
-client.
+SDK or use the Streamable HTTP example.

package/examples/openai-agents-stdio/agent.py

@@ -35,6 +35,8 @@ async def main() -> None:
             config_path,
             "--store",
             store_path,
+            "--alias-mode",
+            "openai",
         ],
         "env": {
             **os.environ,