openmates 0.28.0-alpha.0 → 0.28.0

package/README.md

@@ -121,8 +121,13 @@ openmates chats share last --expires 604800
 openmates chats delete <chat-id> --yes
 ```
 
-Exports include YAML and Markdown. When present, code embeds and video
-transcripts are written as separate files.
+Exports include YAML and Markdown. When present, code embeds, video transcripts,
+and calendar events are written as separate files. Calendar files appear in
+`calendar/` as `.ics` files, each containing only its primary event.
+
+The TypeScript SDK also supports local calendar export from decrypted embed
+content. `buildCalendarEventFile(embedId, content)` returns an RFC 5545 string;
+it requires a valid finished calendar event and does not contact a calendar provider.
 
 ### Use apps and typed commands
 
@@ -337,13 +342,14 @@ Treat these files like account credentials.
 
 ## Node.js SDK
 
-The npm package also exports an API-key SDK for Node.js. Use it when you want a
-programmatic client instead of shell commands.
+The npm package also exports a Node.js SDK. Without an API key, supported app
+skills and `chats.send()` use the shared free allowance without an account.
+A configured `OPENMATES_API_KEY` automatically uses your account instead.
 
-```ts
+```typescript
 import { OpenMates } from "openmates";
 
-const om = new OpenMates({ apiKey: process.env.OPENMATES_API_KEY });
+const om = new OpenMates();
 
 const search = await om.apps.web.search({
   requests: [{ query: "OpenMates SDK examples" }],
@@ -352,8 +358,22 @@ const search = await om.apps.web.search({
 const response = await om.chats.send("Summarize this release note draft.");
 ```
 
-SDK chats are non-persistent by default. Use `saveToAccount: true` only when you
-intentionally want the chat saved to the OpenMates account.
+Check the allowance with `await om.anonymous.status()`. No identity setup is
+needed. Free usage is limited by public IP and a shared daily, weekly, and monthly
+service allowance; people on the same network may share the IP limit.
+When the allowance is used or unavailable, `OpenMatesSignupRequiredError` exposes
+`signupRequired`, `code`, and `reason`, with a message directing users to create
+an account. Provider and network failures remain separate errors.
+
+Pass `apiKey` or set `OPENMATES_API_KEY` to use an account. Invalid or exhausted
+keys never fall back to free usage. For advanced free-only use, `anonymous: true`
+ignores an environment key; it cannot be combined with an explicit `apiKey`.
+
+SDK chats are non-persistent by default. Account-only options, including saved
+chats, Memories, Teams, focus modes, and model overrides, require an API key.
+Use `chats.send()` for anonymous AI chat with automatic routing; `apps.ai.ask()`
+requires an account. With an API key, use `saveToAccount: true` when you want the
+chat saved to the OpenMates account.
 
 ## Versioning
 
