@colixsystems/widget-sdk 0.152.0 → 0.154.0

package/README.md

@@ -47,7 +47,7 @@ The data layer lives in **four separate domain-client packages**, each instantia
 | **DATASTORE** | `useDatastoreSchema(tableId)` | `{ schema, loading, error, refetch }` | `schema(tableId)` — `datastore.read:<table>` |
 | **DATASTORE** | `useBoundColumns(tableId, shape, props)` | `{ columns, resolved, missing, loading, error }` | `schema(tableId)` (built on `useDatastoreSchema`) — `datastore.read:<table>`. Resolves author-bound column NAMES from `props` by exact name → case-insensitive name → first unclaimed column matching `shape[key].dataType`, so a column an author renamed after install still resolves instead of `record[props.titleField]` reading `undefined`. `columns` holds the resolved NAME (`record[columns.titleField]`); `resolved` holds the full `Column`; `missing` lists non-`optional` keys that never resolved. Falsy `tableId` collapses to `{ columns: {}, resolved: {}, missing: Object.keys(shape), loading: false, error: null }`. |
 | **DATASTORE** | `useInterpretDraft(tableId)` | `{ interpret, interpreting, error, result, available }` | `interpret(tableId, body)` — `datastore.read:<table>`. Turns ONE sentence a user typed ("walk at 11 am tomorrow") into DRAFT column values so a form can prefill itself. IMPERATIVE: call `interpret(text, { fields?, timeZone? })` from an event handler, never on mount. It DRAFTS and writes nothing — show the values for review, then submit through `useDatastoreMutation().create`. Resolves to `{ values, unresolved }`; `values` is keyed by column NAME (the shape `create()` takes) and `unresolved` names the fields the sentence did not state. Only text / number / boolean / date / datetime / array columns are drafted — `FILE`, `RELATION`, `USER` and `USER_GROUP` carry ids and are never guessed. Fails closed to an empty draft. **Every call spends the workspace's AI credits** and is rate-limited per actor, so call it once per user action (never on mount or in a render loop); once the workspace runs out the call is refused with a generic 429 — an app user is deliberately **not** told the workspace's billing state, since they have never heard of an AI credit and cannot buy one. Never surface a raw error to the person filling the form: say drafting is unavailable and keep every field editable by hand. `available` is false where the host brokers no interpreter. |
