Input/Output Interfaces

Overview

Complete input and output type definitions for the three workers in this project.

write-agent-digest

Creates a digest page in Notion documenting an agent’s execution.

WriteAgentDigestInput

interface WriteAgentDigestInput {
  agent_name: string;
  agent_emoji: string;
  status_type: StatusType;
  status_value: StatusValue;
  run_time_chicago: string;
  scope: string;
  input_versions: string;
  flagged_items: FlaggedItem[];
  actions_taken: ActionsTaken;
  summary: string;
  needs_review: NeedsReview[];
  escalations: Escalation[];
  target_database: TargetDatabase;
  doc_type: string;
  client_relation_ids?: string[];
  project_relation_ids?: string[];
}

agent_name

string

required

Name of the agent (e.g., “Inbox Manager”, “GitHub Insyncerator”)

agent_emoji

string

required

Emoji icon for the agent (e.g., ”📧”, ”🐙”)

status_type

StatusType

required

Type of status: "sync", "snapshot", "report", or "heartbeat"

status_value

StatusValue

required

Outcome: "complete", "partial", "failed", "full_report", or "stub"

run_time_chicago

string

required

ISO 8601 timestamp of execution (will be formatted to Chicago time)

scope

string

required

Description of what the agent processed (e.g., “Processed 15 emails”)

input_versions

string

required

Version info for data sources (e.g., “Gmail API v1, filters v3”)

flagged_items

FlaggedItem[]

required

Array of items that need attention

actions_taken

ActionsTaken

required

Tasks created or updated during execution

summary

string

required

Brief summary of the execution

needs_review

NeedsReview[]

required

Items requiring human review

escalations

Escalation[]

required

Items escalated to other agents or humans

target_database

TargetDatabase

required

Which database to write to: "docs" or "home_docs"

doc_type

string

required

Document type (e.g., “Email Triage”, “GitHub Sync”)

client_relation_ids

string[]

Array of Notion page IDs to link as client relations

project_relation_ids

string[]

Array of Notion page IDs to link as project relations

WriteAgentDigestOutput

type WriteAgentDigestOutput =
  | {
      success: true;
      page_url: string;
      page_id: string;
      title: string;
      is_error_titled: boolean;
      is_heartbeat: boolean;
    }
  | { success: false; error: string };

Success response:

success

true

required

Operation succeeded

page_url

string

required

Full Notion URL to the created digest page

page_id

string

required

Notion page ID (32-character hex string)

title

string

required

Full title of the created page

is_error_titled

boolean

required

Whether the title includes “⚠️” or ”❌” prefix (for failed/partial status)

is_heartbeat

boolean

required

Whether this was a heartbeat digest (no actionable work)

Error response:

success

false

required

Operation failed

error

string

required

Human-readable error message

Example

const input: WriteAgentDigestInput = {
  agent_name: "Inbox Manager",
  agent_emoji: "📧",
  status_type: "sync",
  status_value: "complete",
  run_time_chicago: "2026-03-04T08:30:00Z",
  scope: "Processed 12 emails",
  input_versions: "Gmail API v1",
  flagged_items: [
    {
      description: "Urgent client email",
      task_link: "https://notion.so/abc123",
    },
  ],
  actions_taken: {
    created_tasks: [
      {
        name: "Respond to client inquiry",
        notion_url: "https://notion.so/abc123",
      },
    ],
    updated_tasks: [],
  },
  summary: "Triaged inbox, created 1 task",
  needs_review: [],
  escalations: [],
  target_database: "docs",
  doc_type: "Email Triage",
};

const result = await fetch("https://api.notion.dev/...", {
  method: "POST",
  body: JSON.stringify(input),
});
// { success: true, page_url: "https://notion.so/...", ... }

check-upstream-status

Looks up the most recent digest page for an agent and returns its status.

CheckUpstreamStatusInput

interface CheckUpstreamStatusInput {
  agent_name: string;
  max_age_hours?: number;
  require_current_cycle?: boolean;
}

agent_name

string

required

Name of the agent to check (must match AGENT_DIGEST_PATTERNS)

max_age_hours

number

Maximum age in hours for the digest to be considered current (default: 24)

require_current_cycle

boolean

If true, digest must be from the current business cycle (default: false)

CheckUpstreamStatusOutput

interface CheckUpstreamStatusOutput {
  found: boolean;
  agent_name: string;
  status: UpstreamStatus;
  status_type: StatusType | null;
  run_time: string | null;
  run_time_age_hours: number | null;
  is_stale: boolean;
  is_heartbeat: boolean;
  is_error_titled: boolean;
  page_url: string | null;
  page_id: string | null;
  degraded: boolean;
  data_completeness_notice: string;
}

found

boolean

required

Whether a digest page was found for this agent

agent_name

string

required

Echo of the requested agent name

status

UpstreamStatus

required

Parsed status: "complete", "partial", "failed", "full_report", "stub", "not_found", "stale", or "unknown"

status_type

StatusType | null

required

Type of status if parsed: "sync", "snapshot", "report", or "heartbeat"

run_time

string | null

required

Run time string from the digest (e.g., “2026-03-04 08:30 (America/Chicago)”)

run_time_age_hours

number | null

required

