@pmate/merry-scheduler 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# Scheduler
 
-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.
+Install @pmate/merry-scheduler and run merry-scheduler --help. Operators use pmate:factory authentication for owned Agent management. New tasks require an original authorized schedule request: an immutable command input reference or a Merry message reference read with a pmate:merry session. Agents use their own exact pmate:merry session and a source reference. No active Runtime Run is required. Source proof is verified by the server; user-provided transcripts are not accepted. Each job remains bound to its owning Agent and original requester conversation. API default https://issue-api.pmate.chat; PMATE_SCHEDULER_API_URL, PMATE_SCHEDULER_NAMESPACE, PMATE_SCHEDULER_TOPIC and PMATE_SCHEDULER_APP configure the independent client. Content JSON accepts prompt and timing only. List/get are read-only. Create/update/pause/resume/cancel use stable idempotency keys; updates also require expectedRevision. Conflict means read current state and reassess. Cancellation deactivates a job and retains history. Due jobs run as normal Runtime inputs on the owning Agent, without Master Agent dispatch.
+
+Run `merry-scheduler --help` for arguments. MCP: `node <plugin-directory>/mcp.mjs`.

package/index.mjs

@@ -0,0 +1,54 @@
+#!/usr/bin/env node
+import {readFileSync,statSync,realpathSync} from 'node:fs'
+import {execFileSync} from 'node:child_process'
+import {pathToFileURL} from 'node:url'
+export const HELP=`Usage: merry-scheduler list --agent ID [--source JSON]
+merry-scheduler get --agent ID --id ID [--source JSON]
+merry-scheduler create --agent ID --file JSON --idempotency-key KEY [--source JSON]
+merry-scheduler update --agent ID --id ID --expected-revision N --file JSON --idempotency-key KEY [--source JSON]
+merry-scheduler pause|resume|cancel --agent ID --id ID --expected-revision N --idempotency-key KEY [--source JSON]
+Content files contain prompt and/or timing. Source files contain verifiable conversation references.
+The target defaults to PMATE_SCHEDULER_AGENT_ID or PCS_AGENT_ID.
+No Runtime is required; uses an exact-app pmate CLI session and the Scheduler API.`
+function jsonFile(file){if(statSync(file).size>128000)throw Error('Scheduler file is too large');const text=readFileSync(file,'utf8');if(Buffer.byteLength(text)>128000)throw Error('Scheduler file is too large');return JSON.parse(text)}
+export function parse(args,env={}){
+ if(args.length===1&&['help','--help'].includes(args[0]))return{help:true}
+ const operation=args[0],fields={list:['agent','source'],get:['agent','id','source'],create:['agent','file','idempotency-key','source'],update:['agent','id','expected-revision','file','idempotency-key','source'],pause:['agent','id','expected-revision','idempotency-key','source'],resume:['agent','id','expected-revision','idempotency-key','source'],cancel:['agent','id','expected-revision','idempotency-key','source']}[operation]
+ if(!fields)throw Error(HELP)
+ const values={}
+ for(let i=1;i<args.length;i+=2){const key=args[i]?.slice(2),value=args[i+1];if(!args[i]?.startsWith('--')||!fields.includes(key)||Object.hasOwn(values,key)||!value?.trim())throw Error(HELP);values[key]=value}
+ const agent=values.agent??env.PMATE_SCHEDULER_AGENT_ID??env.PCS_AGENT_ID
+ if(!/^0x[a-f0-9]{64}$/.test(agent??''))throw Error('Explicit Agent Profile ID required (--agent)')
+ const body={}
+ for(const key of ['id','idempotency-key'])if(values[key])body[key==='id'?'id':'idempotencyKey']=values[key]
+ if(values['expected-revision']){if(!/^[1-9][0-9]*$/.test(values['expected-revision'])||!Number.isSafeInteger(Number(values['expected-revision'])))throw Error('Positive revision required');body.expectedRevision=Number(values['expected-revision'])}
+ if(operation!=='list'&&operation!=='create'&&!body.id||!['list','get'].includes(operation)&&!body.idempotencyKey||['update','pause','resume','cancel'].includes(operation)&&!body.expectedRevision)throw Error(HELP)
+ if(['create','update'].includes(operation)){
+  if(!values.file)throw Error(HELP)
+  const patch=jsonFile(values.file)
+  if(!patch||typeof patch!=='object'||Array.isArray(patch)||!Object.keys(patch).length||Object.keys(patch).some(key=>!['prompt','timing'].includes(key)))throw Error('Scheduler content accepts only prompt and timing')
+  Object.assign(body,patch)
+ }
+ if(values.source)body.source=jsonFile(values.source)
+ else if(env.MERRY_RUNTIME_INPUT_ID)body.source={kind:'command',inputId:env.MERRY_RUNTIME_INPUT_ID}
+ if(operation==='create'&&!body.source)throw Error('An authorized source is required (--source JSON)')
+ return{agent,operation,body}
+}
+export function readSession(app,env){try{return JSON.parse(execFileSync('pmate',['session','read','--app',app],{env,encoding:'utf8',timeout:15000,maxBuffer:32768,stdio:['ignore','pipe','pipe']}))}catch{throw Error(`Unable to read session; run pmate login --app ${app}`)}}
+export async function scheduler(args,{env=process.env,fetcher=fetch,session=readSession}={}){
+ const parsed=parse(args,env);if(parsed.help)return HELP
+ const {agent,operation,body}=parsed,app=env.PMATE_SCHEDULER_APP??(env.PCS_AGENT_ID?'pmate:merry':'pmate:factory')
+ const identity=await session(app,env)
+ if(!identity?.token||!identity.accountId||!identity.profileId||!Number.isFinite(Date.parse(identity.expiresAt))||Date.parse(identity.expiresAt)<=Date.now())throw Error(`Session missing or expired; run pmate login --app ${app}`)
+ if(env.PCS_AGENT_ID&&identity.profileId!==env.PCS_AGENT_ID)throw Error('Scheduler session does not match the executing Agent')
+ const base=new URL(env.PMATE_SCHEDULER_API_URL??env.PCS_ISSUES_API_URL??'https://issue-api.pmate.chat')
+ if(base.protocol!=='https:'&&!(base.protocol==='http:'&&['127.0.0.1','localhost','[::1]'].includes(base.hostname)))throw Error('Scheduler API requires HTTPS or loopback')
+ const namespace=env.PMATE_SCHEDULER_NAMESPACE??'pcs-agent',topic=env.PMATE_SCHEDULER_TOPIC??'merry'
+ const url=new URL(`/v2/topics/${encodeURIComponent(namespace)}/${encodeURIComponent(topic)}/agents/${encodeURIComponent(agent)}/schedules/${operation}`,base)
+ const response=await fetcher(url,{method:'POST',headers:{authorization:`Bearer ${identity.token}`,'x-pmate-app':app,'content-type':'application/json',...(env.PCS_AGENT_ID?{'x-pcs-agent-id':env.PCS_AGENT_ID}:{})},body:JSON.stringify(body),signal:AbortSignal.timeout(30000),redirect:'error'})
+ let result;try{result=await response.json()}catch{throw Error(`Scheduler API returned invalid JSON (${response.status}); mutation outcome may be uncertain`)}
+ if(!response.ok||!result.success)throw Object.assign(Error(result.message??`Scheduler operation failed (${response.status})`),{httpCode:response.status})
+ return result.data
+}
+export default async function invoke(_host,args){return scheduler(args)}
+if(process.argv[1]&&import.meta.url===pathToFileURL(realpathSync(process.argv[1])).href){try{const result=await scheduler(process.argv.slice(2));console.log(typeof result==='string'?result:JSON.stringify(result))}catch(error){console.error(error.message);process.exitCode=1}}

