@inferencesh/app 0.2.0 → 0.3.0

package/README.md

@@ -23,6 +23,7 @@ npm install @inferencesh/app
 | `download()` | download a url to a directory with caching |
 | `textMeta`, `imageMeta`, `videoMeta`, `audioMeta`, `rawMeta` | output metadata factories for usage-based pricing |
 | `createStreamSchema`, `pcm16`, `media`, `Live` | live fields for stream functions — values that flow over the socket while the task runs |
+| `meta()` | per-function credentials and annotations (`<Name>Meta` exports) |
 
 ## file handling
 
@@ -297,6 +298,27 @@ the client closing the socket ends the `for await`, so the final yield goes afte
 
 binary frames are perishable media, so the kernel keeps at most 256 of them queued for the app (about five seconds of 20 ms audio) and drops the oldest when the app reads slower than the client sends — latency stays bounded instead of growing for ever. text frames (commands and patches) are never dropped. `socket.dropped` counts the binary frames lost so far, and `socket.binaryBacklog = null` turns dropping off when every frame matters (a file sent in chunks).
 
+## per-function credentials and annotations
+
+export `<PascalName>Meta` next to a function's input and output schemas. `credentials` narrows what the function needs at run time (each entry must also be in inf.yml's `credentials:`; a function without it gets the app-wide list). `annotations` are hints about what it does.
+
+```javascript
+import { meta } from "@inferencesh/app";
+
+export const CreateEventInput = z.object({ title: z.string() });
+export const CreateEventOutput = z.object({ id: z.string() });
+export const CreateEventMeta = meta({
+  credentials: [{ key: "google.calendar.events" }],
+  annotations: { readOnlyHint: false, destructiveHint: false },
+});
+
+export class App {
+  async createEvent(input) { /* ... */ }
+}
+```
+
+`meta()` returns its argument unchanged after the same checks as sdk-py's `@function` (it throws on an empty `credentials` list, unknown keys, wrong value types, or a credential with neither `key` nor `provider`). it gives editors the `CredentialRequirement` and `ToolAnnotations` types (add `// @ts-check` to a `.js` file to get errors, not only completions).
+
 ## requirements
 
 - node.js 18.0.0 or higher

package/dist/index.d.ts

@@ -4,6 +4,8 @@ export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js"
 export type { Socket, Frame } from "./socket.js";
 export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, CLEAR_KEY, ERROR_KEY, BINARY_SCHEMA_MARKER, } from "./stream.js";
 export type { Update } from "./stream.js";
+export { meta } from "./meta.js";
+export type { FunctionMeta } from "./meta.js";
 export { StorageDir, ensureDir } from "./storage.js";
 export type { StorageDirValue } from "./storage.js";
 export { download } from "./download.js";

package/dist/index.js

@@ -3,6 +3,8 @@ export { File } from "./file.js";
 // Zod schema utilities
 export { createFileSchema, isFileSchema, FILE_SCHEMA_MARKER } from "./schema.js";
 export { createStreamSchema, media, pcm16, Live, liveFields, binaryField, STREAM_SCHEMA_MARKER, CLEAR_KEY, ERROR_KEY, BINARY_SCHEMA_MARKER, } from "./stream.js";
+// Per-function metadata: credentials and annotations (<PascalName>Meta exports)
+export { meta } from "./meta.js";
 // Storage directories
 export { StorageDir, ensureDir } from "./storage.js";
 // Download utility

