Input schema (JSON)
{
"type": "object",
"required": [
"entityType"
],
"properties": {
"goal": {
"type": "string",
"description": "rhythm: required run instructions; skill uses instructions instead."
},
"kind": {
"type": "string",
"description": "tracker: required; habit|metric|goal|log|status|custom."
},
"name": {
"type": "string",
"description": "Required: tracker/area/project/rhythm and entityType:\"skill\". skill_invoke/skill_run: alternative to skillId. Existing skill names preview changes; new names create. Active tracker duplicates are rejected; archived names reactivate."
},
"tags": {
"type": "array",
"items": {
"type": "string"
},
"description": "task: tags to attach."
},
"unit": {
"type": "string",
"description": "tracker: unit of measure."
},
"actor": {
"type": "string",
"description": "task/area/project/heading: actor (me|agent) recorded in activity ledger."
},
"child": {
"type": "string",
"description": "tag_relation: required child tag."
},
"notes": {
"type": [
"array",
"string"
],
"description": "note: array (max 100), each requires content and confidence (0–1), plus tags and exactly 3 sampleQuestions in the user’s voice; optional source/memoryType (episodic|semantic|procedural)/validFrom. task/area/project: markdown string."
},
"order": {
"type": "number",
"description": "task/area/project/heading: sort order."
},
"owner": {
"enum": [
"me",
"agent",
"unassigned"
],
"type": "string",
"description": "task: assignee."
},
"patch": {
"type": "object",
"properties": {
"name": {
"type": "string"
},
"notes": {
"type": "string"
},
"order": {
"type": "number"
},
"steps": {
"type": "array",
"items": {
"type": "object",
"required": [
"op",
"stepId"
],
"properties": {
"op": {
"enum": [
"suggest",
"edit",
"dismiss",
"accept"
],
"type": "string"
},
"text": {
"type": "string"
},
"order": {
"type": "number"
},
"stepId": {
"type": "string"
}
}
},
"maxItems": 25,
"description": "accept turns a saved suggestion into a To-do."
},
"areaId": {
"type": [
"string",
"null"
]
},
"status": {
"enum": [
"active",
"paused",
"done",
"canceled"
],
"type": "string"
},
"whenAt": {
"type": [
"number",
"null"
]
},
"purpose": {
"type": "string"
},
"archived": {
"type": "boolean"
},
"deadline": {
"type": [
"number",
"null"
]
},
"progress": {
"type": "string"
},
"resources": {
"type": "array",
"items": {
"type": "object",
"required": [
"op"
],
"properties": {
"op": {
"enum": [
"attach",
"suggest",
"remove",
"restore"
],
"type": "string"
},
"url": {
"type": [
"string",
"null"
]
},
"role": {
"enum": [
"reference",
"method"
],
"type": "string"
},
"label": {
"type": [
"string",
"null"
]
},
"reason": {
"enum": [
"created_for",
"deliberately_used",
"suggested"
],
"type": "string"
},
"source": {
"type": "object",
"required": [
"kind",
"id",
"scope"
],
"properties": {
"id": {
"type": "string"
},
"kind": {
"enum": [
"note",
"task",
"tracker",
"tracker_entry",
"skill",
"profile_block",
"external"
],
"type": "string"
},
"scope": {
"type": "object",
"required": [
"kind"
],
"properties": {
"kind": {
"enum": [
"private",
"workspace"
],
"type": "string"
},
"orgId": {
"type": "string"
},
"workspaceId": {
"type": "string"
}
}
}
}
},
"resourceId": {
"type": "string"
}
}
},
"maxItems": 25,
"description": "Attach created_for/deliberately_used sources; otherwise suggest. Removed links need restore; links do not share source content."
},
"checkpoint": {
"type": "string",
"description": "Factual handoff: changes, unfinished work, next step (4 KiB)."
},
"whenBucket": {
"enum": [
"anytime",
"someday",
null
],
"type": [
"string",
"null"
]
},
"instructions": {
"type": "string"
}
},
"description": "Project: sparse changes; omitted fields stay. Max 25 step/resource changes.",
"additionalProperties": false
},
"scope": {
"enum": [
"global",
"workspace",
"private"
],
"type": "string",
"description": "Profile: global|workspace. Projects: private; workspace requires workspaceId."
},
"title": {
"type": "string",
"description": "task/heading: required title/label."
},
"areaId": {
"type": "string",
"description": "project: required parent area."
},
"parent": {
"type": "string",
"description": "tag_relation: required parent tag of child_of edge."
},
"source": {
"type": "string",
"description": "note/tracker_entry: provenance; defaults conversation/agent-mcp respectively."
},
"status": {
"enum": [
"open",
"in_progress",
"done",
"canceled"
],
"type": "string",
"description": "task: initial status."
},
"whenAt": {
"type": "number",
"description": "task/project: schedule date (ms epoch)."
},
"content": {
"type": "string",
"description": "profile: required block content."
},
"deliver": {
"type": "object",
"description": "entityType:\"skill\": required with trigger; rhythm: required. Omit for on-demand. Scheduled output: {kind:'note',tags?:string[]}|{kind:'profile_block',blockName:string}|{kind:'notify'}."
},
"entries": {
"type": "array",
"description": "tracker_entry: up to 100 for one trackerId; each {payload,loggedAt?,agentNote?,noteIds?,source?,metadata?,externalId?}. Mutually exclusive with top-level payload. Receipts list saved/failed items and duplicates for stored externalIds; do not claim all saved from a partial result."
},
"noteIds": {
"type": "array",
"items": {
"type": "string"
},
"description": "tracker_entry: archival note IDs to attach. tracker_note_link: required note IDs to link."
},
"payload": {
"type": "object",
"description": "tracker_entry: tracker-defined data point; required unless entries is used."
},
"posture": {
"type": "string",
"description": "entityType:\"skill\" with trigger, or rhythm: read|propose|act; default read."
},
"skillId": {
"type": "string",
"description": "skill_invoke/skill_run: skill to run now/begin; required unless name is given."
},
"trigger": {
"type": "object",
"description": "entityType:\"skill\": optional; rhythm: required. Requires deliver. Penny does not run it; due signals reach the connected agent. Schedule: {kind:\"schedule\",cadence:\"daily\"|\"weekly\"|\"monthly\",at?:\"Fri 16:00\",timezone?:\"America/Denver\"}. ALWAYS set IANA timezone; default UTC shifts local times. Event: {kind:\"event\",on:\"note.created\",where?:{tags?:string[]}}."
},
"deadline": {
"type": "number",
"description": "task/project: hard due date (ms epoch)."
},
"rhythmId": {
"type": "string",
"description": "rhythm_run: rhythm to begin; or pass name."
},
"agentNote": {
"type": "string",
"description": "tracker_entry, single only: short non-searchable caption."
},
"blockName": {
"type": "string",
"description": "profile: required block name to upsert."
},
"dependsOn": {
"type": "array",
"items": {
"type": "string"
},
"description": "task: full prerequisite taskId set; replaces all."
},
"headingId": {
"type": "string",
"description": "task: parent heading."
},
"linkNotes": {
"type": "array",
"items": {
"type": "string"
},
"description": "task: note IDs to link."
},
"projectId": {
"type": "string",
"description": "task: parent Project. heading: required parent Project."
},
"reasoning": {
"type": "string",
"description": "tag_relation: short edge justification, typically a user quote."
},
"trackerId": {
"type": "string",
"description": "tracker_entry: required tracker to log against."
},
"entityType": {
"enum": [
"profile",
"task",
"area",
"project",
"project_interaction",
"heading",
"tracker",
"tracker_entry",
"rhythm",
"rhythm_run",
"skill",
"skill_invoke",
"skill_run",
"tag_relation",
"tracker_note_link",
"note"
],
"type": "string",
"description": "What to create; first match in the tool description's ladder wins."
},
"externalId": {
"type": "string",
"description": "tracker_entry, also entries items: source record ID, max 200 chars. Use for imports/sync: repeats on the same tracker return the existing entry as duplicate. Opaque, unencrypted: never include content."
},
"recordedAt": {
"type": "number",
"description": "tracker_entry, single only: observation time (ms epoch); default now."
},
"recurrence": {
"type": "object",
"required": [
"cadence"
],
"properties": {
"at": {
"type": "string",
"description": "daily: HH:MM; weekly: <Wd> HH:MM; monthly: DD HH:MM."
},
"cadence": {
"enum": [
"daily",
"weekly",
"monthly"
],
"type": "string"
},
"timezone": {
"type": "string",
"description": "IANA timezone (e.g. America/New_York)."
}
},
"description": "task: repeat. Returned taskId is the first occurrence; completion returns nextTaskId (see penny_edit status). Never reuse a completed occurrence's ID."
},
"targetSpec": {
"type": "object",
"description": "tracker: JSON target spec, interpreted at retrieval (e.g. {kind:'daily_minimum',value:10000})."
},
"whenBucket": {
"enum": [
"anytime",
"someday"
],
"type": "string",
"description": "task/project: undated bucket; mutually exclusive with whenAt."
},
"description": {
"type": "string",
"description": "tracker: required meaning. entityType:\"skill\"/rhythm: required one-line purpose, including on-demand skills."
},
"interaction": {
"type": "object",
"required": [
"kind",
"state"
],
"properties": {
"kind": {
"enum": [
"proposal",
"attention"
],
"type": "string"
},
"state": {
"enum": [
"proposed",
"declined",
"deferred",
"presented",
"dismissed",
"accepted"
],
"type": "string"
},
"taskId": {
"type": "string"
},
"content": {
"type": "string",
"description": "Rationale required for reconsideration."
},
"eventKey": {
"type": "string"
},
"objective": {
"type": "string",
"description": "First proposal objective."
},
"reconsider": {
"type": "boolean"
},
"urgencyKey": {
"type": "string"
},
"deferredUntil": {
"type": "number"
},
"expectedUpdatedAt": {
"type": "number"
}
},
"description": "project_interaction: actor decision; read first, update with expectedUpdatedAt."
},
"operationId": {
"type": "string",
"description": "Project receipt key; identical retries only."
},
"instructions": {
"type": "string",
"description": "skill: required know-how for invocation or when a connected agent picks up a due skill. Replaces rhythm goal."
},
"retrievalPlan": {
"type": "array",
"description": "entityType:\"skill\"/rhythm: optional deterministic steps [{tool,args}] for a bounded tier."
},
"trackerEntryId": {
"type": "string",
"description": "tracker_note_link: required entry to attach notes to."
},
"expectedRevision": {
"type": "number",
"description": "Project revision from Brief; reconcile conflicts."
},
"expectedUpdatedAt": {
"type": "number",
"description": "Source version from read."
}
}
}