-| **AGENTS** | `useAgent(agentRef)` | `{ send, reset, messages, sending, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). IMPERATIVE: call `send(text)` from an event handler, never on mount — the first send opens the conversation, so a widget nobody types into costs nothing. `messages` is the running transcript, oldest first. You **cannot** set or read the system prompt, replay an edited transcript, or pick a model: the server assembles every turn from the stored prompt plus the stored history, and `content` is the only thing that reaches the wire. `reset()` drops the thread (a "new chat" affordance). **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. |
+| **AGENTS** | `useAgent(agentRef)` | `{ send, reset, messages, sending, error, available }` | `ctx.agents` — `ai.invoke:*`. Hold a conversation with one of the WORKSPACE's own AI agents (an author-written name + system prompt). IMPERATIVE: call `send(text)` from an event handler, never on mount — the first send opens the conversation, so a widget nobody types into costs nothing. `messages` is the running transcript, oldest first. You **cannot** set or read the system prompt, replay an edited transcript, or pick a model: the server assembles every turn from the stored prompt plus the stored history, and `content` is the only thing that reaches the wire. `reset()` drops the thread (a "new chat" affordance). **Every send spends the workspace's AI credits** and is rate-limited per caller AND per workspace. Rejects with `AgentError`; branch on `.code` — `AI_QUOTA_EXCEEDED` (429) is the workspace's credit ceiling and will NOT clear on a retry, unlike `RATE_LIMITED`, so never offer "try again" for it, and `AGENT_DISABLED` (409) means the author turned it off, so hide the affordance. Never surface a raw error or the workspace's billing state to an app user. `available` is false when no agent is bound or the host brokers none — render a visible unbound state, never a blank box. An assistant message that used a tool also carries **`activity`** — what the agent DID with the user's data: the table it read, or the table and columns it CHANGED (never the values, and never a row the permissions refused). **Render a write.** A reply saying "done!" is not evidence a row was written, and if the agent got it wrong the user has no other way to notice. A talk-only turn omits the key entirely. |
 | **DATASTORE** | `useDatastoreMutation(table)` | `{ create, update, delete }` | `records(table).{ create, update (PATCH), delete }` — `datastore.write:*`. **To CLEAR a cell, pass it empty** — `update(id, { when: null })` (also `""` or `[]`) empties that cell and it reads back as `null` (`[]` on an array column). There is no separate clear call, so never write a sentinel such as `0` or a placeholder date to mean "no value". `false` and `0` are values, not clears, and a REQUIRED column cannot be cleared. |
 | **DATASTORE** | `useDatastoreSubscription(table, handlers, options)` (optional: options) | `{ status }` — `"connecting" \| "live" \| "reconnecting" \| "fallback"` | `records(table).subscribe` — `datastore.read:<table>`. Live `onCreated` / `onUpdated` / `onDeleted` off the REQ-RT-07 socket; never throws, resolving to `{ status: "fallback" }` so the widget polls instead. A whole-table subscribe is gated on read-EVERY-row, because one envelope reaches every subscriber of the table — so for a table governed by per-record grants pass `options.scope`: `{ kind: "record", record_id }` for one row, or `{ kind: "parent", relation_column, record_id }` for the rows whose RELATION column points at that parent (the column must carry `inheritAcl`, else the subscribe reports `"fallback"`). Re-subscribes on the scope's VALUES, so a fresh object literal each render is fine. |
 | **DATASTORE** | `useRecordPermissions(tableId, recordId)` | `{ permissions, loading, error, grant, revoke, update, refetch }` | `records(table).permissions(record).{ list, grant, update, revoke }` — `acl.write:records` (+ `can_grant` on the record) |
@@ -72,7 +72,23 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.152.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.154.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.154.0 (contract 1.120.0)
+
+**An agent can now tell you what it DID (sc-8332).** An assistant `AgentMessage` may carry `activity`: one entry per tool the agent ran, naming the table it read, or the table and the columns it changed. Additive — a talk-only turn omits the key, so nothing existing changes shape.
+
+Render the writes. An assistant that silently changes a person's data is not trustworthy however correct its permissions are, and a chat bubble saying "done!" is not evidence a row was written. Reads can stay quiet; a change should not. The summary never carries row VALUES and never names a row the permissions refused, so showing it cannot leak what the reader could not already see.
+
+### What's new in 0.153.0 (contract 1.118.0 — unchanged)
+
+**`./host` publishes the local-clock DATETIME conversion `<DateTimePicker>` uses (sc-8448).** The Studio's Data Manager sliced the stored UTC string and saved the input's value without a zone, so it showed and wrote UTC labelled as local. It now reads the same conversion the picker does, so a stored instant shows the same wall clock in the Studio and in the Player.
+
+- **`isoToDateTimeLocalInput(value)`** — a stored instant as `<input type="datetime-local">`'s `YYYY-MM-DDTHH:mm` on the viewer's clock. A bare `YYYY-MM-DD` is local midnight.
+- **`dateTimeLocalInputToIso(raw)`** — the inverse: a local `YYYY-MM-DDTHH:mm` as a full UTC ISO instant.
+- **`formatDateTimeLabel(value, mode)`** — the picker's trigger label (`YYYY-MM-DD HH:mm` local for `"datetime"`).
+
+Behaviour: a bare date given to a `mode="datetime"` picker now shows local midnight instead of UTC midnight (which read as the previous evening west of Greenwich), and a year before 1000 is zero-padded so typing a year no longer clears the web input. Otherwise additive.
 
 ### What's new in 0.152.0 (contract 1.118.0 — unchanged)
 

package/dist/contract.cjs

@@ -1286,6 +1286,11 @@ const HOOKS = [
       "opens the conversation, so a widget nobody types into costs nothing. " +
       "`messages` is the running transcript, oldest first, each " +
       "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
+      "An assistant message that used a tool also carries `activity`: what " +
+      "the agent DID — the table it read, or the table and columns it " +
+      "CHANGED. Render a write: a reply saying 'done!' is not evidence a " +
+      "row was written, and the user has no other way to notice a mistake. " +
+      "A talk-only turn omits the key entirely. " +
       "You CANNOT set the system prompt, replay an edited transcript, " +
       "or pick a model. No API returns the prompt — but that is a guarantee " +
       "about the WIRE, not secrecy: a model can be talked into repeating its " +
@@ -4227,6 +4232,11 @@ const CONTRACT = deepFreeze({
   //    and the inherited colours are hex-guarded on the way out as well as in.
   //    Every colour still falls back to the sidebar's: an untouched workspace is
   //    unchanged.
+  // 1.120.0: additive (sc-8332) — an assistant `AgentMessage` may carry
+  // `activity`, a compact record of what the agent DID with the user's data
+  // (the table it read; the table and columns it CHANGED). Absent on a
+  // talk-only turn, so nothing existing changes shape. Render a write: a
+  // reply saying "done!" is not evidence a row was written.
   // 1.116.0: additive (sc-7991) — `useAgent(agentRef)` + the `agents` host
   // client + the `agentRef` propertySchema type + the `ai.invoke:*` scope. A
   // widget can hold a conversation with one of the WORKSPACE's own AI agents.
@@ -4288,7 +4298,7 @@ const CONTRACT = deepFreeze({
   //    untouched and renders byte-identically, and an unresolvable binding
   //    fails the existing hex guard, dropping the wash rather than painting it
   //    blank.
-  version: "1.119.0",
+  version: "1.120.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -1286,6 +1286,11 @@ const HOOKS = [
       "opens the conversation, so a widget nobody types into costs nothing. " +
       "`messages` is the running transcript, oldest first, each " +
       "{ id, role, content, created_at } with role 'user' | 'assistant'. " +
+      "An assistant message that used a tool also carries `activity`: what " +
+      "the agent DID — the table it read, or the table and columns it " +
+      "CHANGED. Render a write: a reply saying 'done!' is not evidence a " +
+      "row was written, and the user has no other way to notice a mistake. " +
+      "A talk-only turn omits the key entirely. " +
       "You CANNOT set the system prompt, replay an edited transcript, " +
       "or pick a model. No API returns the prompt — but that is a guarantee " +
       "about the WIRE, not secrecy: a model can be talked into repeating its " +
@@ -4223,6 +4228,11 @@ const CONTRACT = deepFreeze({
   //    and the inherited colours are hex-guarded on the way out as well as in.
   //    Every colour still falls back to the sidebar's: an untouched workspace is
   //    unchanged.
+  // 1.120.0: additive (sc-8332) — an assistant `AgentMessage` may carry
+  // `activity`, a compact record of what the agent DID with the user's data
+  // (the table it read; the table and columns it CHANGED). Absent on a
+  // talk-only turn, so nothing existing changes shape. Render a write: a
+  // reply saying "done!" is not evidence a row was written.
   // 1.116.0: additive (sc-7991) — `useAgent(agentRef)` + the `agents` host
   // client + the `agentRef` propertySchema type + the `ai.invoke:*` scope. A
   // widget can hold a conversation with one of the WORKSPACE's own AI agents.
@@ -4284,7 +4294,7 @@ const CONTRACT = deepFreeze({
   //    untouched and renders byte-identically, and an unresolvable binding
   //    fails the existing hex guard, dropping the wash rather than painting it
   //    blank.
-  version: "1.119.0",
+  version: "1.120.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/datetimepicker-format.js

@@ -15,12 +15,33 @@ export function parseToDate(value) {
   return new Date();
 }
 
+const DATE_ONLY = /^\d{4}-\d{2}-\d{2}$/;
+
+// A stored DATETIME instant → `<input type="datetime-local">`'s
+// `YYYY-MM-DDTHH:mm` on the viewer's local clock. A bare calendar date is
+// local midnight, not UTC midnight, so it never slips a day west of Greenwich.
+export function isoToDateTimeLocalInput(value) {
+  if (value == null || value === "") return "";
+  if (typeof value === "string" && DATE_ONLY.test(value)) return `${value}T00:00`;
+  const d = new Date(value);
+  if (Number.isNaN(d.getTime())) return "";
+  return `${formatToIso(d, "date")}T${formatToIso(d, "time")}`;
+}
+
+// The inverse: a naive local `YYYY-MM-DDTHH:mm` → a full UTC ISO instant.
+export function dateTimeLocalInputToIso(raw) {
+  if (raw == null || raw === "") return "";
+  const d = new Date(raw);
+  if (Number.isNaN(d.getTime())) return "";
+  return d.toISOString();
+}
+
 export function formatToIso(date, mode) {
   if (!(date instanceof Date) || Number.isNaN(date.getTime())) return null;
   if (mode === "date") {
     // Local-date ISO (yyyy-mm-dd) — calendar dates are timezone-free so a
     // "May 28" picked in Stockholm doesn't read as "May 27" in NYC.
-    const y = date.getFullYear();
+    const y = String(date.getFullYear()).padStart(4, "0");
     const m = String(date.getMonth() + 1).padStart(2, "0");
     const d = String(date.getDate()).padStart(2, "0");
     return `${y}-${m}-${d}`;
@@ -46,10 +67,8 @@ export function formatDisplayLabel(value, mode) {
   }
   if (effectiveMode === "date") return String(value).slice(0, 10);
   if (effectiveMode === "time") return String(value).slice(0, 5);
-  // datetime — render the stored UTC ISO in the user's local clock.
-  const d = new Date(value);
-  if (Number.isNaN(d.getTime())) return String(value);
-  return `${formatToIso(d, "date")} ${formatToIso(d, "time")}`;
+  const local = isoToDateTimeLocalInput(value);
+  return local ? local.replace("T", " ") : String(value);
 }
 
 // Perceived-luminance test for a hex colour (`#rgb` or `#rrggbb`). The web

