@mindstudio-ai/agent 0.1.101 → 0.1.103

package/dist/index.d.ts

@@ -22,6 +22,18 @@ interface PutOptions {
      * assets baked into source.
      */
     contentAddressed?: boolean;
+    /**
+     * Cache-Control header stored on the object and served by the CDN — this is
+     * how you control public-read freshness. Defaults (public stores):
+     * auto-minted keys (`key` omitted — UUID or content-addressed, never
+     * reused) → `public, max-age=31536000, immutable`; explicitly named
+     * (overwritable) keys → `public, max-age=300`, so an overwrite propagates
+     * within ~5 minutes. Recipes: `'public, max-age=31536000, immutable'`
+     * (content never changes at this key), `'public, max-age=60'` (near-live
+     * config), `'no-store'` (revalidate every read). Validated server-side —
+     * known directives only.
+     */
+    cacheControl?: string;
 }
 /** Options for {@link Store.list}. */
 interface ListOptions {
@@ -150,6 +162,12 @@ declare class Store {
         filename?: string;
         maxSize?: number;
         expiresIn?: number;
+        /**
+         * Cache-Control header stored on the uploaded object and served by the
+         * CDN (see {@link PutOptions.cacheControl}). Public uploads default to
+         * `public, max-age=300` server-side.
+         */
+        cacheControl?: string;
     }): Promise<UploadToken>;
     private _toFile;
 }
@@ -1618,10 +1636,20 @@ type JewelMethodInput<M extends JewelMethod> = Parameters<M> extends [] ? undefi
 interface JewelProposal<I> {
     input: I | null;
     reasoning: string;
+    /**
+     * Transcript id(s) of the runTask call(s) that constitute this decision
+     * (`task.traceId`; an array for escalation chains). Attaching preserves
+     * the full model transcript with the pair — the training row and, at
+     * auto, the audit trail. Helper/formatting calls stay unattached: the
+     * attachment is the label for which run WAS the decision.
+     */
+    trace?: string | string[];
 }
 interface JewelVerdict {
     verdict: 'agree' | 'disagree' | 'skip';
     notes?: string;
+    /** Transcript id(s) of the judge's runTask call(s), when grade used one. */
+    trace?: string | string[];
 }
 /**
  * Argument to a custom `grade`. `proposed` is null when the jewel abstained;
@@ -1712,6 +1740,14 @@ interface JewelPairRecord<I = unknown, S = unknown> {
         message: string;
         stack?: string;
     };
+    /**
+     * Transcript ids attached by propose. The transcripts themselves live
+     * platform-side, recorded per turn and keyed by (run id, trace id) — the
+     * record carries only the ids.
+     */
+    trace?: string[];
+    /** Transcript ids attached by a custom grade's verdict. */
+    gradeTrace?: string[];
     /**
      * Whether this jewel declares a custom `grade`. The platform's deferred
      * grading dispatches a grade-mode run when true; when false it grades
@@ -2561,6 +2597,14 @@ interface RunTaskResult<T = unknown> {
     usage: TaskUsage;
     /** Summary of every tool call made during execution. */
     toolCalls: TaskToolCall[];
+    /**
+     * Stable id for this task's model transcript. Inside a jewel, attach it to
+     * the propose/grade return (`trace: task.traceId`) to preserve the full
+     * transcript with the pair — the training row and the audit trail. The
+     * platform records transcripts server-side per turn; only the id rides the
+     * result.
+     */
+    traceId: string;
 }
 
 /**
@@ -6077,6 +6121,8 @@ interface SearchGoogleStepInput {
     dateRange?: "hour" | "day" | "week" | "month" | "year" | "any";
     /** Number of results to return (1-100, default: 30) */
     numResults?: number;
