ticlawk 0.1.16-dev.13 → 0.1.16-dev.14

package/bin/ticlawk.mjs

@@ -42,6 +42,7 @@ import {
   runDashboardSetCommand,
   runDashboardGetCommand,
   runCredentialRequestCommand,
+  runBriefingPublishCommand,
   runServiceCreateCommand,
   runServiceUpdateCommand,
   runServiceDeleteCommand,
@@ -538,6 +539,20 @@ async function main() {
     process.exit(1);
   }
 
+  if (command === 'briefing') {
+    const sub = args._[1];
+    if (args.help || args.h || !sub) {
+      console.log(AGENT_COMMAND_HELP.briefing);
+      return;
+    }
+    if (sub === 'publish') {
+      process.exitCode = await runBriefingPublishCommand(args);
+      return;
+    }
+    console.error(`unknown briefing subcommand: ${sub}`);
+    process.exit(1);
+  }
+
   if (command === 'credential') {
     const sub = args._[1];
     if (args.help || args.h || !sub) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ticlawk",
-  "version": "0.1.16-dev.13",
+  "version": "0.1.16-dev.14",
   "description": "Local connector that links agent harnesses (Claude Code, Codex, OpenClaw, opencode, Pi) to the Ticlawk mobile app.",
   "type": "module",
   "main": "ticlawk.mjs",

package/src/adapters/ticlawk/api.mjs

@@ -610,6 +610,18 @@ export async function callService({ actingAgentId, name, input }) {
   );
 }
 
+// ── Briefings (CoS publish) ──
+
+export async function publishBriefing({actingAgentId, bodyText, bodyHtml}) {
+  const body = { acting_as_agent_id: actingAgentId };
+  if (bodyText != null) body.body_text = bodyText;
+  if (bodyHtml != null) body.body_html = bodyHtml;
+  return apiFetch('/api/agent/briefings', {
+    method: 'POST',
+    body: JSON.stringify(body),
+  });
+}
+
 // ── Credentials (CoS slot creation) ──
 
 export async function requestCredential({

package/src/adapters/ticlawk/index.mjs

@@ -167,11 +167,11 @@ const COS_ADDENDUM = [
   '',
   'Owner model: hold the user\'s preferences and constraints across workstreams. Apply them consistently. Do not "for-your-own-good" around stated preferences.',
   '',
-  '奏折 / report posture: publish status to the user by sending a message into the CoS DM with `ticlawk message send --target dm:@<owner> --kind report` (stdin = the report body). Use this for scheduled summaries, escalations, or workstream check-ins. Reports surface in the Office → 奏折 sub-tab; chat replies do not. Do not over-spam reports — one per meaningful state change.',
+  'Briefing posture: publish briefings via `ticlawk briefing publish` — this is a SEPARATE surface from chat. Two content formats: `--text "<≤100 chars>"` for short pings, or `--html <path/to/file.html>` for rich one-page bodies. Briefings do NOT appear in the chat stream — they only render in Office → Briefings as full-screen cards owner steps through. Do not over-spam — one per meaningful state change. When the owner taps "comment" on a briefing, the inbound reply message carries metadata.context_ref = { kind: "briefing", briefing_id }; thread the conversation from there.',
   '',
-  'Dashboard posture: maintain a per-workstream dashboard via `ticlawk dashboard set --target "#<ws>"` (stdin JSON: { data_json, html_template }). data_json holds the live numbers; html_template is the hand-written rendering. CoS replaces wholesale — there is no partial update protocol, and there is no schema lock-in on data_json. Use the dashboard for at-a-glance state; use 奏折 for narrative.',
+  'Dashboard posture: maintain a per-workstream dashboard via `ticlawk dashboard set --target "#<ws>"` (stdin JSON: { data_json, html_template }). data_json holds the live numbers; html_template is the hand-written rendering. CoS replaces wholesale — there is no partial update protocol, and there is no schema lock-in on data_json. Use the dashboard for at-a-glance state; use Briefings for narrative. When the owner replies to a dashboard via the Office "聊一下" path, the inbound message carries metadata.context_ref pointing at the workstream; thread the conversation from there.',
   '',
-  'Cadence: schedule your own daily 晨报 via `ticlawk reminder schedule --title "晨报" --in-minutes 1440 --anchor-conversation-id <your DM with owner>` after you handle this turn. The reminder fires by waking you with a system message; treat that wake as the trigger to compile the day\'s 奏折 across workstreams. Re-schedule on each fire so the cadence persists. Skip a day only if you are explicitly told to.',
+  'Cadence: schedule your own daily morning briefing via `ticlawk reminder schedule --title "morning briefing" --in-minutes 1440 --anchor-conversation-id <your DM with owner>` after you handle this turn. The reminder fires by waking you with a system message; treat that wake as the trigger to compile the day\'s briefings across workstreams. Re-schedule on each fire so the cadence persists. Skip a day only if you are explicitly told to.',
   '[/cos-role]',
 ].join('\n');
 

package/src/cli/agent-commands.mjs

@@ -161,7 +161,7 @@ export async function runMessageSendCommand(args) {
   }
 
   // Optional --kind <s> classifies the message via metadata.kind. The
-  // canonical user-facing value is 'report' (奏折 surface). Anything else
+  // canonical user-facing value is 'briefing' (Office Briefings surface). Anything else
   // is passed through as-is so we don't have to update this list to add
   // new conventions.
   const kind = getArg(args, 'kind');
@@ -1022,6 +1022,41 @@ export async function runServiceCallCommand(args) {
   return exitFromStatus(res.statusCode);
 }
 
+export async function runBriefingPublishCommand(args) {
+  const env = requireAgentEnv();
+  const textArg = getArg(args, 'text');
+  const htmlPath = getArg(args, 'html');
+  if ((textArg && htmlPath) || (!textArg && !htmlPath)) {
+    console.error('exactly one of --text "<short>" or --html <path> is required');
+    return 2;
+  }
+  let bodyText = null;
+  let bodyHtml = null;
+  if (textArg) {
+    if (textArg.length > 100) {
+      console.error('--text must be ≤100 chars');
+      return 2;
+    }
+    bodyText = textArg;
+  } else {
+    try {
+      const fs = await import('node:fs');
+      bodyHtml = fs.readFileSync(String(htmlPath), 'utf8');
+    } catch (err) {
+      console.error(`could not read --html file: ${err?.message || err}`);
+      return 2;
+    }
+  }
+  const res = await daemonRequest({
+    method: 'POST',
+    path: '/agent/briefing/publish',
+    headers: commonHeaders(env),
+    body: { body_text: bodyText, body_html: bodyHtml },
+  });
+  printJson(res.body);
+  return exitFromStatus(res.statusCode);
+}
+
 export async function runCredentialRequestCommand(args) {
   const env = requireAgentEnv();
   const name = getArg(args, 'name');
@@ -1158,7 +1193,7 @@ export const AGENT_COMMAND_HELP = {
   ticlawk message send --target "<target>" [--seen-up-to-seq N] [--reply-to <msg-id>] [--attach <file> ...] [--kind <kind>]
     Body is read from stdin (use <<'EOF' ... EOF for multiline).
     --kind <kind> tags this message via metadata.kind. The CoS uses
-      --kind report to publish a 奏折 / status report that the Office
+      --kind briefing to publish a status briefing that the Office
       tab can list separately.
     Targets:
       dm:@<user>         private message
@@ -1236,6 +1271,14 @@ export const AGENT_COMMAND_HELP = {
     Any agent. Returns contract_schema + description.
   service call --name X    # input from stdin (JSON)
     Any agent. Backend proxies to endpoint_config.url. No retry.
+`,
+  briefing: `ticlawk briefing publish (--text "..." | --html <path>)
+    CoS-only. Publish a briefing to the owner's Office → Briefings.
+    --text  short plain text (≤100 chars), use for one-liner pings
+    --html  path to an HTML file; body is rendered as a full-screen card
+    Briefings are independent of chat — they do NOT appear in the CoS
+    DM message stream. Use this verb (not \`message send\`) for any
+    status surface the owner consumes in Office.
 `,
   credential: `ticlawk credential request --name <ENV_VAR> [--description Y] [--workstream "#<ws>"]
     CoS-only. Pre-allocate a credential slot. Response includes a deep

package/src/core/agent-cli-handlers.mjs

@@ -908,6 +908,26 @@ export async function handleServiceCall(req, body, ctx) {
   }
 }
 
+export async function handleBriefingPublish(req, body, ctx) {
+  const actingAgentId = getActingAgentId(req, body);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const bodyText = typeof body?.body_text === 'string' && body.body_text.trim() ? body.body_text : null;
+  const bodyHtml = typeof body?.body_html === 'string' && body.body_html.trim() ? body.body_html : null;
+  if ((bodyText && bodyHtml) || (!bodyText && !bodyHtml)) {
+    return { status: 400, body: { error: 'exactly one of body_text or body_html is required' } };
+  }
+  if (bodyText && bodyText.length > 100) {
+    return { status: 400, body: { error: 'body_text must be ≤100 chars' } };
+  }
+  try {
+    const data = await api.publishBriefing({ actingAgentId, bodyText, bodyHtml });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'briefing publish failed' } };
+  }
+}
+
 export async function handleCredentialRequest(req, body, ctx) {
   const actingAgentId = getActingAgentId(req, body);
   const v = validateActingAgent(actingAgentId, ctx);

package/src/core/http.mjs

@@ -13,6 +13,7 @@ import {
   handleWorkstreamDashboardSet,
   handleWorkstreamDashboardGet,
   handleCredentialRequest,
+  handleBriefingPublish,
   handleServiceCreate,
   handleServiceUpdate,
   handleServiceDelete,
@@ -287,6 +288,12 @@ export function startLocalHttpServer({ port, adapter, ctx }) {
         const r = await handleWorkstreamDashboardGet(req, parseQuery(req.url || ''), cliCtx);
         return writeJson(res, r.status, r.body);
       }
+      if (urlNoQuery === '/agent/briefing/publish' && method === 'POST') {
+        const body = await readJsonBody(req);
+        if (body === null) return writeJson(res, 400, { error: 'invalid json body' });
+        const r = await handleBriefingPublish(req, body, cliCtx);
+        return writeJson(res, r.status, r.body);
+      }
       if (urlNoQuery === '/agent/credential/request' && method === 'POST') {
         const body = await readJsonBody(req);
         if (body === null) return writeJson(res, 400, { error: 'invalid json body' });