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

package/dist/packages/sdk/examples/outbound-management/fixtures/plan.json

@@ -0,0 +1,69 @@
+{
+  "updated_contacts": [
+    {
+      "id": "c1",
+      "name": "Alex Kim",
+      "email": "alex@north.example",
+      "company": "North",
+      "role": "Operations lead",
+      "fit": "Manages a small logistics team",
+      "sources": [],
+      "status": "replied",
+      "next_action": "Send pricing",
+      "next_action_date": "2026-09-17",
+      "introduction_path": ""
+    },
+    {
+      "id": "c2",
+      "name": "Morgan Bell",
+      "email": "morgan@south.example",
+      "company": "South",
+      "role": "Operations lead",
+      "fit": "Manages a small logistics team",
+      "sources": [],
+      "status": "customer",
+      "next_action": "",
+      "next_action_date": "",
+      "introduction_path": ""
+    },
+    {
+      "id": "c3",
+      "name": "Sam Lee",
+      "email": "sam@east.example",
+      "company": "East",
+      "role": "Operations lead",
+      "fit": "Manages a small logistics team",
+      "sources": [],
+      "status": "opted_out",
+      "next_action": "",
+      "next_action_date": "",
+      "introduction_path": ""
+    }
+  ],
+  "resolutions": [
+    {
+      "id": "m1",
+      "contact_id": "c1",
+      "resolution": "Recorded reply"
+    },
+    {
+      "id": "m2",
+      "contact_id": "c3",
+      "resolution": "Recorded reply"
+    },
+    {
+      "id": "m3",
+      "contact_id": "",
+      "resolution": "Review sender"
+    }
+  ],
+  "day_tasks": [
+    {
+      "contact_id": "c1",
+      "action": "Send pricing",
+      "due_date": "2026-09-17",
+      "reason": "Requested by Alex",
+      "draft": "Hello Alex, let us review your needs."
+    }
+  ]
+}

package/dist/packages/sdk/examples/outbound-management/fixtures/receipt.json

@@ -0,0 +1 @@
+{"day": "2026-09-17", "crm_sha256": "71a30d38fb2fcffb773ab3071367a239af0c01abca0394daef1d66a58fde9635", "contacts": 3, "messages": 3}

package/dist/packages/sdk/examples/outbound-management/fixtures/state.json

@@ -0,0 +1,99 @@
+{
+  "target": {
+    "customer": "Operations leaders at small US logistics companies who still process customer requests manually.",
+    "offer": "A service that turns repeated work into reusable automated workflows.",
+    "new_prospects_per_day": 3,
+    "mailbox_url": "https://mail.google.com/mail/u/0/"
+  },
+  "contacts": [
+    {
+      "id": "c1",
+      "name": "Alex Kim",
+      "email": "alex@north.example",
+      "company": "North",
+      "role": "Operations lead",
+      "fit": "Manages a small logistics team",
+      "sources": [],
+      "status": "replied",
+      "next_action": "Send pricing",
+      "next_action_date": "2026-09-17",
+      "manual_notes": "Keep this owner note.",
+      "introduction_path": ""
+    },
+    {
+      "id": "c2",
+      "name": "Morgan Bell",
+      "email": "morgan@south.example",
+      "company": "South",
+      "role": "Operations lead",
+      "fit": "Manages a small logistics team",
+      "sources": [],
+      "status": "customer",
+      "next_action": "",
+      "next_action_date": "",
+      "manual_notes": "Keep this owner note.",
+      "introduction_path": ""
+    },
+    {
+      "id": "c3",
+      "name": "Sam Lee",
+      "email": "sam@east.example",
+      "company": "East",
+      "role": "Operations lead",
+      "fit": "Manages a small logistics team",
+      "sources": [],
+      "status": "opted_out",
+      "next_action": "",
+      "next_action_date": "",
+      "manual_notes": "Keep this owner note.",
+      "introduction_path": ""
+    }
+  ],
+  "messages": [
+    {
+      "id": "m1",
+      "url": "https://mail.google.com/mail/u/0/#inbox/m1",
+      "email": "alex@north.example",
+      "at": "2026-09-17T09:00:00-04:00",
+      "direction": "received",
+      "text": "Can you send pricing today?",
+      "contact_id": "c1",
+      "resolution": "Recorded reply"
+    },
+    {
+      "id": "m2",
+      "url": "https://mail.google.com/mail/u/0/#inbox/m2",
+      "email": "sam@east.example",
+      "at": "2026-09-17T10:00:00-04:00",
+      "direction": "received",
+      "text": "Please stop contacting me.",
+      "contact_id": "c3",
+      "resolution": "Recorded reply"
+    },
+    {
+      "id": "m3",
+      "url": "https://mail.google.com/mail/u/0/#inbox/m3",
+      "email": "",
+      "at": "2026-09-17T11:00:00-04:00",
+      "direction": "received",
+      "text": "Alex: send the contract. Sender address was not captured.",
+      "contact_id": "",
+      "resolution": "Review sender"
+    }
+  ],
+  "days": {
+    "2026-09-17": {
+      "tasks": [
+        {
+          "contact_id": "c1",
+          "action": "Send pricing",
+          "due_date": "2026-09-17",
+          "reason": "Requested by Alex",
+          "draft": "Hello Alex, let us review your needs."
+        }
+      ],
+      "research_notes": "Happenstance: No new prospects in this state test."
+    }
+  },
+  "last_plan": "f3052a54726c6e2b793368cd8138303959e788fe23adee2f2975fdf4303737f4"
+}

