@frontera-sdk/functions 1.50.81 → 1.50.83

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@frontera-sdk/functions",
-  "version": "1.50.81",
+  "version": "1.50.83",
   "description": "Author Frontera functions: manifest, triggers and the typed handler contract.",
   "keywords": [
     "frontera",
@@ -42,7 +42,7 @@
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@frontera-sdk/blueprint": "1.50.81",
+    "@frontera-sdk/blueprint": "1.50.83",
     "cron-parser": "^5.0.6"
   }
 }

package/src/runtime-context.ts

@@ -34,6 +34,7 @@ import type {
   AutomationContext,
   BlueprintQueryOptions,
   BlueprintQueryResult,
+  ConversationTranscript,
   HttpRequest,
   HttpResponse,
   PluginCallResult,
@@ -159,6 +160,98 @@ function summarize<T>(
   return size <= DETAIL_MAX_CHARS ? detail : { omitted: 'summary too large', chars: size }
 }
 
+/**
+ * Every transcript `ctx.conversation.transcript()` has handed out, its `turns`
+ * array, and each of its turns.
+ *
+ * A step's return value is copied into its trace row, and the trace is exactly
+ * where a person's own words must not be kept. Branding the objects — not
+ * inspecting their shape — is what makes the check exact: a value that merely
+ * looks like a transcript is the author's own data and stays readable. Each
+ * turn is branded too, so `turns.filter(…)`, `turns.slice()` or one picked
+ * turn is still recognized. Held weakly, so nothing here keeps a transcript
+ * alive.
+ */
+const handedOut = new WeakMap<object, 'transcript' | 'turns' | 'turn'>()
+
+function brandTranscript(transcript: ConversationTranscript | null): ConversationTranscript | null {
+  if (transcript) {
+    handedOut.set(transcript, 'transcript')
+    if (Array.isArray(transcript.turns)) {
+      handedOut.set(transcript.turns, 'turns')
+      for (const turn of transcript.turns) {
+        if (typeof turn === 'object' && turn !== null) handedOut.set(turn, 'turn')
+      }
+    }
+  }
+  return transcript
+}
+
+const TRANSCRIPT_SEARCH_DEPTH = 4
+const TRANSCRIPT_SEARCH_NODES = 200
+
+/**
+ * How many handed-out turns a step result carries, or null when it carries
+ * none. Searched through arrays and plain objects up to four levels down and
+ * at most 200 values — `{ data: { transcript } }` and `{ request: turns.at(-2) }`
+ * are as much a leak as the transcript itself — so a large result pays a fixed
+ * cost. Text copied OUT of a turn is a plain string and is not recognized.
+ *
+ * Fail-closed: a result too big or too deep to search completely is reported
+ * as not inspected, and the step records that instead of the result.
+ */
+function transcriptTurnsIn(
+  out: unknown,
+): { kind: 'found'; turnCount: number } | { kind: 'not-inspected' } | { kind: 'clean' } {
+  const turns = new Set<object>()
+  let found = false
+  let complete = true
+  const queue: Array<{ value: object; depth: number }> = []
+  if (typeof out === 'object' && out !== null) queue.push({ value: out, depth: 0 })
+  // `queue` only grows up to the node budget, so the whole search allocates a
+  // bounded amount however large the result is: children are walked lazily
+  // and the walk stops at the first child that would not fit.
+  for (let next = 0; next < queue.length; next++) {
+    const { value, depth } = queue[next]!
+    const brand = handedOut.get(value)
+    if (brand) {
+      found = true
+      const held = brand === 'turn' ? [value] : brand === 'turns' ? (value as unknown[]) : (value as ConversationTranscript).turns
+      for (const turn of held) if (typeof turn === 'object' && turn !== null) turns.add(turn)
+      continue
+    }
+    // Any object is searched, not only plain ones: a class instance serializes
+    // its own fields, and a turn could be one of them.
+    for (const child of objectChildren(value)) {
+      if (depth >= TRANSCRIPT_SEARCH_DEPTH || queue.length >= TRANSCRIPT_SEARCH_NODES) {
+        // Something here is left unsearched. The nodes already queued are
+        // still visited, so a transcript among them is still counted.
+        complete = false
+        break
+      }
+      queue.push({ value: child, depth: depth + 1 })
+    }
+  }
+  if (found) return { kind: 'found', turnCount: turns.size }
+  return complete ? { kind: 'clean' } : { kind: 'not-inspected' }
+}
+
+/** The object-valued children of an array or object, one at a time. */
+function* objectChildren(value: object): Generator<object> {
+  if (Array.isArray(value)) {
+    for (let i = 0; i < value.length; i++) {
+      const child: unknown = value[i]
+      if (typeof child === 'object' && child !== null) yield child
+    }
+    return
+  }
+  for (const key in value) {
+    if (!Object.prototype.hasOwnProperty.call(value, key)) continue
+    const child: unknown = (value as Record<string, unknown>)[key]
+    if (typeof child === 'object' && child !== null) yield child
+  }
+}
+
 /**
  * What an author-declared step records about its own return value.
  *
@@ -169,8 +262,16 @@ function summarize<T>(
  * that returns a thousand warehouse rows must not write them a second time into
  * the audit trail.
  */
-function stepResultDetail(out: unknown): Record<string, unknown> | undefined {
+function stepResultDetail(out: unknown, transcriptHandedOut = false): Record<string, unknown> | undefined {
   if (out === undefined) return undefined
+  // Searched only once this execution has handed out a transcript: a run that
+  // never read one cannot return one, and its steps keep recording exactly
+  // what they always did — including results too large or deep to search.
+  if (transcriptHandedOut) {
+    const search = transcriptTurnsIn(out)
+    if (search.kind === 'found') return { omitted: 'conversation transcript', turnCount: search.turnCount }
+    if (search.kind === 'not-inspected') return { omitted: 'result not inspected' }
+  }
   const size = jsonSize(out)
   if (size === null) return { omitted: 'result not serializable' }
   return size <= DETAIL_MAX_CHARS
@@ -560,6 +661,9 @@ export function buildContext(deps: Deps): AutomationContext {
    */
   const namesThisExecution = new Set<string>()
 
+  /** Set once `ctx.conversation.transcript()` has returned a transcript in this execution. */
+  let transcriptHandedOut = false
+
   /**
    * Run `fn` as a durable step.
    *
@@ -606,7 +710,7 @@ export function buildContext(deps: Deps): AutomationContext {
         await completeStep(stepId, {
           status: 'ok',
           durationMs: Date.now() - t0,
-          detail: stepResultDetail(out),
+          detail: stepResultDetail(out, transcriptHandedOut),
         })
         return out
       } catch (err) {
@@ -1076,5 +1180,28 @@ export function buildContext(deps: Deps): AutomationContext {
         }),
       ) as Promise<BlueprintQueryResult<T>>,
     },
+
+    conversation: {
+      transcript: () =>
+        step('conversation', 'transcript', async () => {
+          requireGrant('conversation:read')
+          // No argument on purpose: the service reads the conversation the
+          // PLATFORM recorded as this run's trigger, so there is nothing an
+          // author could name to read someone else's.
+          const res = await scoped('/ctx/conversation-transcript', { method: 'POST', body: '{}' })
+          if (!res.ok) throw new Error(`ctx.conversation.transcript → ${res.status} ${await refusal(res)}`)
+          const transcript = brandTranscript(
+            ((await res.json()) as { data: { transcript: ConversationTranscript | null } }).data.transcript,
+          )
+          if (transcript) transcriptHandedOut = true
+          return transcript
+        },
+        // The turn count only. The text is what the person wrote, and step
+        // details are rendered verbatim and kept as long as the run is. A step
+        // that RETURNS the transcript is summarized the same way — see
+        // `stepResultDetail`.
+        (out) => (out ? { turnCount: out.turns.length } : { transcript: false }),
+      ) as Promise<ConversationTranscript | null>,
+    },
   }
 }

package/src/testing.ts

@@ -12,6 +12,7 @@ import type {
   AutomationContext,
   BlueprintQueryOptions,
   BlueprintQueryResult,
+  ConversationTranscript,
   Grant,
   HttpRequest,
   HttpResponse,
@@ -47,8 +48,8 @@ import type {
  * for a refusal, and on `calls` for what ran.
  */
 export interface TestCall {
-  kind: 'step' | 'log' | 'agent' | 'plugin' | 'http' | 'blueprint' | 'action' | 'file'
-  /** Step name, log message, agent slug, `install:capability`, URL, object type, or Action apiName. */
+  kind: 'step' | 'log' | 'agent' | 'plugin' | 'http' | 'blueprint' | 'action' | 'file' | 'conversation'
+  /** Step name, log message, agent slug, `install:capability`, URL, object type, Action apiName, or `transcript`. */
   label: string
   /** Present on a step: how it ended. */
   status?: 'ok' | 'error'
@@ -88,6 +89,12 @@ export interface TestContextOptions {
   >
   /** Answers outbound requests. Unstubbed, `ctx.http.fetch` throws. */
   http?: (req: HttpRequest) => Promise<HttpResponse> | HttpResponse
+  /**
+   * What `ctx.conversation.transcript()` returns. Omitted, it returns `null` —
+   * a run that was not started from a conversation, which is a real answer and
+   * a branch worth testing.
+   */
+  conversation?: ConversationTranscript | null
   /** Rows per object type. An unstubbed type returns no rows, which is a real
    *  answer and usually the branch worth testing. */
   blueprint?: Record<string, BlueprintQueryResult<never> | BlueprintQueryResult<Record<string, unknown>>>
@@ -317,6 +324,14 @@ export function createTestContext(options: TestContextOptions = {}): TestContext
         return (stub ?? { rows: [], hasMore: false }) as BlueprintQueryResult<T>
       },
     },
+
+    conversation: {
+      async transcript(): Promise<ConversationTranscript | null> {
+        requireGrant('conversation:read')
+        calls.push({ kind: 'conversation', label: 'transcript' })
+        return options.conversation ?? null
+      },
+    },
   }
 
   return { ctx, calls, steps, logs }

package/src/types.ts

@@ -4,7 +4,7 @@
 // `AutomationContext` needs it to resolve. See the packaging note in
 // docs/superpowers/specs/2026-07-29-automations-ctx-blueprint-query-design.md —
 // a subset install that cannot resolve it aborts `bun install` outright.
-import type { WhereNode } from '@frontera-sdk/blueprint/types'
+import type { NearestRequest, WhereNode } from '@frontera-sdk/blueprint/types'
 
 /**
  * Cron, manual, and agent for now; event and webhook land with Event Triggers.
@@ -46,6 +46,8 @@ export type AutomationTrigger =
  */
 export type Grant =
   | 'blueprint:read'
+  /** Read the conversation that started the run — see `ctx.conversation`. */
+  | 'conversation:read'
   | `agent:${string}:run`
   /**
    * One capability of one Plugin install: `plugin:<install>:<capability>`.
@@ -242,6 +244,38 @@ export interface ResolvedFileHandle {
   name: string | null
 }
 
+/**
+ * The conversation that started a run, as the person saw it: what they wrote
+ * and what the agent wrote back, as text.
+ *
+ * Only the stretch that belongs to this run is included — earlier requests in
+ * the same conversation, already handled by earlier runs that read a
+ * transcript and finished successfully or are still running, and anything
+ * before a quiet gap of more than six hours are left out.
+ *
+ * Replaced with `[removed]`: card numbers of the major card brands (Visa,
+ * Mastercard, American Express, Discover, UnionPay), with the digit groups
+ * separated by a single space or dash, or written together (an expiry or
+ * security code after the number stays); Singapore NRIC/FIN numbers; and —
+ * within the six words after "password", "passcode", "PIN", "OTP", "one-time
+ * code" or "verification code" (or the Indonesian and Malay "kata sandi",
+ * "sandi", "kode verifikasi", "kode OTP", "kata laluan", "kod pengesahan"), or
+ * the first six words of the person's reply right after the agent asks for one
+ * of these — any word containing a digit.
+ * Words without a digit stay. This removes obvious secrets; it is not a guarantee: keep the
+ * transcript where only the people who need it can read it.
+ */
+export interface ConversationTranscript {
+  /** The agent the person was talking to. */
+  agentName: string
+  /** ISO 8601 time of the first included turn. */
+  startedAt: string
+  /** ISO 8601 time of the last included turn. */
+  endedAt: string
+  /** Oldest first. A card the agent showed reads as one line of text. */
+  turns: Array<{ role: 'user' | 'agent'; text: string; at: string }>
+}
+
 /** What `ctx.plugin(install).call(...)` resolves to. */
 export interface PluginCallResult<T = unknown> {
   /** Whatever the capability returned. Shape is the plugin's, not the platform's. */
@@ -467,6 +501,35 @@ export interface AutomationContext {
       options?: BlueprintQueryOptions,
     ): Promise<BlueprintQueryResult<T>>
   }
+  conversation: {
+    /**
+     * The conversation that started THIS run, as the person saw it.
+     *
+     * `null` when the run was not started from a conversation (a schedule, a
+     * manual run, an App), when that conversation was deleted, and in dry (dev)
+     * runs.
+     *
+     * Call it inside a `ctx.step.run` step — required, not a style choice.
+     * Outside a step it reads the conversation again on every resumption, and
+     * what it returns can change between reads: an earlier run from the same
+     * conversation that finishes, or reads, in the meantime moves where this
+     * run's part begins. Act on it in that same step and return only a
+     * summary, because step results are kept to resume the run.
+     *
+     * When a step returns the transcript,
+     * its `turns` or any of its turns — alone or inside objects and arrays up
+     * to four levels deep — its trace row records only the turn count; a
+     * result too large or too deep to check completely is not recorded at all.
+     * Everything else is recorded as written: text copied out of it, including
+     * new objects built from its turns (`turns.map(t => ({ role: t.role, text:
+     * t.text }))`), a copy restored after the run resumes, an error message
+     * built from it, and the Function's final return value (recorded as the
+     * run's result). Requires the
+     * `conversation:read` grant. Reads only the run's own conversation — there
+     * is no way to name another one.
+     */
+    transcript(): Promise<ConversationTranscript | null>
+  }
   /**
    * Durable steps. See `StepApi`.
    *
@@ -545,6 +608,10 @@ export interface BlueprintQueryOptions {
    *  first page. Cursor-based, so a scan stays correct while the table moves
    *  underneath it — which a cron-driven automation's table always does. */
   pageToken?: string
+  /** Closest first from `nearest.from`, with `_distanceMeters` on each row.
+   *  `where` must also hold a `nearby` or `withinBbox` on the same location,
+   *  and `orderBy` must be omitted. */
+  nearest?: NearestRequest
 }
 
 export interface BlueprintQueryResult<T = Record<string, unknown>> {