@method-ai-hq/sdk 0.0.0-stage → 0.14.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Method
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,24 @@
-# Temporary Holding Version
+# @method-ai-hq/sdk
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MIT-licensed JavaScript API and the `method` CLI. Source and releases: https://github.com/method-ai-hq/method-sdk
+
+```sh
+npm install https://github.com/method-ai-hq/method-sdk/releases/download/v0.14.2/method-ai-hq-sdk-0.14.2.tgz
+npx method --version
+```
+
+```js
+import {readFileSync} from 'node:fs';
+import {loadMethod, runMethod, inspectRun} from '@method-ai-hq/sdk';
+const method = loadMethod(readFileSync('task.method', 'utf8'));
+const result = await runMethod('task.method', {allow_local_processes: true}, {inputs: {}, runDir: 'runs/first'});
+console.log(result.status, inspectRun('runs/first'));
+```
+
+New Methods use method/3.4: models, limits, tools, secret names, and the Method ID are in the Method file. Documents in method/3.1 to 3.3 load and run unchanged. `runMethod` is the bare runtime: it does not sign in, save versions, or use hosted models; `method run` does. The executor is the pinned @withmethod/runtime dependency. Python uses method-bridge to call the same runtime.
+
+To run a published Method from an app, use `new Method().run({method: 'wf_…', inputs})`. See https://docs.withmethod.ai/guides/production.
+
+Browser-safe document modules are available at `@method-ai-hq/sdk/schema`, `/validate`, `/execution`, `/inspection`, and `/result-files`. Node tools use `/identity`, `/method-package`, `/method-client`, `/method-sync`, and `/process`. Do not import the Node package root into a browser bundle.
+
+Before creating, editing, or proposing a Method, run `method authoring` and read its guidance. Do this before choosing an existing Method as a reference. The package includes reviewed examples. Saving versions, hosted models, and production runs need a Method account; local validation and script runs do not.

package/dist/packages/contracts/src/identity.d.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export declare const StableIdSchema: z.ZodString;
+export declare const Sha256Schema: z.ZodString;
+export declare const ConfidenceSchema: z.ZodNumber;
+export declare function canonicalJson(value: unknown): string;
+export declare function sha256(value: string): string;
+export declare function semanticDigest(value: unknown): string;
+/**
+ * Document identity preserves authored step and classifier option order. The Method ID (`id:`) names the account
+ * Method and is not content: a copy with another ID has the same digest.
+ */
+export declare function workflowDocumentDigest(value: {
+    steps: Record<string, unknown>;
+}): string;
+/** A version ID: the same content (package digest) of a Method is always the same version. */
+export declare function versionIdFor(methodId: string, packageDigest: string): string;

package/dist/packages/contracts/src/identity.js

@@ -0,0 +1,41 @@
+import { createHash } from "node:crypto";
+import { z } from "zod";
+import { documentForDigest } from "@withmethod/runtime/document.js";
+export const StableIdSchema = z.string().regex(/^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/, "stable IDs use lowercase letters, numbers, dots, underscores, and hyphens");
+export const Sha256Schema = z.string().regex(/^[a-f0-9]{64}$/);
+export const ConfidenceSchema = z.number().min(0).max(1);
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+export function sha256(value) {
+    return createHash("sha256").update(value, "utf8").digest("hex");
+}
+export function semanticDigest(value) {
+    return sha256(canonicalJson(value));
+}
+/**
+ * Document identity preserves authored step and classifier option order. The Method ID (`id:`) names the account
+ * Method and is not content: a copy with another ID has the same digest.
+ */
+export function workflowDocumentDigest(value) {
+    const content = documentForDigest(value);
+    return semanticDigest({ ...content, steps: Object.entries(value.steps).map(([id, raw]) => {
+            const step = raw;
+            return [id, step?.do?.kind === 'classify'
+                    ? { ...step, do: { ...step.do, options: Object.entries(step.do.options ?? {}) } }
+                    : raw];
+        }) });
+}
+/** A version ID: the same content (package digest) of a Method is always the same version. */
+export function versionIdFor(methodId, packageDigest) {
+    return `v_${sha256(`${methodId}:${packageDigest}`).slice(0, 32)}`;
+}
+function canonicalize(value) {
+    if (Array.isArray(value))
+        return value.map(canonicalize);
+    if (value === null || typeof value !== "object")
+        return value;
+    return Object.fromEntries(Object.entries(value)
+        .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0)
+        .map(([key, child]) => [key, canonicalize(child)]));
+}