package/dist/packages/sdk/examples/outbound-management/fixtures/tasks.md

@@ -0,0 +1,16 @@
+# Outbound tasks — 2026-09-17
+
+## Send pricing: Alex Kim · North
+Due: 2026-09-17
+
+Requested by Alex
+
+Hello Alex, let us review your needs.
+
+## Messages to review
+
+m3: Review sender
+
+## Research notes
+
+Happenstance: No new prospects in this state test.

package/dist/packages/sdk/examples/outbound-management/inputs.json

@@ -0,0 +1,4 @@
+{
+  "day": "2026-09-17",
+  "from_date": "2026-09-10"
+}

package/dist/packages/sdk/examples/outbound-management/outbound.method

@@ -0,0 +1,277 @@
+format: method/3.4
+name: Manage daily outbound
+goal: Read campaign email, find prospects in Happenstance, enrich them from company and LinkedIn pages, update the CRM, and prepare today's outreach tasks.
+inputs:
+  day:
+    type: text
+    description: Date to plan, YYYY-MM-DD.
+  from_date:
+    type: text
+    description: First email date to read, YYYY-MM-DD. Use an overlap with the last run.
+state:
+  crm:
+    type: text
+    description: CRM as JSON text in shared Method account state. Updated only by save_day, after every check passes.
+environment:
+  browser:
+    type: browser
+    description: Browser signed in to email, Happenstance, and LinkedIn.
+steps:
+  read_crm:
+    name: Read the CRM
+    purpose: Rejects an invalid date or an email start date after the planned day. Returns the target settings, the contacts, the IDs of messages already matched to a contact, and the hash of the supplied CRM text. Changes nothing.
+    in:
+      day: inputs.day
+      from_date: inputs.from_date
+      crm: state.crm
+    do: {kind: run, runtime: python, entrypoint: read_crm.py}
+    out:
+      target:
+        type: record
+        fields: {customer: text, offer: text, new_prospects_per_day: number, mailbox_url: text}
+        description: Target customer, offer, daily prospect limit, and mailbox URL.
+      contacts:
+        type: list
+        fields:
+          id: text
+          name: text
+          email: text
+          company: text
+          role: text
+          fit: text
+          sources: {type: list, items: text}
+          status: text
+          next_action: text
+          next_action_date: text
+          introduction_path: text
+          manual_notes: text
+        description: Contacts saved in the CRM.
+      resolved:
+        type: list
+        items: text
+        description: IDs of saved messages that are matched to a contact.
+      crm_sha256:
+        type: text
+        description: SHA-256 of the CRM text that this run read.
+
+  read_email:
+    name: Read campaign email
+    no_effect_reason: Reads the mailbox in the browser; sends, replies to, and deletes nothing.
+    accept:
+      untrusted_content_can_act: The agent needs the signed-in mailbox to read campaign email. The prompt asks it only to search and read; nothing is sent until a person reviews the tasks.
+    changes: [environment.browser]
+    in:
+      mailbox_url: target.mailbox_url
+      offer: target.offer
+      from_date: inputs.from_date
+      day: inputs.day
+      contacts: contacts
+    do:
+      kind: agent
+      model: default
+      browser: environment.browser
+      prompt: |
+        Open {{mailbox_url}} and read the received and sent campaign email from {{from_date}} through {{day}}.
+        Search by the addresses and companies in contacts and by this offer: {{offer}}
+        Open each matching thread and keep every message, including opt-outs and replies from people who are not in contacts.
+        Set contact_id when the address matches a contact; otherwise leave it empty. Leave email empty when the address is not shown.
+        If you cannot open the mailbox, set status to blocked and say why in notes.
+    out:
+      messages:
+        type: list
+        fields: {id: text, url: text, email: text, at: text, direction: text, text: text, contact_id: text}
+        description: Campaign messages. id is the mailbox message ID, url the thread link, at an ISO date and time, direction received or sent.
+      email_search:
+        type: record
+        fields: {status: text, notes: text}
+        description: complete or blocked, and what limited the search.
+    check: {kind: run, runtime: python, entrypoint: check_sources.py, args: [email]}
+    reading:
+      check_name: Check email records
+      check: Requires a complete search, unique message IDs, valid dates, https thread links, and message text.
+
+  find_prospects:
+    name: Find prospects in Happenstance
+    no_effect_reason: Searches Happenstance in the browser; sends no messages or introduction requests.
+    accept:
+      untrusted_content_can_act: The agent needs the signed-in Happenstance account to search the network. The prompt asks it only to search; no message or introduction request is sent.
+    changes: [environment.browser]
+    after: read_email
+    in:
+      customer: target.customer
+      offer: target.offer
+      limit: target.new_prospects_per_day
+      contacts: contacts
+    do:
+      kind: agent
+      model: default
+      browser: environment.browser
+      prompt: |
+        Open https://happenstance.ai and ask:
+        "Find people in my network who fit this customer description: {{customer}}
+        I offer {{offer}} Show their current roles, companies, profile links,
+        and how I can reach them or get an introduction."
+        Choose up to {{limit}} people from the results who fit the description and are not in contacts.
+        Copy their details as Happenstance shows them. Leave email empty when it is not shown.
+        If no one fits, return no prospects. If you cannot search, set status to blocked and say why in notes.
+    out:
+      prospects:
+        type: list
+        fields: {name: text, email: text, company: text, role: text, profile_url: text, introduction_path: text}
+        description: New people who fit the target customer.
+      prospect_search:
+        type: record
+        fields: {status: text, notes: text}
+        description: complete or blocked, and what limited the search.
+    check: {kind: run, runtime: python, entrypoint: check_sources.py, args: [prospects]}
+    reading:
+      check_name: Check search access
+      check: Requires a complete Happenstance search. A complete search may find no prospects.
+
+  enrich:
+    name: Check each prospect's pages
+    no_effect_reason: Reads company and LinkedIn pages in the browser; sends no messages or connection requests.
+    accept:
+      untrusted_content_can_act: The agent needs the signed-in browser to read LinkedIn profiles. The prompt asks it only to read pages; no message or connection request is sent.
+    changes: [environment.browser]
+    after: find_prospects
+    each: {prospect: prospects}
+    in:
+      offer: target.offer
+    do:
+      kind: agent
+      model: default
+      browser: environment.browser
+      prompt: |
+        Open the website of {{prospect.company}} and the LinkedIn profile of {{prospect.name}} ({{prospect.profile_url}}; search LinkedIn when this is empty).
+        Record each page you read with its URL and the facts you read there.
+        From those facts, give the current role and one sentence on why this offer fits: {{offer}}
+        Give an email address only when a page shows it; otherwise leave email empty.
+        In notes, name each page that you could not open.
+    out:
+      enrichment:
+        type: record
+        fields:
+          email: text
+          role: text
+          fit: text
+          sources: {type: list, fields: {url: text, facts: text}}
+          notes: text
+        description: What the prospect's pages show.
+    check: {kind: run, runtime: python, entrypoint: check_sources.py, args: [enrichment]}
+    reading:
+      check_name: Check page records
+      check: Requires at least one source, each with an https link and the facts read there.
+
+  update_contacts:
+    name: Update contacts
+    in:
+      contacts: contacts
+      resolved: resolved
+      messages: messages
+      prospects: prospects
+      enrichment: enrichment
+    do:
+      kind: call
+      model: default
+      prompt: |
+        Return each contact that the new messages or the new prospects add or change.
+        Skip messages whose id is in resolved. Match each other message to a contact by contact_id or exact email.
+        Give each message a short resolution, such as "Asked for pricing". When no contact matches, leave contact_id empty and say what a person must check.
+        Set the contact's status, next_action, and next_action_date from its messages. Status is new, contacted, replied, qualified, meeting, customer, closed, or opted_out.
+        Never change a customer or opted_out status. Leave next_action_date empty when nothing is due.
+        Add each prospect with status new. The enrichment at the same position gives its role, fit, email, and sources (the page URLs).
+        Use email:<address> as a new contact's id, or its profile_url when the email is unknown. Leave an unknown email empty.
+    out:
+      updated_contacts:
+        type: list
+        fields:
+          id: text
+          name: text
+          email: text
+          company: text
+          role: text
+          fit: text
+          sources: {type: list, items: text}
+          status: text
+          next_action: text
+          next_action_date: text
+          introduction_path: text
+        description: New and changed contacts.
+      resolutions:
+        type: list
+        fields: {id: text, contact_id: text, resolution: text}
+        description: One entry for each new message.
+    check: {kind: run, runtime: python, entrypoint: check_plan.py, args: [contacts]}
+    reading:
+      check_name: Check contacts
+      check: Requires unique contacts with a valid status and date, collected sources and a fit for new prospects, one contact per email, unchanged customer and opt-out status, and one resolution per new message whose contact matches by ID or exact email.
+
+  draft_tasks:
+    name: Draft today's tasks
+    in:
+      day: inputs.day
+      offer: target.offer
+      contacts: contacts
+      updated_contacts: updated_contacts
+      enrichment: enrichment
+    do:
+      kind: call
+      model: default
+      prompt: |
+        Write the outreach tasks due on {{day}}. A contact in updated_contacts replaces the contact with the same id in contacts.
+        Make one task for each contact whose next_action_date is {{day}} or earlier, and one for each contact with status new.
+        Skip contacts whose status is customer, closed, or opted_out.
+        Set action to the next action, due_date to next_action_date or {{day}} when it is empty, and reason to one sentence.
+        Write a short draft email that uses the contact's facts and this offer: {{offer}} Leave draft empty when the task is not an email, such as a meeting.
+        Two tasks written the way they should be, for other contacts:
+        - A reply that asked for pricing: action "Send pricing", reason "Jordan asked for pricing on 2026-09-15.",
+          draft "Hi Jordan, thanks for asking. Pricing starts at $400 a month for one workflow; I attached the one-page summary. Would a 20-minute call next week help?"
+        - A new prospect: action "Ask Sam for an introduction", reason "New prospect; Sam knows Priya from their time at Bayside Freight.",
+          draft "Hi Sam, could you introduce me to Priya at Coastline Logistics? Her team still handles customer requests by hand, and I think our workflows could help."
+    out:
+      day_tasks:
+        type: list
+        fields: {contact_id: text, action: text, due_date: text, reason: text, draft: text}
+        description: Tasks and outreach drafts for review.
+    check: {kind: run, runtime: python, entrypoint: check_plan.py, args: [tasks]}
+    reading:
+      check_name: Check tasks
+      check: Requires unique tasks with an action and a reason, due by the planned day, for known contacts that are not customers, closed, or opted out.
+
+  save_day:
+    name: Update the CRM and save today's tasks
+    purpose: Repeats the contact and task checks, then rejects a changed CRM unless this plan is already saved. Saves new and changed contacts with their owner notes kept, message resolutions, today's tasks, and research notes made from the search and page notes. Returns the replacement for state.crm, the task list, and a receipt. Repeating the same plan reuses its state update and rewrites the same local result files.
+    changes: [state.crm]
+    in:
+      crm: state.crm
+      crm_sha256: crm_sha256
+      day: inputs.day
+      contacts: contacts
+      resolved: resolved
+      messages: messages
+      email_search: email_search
+      prospect_search: prospect_search
+      enrichment: enrichment
+      updated_contacts: updated_contacts
+      resolutions: resolutions
+      day_tasks: day_tasks
+    do: {kind: run, runtime: python, entrypoint: save_day.py}
+    out:
+      tasks:
+        type: file
+        description: Daily task list and outreach drafts for review.
+      receipt:
+        type: file
+        description: Saved CRM hash, contact count, and message count.
+    check: {file: tasks}
+result:
+  tasks: tasks
+  receipt: receipt
+run_prompt: Run Manage daily outbound for today using my CRM and new messages. Show me the tasks and outreach drafts for review.
+files:
+  - crm.py
+  - read_crm.py
+  - check_sources.py
+  - check_plan.py
+  - save_day.py