package/dist/meta.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Per-function metadata: the credentials a function needs and hints about
+ * what it does. Node twin of sdk-py's `@function(credentials=..., annotations=...)`.
+ *
+ * Export it next to the function's Input and Output schemas, named
+ * `<PascalName>Meta`; the kernel's discovery reads it from there:
+ *
+ * ```js
+ * import { meta } from "@inferencesh/app";
+ *
+ * export const CreateEventInput = z.object({ ... });
+ * export const CreateEventOutput = z.object({ ... });
+ * export const CreateEventMeta = meta({
+ *   credentials: [{ key: "google.calendar.events" }],
+ *   annotations: { readOnlyHint: false, destructiveHint: false },
+ * });
+ *
+ * export class App { async createEvent(input) { ... } }
+ * ```
+ */
+import type { CredentialRequirement, ToolAnnotations } from "./types.js";
+export interface FunctionMeta {
+    /**
+     * The credentials this function needs at run time. Each entry must be
+     * covered by the app-wide `credentials:` in inf.yml. A function without
+     * this gets the app-wide list.
+     */
+    credentials?: CredentialRequirement[];
+    /** Hints about the function's behavior (read-only, destructive, ...). */
+    annotations?: ToolAnnotations;
+}
+/**
+ * Declares a function's metadata and returns `m` unchanged. Editors
+ * type-check the declaration, plain `.js` apps included (with `// @ts-check`).
+ *
+ * Throws on a malformed declaration, at import time, with the same checks as
+ * sdk-py's `@function`: an empty `credentials` list (omit it to use the
+ * app-wide list from inf.yml), unknown keys, wrong value types, or a
+ * credential with neither `key` nor `provider`. A null hint means
+ * "not declared"; the schema omits it.
+ */
+export declare function meta(m: FunctionMeta): FunctionMeta;

package/dist/meta.js

@@ -0,0 +1,102 @@
+/**
+ * Per-function metadata: the credentials a function needs and hints about
+ * what it does. Node twin of sdk-py's `@function(credentials=..., annotations=...)`.
+ *
+ * Export it next to the function's Input and Output schemas, named
+ * `<PascalName>Meta`; the kernel's discovery reads it from there:
+ *
+ * ```js
+ * import { meta } from "@inferencesh/app";
+ *
+ * export const CreateEventInput = z.object({ ... });
+ * export const CreateEventOutput = z.object({ ... });
+ * export const CreateEventMeta = meta({
+ *   credentials: [{ key: "google.calendar.events" }],
+ *   annotations: { readOnlyHint: false, destructiveHint: false },
+ * });
+ *
+ * export class App { async createEvent(input) { ... } }
+ * ```
+ */
+const CREDENTIAL_STR_KEYS = ["provider", "name", "website", "key", "description"];
+const CREDENTIAL_LIST_KEYS = ["secrets", "scopes"];
+const CREDENTIAL_KEYS = [...CREDENTIAL_STR_KEYS, "optional", ...CREDENTIAL_LIST_KEYS];
+const ANNOTATION_HINT_KEYS = ["readOnlyHint", "destructiveHint", "idempotentHint", "openWorldHint"];
+const ANNOTATION_KEYS = ["title", ...ANNOTATION_HINT_KEYS];
+const isObject = (v) => v !== null && typeof v === "object" && !Array.isArray(v);
+const typeName = (v) => (v === null ? "null" : Array.isArray(v) ? "array" : typeof v);
+const unknownKeys = (obj, allowed) => Object.keys(obj).filter((k) => !allowed.includes(k)).sort();
+function checkCredential(i, entry) {
+    const where = `meta() credentials[${i}]`;
+    if (!isObject(entry))
+        throw new TypeError(`${where}: expected an object, got ${typeName(entry)}`);
+    const unknown = unknownKeys(entry, CREDENTIAL_KEYS);
+    if (unknown.length > 0) {
+        throw new Error(`${where}: unknown keys ${JSON.stringify(unknown)}; allowed: ${JSON.stringify(CREDENTIAL_KEYS)}`);
+    }
+    for (const k of CREDENTIAL_STR_KEYS) {
+        if (entry[k] !== undefined && typeof entry[k] !== "string") {
+            throw new TypeError(`${where}.${k}: expected a string, got ${typeName(entry[k])}`);
+        }
+    }
+    if (entry.optional !== undefined && typeof entry.optional !== "boolean") {
+        throw new TypeError(`${where}.optional: expected a boolean, got ${typeName(entry.optional)}`);
+    }
+    for (const k of CREDENTIAL_LIST_KEYS) {
+        const v = entry[k];
+        if (v !== undefined && !(Array.isArray(v) && v.every((s) => typeof s === "string"))) {
+            throw new TypeError(`${where}.${k}: expected a list of strings`);
+        }
+    }
+    if (!entry.key && !entry.provider) {
+        throw new Error(`${where}: set 'key' (a capability like 'google.calendar.events') or 'provider'`);
+    }
+}
+function checkAnnotations(annotations) {
+    if (!isObject(annotations)) {
+        throw new TypeError(`meta() annotations: expected an object, got ${typeName(annotations)}`);
+    }
+    const unknown = unknownKeys(annotations, ANNOTATION_KEYS);
+    if (unknown.length > 0) {
+        throw new Error(`meta() annotations: unknown keys ${JSON.stringify(unknown)}; allowed: ${JSON.stringify(ANNOTATION_KEYS)}`);
+    }
+    if (annotations.title !== undefined && typeof annotations.title !== "string") {
+        throw new TypeError("meta() annotations.title: expected a string");
+    }
+    for (const k of ANNOTATION_HINT_KEYS) {
+        const v = annotations[k];
+        if (v !== undefined && v !== null && typeof v !== "boolean") {
+            throw new TypeError(`meta() annotations.${k}: expected a boolean, got ${typeName(v)}`);
+        }
+    }
+}
+/**
+ * Declares a function's metadata and returns `m` unchanged. Editors
+ * type-check the declaration, plain `.js` apps included (with `// @ts-check`).
+ *
+ * Throws on a malformed declaration, at import time, with the same checks as
+ * sdk-py's `@function`: an empty `credentials` list (omit it to use the
+ * app-wide list from inf.yml), unknown keys, wrong value types, or a
+ * credential with neither `key` nor `provider`. A null hint means
+ * "not declared"; the schema omits it.
+ */
+export function meta(m) {
+    if (!isObject(m))
+        throw new TypeError(`meta(): expected an object, got ${typeName(m)}`);
+    const unknown = unknownKeys(m, ["credentials", "annotations"]);
+    if (unknown.length > 0) {
+        throw new Error(`meta(): unknown keys ${JSON.stringify(unknown)}; allowed: ["credentials","annotations"]`);
+    }
+    if (m.credentials !== undefined) {
+        if (!Array.isArray(m.credentials)) {
+            throw new TypeError(`meta() credentials: expected a list of objects, got ${typeName(m.credentials)}`);
+        }
+        if (m.credentials.length === 0) {
+            throw new Error("meta() credentials: empty list; omit credentials to use the app-wide list from inf.yml");
+        }
+        m.credentials.forEach((c, i) => checkCredential(i, c));
+    }
+    if (m.annotations !== undefined)
+        checkAnnotations(m.annotations);
+    return m;
+}