package/dist/packages/contracts/src/method-package.d.ts

@@ -0,0 +1,71 @@
+import { z } from 'zod';
+export declare const packagePath: (path: string) => string;
+export declare const PackageFileSchema: z.ZodObject<{
+    path: z.ZodEffects<z.ZodString, string, string>;
+    sha256: z.ZodString;
+    size: z.ZodNumber;
+}, "strict", z.ZodTypeAny, {
+    sha256: string;
+    path: string;
+    size: number;
+}, {
+    sha256: string;
+    path: string;
+    size: number;
+}>;
+export declare const MethodPackageSchema: z.ZodEffects<z.ZodObject<{
+    schema: z.ZodLiteral<"method-package/1">;
+    runtime: z.ZodString;
+    files: z.ZodArray<z.ZodObject<{
+        path: z.ZodEffects<z.ZodString, string, string>;
+        sha256: z.ZodString;
+        size: z.ZodNumber;
+    }, "strict", z.ZodTypeAny, {
+        sha256: string;
+        path: string;
+        size: number;
+    }, {
+        sha256: string;
+        path: string;
+        size: number;
+    }>, "many">;
+    digest: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    files: {
+        sha256: string;
+        path: string;
+        size: number;
+    }[];
+    schema: "method-package/1";
+    runtime: string;
+    digest: string;
+}, {
+    files: {
+        sha256: string;
+        path: string;
+        size: number;
+    }[];
+    schema: "method-package/1";
+    runtime: string;
+    digest: string;
+}>, {
+    files: {
+        sha256: string;
+        path: string;
+        size: number;
+    }[];
+    schema: "method-package/1";
+    runtime: string;
+    digest: string;
+}, {
+    files: {
+        sha256: string;
+        path: string;
+        size: number;
+    }[];
+    schema: "method-package/1";
+    runtime: string;
+    digest: string;
+}>;
+export type MethodPackage = z.infer<typeof MethodPackageSchema>;
+export declare function packageDigest(workflow: unknown, value: Pick<MethodPackage, 'runtime' | 'files'>): string;

package/dist/packages/contracts/src/method-package.js

@@ -0,0 +1,22 @@
+import { z } from 'zod';
+import { canonicalJson, sha256, workflowDocumentDigest } from './identity.js';
+export const packagePath = (path) => {
+    if (!path || path.length > 500 || path.startsWith('/') || path.includes('\\') || /^[A-Za-z]:/.test(path) || path.split('/').some(p => !p || ['.', '..', '.git', 'node_modules', '.venv', '.codex', '.claude'].includes(p) || p.startsWith('.env') || p === 'secrets.env'))
+        throw Error(`Invalid package path: ${path}`);
+    return path;
+};
+export const PackageFileSchema = z.strictObject({ path: z.string().refine(p => { try {
+        packagePath(p);
+        return true;
+    }
+    catch {
+        return false;
+    } }), sha256: z.string().regex(/^[a-f0-9]{64}$/), size: z.number().int().min(0).max(20_000_000) });
+export const MethodPackageSchema = z.strictObject({
+    schema: z.literal('method-package/1'), runtime: z.string().regex(/^\d+\.\d+\.\d+$/),
+    files: z.array(PackageFileSchema).max(10000), digest: z.string().regex(/^[a-f0-9]{64}$/),
+}).superRefine((p, ctx) => { if (new Set(p.files.map(f => f.path)).size !== p.files.length)
+    ctx.addIssue({ code: 'custom', message: 'Duplicate package paths' }); });
+export function packageDigest(workflow, value) {
+    return sha256(canonicalJson({ document: workflowDocumentDigest(workflow), runtime: value.runtime, files: [...value.files].sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0) }));
+}

package/dist/packages/method-document/src/conversion-report.d.ts