package/dist/datetimepicker.js

@@ -26,7 +26,11 @@
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
-import { isDarkColor } from "./datetimepicker-format.js";
+import {
+  isDarkColor,
+  isoToDateTimeLocalInput,
+  dateTimeLocalInputToIso,
+} from "./datetimepicker-format.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
 
 const MODE_TO_INPUT_TYPE = {
@@ -51,15 +55,7 @@ function _isoToInputValue(value, mode) {
   if (mode === "time") {
     return String(value).slice(0, 5);
   }
-  // datetime-local
-  const d = new Date(value);
-  if (Number.isNaN(d.getTime())) return "";
-  const y = d.getFullYear();
-  const m = String(d.getMonth() + 1).padStart(2, "0");
-  const day = String(d.getDate()).padStart(2, "0");
-  const hh = String(d.getHours()).padStart(2, "0");
-  const mm = String(d.getMinutes()).padStart(2, "0");
-  return `${y}-${m}-${day}T${hh}:${mm}`;
+  return isoToDateTimeLocalInput(value);
 }
 
 // Translate the input's typed string back to the ISO format the wire wants.
@@ -69,9 +65,7 @@ function _isoToInputValue(value, mode) {
 function _inputValueToIso(raw, mode) {
   if (raw == null || raw === "") return "";
   if (mode === "date" || mode === "time") return raw;
-  const d = new Date(raw);
-  if (Number.isNaN(d.getTime())) return "";
-  return d.toISOString();
+  return dateTimeLocalInputToIso(raw);
 }
 
 export function DateTimePicker({

package/dist/hooks.js

@@ -2762,7 +2762,9 @@ function toAgentError(err) {
  * who places the widget and never types costs the workspace nothing.
  *
  * `messages` is the running transcript this widget has seen, oldest first,
- * each `{ id, role, content, created_at }` with `role` of "user" | "assistant".
+ * each `{ id, role, content, created_at }` with `role` of "user" | "assistant".
+ * An assistant message that used a tool also carries `activity` — what the
+ * agent DID with the user's data. Render the writes: "done!" is not evidence.
  * The SERVER owns the real transcript and the system prompt: the widget sends
  * one message and can neither read nor set the prompt.
  *

package/dist/host.d.ts

@@ -452,3 +452,22 @@ export function resolveGradientTokenStops(
   gradient: unknown,
   theme: unknown,
 ): unknown;
+
+/**
+ * sc-8448 — a stored DATETIME instant as `<input type="datetime-local">`'s
+ * `YYYY-MM-DDTHH:mm` on the viewer's local clock. A bare `YYYY-MM-DD` is local
+ * midnight. Empty or unparseable input returns `""`.
+ */
+export function isoToDateTimeLocalInput(value: unknown): string;
+
+/** sc-8448 — a local `YYYY-MM-DDTHH:mm` as a full UTC ISO instant, or `""`. */
+export function dateTimeLocalInputToIso(raw: unknown): string;
+
+/**
+ * sc-8448 — the `<DateTimePicker>` trigger label: for `"datetime"` the stored
+ * instant as `YYYY-MM-DD HH:mm` local time, falling back to the raw string.
+ */
+export function formatDateTimeLabel(
+  value: unknown,
+  mode: "date" | "time" | "datetime",
+): string;

package/dist/host.js

@@ -124,3 +124,10 @@ export {
   normaliseThemeGradient,
   normaliseLoginDesign,
 } from "./theme-background.js";
+
+// sc-8448: one DATETIME local-clock conversion for the picker and the Studio.
+export {
+  isoToDateTimeLocalInput,
+  dateTimeLocalInputToIso,
+  formatDisplayLabel as formatDateTimeLabel,
+} from "./datetimepicker-format.js";

package/dist/index.d.ts

@@ -1212,9 +1212,30 @@ export interface AgentMessage {
   /** The system prompt is NOT part of the transcript — it lives on the agent. */
   role: "user" | "assistant";
   content: string;
+  /**
+   * sc-8332 — what the agent DID on this turn, for the person to see. Present
+   * only on an assistant message that used a tool; a talk-only turn omits the
+   * key rather than carrying an empty marker you would have to special-case.
+   *
+   * Show a WRITE. A reply saying "done!" is not evidence a row was changed,
+   * and if the agent got it wrong the user has no other way to notice.
+   */
+  activity?: AgentActivity[];
   created_at: string;
 }
 
+/**
+ * One tool the agent ran. Names the table it touched and, for a write, the
+ * columns it set — never the values, and never a row the permissions refused.
+ */
+export interface AgentActivity {
+  tool: string;
+  ok: boolean;
+  table?: string;
+  record_id?: string;
+  fields?: string[];
+}
+
 export interface AgentApi {
   /** Imperative — call from an event handler. The first send opens the thread. */
   send(text: string): Promise<AgentMessage | null>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.152.0",
+  "version": "0.154.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",