Hours since the digest was created (null if not found or unparseable)

is_stale

boolean

required

True if age exceeds max_age_hours

is_heartbeat

boolean

required

True if digest contains “Heartbeat: no actionable items”

is_error_titled

boolean

required

True if page title starts with ⚠️ or ❌

page_url

string | null

required

Full Notion URL to the digest page

page_id

string | null

required

Notion page ID

degraded

boolean

required

True if status is partial, failed, or stale

data_completeness_notice

string

required

Human-readable explanation of data completeness (e.g., “Data is current”)

Example

const input: CheckUpstreamStatusInput = {
  agent_name: "GitHub Insyncerator",
  max_age_hours: 2,
};

const result = await fetch("https://api.notion.dev/...", {
  method: "POST",
  body: JSON.stringify(input),
});

// Example response:
// {
//   found: true,
//   agent_name: "GitHub Insyncerator",
//   status: "complete",
//   status_type: "sync",
//   run_time: "2026-03-04 08:00 (America/Chicago)",
//   run_time_age_hours: 1.5,
//   is_stale: false,
//   is_heartbeat: false,
//   is_error_titled: false,
//   page_url: "https://notion.so/...",
//   page_id: "abc123...",
//   degraded: false,
//   data_completeness_notice: "Data is current"
// }

create-handoff-marker

Creates a handoff task and/or returns a formatted handoff block for escalations.

CreateHandoffMarkerInput

interface CreateHandoffMarkerInput {
  source_agent: string;
  target_agent: string;
  escalation_reason: string;
  source_digest_url: string;
  create_task: boolean;
  task_priority?: TaskPriority;
  client_relation_ids?: string[];
  project_relation_ids?: string[];
}

source_agent

string

required

Name of the agent creating the handoff

target_agent

string

required

Name of the agent or person receiving the handoff

escalation_reason

string

required

Why this item is being escalated

source_digest_url

string

required

URL to the source agent’s digest page

create_task

boolean

required

Whether to create a Notion task page for this handoff

task_priority

TaskPriority

Priority if creating a task: "🔴 High", "🟡 Medium", or "🟢 Low"

client_relation_ids

string[]

Client page IDs to link to the task

project_relation_ids

string[]

Project page IDs to link to the task

CreateHandoffMarkerOutput

type CreateHandoffMarkerOutput =
  | {
      success: true;
      handoff_block: string;
      task_created: boolean;
      task_url: string | null;
      task_id: string | null;
      duplicate_prevented: boolean;
      existing_task_url: string | null;
      escalation_capped: boolean;
      needs_manual_review: boolean;
    }
  | { success: false; error: string };

Success response:

success

true

required

Operation succeeded

handoff_block

string

required

Markdown-formatted handoff block to include in digest

task_created

boolean

required

Whether a new task was created

task_url

string | null

required

URL to the created task (null if not created)

task_id

string | null

required

Notion page ID of the created task

duplicate_prevented

boolean

required

Whether an existing open task was found, preventing duplicate creation

existing_task_url

string | null

required

URL to existing task if duplicate was prevented

escalation_capped

boolean

required

Whether escalation was rate-limited (max 3 per agent per day)

needs_manual_review

boolean

required

Whether this handoff requires manual review

Error response:

success

false

required

Operation failed

error

string

required

Human-readable error message

Example

const input: CreateHandoffMarkerInput = {
  source_agent: "Inbox Manager",
  target_agent: "Personal Ops Manager",
  escalation_reason: "Complex scheduling conflict requiring manual resolution",
  source_digest_url: "https://notion.so/...",
  create_task: true,
  task_priority: "🔴 High",
  client_relation_ids: ["abc123"],
};

const result = await fetch("https://api.notion.dev/...", {
  method: "POST",
  body: JSON.stringify(input),
});

// Example response:
// {
//   success: true,
//   handoff_block: "🤝 Escalated to Personal Ops Manager...\n\n...",
//   task_created: true,
//   task_url: "https://notion.so/...",
//   task_id: "xyz789",
//   duplicate_prevented: false,
//   existing_task_url: null,
//   escalation_capped: false,
//   needs_manual_review: false
// }

Types

Shared Utilities

Overview

write-agent-digest

WriteAgentDigestInput

WriteAgentDigestOutput

Example

check-upstream-status

CheckUpstreamStatusInput

CheckUpstreamStatusOutput

Example

create-handoff-marker

CreateHandoffMarkerInput

CreateHandoffMarkerOutput

Example

Build docs developers (and LLMs) love

Types

Shared Utilities

​Overview

​write-agent-digest

​WriteAgentDigestInput

​WriteAgentDigestOutput

​Example

​check-upstream-status

​CheckUpstreamStatusInput

​CheckUpstreamStatusOutput

​Example

​create-handoff-marker

​CreateHandoffMarkerInput

​CreateHandoffMarkerOutput

​Example

Build docs developers (and LLMs) love

Overview

write-agent-digest

WriteAgentDigestInput

WriteAgentDigestOutput

Example

check-upstream-status

CheckUpstreamStatusInput

CheckUpstreamStatusOutput

Example

create-handoff-marker

CreateHandoffMarkerInput

CreateHandoffMarkerOutput

Example