ticlawk 0.1.16-dev.13 → 0.1.16-dev.15

package/bin/ticlawk.mjs

@@ -42,6 +42,8 @@ import {
   runDashboardSetCommand,
   runDashboardGetCommand,
   runCredentialRequestCommand,
+  runBriefingPublishCommand,
+  runBriefingGetCommand,
   runServiceCreateCommand,
   runServiceUpdateCommand,
   runServiceDeleteCommand,
@@ -538,6 +540,24 @@ 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;
+    }
+    if (sub === 'get') {
+      process.exitCode = await runBriefingGetCommand(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.15",
   "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,24 @@ export async function callService({ actingAgentId, name, input }) {
   );
 }
 
+// ── Briefings (CoS publish) ──
+
+export async function getBriefing({actingAgentId, briefingId}) {
+  const params = new URLSearchParams();
+  params.set('acting_as_agent_id', actingAgentId);
+  return apiFetch(`/api/agent/briefings/${encodeURIComponent(briefingId)}?${params}`);
+}
+
+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');
 
@@ -180,12 +180,39 @@ function buildCosAddendum(msg) {
   return COS_ADDENDUM;
 }
 
+// Quote block: surfaced just above the user's reply so the agent sees
+// what artifact the reply is *about*. Source of truth is
+// `messages.metadata.quote = { kind, ref, snippet }`. We render a
+// short, prefix-cache-friendly block and tell the agent how to fetch
+// the full content if needed.
+function buildQuoteBlock(msg) {
+  const meta = msg.message_metadata || msg.metadata || null;
+  const quote = meta && typeof meta === 'object' ? meta.quote : null;
+  if (!quote || typeof quote !== 'object') return '';
+  const kind = String(quote.kind || '').trim();
+  const ref = String(quote.ref || '').trim();
+  const snippet = String(quote.snippet || '').trim();
+  if (!kind || !ref) return '';
+  const fetchHint = kind === 'briefing'
+    ? `ticlawk briefing get ${ref}`
+    : kind === 'dashboard'
+      ? `ticlawk dashboard get --target "#${ref}"`
+      : kind === 'message'
+        ? `ticlawk message read --around ${ref}`
+        : '';
+  const lines = ['[quote', `  kind=${kind} ref=${ref}`];
+  if (snippet) lines.push(`  "${snippet.replace(/"/g, '\\"')}"`);
+  if (fetchHint) lines.push(`  fetch: ${fetchHint}`);
+  lines.push('[/quote]');
+  return lines.join('\n');
+}
+
 // Wrap each per-turn message with an explicit reply instruction so the
 // runtime LLM never has to remember the standing prompt to figure out
 // HOW to reply. Codex in particular treats the developerInstructions as
 // background and ignores the chat-send pattern without this per-turn
 // nudge.
-function buildWakePromptText({ envelopeHeader, target, rawText, groupContext, charterBlock, cosAddendum }) {
+function buildWakePromptText({ envelopeHeader, target, rawText, groupContext, charterBlock, cosAddendum, quoteBlock }) {
   const body = `${envelopeHeader} ${rawText || ''}`.trim();
   const lines = [];
   if (charterBlock) {
@@ -194,6 +221,9 @@ function buildWakePromptText({ envelopeHeader, target, rawText, groupContext, ch
   if (cosAddendum) {
     lines.push(cosAddendum, '');
   }
+  if (quoteBlock) {
+    lines.push(quoteBlock, '');
+  }
   lines.push('New message received:', '', body);
   if (groupContext) {
     lines.push('', groupContext);
@@ -230,8 +260,9 @@ export function normalizeInboundMessage(msg) {
   const groupContext = buildGroupContextBlock(enriched);
   const charterBlock = buildCharterBlock(enriched);
   const cosAddendum = buildCosAddendum(enriched);
+  const quoteBlock = buildQuoteBlock(enriched);
   const text = header
-    ? buildWakePromptText({ envelopeHeader: header, target, rawText, groupContext, charterBlock, cosAddendum })
+    ? buildWakePromptText({ envelopeHeader: header, target, rawText, groupContext, charterBlock, cosAddendum, quoteBlock })
     : rawText;
   return {
     bindingId: recipientAgentId,

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,56 @@ export async function runServiceCallCommand(args) {
   return exitFromStatus(res.statusCode);
 }
 
+export async function runBriefingGetCommand(args) {
+  const env = requireAgentEnv();
+  const id = args._[2] || getArg(args, 'id');
+  if (!id) { console.error('briefing id required (positional or --id)'); return 2; }
+  const params = new URLSearchParams();
+  params.set('id', id);
+  const res = await daemonRequest({
+    method: 'GET',
+    path: `/agent/briefing/get?${params}`,
+    headers: commonHeaders(env),
+  });
+  printJson(res.body);
+  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 +1208,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 +1286,19 @@ 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|get>
+  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.
+  briefing get <id>
+    Fetch a briefing including body_text/body_html. Use this when a
+    quote (metadata.quote.kind=briefing) points at a briefing whose
+    full body you want to read.
 `,
   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,40 @@ export async function handleServiceCall(req, body, ctx) {
   }
 }
 
+export async function handleBriefingGet(req, query, ctx) {
+  const actingAgentId = getActingAgentId(req, query);
+  const v = validateActingAgent(actingAgentId, ctx);
+  if (!v.ok) return { status: v.status, body: { error: v.error } };
+  const briefingId = String(query?.id || '').trim();
+  if (!briefingId) return { status: 400, body: { error: 'id is required' } };
+  try {
+    const data = await api.getBriefing({ actingAgentId, briefingId });
+    return { status: 200, body: data };
+  } catch (err) {
+    return { status: err?.status || 500, body: { error: err?.message || 'briefing get failed' } };
+  }
+}
+
+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,8 @@ import {
   handleWorkstreamDashboardSet,
   handleWorkstreamDashboardGet,
   handleCredentialRequest,
+  handleBriefingPublish,
+  handleBriefingGet,
   handleServiceCreate,
   handleServiceUpdate,
   handleServiceDelete,
@@ -287,6 +289,16 @@ 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/briefing/get' && method === 'GET') {
+        const r = await handleBriefingGet(req, parseQuery(req.url || ''), 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' });

package/src/runtimes/_shared/standing-prompt.mjs

@@ -22,6 +22,7 @@ to users or groups.
 - Always claim a task via \`ticlawk task claim\` before doing any substantive work on it. If the claim fails, stop immediately and pick a different task.
 - Use only the provided \`ticlawk\` CLI commands for messaging.
 - If the turn opens with a \`[charter] ... [/charter]\` block, that is the workstream's binding spec (规章制度). Every action you take in this conversation must conform to it. If a request conflicts with the charter, stop and surface the conflict to the Chief of Staff (CoS) — don't silently route around it.
+- If the turn opens with a \`[quote ... [/quote]\` block, the user is replying with a quoted artifact in context. The block carries \`kind=<message|briefing|dashboard>\`, \`ref=<id>\`, a snippet, and a \`fetch:\` command to read the full content if you need it. Treat the user's text as a response *to* that artifact.
 - Shared services are CoS-published tools you can invoke. \`ticlawk service list\` shows available names + descriptions; \`ticlawk service info --name X\` shows the input contract; \`ticlawk service call --name X\` runs it with stdin JSON input. There is no retry — call failure means stop and report; do not loop.
 
 ## Startup checklist (every turn)