@machinemetrics/mm-react-tools 5.3.0 → 5.4.0

package/README.md

@@ -147,6 +147,51 @@ const { range } = useMMAppContext();
 
 Contact support@machinemetrics.com for a Client ID and Secret.
 
+## Hand a prompt or context to Max
+
+Inside `MMProvider`, `useMMAgent()` exposes `ask` and `report`:
+
+```tsx
+const agent = useMMAgent();
+// The host forwards the active thread from Max's cml:current message.
+const { threadId } = useMMAppContext() as { threadId?: string | null };
+
+// Call directly from a user click or key press.
+const result = agent.ask('Build a scrap log', { newConversation: true });
+if (result.ok) {
+  // Navigate here if the app also needs to change pages.
+}
+
+// Background context does not require user activation.
+if (threadId) {
+  agent.report('app.context', { threadId, summary: 'Scrap log selected' });
+}
+```
+
+`ask` trims the prompt and accepts up to `ASK_MAX_LENGTH` (4000) characters.
+It returns `{ ok: false, reason }` for `empty`, `too-long`, `not-embedded`, or
+`no-user-action`. A successful result means the message was posted to the host;
+the host independently checks the source zone and user activation. With
+`newConversation: true`, the prompt requests a fresh conversation's first
+message. Otherwise it requests a composer prefill in the open conversation.
+Ask before navigating so the source frame still exists when the host receives it.
+
+`report` accepts `app.error`, `app.event`, or `app.context`, plus a required
+`AgentEventPayload` containing `threadId` from the host context populated by
+`cml:current`. Wait for that thread before reporting; do not invent a thread ID.
+It posts `agent:event` with a generated unique `id`, the kind and an ISO timestamp, returning
+`false` outside an embedded app or when `payload.threadId` is missing, not a string, or blank (including whitespace-only). No message is sent in those cases. It does not send a user message. Today, reports
+only reach Max from the `cml-renderer` zone. Payload `type` and `instanceId`
+fields are discarded so they cannot override the transport envelope.
+
+The library exports `AGENT_ASK` (`agent:ask`), `AGENT_ASK_CONSUMED`
+(`agent:ask-consumed`), and `AGENT_ASK_SOURCES` for the shared protocol.
+`AgentAskPayload` describes the app-to-host `{ prompt, newConversation? }`
+request. `AgentHostPrompt` describes the host-forwarded `{ at, prompt, source }`
+prompt. `AgentAskConsumedPayload` is `{ kind, at }`, where `kind` is
+`newThreadPrompt` or `agentAsk`. Timestamps are numbers; the host remains
+responsible for checking the source frame and user activation.
+
 ## License
 
 MIT © [MachineMetrics](https://github.com/machinemetrics)

package/dist/index.d.ts

@@ -10,4 +10,6 @@ export type { MMContextValue, MMAuthResult, MMUrls, MMRequest, MMRequestOptions,
 export type { MMProviderProps, MMReleaseStage } from './MMProvider';
 export type { UseApiRequestOptions, UseApiRequestResult } from './hooks';
 export type { DateRangePreset, DateRangeValue, MMAppSettingConfig, MMAppDateRangeDeclaration, MMAppSettingOption, MMAppSettingOptions, MMAppSettingValidateResult, MMAppInputSetting, MMAppSelectSetting, MMAppRadioSetting, MMAppThresholdsSetting, MMAppThresholdField, MMAppCustomSetting, MMAppDateRangeSetting, MMAppSettingCallbacks, MMAppSettingConfigFor, MMAppLooseSetting, } from './settings';
+export { useMMAgent, ASK_MAX_LENGTH, AGENT_ASK, AGENT_ASK_CONSUMED, AGENT_ASK_SOURCES, } from './useMMAgent';
+export type { AgentEventKind, AgentEvent, AgentEventPayload, AgentAskPayload, AgentHostPrompt, AgentAskConsumedPayload, AskOptions, AskResult, MMAgent, } from './useMMAgent';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,iBAAiB,CAAC;AAC5C,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,IAAI,MAAM,QAAQ,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,uBAAuB,EACvB,SAAS,EACT,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,IAAI,EACJ,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,0BAA0B,GAC3B,CAAC;AAEF,YAAY,EACV,cAAc,EACd,YAAY,EACZ,MAAM,EACN,SAAS,EACT,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACzE,YAAY,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,aAAa,MAAM,iBAAiB,CAAC;AAC5C,OAAO,UAAU,MAAM,cAAc,CAAC;AACtC,OAAO,EAAE,cAAc,EAAE,MAAM,eAAe,CAAC;AAC/C,OAAO,IAAI,MAAM,QAAQ,CAAC;AAC1B,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,0BAA0B,EAAE,MAAM,YAAY,CAAC;AAC5E,OAAO,EACL,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,SAAS,EACT,aAAa,EACb,cAAc,EACd,iBAAiB,EACjB,oBAAoB,EACpB,uBAAuB,EACvB,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EAClB,MAAM,SAAS,CAAC;AAEjB,OAAO,EACL,uBAAuB,EACvB,SAAS,EACT,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,eAAe,EACf,YAAY,EACZ,eAAe,EACf,uBAAuB,EACvB,uBAAuB,EACvB,wBAAwB,EACxB,iBAAiB,EACjB,iBAAiB,EACjB,cAAc,EACd,aAAa,EACb,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,kBAAkB,EAClB,gBAAgB,EAChB,iBAAiB,EACjB,oBAAoB,EACpB,UAAU,EACV,IAAI,EACJ,cAAc,EACd,eAAe,EACf,kBAAkB,EAClB,0BAA0B,GAC3B,CAAC;AAEF,YAAY,EACV,cAAc,EACd,YAAY,EACZ,MAAM,EACN,SAAS,EACT,gBAAgB,GACjB,MAAM,aAAa,CAAC;AACrB,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AACpE,YAAY,EAAE,oBAAoB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AACzE,YAAY,EACV,eAAe,EACf,cAAc,EACd,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,EAClB,mBAAmB,EACnB,0BAA0B,EAC1B,iBAAiB,EACjB,kBAAkB,EAClB,iBAAiB,EACjB,sBAAsB,EACtB,mBAAmB,EACnB,kBAAkB,EAClB,qBAAqB,EACrB,qBAAqB,EACrB,qBAAqB,EACrB,iBAAiB,GAClB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,UAAU,EACV,cAAc,EACd,SAAS,EACT,kBAAkB,EAClB,iBAAiB,GAClB,MAAM,cAAc,CAAC;AACtB,YAAY,EACV,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,uBAAuB,EACvB,UAAU,EACV,SAAS,EACT,OAAO,GACR,MAAM,cAAc,CAAC"}