package/manifest.json

@@ -0,0 +1,113 @@
+{
+  "schemaVersion": 2,
+  "id": "scheduler",
+  "kind": "plugin",
+  "name": "Scheduler",
+  "version": "1.0.0",
+  "description": "Independent authenticated Agent schedule management; no Runtime required",
+  "docs": [
+    {
+      "name": "host-instructions",
+      "content": "Scheduler is an independent plugin. Read scheduler help before CRUD. Use the exact authenticated identity, a verified source reference, current revisions and stable idempotency keys. Runtime is only needed later to execute due tasks in their owning Agent environment."
+    },
+    {
+      "name": "scheduler",
+      "content": "Install @pmate/merry-scheduler and run merry-scheduler --help. Operators use pmate:factory authentication for owned Agent management. New tasks require an original authorized schedule request: an immutable command input reference or a Merry message reference read with a pmate:merry session. Agents use their own exact pmate:merry session and a source reference. No active Runtime Run is required. Source proof is verified by the server; user-provided transcripts are not accepted. Each job remains bound to its owning Agent and original requester conversation. API default https://issue-api.pmate.chat; PMATE_SCHEDULER_API_URL, PMATE_SCHEDULER_NAMESPACE, PMATE_SCHEDULER_TOPIC and PMATE_SCHEDULER_APP configure the independent client. Content JSON accepts prompt and timing only. List/get are read-only. Create/update/pause/resume/cancel use stable idempotency keys; updates also require expectedRevision. Conflict means read current state and reassess. Cancellation deactivates a job and retains history. Due jobs run as normal Runtime inputs on the owning Agent, without Master Agent dispatch."
+    }
+  ],
+  "configSchema": {
+    "type": "object",
+    "properties": {},
+    "additionalProperties": false
+  },
+  "executables": [
+    {
+      "name": "scheduler",
+      "entry": "./index.mjs"
+    },
+    {
+      "name": "mcp",
+      "entry": "./mcp.mjs"
+    }
+  ],
+  "services": [],
+  "defaultForAgents": true,
+  "commands": [
+    {
+      "name": "schedule",
+      "description": "管理我的定时任务",
+      "usage": "/schedule <任务安排或修改要求>",
+      "arguments": {
+        "type": "text",
+        "required": true,
+        "placeholder": "描述任务内容、时间或需要修改的计划"
+      },
+      "execution": {
+        "type": "agent",
+        "executor": "target-agent",
+        "inference": {
+          "mode": "explicit",
+          "engine": "codex",
+          "model": "gpt-6.1-sol",
+          "reasoningEffort": "medium"
+        }
+      },
+      "subcommands": [
+        {
+          "name": "show",
+          "description": "查看我的定时任务",
+          "usage": "/schedule show [查看范围]",
+          "arguments": {
+            "type": "text",
+            "required": false
+          }
+        },
+        {
+          "name": "create",
+          "description": "创建定时任务",
+          "usage": "/schedule create <任务要求>",
+          "arguments": {
+            "type": "text",
+            "required": true
+          }
+        },
+        {
+          "name": "update",
+          "description": "修改定时任务",
+          "usage": "/schedule update <任务要求>",
+          "arguments": {
+            "type": "text",
+            "required": true
+          }
+        },
+        {
+          "name": "pause",
+          "description": "暂停定时任务",
+          "usage": "/schedule pause <任务要求>",
+          "arguments": {
+            "type": "text",
+            "required": true
+          }
+        },
+        {
+          "name": "resume",
+          "description": "恢复定时任务",
+          "usage": "/schedule resume <任务要求>",
+          "arguments": {
+            "type": "text",
+            "required": true
+          }
+        },
+        {
+          "name": "cancel",
+          "description": "取消定时任务",
+          "usage": "/schedule cancel <任务要求>",
+          "arguments": {
+            "type": "text",
+            "required": true
+          }
+        }
+      ]
+    }
+  ]
+}