package/dist/packages/sdk/examples/outbound-management/read_crm.py

@@ -0,0 +1,4 @@
+import json
+import sys
+from crm import read
+print(json.dumps(read(json.load(sys.stdin))))

package/dist/packages/sdk/examples/outbound-management/save_day.py

@@ -0,0 +1,4 @@
+import json
+import sys
+from crm import save
+print(json.dumps(save(json.load(sys.stdin))))

package/dist/packages/sdk/examples/outbound-management/starter/crm.json

@@ -0,0 +1,11 @@
+{
+  "target": {
+    "customer": "Operations leaders at small US logistics companies who still process customer requests manually.",
+    "offer": "A service that turns repeated work into reusable automated workflows.",
+    "new_prospects_per_day": 3,
+    "mailbox_url": "https://mail.google.com/mail/u/0/"
+  },
+  "contacts": [],
+  "messages": [],
+  "days": {}
+}

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

@@ -0,0 +1,41 @@
+# Social research example
+
+This Method researches a topic on Grok, alphaXiv, and LinkedIn, then writes a
+briefing with quotes and source links. It uses the SDK's standard browser tools.
+
+The Method has two steps:
+
+1. `gather_sources` (agent with a browser): opens Grok, alphaXiv, and LinkedIn in
+   browser tabs, asks the two quoted questions, searches LinkedIn, and reads the
+   useful posts and papers. It returns the sources and its research notes.
+2. `write_briefing` (call): writes the briefing from the collected sources. It
+   needs no browser and no tools, so it is a call, not an agent.
+
+The result contains the briefing draft, the sources, and the research notes. The
+sample topic and dates are in `inputs.json`; change them for the next run.
+
+## Run
+
+```sh
+method run social-briefing.method --inputs inputs.json
+```
+
+The step selects `browser: environment.browser`. The SDK supplies browser-use's
+standard controls and connects the browser during normal run setup. On macOS, the
+default connection copies the last-used Chrome profile and runs headless. Run
+`method browser connect` to choose another browser.
+
+## Two choices in the file
+
+- `no_effect_reason`: the browser step only reads. It sends, posts, and submits
+  nothing, so there is no change to read back.
+- `accept: {untrusted_content_can_act: ...}`: `validate` warns when an agent that
+  reads web pages could also change things with the same browser. Here the agent
+  needs the signed-in browser to read, and a person reads the briefing before it
+  is shared, so the warning is accepted with that reason.
+
+The count check stops an empty source list. It does not show that all three sites
+were covered or that the briefing is good; read the briefing and open its links.
+
+`result.fixture.json` is a fictional illustration of the result shape. It is not
+a recorded research result.

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