@@ -374,3 +394,36 @@ Install stable releases with `npm install -g openmates`. Install prereleases wit
 - [SDK guide](https://openmates.org/docs/user-guide/developers/sdk)
 - [Source code](https://github.com/glowingkitty/OpenMates/tree/dev/frontend/packages/openmates-cli)
 - [Issue tracker](https://github.com/glowingkitty/OpenMates/issues)
+## Experimental image decisions
+
+`apps.ai.decide` supports Jev 1.14 decisions over inline PNG/JPEG images:
+
+```typescript
+import { readFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { OpenMates } from "openmates";
+
+const om = new OpenMates();
+const ref = randomUUID();
+const result = await om.apps.ai.decide({
+  state: { board: ref },
+  questions: { clear: { type: "noul", instructions: "Is the path to the exit clear?" } },
+  assets: {
+    [ref]: { type: "image", format: "png", data_base64: (await readFile("board.png")).toString("base64") }
+  }
+});
+console.log(result);
+```
+
+Every asset needs a canonical lowercase UUID key referenced in a string value
+in state, instructions, or criteria. OpenMates validates up to four still images,
+1 MiB decoded per image and 4 MiB total, with both dimensions 280–1568 pixels.
+State/questions remain limited to 16 KiB; the complete JSON body is limited to
+6 MiB. Use `jpg` or `jpeg` for JPEG bytes. CLI callers can pass the same JSON
+shape with `openmates apps ai decide --input '<JSON>' --json`.
+
+This prototype feature calls TypeSafe directly, never OpenRouter fallback.
+Image tokens use the same applicable free allowance or account credits. No
+provider key or image header is required from the caller. It does not fetch
+remote images or create stored uploads; account upload flows still need signup.
+See [REST image decisions](https://github.com/glowingkitty/OpenMates/blob/dev/docs/architecture/apps/rest-api.md#experimental-image-decisions).

package/dist/{chunk-F2U6KIMR.js → chunk-5OCI636P.js}

@@ -181,22 +181,47 @@ async function recoveryEnvelopeKey(sharedSecret, associatedData) {
   const salt = await sha256(new TextEncoder().encode("openmates:chat-recovery-envelope:v1"));
   return hkdfSha256(sharedSecret, salt, await sha256(associatedData));
 }
+async function openChatMetadataRecoveryEnvelope(envelope, options) {
+  if (options.stage !== "initial" && options.stage !== "postprocessing") throw new Error("unsupported metadata stage");
+  const aad = concatBytes(
+    new TextEncoder().encode("OMCM1"),
+    ...[options.ownerId, options.chatId, options.taskId, options.jobId].map((value) => lengthPrefix(canonicalUuid(value, "metadata_identity"))),
+    lengthPrefix(new TextEncoder().encode(options.stage)),
+    recoveryKeyVersion(options.keyVersion)
+  );
+  const bytes = await openRecoveryEnvelopeWithAssociatedData(envelope, options.recoveryPrivateKey, aad, 64 * 1024);
+  const payload = JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes));
+  const identity = {
+    owner_id: options.ownerId,
+    chat_id: options.chatId,
+    task_id: options.taskId,
+    job_id: options.jobId,
+    stage: options.stage,
+    key_version: options.keyVersion
+  };
+  if (!payload || typeof payload !== "object" || Array.isArray(payload) || Object.keys(payload).sort().join(",") !== [...Object.keys(identity), "metadata"].sort().join(",") || Object.entries(identity).some(([key, value]) => payload[key] !== value)) throw new Error("metadata identity mismatch");
+  const metadata = payload.metadata;
+  if (!metadata || typeof metadata !== "object" || Array.isArray(metadata) || !Object.keys(metadata).length || Object.entries(metadata).some(([key, value]) => !["title", "summary", "category", "icon"].includes(key) || typeof value !== "string" || !value.length)) throw new Error("invalid metadata fields");
+  return metadata;
+}
 async function openChatCompletionRecoveryEnvelope(envelope, options) {
+  return openRecoveryEnvelopeWithAssociatedData(envelope, options.recoveryPrivateKey, recoveryAssociatedData(options), CHAT_RECOVERY_MAX_PAYLOAD_BYTES);
+}
+async function openRecoveryEnvelopeWithAssociatedData(envelope, recoveryPrivateKeyEncoded, associatedData, maxPayloadBytes) {
   if (!envelope || Object.keys(envelope).sort().join(",") !== "ciphertext,epk,nonce,v" || envelope.v !== CHAT_RECOVERY_PROTOCOL_VERSION) {
     throw new Error("invalid recovery envelope fields or version");
   }
   const recoveryPrivateKey = base64UrlToBytes(
-    options.recoveryPrivateKey,
+    recoveryPrivateKeyEncoded,
     "recovery_private_key",
     CHAT_RECOVERY_KEY_BYTES
   );
   const ephemeralPublicKey = base64UrlToBytes(envelope.epk, "epk", CHAT_RECOVERY_KEY_BYTES);
   const nonce = base64UrlToBytes(envelope.nonce, "nonce", CHAT_RECOVERY_NONCE_BYTES);
   const ciphertext = base64UrlToBytes(envelope.ciphertext, "ciphertext");
-  if (ciphertext.length < 16 || ciphertext.length - 16 > CHAT_RECOVERY_MAX_PAYLOAD_BYTES) {
+  if (ciphertext.length < 16 || ciphertext.length - 16 > maxPayloadBytes) {
     throw new Error("ciphertext payload size is invalid");
   }
-  const associatedData = recoveryAssociatedData(options);
   const sharedSecret = nacl.scalarMult(recoveryPrivateKey, ephemeralPublicKey);
   const envelopeKeyBytes = await recoveryEnvelopeKey(sharedSecret, associatedData);
   const envelopeKey = await cryptoApi.subtle.importKey(
@@ -1289,6 +1314,7 @@ export {
   bytesToBase64Url,
   deriveTeamInviteKey,
   deriveChatCompletionRecoveryKeypair,
+  openChatMetadataRecoveryEnvelope,
   openChatCompletionRecoveryEnvelope,
   openRecoveryOutputEnvelope,
   hashEmail,