package/mcp.mjs

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+import {schedulerTools,callSchedulerTool} from './tools.mjs'
+let buffer=''
+const decoder=new TextDecoder()
+for await(const chunk of process.stdin){
+ buffer+=decoder.decode(chunk,{stream:true})
+ for(;;){const end=buffer.indexOf('\n');if(end<0)break;const line=buffer.slice(0,end);buffer=buffer.slice(end+1);if(!line.trim())continue
+  let request
+  try{request=JSON.parse(line);if(request.id===undefined)continue;let result
+   if(request.method==='initialize')result={protocolVersion:'2024-11-05',capabilities:{tools:{}},serverInfo:{name:'scheduler',version:'1'}}
+   else if(request.method==='tools/list')result={tools:schedulerTools}
+   else if(request.method==='tools/call'){try{result={content:[{type:'text',text:JSON.stringify(await callSchedulerTool(request.params.name,request.params.arguments??{}))}]}}catch(error){const status=error.httpCode;result={isError:true,content:[{type:'text',text:status===409?'Scheduler conflict: read the current entry before reassessing; a reused key must keep the identical payload.':status===403?'Scheduler operation is not authorized for this request.':status===404?'Scheduler entry was not found.':status===400?'Invalid scheduler arguments. Read scheduler_help.':'Scheduler operation failed or its outcome is uncertain. Retry only the same operation with the same idempotency key.'}]}}}
+   else if(request.method==='ping')result={}
+   else{process.stdout.write(JSON.stringify({jsonrpc:'2.0',id:request.id,error:{code:-32601,message:'Method not found'}})+'\n');continue}
+   process.stdout.write(JSON.stringify({jsonrpc:'2.0',id:request.id,result})+'\n')
+  }catch{process.stdout.write(JSON.stringify({jsonrpc:'2.0',id:request?.id??null,error:{code:-32603,message:'Invalid scheduler protocol request'}})+'\n')}
+ }
+}