@@ -0,0 +1,138 @@
+import { z } from "zod";
+import { type Workflow } from "../../workflow-language/src/schema.js";
+export declare const ConversionReportSchema: z.ZodObject<{
+    schema: z.ZodLiteral<"workflow-conversion/1">;
+    source_sha256: z.ZodString;
+    workflow_sha256: z.ZodString;
+    references: z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        sha256: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        sha256: string;
+        name: string;
+    }, {
+        sha256: string;
+        name: string;
+    }>, "many">;
+    status: z.ZodEnum<["ready", "needs_review"]>;
+    attempts: z.ZodNumber;
+    selected_attempt: z.ZodNumber;
+    coverage: z.ZodArray<z.ZodObject<{
+        source_id: z.ZodString;
+        result: z.ZodEnum<["covered", "missing", "ambiguous"]>;
+        locations: z.ZodArray<z.ZodString, "many">;
+        explanation: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        result: "missing" | "ambiguous" | "covered";
+        source_id: string;
+        locations: string[];
+        explanation: string;
+    }, {
+        result: "missing" | "ambiguous" | "covered";
+        source_id: string;
+        locations: string[];
+        explanation: string;
+    }>, "many">;
+    concerns: z.ZodArray<z.ZodString, "many">;
+    review_method: z.ZodLiteral<"format_validation">;
+    editor: z.ZodOptional<z.ZodObject<{
+        agent: z.ZodLiteral<"Method Editing Agent">;
+        summary: z.ZodString;
+        elapsed_ms: z.ZodNumber;
+        changed_paths: z.ZodArray<z.ZodString, "many">;
+    }, "strict", z.ZodTypeAny, {
+        agent: "Method Editing Agent";
+        summary: string;
+        elapsed_ms: number;
+        changed_paths: string[];
+    }, {
+        agent: "Method Editing Agent";
+        summary: string;
+        elapsed_ms: number;
+        changed_paths: string[];
+    }>>;
+    requirement_coverage: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        source_id: z.ZodString;
+        result: z.ZodEnum<["covered", "missing", "ambiguous"]>;
+        locations: z.ZodArray<z.ZodString, "many">;
+        explanation: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        result: "missing" | "ambiguous" | "covered";
+        source_id: string;
+        locations: string[];
+        explanation: string;
+    }, {
+        result: "missing" | "ambiguous" | "covered";
+        source_id: string;
+        locations: string[];
+        explanation: string;
+    }>, "many">>;
+}, "strict", z.ZodTypeAny, {
+    status: "ready" | "needs_review";
+    schema: "workflow-conversion/1";
+    references: {
+        sha256: string;
+        name: string;
+    }[];
+    attempts: number;
+    source_sha256: string;
+    workflow_sha256: string;
+    selected_attempt: number;
+    coverage: {
+        result: "missing" | "ambiguous" | "covered";
+        source_id: string;
+        locations: string[];
+        explanation: string;
+    }[];
+    concerns: string[];
+    review_method: "format_validation";
+    editor?: {
+        agent: "Method Editing Agent";
+        summary: string;
+        elapsed_ms: number;
+        changed_paths: string[];
+    } | undefined;
+    requirement_coverage?: {
+        result: "missing" | "ambiguous" | "covered";
+        source_id: string;
+        locations: string[];
+        explanation: string;
+    }[] | undefined;
+}, {
+    status: "ready" | "needs_review";
+    schema: "workflow-conversion/1";
+    references: {
+        sha256: string;
+        name: string;
+    }[];
+    attempts: number;
+    source_sha256: string;
+    workflow_sha256: string;
+    selected_attempt: number;
+    coverage: {
+        result: "missing" | "ambiguous" | "covered";
+        source_id: string;
+        locations: string[];
+        explanation: string;
+    }[];
+    concerns: string[];
+    review_method: "format_validation";
+    editor?: {
+        agent: "Method Editing Agent";
+        summary: string;
+        elapsed_ms: number;
+        changed_paths: string[];
+    } | undefined;
+    requirement_coverage?: {
+        result: "missing" | "ambiguous" | "covered";
+        source_id: string;
+        locations: string[];
+        explanation: string;
+    }[] | undefined;
+}>;
+export type ConversionReport = z.infer<typeof ConversionReportSchema>;
+export declare function sourceSegments(source: string): Array<{
+    id: string;
+    text: string;
+}>;
+export declare function renderPrompt(workflow: Workflow): string;

