tina4-nodejs 3.13.146 → 3.13.148

package/CLAUDE.md

@@ -13,13 +13,13 @@ Even if the skill text is not currently loaded, these are non-negotiable:
 
 The full discipline lives in `.claude/skills/tina4-maintainer/SKILL.md`; this block is the always-on floor.
 
-# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.146)
+# CLAUDE.md - AI Developer Guide for tina4-nodejs (v3.13.148)
 
 > This file helps AI assistants (Claude, Copilot, Cursor, etc.) understand and work on this codebase effectively.
 
 ## What This Project Is
 
-Tina4 for Node.js/TypeScript v3.13.146 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
+Tina4 for Node.js/TypeScript v3.13.148 - The Intelligent Native Application 4ramework. A convention-over-configuration structural paradigm. The developer writes TypeScript; Tina4 is invisible infrastructure.
 
 The philosophy: zero ceremony, batteries included, file system as source of truth.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tina4-nodejs",
-  "version": "3.13.146",
+  "version": "3.13.148",
   "type": "module",
   "description": "Tina4 for Node.js/TypeScript - native TypeScript conventions and shared Tina4 contracts",
   "keywords": [

package/packages/cli/dist/bin.js

@@ -16940,6 +16940,7 @@ var init_router = __esm({
               path: route.pattern,
               handler: route.filePath ?? (route.handler.name || "(anonymous)"),
               middlewareCount: route.middlewares?.length ?? 0,
+              middleware: (route.middlewares ?? []).map((attached) => typeof attached === "string" ? attached : attached?.name || attached?.constructor?.name || "(anonymous)"),
               cached: route.cached ?? false,
               secure: route.secure ?? false
             });
@@ -23877,6 +23878,7 @@ __export(session_exports, {
   isSecureScheme: () => isSecureScheme,
   isValidSessionId: () => isValidSessionId,
   sessionCookieName: () => sessionCookieName,
+  sessionCookieToSend: () => sessionCookieToSend,
   sessionStrictMode: () => sessionStrictMode
 });
 import { createHash as createHash5, randomBytes as randomBytes6 } from "node:crypto";
@@ -23937,6 +23939,15 @@ function buildSessionCookie(sessionId, ttl, cookieName, forwardedProto, socketEn
   parts.push(`Max-Age=${ttl}`);
   return parts.join("; ");
 }
+function sessionCookieToSend(sess, existingSid, rawReq, rawRes) {
+  const newSid = sess.sessionId ?? sess.getSessionId?.();
+  if (!newSid || newSid === existingSid || sess.isFresh() || rawRes.headersSent) return null;
+  const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
+  const xfProto = rawReq.headers["x-forwarded-proto"];
+  const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
+  const socketEncrypted = rawReq.socket?.encrypted === true;
+  return buildSessionCookie(newSid, ttl, void 0, forwardedProto, socketEncrypted);
+}
 var SESSION_ID_PATTERN, VALID_SESSION_BACKENDS, CANONICAL_SESSION_BACKENDS, RETIRED_SESSION_BACKENDS, FileSessionHandler, RedisSessionHandler, FLASH_PREFIX, Session;
 var init_session = __esm({
   "../core/src/session.ts"() {
@@ -24299,7 +24310,6 @@ var init_session = __esm({
         const now = Math.floor(Date.now() / 1e3);
         this.data = { _created: now, _accessed: now };
         this.dirty = false;
-        this.safeWrite(this.sessionId, this.data, this.ttl);
         this.stored = false;
         this.loaded = /* @__PURE__ */ new Map();
         this.cleared = false;
@@ -24450,6 +24460,19 @@ var init_session = __esm({
         const result = this.flash(key);
         return result !== void 0 ? result : defaultValue;
       }
+      /**
+       * Whether this session is only an id: nothing has stored it and it holds no
+       * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+       * Such a session has no record and needs no cookie, so save() writes nothing
+       * for it and the server sends no cookie for it. It stops being fresh when
+       * something is stored in it. Calls that mark a session changed without leaving
+       * anything in it (deleting a key it never had, clear(), regenerate() on an
+       * empty session) leave it fresh: a record with no data is not a session.
+       */
+      isFresh() {
+        if (this.stored) return false;
+        return !this.data || Object.keys(this.data).every((k) => k === "_created" || k === "_accessed");
+      }
       /**
        * Get the current session ID.
        */
@@ -24512,7 +24535,7 @@ var init_session = __esm({
        */
       save() {
         if (!this.sessionId || !this.data) return true;
-        if (!this.dirty && !this.stored) return true;
+        if (this.isFresh()) return true;
         let record = this.data;
         if (this.stored) {
           const current = this.safeRead(this.sessionId);
@@ -24699,7 +24722,7 @@ function errorLabel(err) {
   return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
 }
 async function sessionAutoStart(rawReq, rawRes, req2) {
-  const { Session: Session2, buildSessionCookie: buildSessionCookie2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
+  const { Session: Session2, sessionCookieToSend: sessionCookieToSend2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
   const cookieHeader = rawReq.headers.cookie ?? "";
   const cookiePrefix = sessionCookieName2() + "=";
   let existingSid;
@@ -24738,13 +24761,9 @@ async function sessionAutoStart(rawReq, rawRes, req2) {
       } catch {
       }
     }
-    const newSid = sess.sessionId ?? sess.getSessionId?.();
-    if (newSid && newSid !== existingSid && !rawRes.headersSent) {
-      const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-      const xfProto = rawReq.headers["x-forwarded-proto"];
-      const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
-      const socketEncrypted = rawReq.socket?.encrypted === true;
-      rawRes.appendHeader("Set-Cookie", buildSessionCookie2(newSid, ttl, void 0, forwardedProto, socketEncrypted));
+    const sessionCookie = sessionCookieToSend2(sess, existingSid, rawReq, rawRes);
+    if (sessionCookie !== null) {
+      rawRes.appendHeader("Set-Cookie", sessionCookie);
     }
     return origEnd(...args);
   };
@@ -27924,7 +27943,8 @@ __export(mcp_exports, {
   mcpTool: () => mcpTool,
   register: () => register,
   registerDevTools: () => registerDevTools,
-  schemaFromParams: () => schemaFromParams
+  schemaFromParams: () => schemaFromParams,
+  validateToolArguments: () => validateToolArguments
 });
 import * as fs4 from "node:fs";
 import * as path3 from "node:path";
@@ -27996,6 +28016,27 @@ function schemaFromParams(params) {
   }
   return schema;
 }
+function validateToolArguments(toolName, schema, args) {
+  const properties = Object.keys(schema.properties ?? {});
+  const takes = properties.length > 0 ? properties.join(", ") : "no arguments";
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    return `arguments must be an object (${toolName} takes ${takes})`;
+  }
+  const supplied = args;
+  for (const requiredName of schema.required ?? []) {
+    if (!(requiredName in supplied)) {
+      return `missing required argument '${requiredName}' (${toolName} takes ${takes})`;
+    }
+  }
+  if (!schema.additionalProperties) {
+    for (const suppliedName of Object.keys(supplied)) {
+      if (!properties.includes(suppliedName)) {
+        return `unknown argument '${suppliedName}' (${toolName} takes ${takes})`;
+      }
+    }
+  }
+  return null;
+}
 function isLocalhost() {
   const hostEnv = process.env.TINA4_HOST_NAME || "localhost:7148";
   const host = hostEnv.split(":")[0];
@@ -28294,7 +28335,12 @@ function registerDevTools(server) {
         if (!/^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/.test(table2)) {
           return { error: "Invalid table name" };
         }
-        return await db.getColumns?.(table2) ?? [];
+        const columns = await db.getColumns?.(table2) ?? [];
+        if (columns.length === 0) {
+          const tables = await db.getTables?.() ?? [];
+          if (!tables.includes(table2)) return { error: `table not found: ${table2}` };
+        }
+        return columns;
       } catch (e) {
         return { error: e.message };
       }
@@ -28313,7 +28359,8 @@ function registerDevTools(server) {
         return routes.map((r) => ({
           method: r.method || "",
           path: r.pattern || r.path || "",
-          auth_required: r.secure ?? false
+          auth_required: r.secure ?? false,
+          middleware: r.middleware ?? []
         }));
       } catch (e) {
         return { error: e.message };
@@ -29459,6 +29506,10 @@ data: ${channel.buffer.shift()}
           throw new Error(`Unknown tool: ${toolName}`);
         }
         const args = params.arguments || {};
+        const invalid = validateToolArguments(toolName, tool.inputSchema, args);
+        if (invalid) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: invalid }, null, 2) }] };
+        }
         const result = await tool.handler(args);
         let content;
         if (typeof result === "string") {
@@ -35497,7 +35548,9 @@ var init_docsParser = __esm({
 // ../core/src/docs.ts
 var docs_exports = {};
 __export(docs_exports, {
-  Docs: () => Docs
+  Docs: () => Docs,
+  paramsFromSignature: () => paramsFromSignature,
+  returnFromSignature: () => returnFromSignature
 });
 import * as fs8 from "node:fs";
 import * as path8 from "node:path";
@@ -35724,6 +35777,54 @@ function scoreFqn(entry, tokens) {
   }
   return score;
 }
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if ("<([{".includes(ch)) depth++;
+    else if (">)]}".includes(ch)) depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else current += ch;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+function closingParen(signature, open) {
+  let depth = 0;
+  for (let i = open; i < signature.length; i++) {
+    if (signature[i] === "(") depth++;
+    else if (signature[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+function paramsFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return [];
+  return splitTopLevel(signature.slice(open + 1, close)).map((raw) => {
+    const [declaration, ...defaultParts] = raw.split(/=(?!>)/);
+    const defaultText = defaultParts.length > 0 ? defaultParts.join("=").trim() : null;
+    const colon = declaration.indexOf(":");
+    const head = (colon < 0 ? declaration : declaration.slice(0, colon)).trim();
+    const optional = head.endsWith("?");
+    return {
+      name: head.replace(/\?$/, ""),
+      type: colon < 0 ? "" : declaration.slice(colon + 1).trim(),
+      required: !optional && defaultText === null && !head.startsWith("..."),
+      default: defaultText
+    };
+  });
+}
+function returnFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return "";
+  const rest = signature.slice(close + 1).trim();
+  return rest.startsWith(":") ? rest.slice(1).trim() : "";
+}
 var STDLIB_ALLOWLIST, _DOCS_CACHE, __FILENAME, __DIRNAME, USER_DIRS, CAMEL_SPLIT, FENCE_RE, CALL_RE, sharedFrameworkIndex, Docs;
 var init_docs = __esm({
   "../core/src/docs.ts"() {
@@ -36029,8 +36130,8 @@ var init_docs = __esm({
           static: entry.static ?? false,
           source: entry.source,
           version: entry.version,
-          params: [],
-          return: ""
+          params: paramsFromSignature(entry.signature),
+          return: returnFromSignature(entry.signature)
         };
       }
       /**

package/packages/core/dist/index.js

@@ -16939,6 +16939,7 @@ var init_router = __esm({
               path: route.pattern,
               handler: route.filePath ?? (route.handler.name || "(anonymous)"),
               middlewareCount: route.middlewares?.length ?? 0,
+              middleware: (route.middlewares ?? []).map((attached) => typeof attached === "string" ? attached : attached?.name || attached?.constructor?.name || "(anonymous)"),
               cached: route.cached ?? false,
               secure: route.secure ?? false
             });
@@ -23856,6 +23857,7 @@ __export(session_exports, {
   isSecureScheme: () => isSecureScheme,
   isValidSessionId: () => isValidSessionId,
   sessionCookieName: () => sessionCookieName,
+  sessionCookieToSend: () => sessionCookieToSend,
   sessionStrictMode: () => sessionStrictMode
 });
 import { createHash as createHash5, randomBytes as randomBytes6 } from "node:crypto";
@@ -23916,6 +23918,15 @@ function buildSessionCookie(sessionId, ttl, cookieName, forwardedProto, socketEn
   parts.push(`Max-Age=${ttl}`);
   return parts.join("; ");
 }
+function sessionCookieToSend(sess, existingSid, rawReq, rawRes) {
+  const newSid = sess.sessionId ?? sess.getSessionId?.();
+  if (!newSid || newSid === existingSid || sess.isFresh() || rawRes.headersSent) return null;
+  const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
+  const xfProto = rawReq.headers["x-forwarded-proto"];
+  const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
+  const socketEncrypted = rawReq.socket?.encrypted === true;
+  return buildSessionCookie(newSid, ttl, void 0, forwardedProto, socketEncrypted);
+}
 var SESSION_ID_PATTERN, VALID_SESSION_BACKENDS, CANONICAL_SESSION_BACKENDS, RETIRED_SESSION_BACKENDS, FileSessionHandler, RedisSessionHandler, FLASH_PREFIX, Session;
 var init_session = __esm({
   "src/session.ts"() {
@@ -24278,7 +24289,6 @@ var init_session = __esm({
         const now = Math.floor(Date.now() / 1e3);
         this.data = { _created: now, _accessed: now };
         this.dirty = false;
-        this.safeWrite(this.sessionId, this.data, this.ttl);
         this.stored = false;
         this.loaded = /* @__PURE__ */ new Map();
         this.cleared = false;
@@ -24429,6 +24439,19 @@ var init_session = __esm({
         const result = this.flash(key);
         return result !== void 0 ? result : defaultValue;
       }
+      /**
+       * Whether this session is only an id: nothing has stored it and it holds no
+       * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+       * Such a session has no record and needs no cookie, so save() writes nothing
+       * for it and the server sends no cookie for it. It stops being fresh when
+       * something is stored in it. Calls that mark a session changed without leaving
+       * anything in it (deleting a key it never had, clear(), regenerate() on an
+       * empty session) leave it fresh: a record with no data is not a session.
+       */
+      isFresh() {
+        if (this.stored) return false;
+        return !this.data || Object.keys(this.data).every((k) => k === "_created" || k === "_accessed");
+      }
       /**
        * Get the current session ID.
        */
@@ -24491,7 +24514,7 @@ var init_session = __esm({
        */
       save() {
         if (!this.sessionId || !this.data) return true;
-        if (!this.dirty && !this.stored) return true;
+        if (this.isFresh()) return true;
         let record = this.data;
         if (this.stored) {
           const current = this.safeRead(this.sessionId);
@@ -24678,7 +24701,7 @@ function errorLabel(err) {
   return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
 }
 async function sessionAutoStart(rawReq, rawRes, req2) {
-  const { Session: Session2, buildSessionCookie: buildSessionCookie2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
+  const { Session: Session2, sessionCookieToSend: sessionCookieToSend2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
   const cookieHeader = rawReq.headers.cookie ?? "";
   const cookiePrefix = sessionCookieName2() + "=";
   let existingSid;
@@ -24717,13 +24740,9 @@ async function sessionAutoStart(rawReq, rawRes, req2) {
       } catch {
       }
     }
-    const newSid = sess.sessionId ?? sess.getSessionId?.();
-    if (newSid && newSid !== existingSid && !rawRes.headersSent) {
-      const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-      const xfProto = rawReq.headers["x-forwarded-proto"];
-      const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
-      const socketEncrypted = rawReq.socket?.encrypted === true;
-      rawRes.appendHeader("Set-Cookie", buildSessionCookie2(newSid, ttl, void 0, forwardedProto, socketEncrypted));
+    const sessionCookie = sessionCookieToSend2(sess, existingSid, rawReq, rawRes);
+    if (sessionCookie !== null) {
+      rawRes.appendHeader("Set-Cookie", sessionCookie);
     }
     return origEnd(...args);
   };
@@ -27880,7 +27899,8 @@ __export(mcp_exports, {
   mcpTool: () => mcpTool,
   register: () => register,
   registerDevTools: () => registerDevTools,
-  schemaFromParams: () => schemaFromParams
+  schemaFromParams: () => schemaFromParams,
+  validateToolArguments: () => validateToolArguments
 });
 import * as fs4 from "node:fs";
 import * as path3 from "node:path";
@@ -27952,6 +27972,27 @@ function schemaFromParams(params) {
   }
   return schema;
 }
+function validateToolArguments(toolName, schema, args) {
+  const properties = Object.keys(schema.properties ?? {});
+  const takes = properties.length > 0 ? properties.join(", ") : "no arguments";
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    return `arguments must be an object (${toolName} takes ${takes})`;
+  }
+  const supplied = args;
+  for (const requiredName of schema.required ?? []) {
+    if (!(requiredName in supplied)) {
+      return `missing required argument '${requiredName}' (${toolName} takes ${takes})`;
+    }
+  }
+  if (!schema.additionalProperties) {
+    for (const suppliedName of Object.keys(supplied)) {
+      if (!properties.includes(suppliedName)) {
+        return `unknown argument '${suppliedName}' (${toolName} takes ${takes})`;
+      }
+    }
+  }
+  return null;
+}
 function isLocalhost() {
   const hostEnv = process.env.TINA4_HOST_NAME || "localhost:7148";
   const host = hostEnv.split(":")[0];
@@ -28250,7 +28291,12 @@ function registerDevTools(server) {
         if (!/^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/.test(table2)) {
           return { error: "Invalid table name" };
         }
-        return await db.getColumns?.(table2) ?? [];
+        const columns = await db.getColumns?.(table2) ?? [];
+        if (columns.length === 0) {
+          const tables = await db.getTables?.() ?? [];
+          if (!tables.includes(table2)) return { error: `table not found: ${table2}` };
+        }
+        return columns;
       } catch (e) {
         return { error: e.message };
       }
@@ -28269,7 +28315,8 @@ function registerDevTools(server) {
         return routes.map((r) => ({
           method: r.method || "",
           path: r.pattern || r.path || "",
-          auth_required: r.secure ?? false
+          auth_required: r.secure ?? false,
+          middleware: r.middleware ?? []
         }));
       } catch (e) {
         return { error: e.message };
@@ -29415,6 +29462,10 @@ data: ${channel.buffer.shift()}
           throw new Error(`Unknown tool: ${toolName}`);
         }
         const args = params.arguments || {};
+        const invalid = validateToolArguments(toolName, tool.inputSchema, args);
+        if (invalid) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: invalid }, null, 2) }] };
+        }
         const result = await tool.handler(args);
         let content;
         if (typeof result === "string") {
@@ -35453,7 +35504,9 @@ var init_docsParser = __esm({
 // src/docs.ts
 var docs_exports = {};
 __export(docs_exports, {
-  Docs: () => Docs
+  Docs: () => Docs,
+  paramsFromSignature: () => paramsFromSignature,
+  returnFromSignature: () => returnFromSignature
 });
 import * as fs8 from "node:fs";
 import * as path8 from "node:path";
@@ -35680,6 +35733,54 @@ function scoreFqn(entry, tokens) {
   }
   return score;
 }
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if ("<([{".includes(ch)) depth++;
+    else if (">)]}".includes(ch)) depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else current += ch;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+function closingParen(signature, open) {
+  let depth = 0;
+  for (let i = open; i < signature.length; i++) {
+    if (signature[i] === "(") depth++;
+    else if (signature[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+function paramsFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return [];
+  return splitTopLevel(signature.slice(open + 1, close)).map((raw) => {
+    const [declaration, ...defaultParts] = raw.split(/=(?!>)/);
+    const defaultText = defaultParts.length > 0 ? defaultParts.join("=").trim() : null;
+    const colon = declaration.indexOf(":");
+    const head = (colon < 0 ? declaration : declaration.slice(0, colon)).trim();
+    const optional = head.endsWith("?");
+    return {
+      name: head.replace(/\?$/, ""),
+      type: colon < 0 ? "" : declaration.slice(colon + 1).trim(),
+      required: !optional && defaultText === null && !head.startsWith("..."),
+      default: defaultText
+    };
+  });
+}
+function returnFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return "";
+  const rest = signature.slice(close + 1).trim();
+  return rest.startsWith(":") ? rest.slice(1).trim() : "";
+}
 var STDLIB_ALLOWLIST, _DOCS_CACHE, __FILENAME, __DIRNAME, USER_DIRS, CAMEL_SPLIT, FENCE_RE, CALL_RE, sharedFrameworkIndex, Docs;
 var init_docs = __esm({
   "src/docs.ts"() {
@@ -35985,8 +36086,8 @@ var init_docs = __esm({
           static: entry.static ?? false,
           source: entry.source,
           version: entry.version,
-          params: [],
-          return: ""
+          params: paramsFromSignature(entry.signature),
+          return: returnFromSignature(entry.signature)
         };
       }
       /**

package/packages/core/src/dispatchPipeline.ts

@@ -367,7 +367,7 @@ export async function sessionAutoStart(
   rawRes: ServerResponse,
   req: Tina4Request,
 ): Promise<void> {
-  const { Session, buildSessionCookie, sessionCookieName, sessionStrictMode } =
+  const { Session, sessionCookieToSend, sessionCookieName, sessionStrictMode } =
     await import("./session.js");
   const cookieHeader = rawReq.headers.cookie ?? "";
 
@@ -433,16 +433,8 @@ export async function sessionAutoStart(
       try { sess.gc(); } catch { /* GC failure is non-critical */ }
     }
 
-    const newSid = (sess as any).sessionId ?? (sess as any).getSessionId?.();
-    if (newSid && newSid !== existingSid && !rawRes.headersSent) {
-      const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-      // Thread the client's real scheme in so an HTTPS deploy behind a
-      // TLS-terminating proxy ships the session cookie with `Secure`
-      // (nodejs#34). `x-forwarded-proto` is the same header request.ts trusts
-      // for URL construction; native socket TLS is the fallback.
-      const xfProto = rawReq.headers["x-forwarded-proto"];
-      const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
-      const socketEncrypted = (rawReq.socket as { encrypted?: boolean })?.encrypted === true;
+    const sessionCookie = sessionCookieToSend(sess, existingSid, rawReq, rawRes);
+    if (sessionCookie !== null) {
       // appendHeader, not setHeader (feature 131 fix, found while proving
       // TC-DEC-02): setHeader REPLACES any existing Set-Cookie value wholesale,
       // so a route that had already called response.cookie() of its own — on
@@ -452,7 +444,7 @@ export async function sessionAutoStart(
       // appendHeader adds to whatever is already there (promoting a scalar to
       // an array, extending an existing array) and behaves exactly like
       // setHeader when nothing is set yet, so the common case is unchanged.
-      rawRes.appendHeader("Set-Cookie", buildSessionCookie(newSid, ttl, undefined, forwardedProto, socketEncrypted));
+      rawRes.appendHeader("Set-Cookie", sessionCookie);
     }
     return origEnd(...args);
   } as typeof rawRes.end;

package/packages/core/src/docs.ts

@@ -61,7 +61,7 @@ export interface MethodSpec {
   static: boolean;
   source: "framework" | "user" | "vendor";
   version: string;
-  params: Array<{ name: string; type: string; default?: string | null }>;
+  params: Array<{ name: string; type: string; required: boolean; default: string | null }>;
   return: string;
 }
 
@@ -448,6 +448,59 @@ function scoreFqn(entry: InternalEntry, tokens: string[]): number {
  */
 const sharedFrameworkIndex = new Map<string, { entries: Map<string, InternalEntry>; mtime: number }>();
 
+/** Split `text` on top-level commas, ignoring commas nested in <>, (), [] or {}. */
+function splitTopLevel(text: string): string[] {
+  const parts: string[] = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if ("<([{".includes(ch)) depth++;
+    else if (">)]}".includes(ch)) depth--;
+    if (ch === "," && depth === 0) { parts.push(current); current = ""; } else current += ch;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+
+/** Index of the `)` closing the parameter list that opens at `open`, or -1. */
+function closingParen(signature: string, open: number): number {
+  let depth = 0;
+  for (let i = open; i < signature.length; i++) {
+    if (signature[i] === "(") depth++;
+    else if (signature[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+
+/** Structured params `[{name, type, required, default}]` from `name(a: T, b?: U = 1) : R`. */
+export function paramsFromSignature(signature: string): MethodSpec["params"] {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return [];
+  return splitTopLevel(signature.slice(open + 1, close)).map((raw) => {
+    const [declaration, ...defaultParts] = raw.split(/=(?!>)/);
+    const defaultText = defaultParts.length > 0 ? defaultParts.join("=").trim() : null;
+    const colon = declaration.indexOf(":");
+    const head = (colon < 0 ? declaration : declaration.slice(0, colon)).trim();
+    const optional = head.endsWith("?");
+    return {
+      name: head.replace(/\?$/, ""),
+      type: colon < 0 ? "" : declaration.slice(colon + 1).trim(),
+      required: !optional && defaultText === null && !head.startsWith("..."),
+      default: defaultText,
+    };
+  });
+}
+
+/** Return type text from `name(...) : R` (or `): R`), "" when absent. */
+export function returnFromSignature(signature: string): string {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return "";
+  const rest = signature.slice(close + 1).trim();
+  return rest.startsWith(":") ? rest.slice(1).trim() : "";
+}
+
 export class Docs {
   private projectRoot: string;
   private frameworkRoots: string[];
@@ -622,8 +675,8 @@ export class Docs {
       static: entry.static ?? false,
       source: entry.source,
       version: entry.version,
-      params: [],
-      return: "",
+      params: paramsFromSignature(entry.signature),
+      return: returnFromSignature(entry.signature),
     };
   }
 

package/packages/core/src/mcp.ts

@@ -91,6 +91,7 @@ export interface JsonSchema {
   type: string;
   properties: Record<string, { type: string; default?: unknown }>;
   required?: string[];
+  additionalProperties?: boolean;
 }
 
 export interface McpToolParam {
@@ -203,6 +204,36 @@ export function schemaFromParams(params: McpToolParam[]): JsonSchema {
   return schema;
 }
 
+/**
+ * Check call arguments against a tool's input schema BEFORE the handler runs.
+ * Returns null when valid, else the actionable message
+ * `missing required argument '<p>' (<tool> takes <p1>, <p2>)` (or
+ * `unknown argument '<k>' (...)`). Byte-identical to tina4-python's
+ * `_validate_tool_arguments` (tina4-php#271) so a wrong key never surfaces as a
+ * raw TypeError / 500.
+ */
+export function validateToolArguments(toolName: string, schema: JsonSchema, args: unknown): string | null {
+  const properties = Object.keys(schema.properties ?? {});
+  const takes = properties.length > 0 ? properties.join(", ") : "no arguments";
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    return `arguments must be an object (${toolName} takes ${takes})`;
+  }
+  const supplied = args as Record<string, unknown>;
+  for (const requiredName of schema.required ?? []) {
+    if (!(requiredName in supplied)) {
+      return `missing required argument '${requiredName}' (${toolName} takes ${takes})`;
+    }
+  }
+  if (!schema.additionalProperties) {
+    for (const suppliedName of Object.keys(supplied)) {
+      if (!properties.includes(suppliedName)) {
+        return `unknown argument '${suppliedName}' (${toolName} takes ${takes})`;
+      }
+    }
+  }
+  return null;
+}
+
 // ── Localhost detection ──────────────────────────────────────
 
 /**
@@ -574,6 +605,10 @@ export class McpServer {
     }
 
     const args = (params.arguments as Record<string, unknown>) || {};
+    const invalid = validateToolArguments(toolName, tool.inputSchema, args);
+    if (invalid) {
+      return { content: [{ type: "text", text: JSON.stringify({ error: invalid }, null, 2) }] };
+    }
     // Tool handlers may be async (the DB tools await the Database wrapper); a
     // sync handler's plain return value passes through `await` unchanged.
     const result = await tool.handler(args);
@@ -1139,7 +1174,14 @@ export function registerDevTools(server: McpServer): void {
         if (!/^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/.test(table)) {
           return { error: "Invalid table name" };
         }
-        return (await db.getColumns?.(table)) ?? [];
+        // Schema metadata (PRAGMA / information_schema via the adapter), never the
+        // first row, so an EMPTY table still reports its columns (tina4-php#271).
+        const columns = (await db.getColumns?.(table)) ?? [];
+        if (columns.length === 0) {
+          const tables = ((await db.getTables?.()) ?? []) as string[];
+          if (!tables.includes(table)) return { error: `table not found: ${table}` };
+        }
+        return columns;
       } catch (e) {
         return { error: (e as Error).message };
       }
@@ -1168,6 +1210,7 @@ export function registerDevTools(server: McpServer): void {
           method: r.method || "",
           path: r.pattern || r.path || "",
           auth_required: r.secure ?? false,
+          middleware: r.middleware ?? [],
         }));
       } catch (e) {
         return { error: (e as Error).message };

package/packages/core/src/router.ts

@@ -187,6 +187,8 @@ export interface RouteInfo {
   path: string;
   handler: string;
   middlewareCount: number;
+  /** Names of the middleware attached to the route (functions / classes / string specs). */
+  middleware: string[];
   cached: boolean;
   secure: boolean;
 }
@@ -486,6 +488,8 @@ export class Router {
           path: route.pattern,
           handler: route.filePath ?? (route.handler.name || "(anonymous)"),
           middlewareCount: route.middlewares?.length ?? 0,
+          middleware: (route.middlewares ?? []).map((attached: any) =>
+            typeof attached === "string" ? attached : (attached?.name || attached?.constructor?.name || "(anonymous)")),
           cached: route.cached ?? false,
           secure: route.secure ?? false,
         });

package/packages/core/src/session.ts

@@ -610,12 +610,14 @@ export class Session {
       }
     }
 
-    // Generate new session
+    // Generate new session. Nothing is written for it yet: a session nobody
+    // writes to has nothing to keep, and writing it here stored one record for
+    // every request that arrived without a cookie (static files, 404s and
+    // /health included). Its first save() after a change writes it whole.
     this.sessionId = randomBytes(16).toString("hex");
     const now = Math.floor(Date.now() / 1000);
     this.data = { _created: now, _accessed: now };
     this.dirty = false;
-    this.safeWrite(this.sessionId, this.data, this.ttl);
     this.stored = false;
     this.loaded = new Map();
     this.cleared = false;
@@ -785,6 +787,20 @@ export class Session {
     return result !== undefined ? result : defaultValue;
   }
 
+  /**
+   * Whether this session is only an id: nothing has stored it and it holds no
+   * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+   * Such a session has no record and needs no cookie, so save() writes nothing
+   * for it and the server sends no cookie for it. It stops being fresh when
+   * something is stored in it. Calls that mark a session changed without leaving
+   * anything in it (deleting a key it never had, clear(), regenerate() on an
+   * empty session) leave it fresh: a record with no data is not a session.
+   */
+  isFresh(): boolean {
+    if (this.stored) return false;
+    return !this.data || Object.keys(this.data).every((k) => k === "_created" || k === "_accessed");
+  }
+
   /**
    * Get the current session ID.
    */
@@ -850,7 +866,7 @@ export class Session {
    */
   save(): boolean {
     if (!this.sessionId || !this.data) return true;
-    if (!this.dirty && !this.stored) return true;
+    if (this.isFresh()) return true;
     let record: SessionData = this.data;
     if (this.stored) {
       const current = this.safeRead(this.sessionId);
@@ -1018,3 +1034,29 @@ export function buildSessionCookie(
   parts.push(`Max-Age=${ttl}`);
   return parts.join("; ");
 }
+
+/**
+ * The Set-Cookie value that hands the client this request's session, or null
+ * when none is owed: the client already holds the id, headers have gone out, or
+ * the session is fresh. A fresh session (only an id: minted for this request
+ * and holding no data) was not stored, so a cookie for it would name nothing:
+ * the next request could not resume it and would be handed another one.
+ */
+export function sessionCookieToSend(
+  sess: { isFresh(): boolean },
+  existingSid: string | undefined,
+  rawReq: { headers: Record<string, string | string[] | undefined>; socket?: unknown },
+  rawRes: { headersSent: boolean },
+): string | null {
+  const newSid = (sess as any).sessionId ?? (sess as any).getSessionId?.();
+  if (!newSid || newSid === existingSid || sess.isFresh() || rawRes.headersSent) return null;
+  const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
+  // Thread the client's real scheme in so an HTTPS deploy behind a
+  // TLS-terminating proxy ships the session cookie with `Secure`
+  // (nodejs#34). `x-forwarded-proto` is the same header request.ts trusts
+  // for URL construction; native socket TLS is the fallback.
+  const xfProto = rawReq.headers["x-forwarded-proto"];
+  const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
+  const socketEncrypted = (rawReq.socket as { encrypted?: boolean } | undefined)?.encrypted === true;
+  return buildSessionCookie(newSid, ttl, undefined, forwardedProto, socketEncrypted);
+}

package/packages/orm/dist/index.js

@@ -4915,6 +4915,7 @@ var init_router = __esm({
               path: route.pattern,
               handler: route.filePath ?? (route.handler.name || "(anonymous)"),
               middlewareCount: route.middlewares?.length ?? 0,
+              middleware: (route.middlewares ?? []).map((attached) => typeof attached === "string" ? attached : attached?.name || attached?.constructor?.name || "(anonymous)"),
               cached: route.cached ?? false,
               secure: route.secure ?? false
             });
@@ -11832,6 +11833,7 @@ __export(session_exports, {
   isSecureScheme: () => isSecureScheme,
   isValidSessionId: () => isValidSessionId,
   sessionCookieName: () => sessionCookieName,
+  sessionCookieToSend: () => sessionCookieToSend,
   sessionStrictMode: () => sessionStrictMode
 });
 import { createHash as createHash5, randomBytes as randomBytes4 } from "node:crypto";
@@ -11892,6 +11894,15 @@ function buildSessionCookie(sessionId, ttl, cookieName, forwardedProto, socketEn
   parts.push(`Max-Age=${ttl}`);
   return parts.join("; ");
 }
+function sessionCookieToSend(sess, existingSid, rawReq, rawRes) {
+  const newSid = sess.sessionId ?? sess.getSessionId?.();
+  if (!newSid || newSid === existingSid || sess.isFresh() || rawRes.headersSent) return null;
+  const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
+  const xfProto = rawReq.headers["x-forwarded-proto"];
+  const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
+  const socketEncrypted = rawReq.socket?.encrypted === true;
+  return buildSessionCookie(newSid, ttl, void 0, forwardedProto, socketEncrypted);
+}
 var SESSION_ID_PATTERN, VALID_SESSION_BACKENDS, CANONICAL_SESSION_BACKENDS, RETIRED_SESSION_BACKENDS, FileSessionHandler, RedisSessionHandler, FLASH_PREFIX, Session;
 var init_session = __esm({
   "../core/src/session.ts"() {
@@ -12254,7 +12265,6 @@ var init_session = __esm({
         const now = Math.floor(Date.now() / 1e3);
         this.data = { _created: now, _accessed: now };
         this.dirty = false;
-        this.safeWrite(this.sessionId, this.data, this.ttl);
         this.stored = false;
         this.loaded = /* @__PURE__ */ new Map();
         this.cleared = false;
@@ -12405,6 +12415,19 @@ var init_session = __esm({
         const result = this.flash(key);
         return result !== void 0 ? result : defaultValue;
       }
+      /**
+       * Whether this session is only an id: nothing has stored it and it holds no
+       * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+       * Such a session has no record and needs no cookie, so save() writes nothing
+       * for it and the server sends no cookie for it. It stops being fresh when
+       * something is stored in it. Calls that mark a session changed without leaving
+       * anything in it (deleting a key it never had, clear(), regenerate() on an
+       * empty session) leave it fresh: a record with no data is not a session.
+       */
+      isFresh() {
+        if (this.stored) return false;
+        return !this.data || Object.keys(this.data).every((k) => k === "_created" || k === "_accessed");
+      }
       /**
        * Get the current session ID.
        */
@@ -12467,7 +12490,7 @@ var init_session = __esm({
        */
       save() {
         if (!this.sessionId || !this.data) return true;
-        if (!this.dirty && !this.stored) return true;
+        if (this.isFresh()) return true;
         let record = this.data;
         if (this.stored) {
           const current = this.safeRead(this.sessionId);
@@ -12654,7 +12677,7 @@ function errorLabel(err) {
   return err instanceof Error ? `${err.name}: ${err.message}` : String(err);
 }
 async function sessionAutoStart(rawReq, rawRes, req2) {
-  const { Session: Session2, buildSessionCookie: buildSessionCookie2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
+  const { Session: Session2, sessionCookieToSend: sessionCookieToSend2, sessionCookieName: sessionCookieName2, sessionStrictMode: sessionStrictMode2 } = await Promise.resolve().then(() => (init_session(), session_exports));
   const cookieHeader = rawReq.headers.cookie ?? "";
   const cookiePrefix = sessionCookieName2() + "=";
   let existingSid;
@@ -12693,13 +12716,9 @@ async function sessionAutoStart(rawReq, rawRes, req2) {
       } catch {
       }
     }
-    const newSid = sess.sessionId ?? sess.getSessionId?.();
-    if (newSid && newSid !== existingSid && !rawRes.headersSent) {
-      const ttl = parseInt(process.env.TINA4_SESSION_TTL ?? "3600", 10);
-      const xfProto = rawReq.headers["x-forwarded-proto"];
-      const forwardedProto = Array.isArray(xfProto) ? xfProto[0] : xfProto;
-      const socketEncrypted = rawReq.socket?.encrypted === true;
-      rawRes.appendHeader("Set-Cookie", buildSessionCookie2(newSid, ttl, void 0, forwardedProto, socketEncrypted));
+    const sessionCookie = sessionCookieToSend2(sess, existingSid, rawReq, rawRes);
+    if (sessionCookie !== null) {
+      rawRes.appendHeader("Set-Cookie", sessionCookie);
     }
     return origEnd(...args);
   };
@@ -15856,7 +15875,8 @@ __export(mcp_exports, {
   mcpTool: () => mcpTool,
   register: () => register,
   registerDevTools: () => registerDevTools,
-  schemaFromParams: () => schemaFromParams
+  schemaFromParams: () => schemaFromParams,
+  validateToolArguments: () => validateToolArguments
 });
 import * as fs4 from "node:fs";
 import * as path3 from "node:path";
@@ -15928,6 +15948,27 @@ function schemaFromParams(params) {
   }
   return schema;
 }
+function validateToolArguments(toolName, schema, args) {
+  const properties = Object.keys(schema.properties ?? {});
+  const takes = properties.length > 0 ? properties.join(", ") : "no arguments";
+  if (typeof args !== "object" || args === null || Array.isArray(args)) {
+    return `arguments must be an object (${toolName} takes ${takes})`;
+  }
+  const supplied = args;
+  for (const requiredName of schema.required ?? []) {
+    if (!(requiredName in supplied)) {
+      return `missing required argument '${requiredName}' (${toolName} takes ${takes})`;
+    }
+  }
+  if (!schema.additionalProperties) {
+    for (const suppliedName of Object.keys(supplied)) {
+      if (!properties.includes(suppliedName)) {
+        return `unknown argument '${suppliedName}' (${toolName} takes ${takes})`;
+      }
+    }
+  }
+  return null;
+}
 function isLocalhost() {
   const hostEnv = process.env.TINA4_HOST_NAME || "localhost:7148";
   const host = hostEnv.split(":")[0];
@@ -16226,7 +16267,12 @@ function registerDevTools(server) {
         if (!/^[A-Za-z_][A-Za-z0-9_$]*(\.[A-Za-z_][A-Za-z0-9_$]*)?$/.test(table2)) {
           return { error: "Invalid table name" };
         }
-        return await db.getColumns?.(table2) ?? [];
+        const columns = await db.getColumns?.(table2) ?? [];
+        if (columns.length === 0) {
+          const tables = await db.getTables?.() ?? [];
+          if (!tables.includes(table2)) return { error: `table not found: ${table2}` };
+        }
+        return columns;
       } catch (e) {
         return { error: e.message };
       }
@@ -16245,7 +16291,8 @@ function registerDevTools(server) {
         return routes.map((r) => ({
           method: r.method || "",
           path: r.pattern || r.path || "",
-          auth_required: r.secure ?? false
+          auth_required: r.secure ?? false,
+          middleware: r.middleware ?? []
         }));
       } catch (e) {
         return { error: e.message };
@@ -17391,6 +17438,10 @@ data: ${channel.buffer.shift()}
           throw new Error(`Unknown tool: ${toolName}`);
         }
         const args = params.arguments || {};
+        const invalid = validateToolArguments(toolName, tool.inputSchema, args);
+        if (invalid) {
+          return { content: [{ type: "text", text: JSON.stringify({ error: invalid }, null, 2) }] };
+        }
         const result = await tool.handler(args);
         let content;
         if (typeof result === "string") {
@@ -23429,7 +23480,9 @@ var init_docsParser = __esm({
 // ../core/src/docs.ts
 var docs_exports = {};
 __export(docs_exports, {
-  Docs: () => Docs
+  Docs: () => Docs,
+  paramsFromSignature: () => paramsFromSignature,
+  returnFromSignature: () => returnFromSignature
 });
 import * as fs8 from "node:fs";
 import * as path8 from "node:path";
@@ -23656,6 +23709,54 @@ function scoreFqn(entry, tokens) {
   }
   return score;
 }
+function splitTopLevel(text) {
+  const parts = [];
+  let depth = 0;
+  let current = "";
+  for (const ch of text) {
+    if ("<([{".includes(ch)) depth++;
+    else if (">)]}".includes(ch)) depth--;
+    if (ch === "," && depth === 0) {
+      parts.push(current);
+      current = "";
+    } else current += ch;
+  }
+  if (current.trim()) parts.push(current);
+  return parts;
+}
+function closingParen(signature, open) {
+  let depth = 0;
+  for (let i = open; i < signature.length; i++) {
+    if (signature[i] === "(") depth++;
+    else if (signature[i] === ")" && --depth === 0) return i;
+  }
+  return -1;
+}
+function paramsFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return [];
+  return splitTopLevel(signature.slice(open + 1, close)).map((raw) => {
+    const [declaration, ...defaultParts] = raw.split(/=(?!>)/);
+    const defaultText = defaultParts.length > 0 ? defaultParts.join("=").trim() : null;
+    const colon = declaration.indexOf(":");
+    const head = (colon < 0 ? declaration : declaration.slice(0, colon)).trim();
+    const optional = head.endsWith("?");
+    return {
+      name: head.replace(/\?$/, ""),
+      type: colon < 0 ? "" : declaration.slice(colon + 1).trim(),
+      required: !optional && defaultText === null && !head.startsWith("..."),
+      default: defaultText
+    };
+  });
+}
+function returnFromSignature(signature) {
+  const open = signature.indexOf("(");
+  const close = open < 0 ? -1 : closingParen(signature, open);
+  if (close < 0) return "";
+  const rest = signature.slice(close + 1).trim();
+  return rest.startsWith(":") ? rest.slice(1).trim() : "";
+}
 var STDLIB_ALLOWLIST, _DOCS_CACHE, __FILENAME, __DIRNAME, USER_DIRS, CAMEL_SPLIT, FENCE_RE, CALL_RE, sharedFrameworkIndex, Docs;
 var init_docs = __esm({
   "../core/src/docs.ts"() {
@@ -23961,8 +24062,8 @@ var init_docs = __esm({
           static: entry.static ?? false,
           source: entry.source,
           version: entry.version,
-          params: [],
-          return: ""
+          params: paramsFromSignature(entry.signature),
+          return: returnFromSignature(entry.signature)
         };
       }
       /**

package/types/core/src/docs.d.ts

@@ -30,7 +30,8 @@ export interface MethodSpec {
     params: Array<{
         name: string;
         type: string;
-        default?: string | null;
+        required: boolean;
+        default: string | null;
     }>;
     return: string;
 }
@@ -69,6 +70,10 @@ export interface DriftHit {
     line: number;
     block: string;
 }
+/** Structured params `[{name, type, required, default}]` from `name(a: T, b?: U = 1) : R`. */
+export declare function paramsFromSignature(signature: string): MethodSpec["params"];
+/** Return type text from `name(...) : R` (or `): R`), "" when absent. */
+export declare function returnFromSignature(signature: string): string;
 export declare class Docs {
     private projectRoot;
     private frameworkRoots;

package/types/core/src/mcp.d.ts

@@ -30,6 +30,7 @@ export interface JsonSchema {
         default?: unknown;
     }>;
     required?: string[];
+    additionalProperties?: boolean;
 }
 export interface McpToolParam {
     name: string;
@@ -57,6 +58,15 @@ export declare function decodeRequest(data: string | Record<string, unknown>): {
  * Since TypeScript erases types at runtime, we use explicit metadata.
  */
 export declare function schemaFromParams(params: McpToolParam[]): JsonSchema;
+/**
+ * Check call arguments against a tool's input schema BEFORE the handler runs.
+ * Returns null when valid, else the actionable message
+ * `missing required argument '<p>' (<tool> takes <p1>, <p2>)` (or
+ * `unknown argument '<k>' (...)`). Byte-identical to tina4-python's
+ * `_validate_tool_arguments` (tina4-php#271) so a wrong key never surfaces as a
+ * raw TypeError / 500.
+ */
+export declare function validateToolArguments(toolName: string, schema: JsonSchema, args: unknown): string | null;
 /**
  * Informational only — whether the CONFIGURED host looks local.
  *

package/types/core/src/router.d.ts

@@ -92,6 +92,8 @@ export interface RouteInfo {
     path: string;
     handler: string;
     middlewareCount: number;
+    /** Names of the middleware attached to the route (functions / classes / string specs). */
+    middleware: string[];
     cached: boolean;
     secure: boolean;
 }

package/types/core/src/session.d.ts

@@ -258,6 +258,16 @@ export declare class Session {
      * Get flash data by key (alias for flash(key) without value).
      */
     getFlash(key: string, defaultValue?: unknown): unknown;
+    /**
+     * Whether this session is only an id: nothing has stored it and it holds no
+     * data of its own (its `_created` / `_accessed` bookkeeping does not count).
+     * Such a session has no record and needs no cookie, so save() writes nothing
+     * for it and the server sends no cookie for it. It stops being fresh when
+     * something is stored in it. Calls that mark a session changed without leaving
+     * anything in it (deleting a key it never had, clear(), regenerate() on an
+     * empty session) leave it fresh: a record with no data is not a session.
+     */
+    isFresh(): boolean;
     /**
      * Get the current session ID.
      */
@@ -388,4 +398,19 @@ export declare function sessionStrictMode(): boolean;
  * http://localhost dev cookies undeliverable.
  */
 export declare function buildSessionCookie(sessionId: string | null, ttl: number, cookieName?: string, forwardedProto?: string, socketEncrypted?: boolean): string;
+/**
+ * The Set-Cookie value that hands the client this request's session, or null
+ * when none is owed: the client already holds the id, headers have gone out, or
+ * the session is fresh. A fresh session (only an id: minted for this request
+ * and holding no data) was not stored, so a cookie for it would name nothing:
+ * the next request could not resume it and would be handed another one.
+ */
+export declare function sessionCookieToSend(sess: {
+    isFresh(): boolean;
+}, existingSid: string | undefined, rawReq: {
+    headers: Record<string, string | string[] | undefined>;
+    socket?: unknown;
+}, rawRes: {
+    headersSent: boolean;
+}): string | null;
 export {};