@@ -0,0 +1,5 @@
+# Request
+
+Research the supplied topic and date range on Grok, alphaXiv, and LinkedIn.
+Read the sources, then write a briefing with short quotes, links, and any gaps
+in the research.

package/dist/packages/sdk/examples/social-briefing/inputs.json

@@ -0,0 +1,5 @@
+{
+  "topic": "Where coding agents fail in real work, and what improves their reliability",
+  "from_date": "2026-09-10",
+  "to_date": "2026-09-17"
+}

package/dist/packages/sdk/examples/social-briefing/result.fixture.json

@@ -0,0 +1,14 @@
+{
+  "briefing": "Here is the latest on what people are saying on coding agent reliability.\n\nThis fictional fixture shows the result format. Alex says \u201cChecks need to cover the changed behavior.\u201d [Source](https://example.com/research).",
+  "sources": [
+    {
+      "platform": "LinkedIn",
+      "author": "Alex (fictional)",
+      "published": "2026-09-15",
+      "url": "https://example.com/research",
+      "quote": "Checks need to cover the changed behavior.",
+      "summary": "A fictional source about testing agent changes."
+    }
+  ],
+  "research_notes": "Illustrative fixture only. No browser research was run to produce this file."
+}

package/dist/packages/sdk/examples/social-briefing/social-briefing.method