package/dist/packages/method-document/src/conversion-report.js

@@ -0,0 +1,23 @@
+import { loadWorkflow, serializeWorkflow } from "../../workflow-language/src/validate.js";
+import { z } from "zod";
+const ReportItemSchema = z.strictObject({
+    source_id: z.string(), result: z.enum(["covered", "missing", "ambiguous"]),
+    locations: z.array(z.string()), explanation: z.string().min(1)
+});
+export const ConversionReportSchema = z.strictObject({
+    schema: z.literal("workflow-conversion/1"), source_sha256: z.string(), workflow_sha256: z.string(),
+    references: z.array(z.strictObject({ name: z.string(), sha256: z.string() })),
+    status: z.enum(["ready", "needs_review"]), attempts: z.number().int().positive(),
+    selected_attempt: z.number().int().positive(),
+    coverage: z.array(ReportItemSchema), concerns: z.array(z.string()),
+    review_method: z.literal("format_validation"),
+    editor: z.strictObject({ agent: z.literal("Method Editing Agent"), summary: z.string(), elapsed_ms: z.number().nonnegative(), changed_paths: z.array(z.string()) }).optional(),
+    requirement_coverage: z.array(ReportItemSchema).optional(),
+});
+export function sourceSegments(source) {
+    return source.split(/\n\s*\n/).filter(text => text.trim()).map((text, index) => ({ id: `source_${index + 1}`, text }));
+}
+export function renderPrompt(workflow) {
+    loadWorkflow(workflow);
+    return serializeWorkflow(workflow);
+}

package/dist/packages/sdk/examples/daily-briefing/README.md

@@ -0,0 +1,31 @@
+# Write a daily briefing
+
+TASK.md contains the task recorded in the Method's goal. daily-briefing.method implements it. approved-report.md contains the complete approved report that the writing step follows.
+
+All people, places, and conversations in this example are fictional. Wren Talbot runs a pottery studio, Larkfield Ceramics, in the invented town of Millbrook.
+
+## Run
+
+Copy this folder to a working folder, then run:
+
+```sh
+cp -R sample prepared_day     # a folder named after the connection needs no binding
+method validate daily-briefing.method
+method run daily-briefing.method --inputs inputs.json
+```
+
+The run saves a version and prints the dashboard link. Method prepares the Python and Node dependencies. For another day, put that day's prepared records in `prepared_day/`, or bind another folder with `method bind daily-briefing.method prepared_day --file FOLDER`.
+
+sample/ contains one complete conversation: 28 messages from the morning of May 11, in which Wren plans a glaze workshop. inputs.json selects that date and timezone. The approved report covers Wren's full day; the sample covers only this conversation.
+
+Open the website returned by the run. Source links open the saved records and selected passages. The Markdown and supporting files are included with the website.
+
+## Files
+
+- daily-briefing.method: input checks, writing with a source check, and website rendering.
+- daily-briefing.method `tools:`: the time calculation tool.
+- briefing_*.py, reader/, vendor/: helpers and website assets.
+- pyproject.toml, uv.lock, package.json, package-lock.json: dependencies.
+- sample/, inputs.json: inputs for a sample run, kept outside the Method's saved files.
+- approved-report.md: complete writing reference.
+- sample-report.md, sample-output.zip: a briefing of the sample conversation, and the website that the Method's own scripts built from it. The draft was written for this example; the time tool, the source check, and the render step ran on it. checks.json records how, with the hashes.

package/dist/packages/sdk/examples/daily-briefing/TASK.md

@@ -0,0 +1,3 @@
+## Request recorded in the Method
+
+Turn one prepared day folder into a complete, cited daily briefing. Follow the approved example for writing and layout, and save the briefing with its website.

package/dist/packages/sdk/examples/daily-briefing/approved-report.md