+    /** Read the page content of the first N results in this same step (0-10, default 0 = off), rather than following up with a Scrape URL step per result. Each page is a full scrape, so this costs substantially more than the search alone. */
+    fetchTopN?: number;
 }
 interface SearchGoogleStepOutput {
     /** List of search result entries */
@@ -6087,7 +6133,17 @@ interface SearchGoogleStepOutput {
         description: string;
         /** URL of the search result page */
         url: string;
+        /** Page content, only present when fetchTopN covered this result */
+        content?: string;
+    }[];
+    /** Google's "People also ask" entries, when Google returned any */
+    peopleAlsoAsk?: {
+        question?: string;
+        snippet?: string;
+        link?: string;
     }[];
+    /** Google's related-search suggestions, when Google returned any */
+    relatedSearches?: string[];
 }
 interface SearchGoogleCalendarEventsStepInput {
     /** Text search term */
@@ -9346,6 +9402,8 @@ interface StepMethods {
      * - Defaults to us/english, but can optionally specify country and/or language.
      * - Defaults to any time, but can optionally specify last hour, last day, week, month, or year.
      * - Defaults to top 30 results, but can specify 1 to 100 results to return.
+     * - Set fetchTopN to also read the page content of the first N results in the same step, instead of following up with a separate Scrape URL step per result. Costs meaningfully more (each page is a full scrape), so ask for the fewest you need.
+     * - Also returns Google's "people also ask" and related searches when available, which are useful for choosing a follow-up query.
      *
      * @example
      * ```typescript

package/dist/index.js

@@ -1968,12 +1968,14 @@ var Store = class {
   async put(content, options) {
     const ext = extensionFor(options?.filename);
     const key = options?.key ?? (options?.contentAddressed ? `${createHash("sha256").update(content).digest("hex")}${ext}` : `${randomUUID()}${ext}`);
+    const cacheControl = options?.cacheControl ?? (!options?.key && this._access === "public" ? "public, max-age=31536000, immutable" : void 0);
     const meta = await this._call("put", {
       store: this._store,
       access: this._access,
       key,
       body: toBase64(content),
-      ...options?.contentType ? { contentType: options.contentType } : {}
+      ...options?.contentType ? { contentType: options.contentType } : {},
+      ...cacheControl ? { cacheControl } : {}
     });
     return this._toFile(key, meta);
   }
@@ -2082,7 +2084,8 @@ var Store = class {
       key,
       ...options?.contentType ? { contentType: options.contentType } : {},
       ...maxSize ? { maxSize } : {},
-      ...options?.expiresIn ? { expiresIn: options.expiresIn } : {}
+      ...options?.expiresIn ? { expiresIn: options.expiresIn } : {},
+      ...options?.cacheControl ? { cacheControl: options.cacheControl } : {}
     });
     return {
       key,
@@ -2275,6 +2278,9 @@ function createVoice(call) {
   };
 }
 
+// src/task/index.ts
+import { randomUUID as randomUUID2 } from "crypto";
+
 // src/generated/metadata.ts
 var stepMetadata = {
   "activeCampaignAddNote": {
@@ -3169,9 +3175,13 @@ var stepMetadata = {
   "searchGoogle": {
     stepType: "searchGoogle",
     description: "Search the web using Google and return structured results.",
-    usageNotes: "- Defaults to us/english, but can optionally specify country and/or language.\n- Defaults to any time, but can optionally specify last hour, last day, week, month, or year.\n- Defaults to top 30 results, but can specify 1 to 100 results to return.",
-    inputSchema: { "type": "object", "properties": { "query": { "type": "string", "description": "The search query to send to Google" }, "exportType": { "enum": ["text", "json"], "type": "string", "description": 'Format for the variable value: "text" or "json"' }, "countryCode": { "type": "string", "description": "Google gl country code (defaults to US)" }, "languageCode": { "type": "string", "description": 'Google hl language code (defaults to "en")' }, "dateRange": { "enum": ["hour", "day", "week", "month", "year", "any"], "type": "string", "description": 'Time range filter: "hour", "day", "week", "month", "year", or "any"' }, "numResults": { "type": "number", "description": "Number of results to return (1-100, default: 30)" } }, "required": ["query", "exportType"] },
-    outputSchema: { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the search result" }, "description": { "type": "string", "description": "Snippet/description of the search result" }, "url": { "type": "string", "description": "URL of the search result page" } }, "required": ["title", "description", "url"] }, "description": "List of search result entries" } }, "required": ["results"] }
+    usageNotes: `- Defaults to us/english, but can optionally specify country and/or language.
+- Defaults to any time, but can optionally specify last hour, last day, week, month, or year.
+- Defaults to top 30 results, but can specify 1 to 100 results to return.
+- Set fetchTopN to also read the page content of the first N results in the same step, instead of following up with a separate Scrape URL step per result. Costs meaningfully more (each page is a full scrape), so ask for the fewest you need.
+- Also returns Google's "people also ask" and related searches when available, which are useful for choosing a follow-up query.`,
+    inputSchema: { "type": "object", "properties": { "query": { "type": "string", "description": "The search query to send to Google" }, "exportType": { "enum": ["text", "json"], "type": "string", "description": 'Format for the variable value: "text" or "json"' }, "countryCode": { "type": "string", "description": "Google gl country code (defaults to US)" }, "languageCode": { "type": "string", "description": 'Google hl language code (defaults to "en")' }, "dateRange": { "enum": ["hour", "day", "week", "month", "year", "any"], "type": "string", "description": 'Time range filter: "hour", "day", "week", "month", "year", or "any"' }, "numResults": { "type": "number", "description": "Number of results to return (1-100, default: 30)" }, "fetchTopN": { "type": "number", "description": "Read the page content of the first N results in this same step (0-10, default 0 = off), rather than following up with a Scrape URL step per result. Each page is a full scrape, so this costs substantially more than the search alone." } }, "required": ["query", "exportType"] },
+    outputSchema: { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "description": "Title of the search result" }, "description": { "type": "string", "description": "Snippet/description of the search result" }, "url": { "type": "string", "description": "URL of the search result page" }, "content": { "type": "string", "description": "Page content, only present when fetchTopN covered this result" } }, "required": ["title", "description", "url"] }, "description": "List of search result entries" }, "peopleAlsoAsk": { "type": "array", "items": { "type": "object", "properties": { "question": { "type": "string" }, "snippet": { "type": "string" }, "link": { "type": "string" } } }, "description": `Google's "People also ask" entries, when Google returned any` }, "relatedSearches": { "type": "array", "items": { "type": "string" }, "description": "Google's related-search suggestions, when Google returned any" } }, "required": ["results"] }
   },
   "searchGoogleCalendarEvents": {
     stepType: "searchGoogleCalendarEvents",
@@ -3747,6 +3757,7 @@ function logTaskResult(result) {
   );
 }
 async function runTaskPoll(httpConfig, body) {
+  const traceId = randomUUID2();
   const { data } = await request(
     httpConfig,
     "POST",
@@ -3805,13 +3816,15 @@ async function runTaskPoll(httpConfig, body) {
         outputTokens: 0,
         totalBillingCost: 0
       },
-      toolCalls: poll.toolCalls ?? []
+      toolCalls: poll.toolCalls ?? [],
+      traceId
     };
     logTaskResult(result);
     return result;
   }
 }
 async function runTaskStream(httpConfig, body, onEvent) {
+  const traceId = randomUUID2();
   const url = `${httpConfig.baseUrl}/developer/v2/task`;
   const res = await fetch(url, {
     method: "POST",
@@ -3876,7 +3889,8 @@ async function runTaskStream(httpConfig, body, onEvent) {
               outputTokens: 0,
               totalBillingCost: 0
             },
-            toolCalls: event.toolCalls ?? []
+            toolCalls: event.toolCalls ?? [],
+            traceId
           };
         }
       } catch (err) {
@@ -3906,7 +3920,8 @@ async function runTaskStream(httpConfig, body, onEvent) {
             outputTokens: 0,
             totalBillingCost: 0
           },
-          toolCalls: event.toolCalls ?? []
+          toolCalls: event.toolCalls ?? [],
+          traceId
         };
       }
     } catch (err) {
@@ -3925,6 +3940,7 @@ async function runTaskStream(httpConfig, body, onEvent) {
 }
 
 // src/task/local.ts
+import { randomUUID as randomUUID3 } from "crypto";
 var DEFAULT_MAX_TURNS = 20;
 var MAX_TURNS_LIMIT = 100;
 var MAX_SCHEMA_REPAIR_ATTEMPTS = 3;
@@ -4156,6 +4172,7 @@ ${structuredOutputExample}
     Math.max(options.maxTurns || DEFAULT_MAX_TURNS, 1),
     MAX_TURNS_LIMIT
   );