@@ -0,0 +1,110 @@
+format: method/3.4
+name: Research social posts and papers
+goal: Read recent posts and papers in the browser, then write a briefing with quotes and links.
+inputs:
+  topic:
+    type: text
+  from_date:
+    type: text
+    description: First publication date, YYYY-MM-DD.
+  to_date:
+    type: text
+    description: Last publication date, YYYY-MM-DD.
+environment:
+  browser:
+    type: browser
+    description: Browser with access to Grok, LinkedIn, and alphaXiv.
+steps:
+  gather_sources:
+    no_effect_reason: Reads posts and papers in the browser; sends, posts and submits nothing.
+    accept:
+      untrusted_content_can_act: The agent needs the signed-in browser to read Grok, alphaXiv, and LinkedIn. The prompt asks it only to search and read, and a person reads the briefing before it is shared.
+    name: Find and read sources
+    changes:
+      - environment.browser
+    in:
+      topic: inputs.topic
+      from_date: inputs.from_date
+      to_date: inputs.to_date
+    do:
+      kind: agent
+      model: default
+      browser: environment.browser
+      prompt: |
+        Use the browser to research {{topic}} from {{from_date}} through {{to_date}}.
+        Open tabs for https://x.com/i/grok, https://www.alphaxiv.org, and https://www.linkedin.com.
+
+        Ask Grok: "What are people saying on Twitter about {{topic}} from {{from_date}}
+        through {{to_date}}? Find useful original posts and disagreements. Give names,
+        dates, direct post links, and short exact quotes. Link both sides of each argument."
+
+        Ask alphaXiv: "Find papers about {{topic}} published from {{from_date}} through
+        {{to_date}}. What is new, and what do the papers say? Give titles, authors,
+        dates, paper links, and short exact quotes."
+
+        Search LinkedIn for posts about the same topic and dates. Open and read the
+        useful posts and papers. Collect who said what, publication dates, direct
+        links, and short exact quotes. In research_notes, record what you searched
+        on each site and any pages you could not read.
+    out:
+      sources:
+        type: list
+        items:
+          type: record
+          fields:
+            platform:
+              type: text
+            author:
+              type: text
+            published:
+              type: text
+            url:
+              type: text
+            quote:
+              type: text
+              description: Short exact quote from the page read; empty when unavailable.
+            summary:
+              type: text
+      research_notes:
+        type: text
+    check:
+      count:
+        value: sources
+        min: 1
+  write_briefing:
+    name: Write the briefing
+    in:
+      topic: inputs.topic
+      sources: sources
+      research_notes: research_notes
+    do:
+      kind: call
+      model: default
+      prompt: |
+        Write a briefing from the collected sources. Start with:
+        "Here is the latest on what people are saying on {{topic}}."
+
+        Give a short topline paragraph with highlights from the posts and papers.
+        Then use short paragraphs like these:
+
+        <Name> on Twitter says "<quote>" [link]. <Useful context.>
+
+        <Name> and <name> are arguing over <issue>: one says "<quote>",
+        while the other says "<quote>" [links to both posts].
+
+        There is a new paper about <finding>. <Authors> say "<quote>" [paper link].
+
+        Include useful LinkedIn posts in the same style. Describe disagreements
+        when the sources show them. Use the collected quotes and put links beside
+        each claim. Keep quotes to at most 25 words per source in total.
+        When a source has no quote, describe it without quotation marks. When
+        research_notes name a site that could not be read, say so in the last sentence.
+    out:
+      briefing:
+        type: text
+        description: Briefing draft with source links.
+result:
+  briefing: briefing
+  sources: sources
+  research_notes: research_notes
+run_prompt: Run this Method for the requested topic and dates. Show the briefing draft and its source links.