@@ -0,0 +1,138 @@
+---
+date: 2026-05-11
+timezone: America/Chicago
+title: May 11 — proposed briefing
+---
+
+# Monday, May 11
+
+_A day in Millbrook_
+
+## TL;DR
+
+
+
+**You planned the Spring Glaze Workshop, fired a bisque load, and agreed to a demo night at the Millbrook Public Library.** In ChatGPT you set the four-week kiln schedule, chose a price of $195, and rewrote the class description until it was plain. You sent the announcement to your mailing list in the afternoon. Nine people had replied by the evening, one more than the class can hold. [Sources](source:chatgpt-0001,chatgpt-0013,gmail-0007,gmail-0012,gmail-0019)
+
+
+
+Between these tasks, you drove to Fennimore Clay Supply for two bags of stoneware, browsed glaze recipes on Instagram, and ate dinner with Theo at the Orchard Street Diner. Your notes asked whether the studio should take commissions this summer or keep the time for classes. [Sources](source:google_timeline-0002,google_timeline-0004,instagram-0011,google_timeline-0007,apple_notes-0001)
+
+
+
+**Time estimates:** about 3 h 40 min in the studio, 1 h 10 min of workshop planning in ChatGPT and email, 45 min on Instagram, 1 h 30 min at dinner, 50 min driving, and 1 h 5 min of Spotify playback. These periods overlap. [Sources](source:time-estimates)
+
+## Morning
+
+
+
+At 7:52, Fennimore Clay Supply emailed that your order of glaze materials was ready to pick up. At 8:05, your calendar showed “Bisque load — empty by Thursday.” [Sources](source:gmail-0002,calendar-0001)
+
+
+
+Google Maps places you at the studio on Orchard Street from 8:20. You loaded the kiln and started the bisque firing at 8:41; the kiln controller’s email confirmed the start. A photo from 8:46 shows the full kiln before you closed the lid. [Sources](source:google_timeline-0001,gmail-0004,photos-0001)
+
+![8:46 AM — the loaded kiln, two shelves of greenware.](source:photos-0001)
+
+
+
+At 9:30, you were on Instagram. A post you saved said, “Test tiles are the cheapest lesson in the studio.” You opened two glaze-recipe posts after it and saved one for a celadon. [Sources](source:instagram-0004,instagram-0006,instagram-0011)
+
+[Saved social session](sessions.html#social-2b6e41c09d1a)
+
+
+
+At 10:05, Dana Ruiz at the library texted: “Would you do a free pottery demo here this spring? Our community room is open most Thursdays.” You answered, “Yes! Let me plan the class first and I’ll send dates.” [Sources](source:imessage-0003,imessage-0004)
+
+## Planning the workshop
+
+
+
+At 10:42, you asked ChatGPT how to plan a four-week evening glaze workshop for eight people with one kiln. It proposed one bisque firing after week 2 and one glaze firing after week 3. After you gave the kiln size and the 22 hours of firing and cooling, it fixed a Tuesday schedule with almost five days of margin. [Sources](source:chatgpt-0001,chatgpt-0003,chatgpt-0004,chatgpt-0005)
+
+
+
+You asked about clay and price. ChatGPT estimated 32 lb of clay for eight people and a cost of $109 per person, including your time. It suggested a price from $185 to $220. You pointed out that the other studio in Millbrook charges $160 without the glaze firing, and asked whether $195 was too much. Its comparison showed that the other class comes to about $180 once two pieces are glaze-fired. You chose $195. [Sources](source:chatgpt-0007,chatgpt-0009,chatgpt-0010,chatgpt-0012,chatgpt-0013)
+
+
+
+The first class description began “Discover the magic of glaze!” You called it “too salesy” and asked for a plain text that says why the class has only eight places. The second version said: “The class is limited to 8 people so that everyone's pieces fit in one kiln load.” [Sources](source:chatgpt-0015,chatgpt-0016,chatgpt-0017)
+
+
+
+You asked for a supply list and a short email to your mailing list. At 11:12, you came back to the conversation with Dana’s invitation. ChatGPT wrote the text of a sign-up form, and at 11:27 confirmed that six demo bowls can go into the workshop’s glaze load if they are bisqued in time. [Sources](source:chatgpt-0019,chatgpt-0021,chatgpt-0022,chatgpt-0025,chatgpt-0028)
+
+## Midday
+
+
+
+At 12:10, Google Maps records a drive to Fennimore Clay Supply. You bought two 25 lb bags of mid-fire stoneware and a set of wooden ribs; the receipt arrived at 12:31. You were back at the studio at 12:58. [Sources](source:google_timeline-0002,gmail-0009,google_timeline-0003)
+
+
+
+From 1:00 to 3:15, you were at the studio. Spotify played most of an album by The Quiet Kilns, then a podcast about running a craft business. At 2:40, you texted Theo a photo of a cracked test tile: “This is why we test.” [Sources](source:google_timeline-0003,spotify-0001,spotify-0009,imessage-0008,photos-0002)
+
+![2:40 PM — a test tile with a crack through the glaze.](source:photos-0002)
+
+## Afternoon
+
+
+
+At 3:20, you sent the announcement to your mailing list with the subject “Spring Glaze Workshop — 8 places”. The text was the draft from the morning, with the dates added. [Sources](source:gmail-0012,chatgpt-0021)
+
+
+
+Replies started at 3:34. By 6:00, seven people had asked for a place. One asked whether children could come: “My daughter is 12 and loves clay — is she too young?” You did not answer that email on May 11. [Sources](source:gmail-0013,gmail-0014,gmail-0016)
+
+
+
+At 4:15, you texted Dana three possible Thursdays for the demo night. She chose Thursday, May 28, and said the library would put down a floor cover. [Sources](source:imessage-0011,imessage-0012)
+
+[Saved social session](sessions.html#social-8f02cd5e7a44)
+
+## Dinner with Theo
+
+
+
+You left the studio at 6:20. Google Maps places you at the Orchard Street Diner from 6:31 to 8:02. Theo texted at 6:28, “Got us the booth by the window.” [Sources](source:google_timeline-0006,google_timeline-0007,imessage-0015)
+
+
+
+At 7:40, two more replies arrived. The class now had nine requests for eight places. [Sources](source:gmail-0018,gmail-0019)
+
+## Evening
+
+
+
+You were home at 8:14. At 8:30, the kiln controller emailed that the bisque firing had finished and the kiln was cooling. [Sources](source:google_timeline-0008,gmail-0021)
+
+## Your May 11 notes
+
+
+
+In a note at 9:12, you wrote: “Nine people for eight places. Start a waiting list, or open a second Tuesday?” Further down: “Commissions pay more per hour, but classes fill the summer calendar and bring people back.” The note ends with a question that you did not answer: “What do I want the studio to be known for?” [Read passage](source:apple_notes-0001#L1-L6)
+
+## Other records
+
+
+
+Spotify saved 12 plays, including repeats and partial plays. [Show all](source:spotify-0001,spotify-0002,spotify-0003,spotify-0004,spotify-0005,spotify-0006,spotify-0007,spotify-0008,spotify-0009,spotify-0010,spotify-0011,spotify-0012)
+
+
+## Supporting document: time-estimates
+
+# May 11 time estimates
+
+**Studio:** [8:20–10:00 AM and 1:00–3:15 PM](source:google_timeline-0001), from Google Maps, minus the time at Fennimore Clay Supply.
+
+**Workshop planning:** First-to-last [ChatGPT messages](documents.html) and the email you sent, split at gaps over 15 minutes.
+
+**Instagram:** First-to-last visits in each [session](sessions.html), split at gaps over five minutes.
+
+**Dinner:** [6:31–8:02 PM](source:google_timeline-0007), from Google Maps.
+
+**Driving:** About 34 minutes [to and from the supply store](source:google_timeline-0002) and 16 minutes [to dinner and home](source:google_timeline-0006), including stops.
+
+**Spotify:** Sum of the [12 saved playback durations](source:spotify-0001), including partial plays.
+
+Studio, planning, and browsing periods can include breaks and overlap. They do not measure continuous attention.

package/dist/packages/sdk/examples/daily-briefing/briefing_artifacts.py

@@ -0,0 +1,39 @@
+"""Read and write the files produced by a briefing run."""
+import hashlib
+import json
+import os
+from pathlib import Path
+
+from briefing_files import folder
+
+
+def digest(path):
+    return hashlib.sha256(path.read_bytes()).hexdigest()
+
+
+def tree(root):
+    return {str(p.relative_to(root)): digest(p) for p in sorted(root.rglob('*')) if p.is_file()}
+
+
+def source_digest():
+    return hashlib.sha256(json.dumps(tree(folder('selected_day')),sort_keys=True).encode()).hexdigest()
+
+
+def local(name):
+    root=Path(os.environ['METHOD_OUTPUT_DIR']).resolve()
+    path=(root/name).resolve()
+    if not path.is_relative_to(root):raise ValueError('Path leaves the run folder')
+    return path
+
+
+def put(path, data):
+    path=local(path)
+    path.parent.mkdir(parents=True,exist_ok=True)
+    path.write_text(json.dumps(data,ensure_ascii=False,indent=2)+'\n');path.chmod(0o600)
+    return {'path':str(path.relative_to(local('.'))),'sha256':digest(path)}
+
+
+def load(ref):
+    path=local(ref['path'])
+    if digest(path)!=ref['sha256']:raise ValueError('The saved file changed')
+    return json.loads(path.read_text())

package/dist/packages/sdk/examples/daily-briefing/briefing_check_inputs.py

@@ -0,0 +1,47 @@
+"""Check the prepared folder, approved example, date, and timezone."""
+import datetime as dt
+import json
+import sys
+from pathlib import Path
+from zoneinfo import ZoneInfo
+
+from briefing_artifacts import source_digest
+from briefing_files import folder, local_path
+from briefing_sessions import social_sessions
+
+
+def inputs(a):
+    date = dt.date.fromisoformat(a['day']).isoformat()
+    zone = ZoneInfo(a['timezone'])
+    prepared = folder('selected_day')
+    if prepared != Path(a['prepared_day']).resolve():
+        raise ValueError('Method folders do not match the runtime tool bindings')
+    required = {
+        'selected_day': ['timeline.jsonl', 'untimed.jsonl', 'records/',
+                         'metadata/documents.json'],
+    }
+    for which, names in required.items():
+        for name in names:
+            try:
+                path = local_path(which, name)
+            except FileNotFoundError:
+                raise ValueError(f'Missing required input: {which}/{name}') from None
+            if not (path.is_dir() if name.endswith('/') else path.is_file()):
+                raise ValueError(f'Expected a {"folder" if name.endswith("/") else "file"}: {which}/{name}')
+    for name in ['timeline.jsonl', 'untimed.jsonl']:
+        for row in map(json.loads, (prepared/name).read_text().splitlines()):
+            if row['date'] != date:
+                raise ValueError('Selected date does not match the prepared day')
+            if row.get('time'):
+                saved = dt.datetime.fromisoformat(row['time'])
+                local = saved.astimezone(zone)
+                if local.date().isoformat() != date or local.utcoffset() != saved.utcoffset():
+                    raise ValueError('Selected timezone does not match the prepared times')
+    report = (Path(__file__).parent/'approved-report.md').read_text()
+    return {'selected_day': {'source_digest': source_digest(), 'folder': str(prepared), 'day': date, 'timezone': a['timezone'], 'start': 'timeline.jsonl'},
+            'session_links': '\n'.join('['+g['platform']+' '+g['start']+'–'+g['end']+'](sessions.html#'+g['id']+')' for g in social_sessions(prepared)),
+            'example': {'report': report}}
+
+
+if __name__ == '__main__':
+    print(json.dumps(inputs(json.load(sys.stdin)), ensure_ascii=False))

package/dist/packages/sdk/examples/daily-briefing/briefing_files.py

@@ -0,0 +1,31 @@
+"""Read the example and selected day's files."""
+import json
+import os
+import sys
+from pathlib import Path
+
+ROOTS = {'selected_day', 'run'}
+
+
+def folder(which):
+    if which not in ROOTS:
+        raise ValueError('Choose selected_day or run')
+    if which == 'run':
+        return Path(os.environ['METHOD_OUTPUT_DIR']).resolve(strict=True)
+    return Path(json.loads(os.environ['METHOD_ENVIRONMENT'])['prepared_day']).resolve(strict=True)
+
+
+def local_path(which, name):
+    root = folder(which)
+    path = (root / name).resolve(strict=True)
+    if not path.is_relative_to(root):
+        raise ValueError('Path is outside the selected folder')
+    return path
+
+
+def page(text, offset):
+    if not isinstance(offset, int) or not 0 <= offset <= len(text):
+        raise ValueError('Invalid character offset')
+    end = min(len(text), offset + 20000)
+    return {'content': text[offset:end], 'next_offset': end if end < len(text) else -1,
+            'total_chars': len(text)}