package/package.json

@@ -1,6 +1,20 @@
 {
   "name": "@pmate/merry-scheduler",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "type": "module",
+  "description": "Independent authenticated Agent schedule management; no Runtime required",
+  "bin": {
+    "merry-scheduler": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "mcp.mjs",
+    "tools.mjs",
+    "manifest.json",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "UNLICENSED"
+}

package/tools.mjs

@@ -0,0 +1,23 @@
+import {mkdtempSync,writeFileSync,rmSync} from 'node:fs'
+import {join} from 'node:path'
+import {tmpdir} from 'node:os'
+import {scheduler,HELP} from './index.mjs'
+const text={type:'string'},source={type:'object',description:'Verified command or original Merry message reference; never a transcript'},timing={type:'object',description:'Validated once, interval or calendar timing'}
+const properties={agentId:text,id:text,expectedRevision:{type:'integer',minimum:1},prompt:text,timing,source,idempotencyKey:text}
+const definitions=[['help',[],[]],['list',['agentId','source'],[]],['get',['agentId','id','source'],['id']],['create',['agentId','prompt','timing','source','idempotencyKey'],['prompt','timing','idempotencyKey']],['update',['agentId','id','expectedRevision','prompt','timing','source','idempotencyKey'],['id','expectedRevision','idempotencyKey']],...['pause','resume','cancel'].map(op=>[op,['agentId','id','expectedRevision','source','idempotencyKey'],['id','expectedRevision','idempotencyKey']])]
+export const schedulerTools=definitions.map(([operation,fields,required])=>({name:`scheduler_${operation}`,description:operation==='help'?'Read the independent Scheduler plugin help':`Manage authorized Agent schedules: ${operation}`,inputSchema:{type:'object',properties:Object.fromEntries(fields.map(k=>[k,properties[k]])),required,additionalProperties:false}}))
+export async function callSchedulerTool(name,value,ports={}){
+ const tool=schedulerTools.find(t=>t.name===name)
+ if(!tool||!value||typeof value!=='object'||Array.isArray(value)||Object.keys(value).some(k=>!Object.hasOwn(tool.inputSchema.properties,k))||tool.inputSchema.required.some(k=>value[k]===undefined))throw Error('Invalid scheduler arguments')
+ if(name==='scheduler_help')return HELP
+ const args=[name.slice(10)],flags={agentId:'agent',expectedRevision:'expected-revision',idempotencyKey:'idempotency-key'}
+ for(const [key,v]of Object.entries(value))if(!['prompt','timing','source'].includes(key))args.push(`--${flags[key]??key}`,String(v))
+ let directory
+ try{
+  const files=[]
+  if(value.source!==undefined)files.push(['source',value.source])
+  if(['scheduler_create','scheduler_update'].includes(name))files.push(['file',Object.fromEntries(Object.entries(value).filter(([k])=>['prompt','timing'].includes(k)))])
+  if(files.length){directory=mkdtempSync(join(tmpdir(),'merry-scheduler-'));for(const [flag,body]of files){const file=join(directory,`${flag}.json`);writeFileSync(file,JSON.stringify(body),{mode:0o600});args.push(`--${flag}`,file)}}
+  return await scheduler(args,ports)
+ }finally{if(directory)rmSync(directory,{recursive:true,force:true})}
+}