package/dist/types.d.ts

@@ -6,12 +6,54 @@ export interface RequestMetadata {
     worker_id: string;
     app_id: string;
     app_version_id: string;
-    app_variant: string;
     gpu_ids: string[];
     task_id: string;
     team_id: string;
     user_id: string;
 }
+/**
+ * CredentialRequirement is an entry under credentials: in inf.yml: keys an
+ * app needs that belong to a provider. Provider names whose credential
+ * supplies them; Secrets lists the keys to inject from it (an API key
+ * credential), Scopes what to ask for (an OAuth one).
+ * 	credentials:
+ * 	  - provider: acme
+ * 	    name: Acme CRM
+ * 	    website: acme.com
+ * 	    secrets: [ACME_API_KEY]
+ * Key is a capability of a provider the platform defines ("x.tweet.read",
+ * "google.sheets"): an OAuth grant with the scopes it implies. An entry sets
+ * Provider, Key, or both; with both, Key decides how it is resolved.
+ */
+export interface CredentialRequirement {
+    provider?: string;
+    /**
+     * Name and Website describe a provider the platform does not list: the
+     * name its credential is shown under and the site its logo comes from.
+     */
+    name?: string;
+    website?: string;
+    key?: string;
+    description?: string;
+    optional?: boolean;
+    secrets?: string[];
+    scopes?: string[];
+}
+/**
+ * ToolAnnotations describes tool behavior so clients can make trust and UX
+ * decisions (e.g., auto-approve read-only tools). All fields are optional hints.
+ */
+export interface ToolAnnotations {
+    /**
+     * Title is the human-readable name clients and the Claude directory show.
+     * It repeats MCPTool.Title because some clients read only this one.
+     */
+    title?: string;
+    readOnlyHint?: boolean;
+    destructiveHint?: boolean;
+    idempotentHint?: boolean;
+    openWorldHint?: boolean;
+}
 export interface AppSDKTypes {
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@inferencesh/app",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "App framework for building inference.sh apps — File handling, output metadata, storage utilities",
   "type": "module",
   "main": "dist/index.js",