+  const traceId = randomUUID3();
   const messages = [
     { role: "user", content: JSON.stringify(options.input) }
   ];
@@ -4175,7 +4192,8 @@ ${structuredOutputExample}
     parsedSuccessfully: parsedSuccessfully2,
     turns,
     usage: totalUsage,
-    toolCalls: toolCallLog
+    toolCalls: toolCallLog,
+    traceId
   });
   const accumulate = (turn) => {
     totalUsage.inputTokens += turn.usage.inputTokens ?? 0;
@@ -4243,7 +4261,8 @@ ${structuredOutputExample}
         model: options.model,
         system,
         messages,
-        tools: wireTools
+        tools: wireTools,
+        traceId
       });
     } catch (err) {
       if (loopCount === 1 && err instanceof TurnError && err.status === 404 && err.errorCode === "not_found") {
@@ -4355,7 +4374,8 @@ ${formatValidationErrors(errors)}`
       model: options.model,
       system,
       messages,
-      tools: []
+      tools: [],
+      traceId
     });
     accumulate(turn);
     finalText = turn.text;
@@ -6647,15 +6667,24 @@ function defineJewel(method, config) {
       durationMs: Date.now() - startedAt,
       ...rest
     });
+    const traceIds = (t) => {
+      if (t === void 0) return void 0;
+      const ids = (Array.isArray(t) ? t : [t]).filter(
+        (id) => typeof id === "string" && id.length > 0
+      );
+      return ids.length > 0 ? ids : void 0;
+    };
     if (Object.prototype.hasOwnProperty.call(params, "grade")) {
       const ctx = params.grade;
       const verdict2 = await runGrade(ctx.proposed, ctx.actual);
+      const gradeTrace2 = traceIds(verdict2.trace);
       return done({
         mode: "grade",
         proposed: ctx.proposed,
         actual: ctx.actual,
         verdict: verdict2.verdict,
-        ...verdict2.notes !== void 0 ? { notes: verdict2.notes } : {}
+        ...verdict2.notes !== void 0 ? { notes: verdict2.notes } : {},
+        ...gradeTrace2 ? { gradeTrace: gradeTrace2 } : {}
       });
     }
     const isShadow = Object.prototype.hasOwnProperty.call(params, "humanInput");
@@ -6682,15 +6711,18 @@ function defineJewel(method, config) {
         error: { phase: "propose", ...errorInfo(e) }
       });
     }
+    const trace = traceIds(proposal.trace);
     if (!isShadow) {
       return done({
         mode,
         subject,
         proposed: proposal.input,
-        reasoning: proposal.reasoning
+        reasoning: proposal.reasoning,
+        ...trace ? { trace } : {}
       });
     }
     const verdict = await runGrade(proposal.input, actual);
+    const gradeTrace = traceIds(verdict.trace);
     return done({
       mode,
       subject,
@@ -6698,7 +6730,9 @@ function defineJewel(method, config) {
       reasoning: proposal.reasoning,
       actual,
       verdict: verdict.verdict,
-      ...verdict.notes !== void 0 ? { notes: verdict.notes } : {}
+      ...verdict.notes !== void 0 ? { notes: verdict.notes } : {},
+      ...trace ? { trace } : {},
+      ...gradeTrace ? { gradeTrace } : {}
     });
   };
   return Object.assign(run, {