@wirecat/cli-core 0.548.0 → 0.549.0

package/dist/cli/program.js

@@ -2,6 +2,7 @@ import { join } from "node:path";
 import { CliError, errorObjectOf, errorRecordOf, exitCodeFor, exitCodeOfError, processStreams, renderError, resolvePaths, } from "@wirecat/cli-base";
 import { metaOf, refuseJoinedPath } from "@wirecat/cli-base/commands";
 import { skillHint } from "@wirecat/cli-base/skill";
+import { COMPACT_FLAG } from "@wirecat/cli-base/standards";
 import { Command, Help } from "commander";
 import { relayCommand } from "../background/relay.js";
 import { failingNotice, scheduledRuns } from "../background/schedules.js";
@@ -17,6 +18,7 @@ import { liftOptionsAfterDashes } from "./after-dashes.js";
 import { logParsedArgv, logVersion } from "./argv-log.js";
 import { commandAvailability } from "./command-availability.js";
 import { commandPathOf } from "./command-contract.js";
+import { entityRows } from "./compact.js";
 import { outputFor, provide } from "./context.js";
 import { refuseByCommandPermissions, refuseWriteBeforeConnecting } from "./early-refusal.js";
 import { changesAuthorityAt, changesAuthorityNow, isLogin, isStoreChange, judgedEffects, judgedTargets, storeChangeRefusal, } from "./effects.js";
@@ -73,6 +75,7 @@ export const createProgram = (definition, { out, err } = {}) => {
         .option("--max-output-bytes <bytes>", "maximum machine output bytes (default: 4194304; 0 disables)")
         .option("--brief", `${found} as reference, title, time, ${messenger ? "sender" : "author"} and excerpt only`)
         .option("--full", `${found} with their whole text and every provider field`)
+        .option(COMPACT_FLAG, "one line per item for an agent: reference first, text last, paging and next steps as # lines")
         .option("--dry-run", "preview parsed arguments and permissions before running the action")
         .option("--yes", "go ahead without the question an ask level puts before a write")
         .option("--record", "keep this run even where the config says record false; record_input false leaves the typed words out")
@@ -82,6 +85,8 @@ export const createProgram = (definition, { out, err } = {}) => {
         program.addCommand(command);
     configure?.(program);
     if (!contractsChecked.has(definition)) {
+        if (definition.rows)
+            entityRows(definition.rows);
         assertSharedContracts(program);
         contractsChecked.add(definition);
     }
@@ -136,7 +141,7 @@ export const run = async (argv, definition, options = {}) => {
         useAsProcessRun(outer);
     }
 };
-const isMachine = (words) => words.some((word) => word === "--json" || word.startsWith("--json=") || word === "--jsonl");
+const isMachine = (words) => words.some((word) => word === "--json" || word.startsWith("--json=") || word === "--jsonl" || word === COMPACT_FLAG);
 const runOnce = async (argv, definition, options) => {
     const streams = options.streams ?? processStreams;
     if (!options.streams)
@@ -218,6 +223,7 @@ const runOnce = async (argv, definition, options) => {
         commandSignal: control.signal,
         trackCloseable: control.trackCloseable,
         app: definition.app,
+        ...(definition.rows ? { rows: definition.rows } : {}),
         platform: options.platform ?? process.platform,
         exit,
         runCommand: (words, given) => run(words, definition, given),

package/dist/domain/providers.d.ts

@@ -1,4 +1,5 @@
 import type { Provider } from "./models.js";
+import { type RefKindName } from "./references.js";
 /** What a search reads; the same names `--only`, `searched` and `skipped` use. */
 export declare const KINDS: readonly ["messages", "mail", "notes", "documents", "meetings", "events"];
 export type Kind = (typeof KINDS)[number];
@@ -8,6 +9,8 @@ export interface ProviderEntry {
     aliases: readonly string[];
     /** The CLI that wrote the entry (`zm`, `drive`). One CLI may write several providers, so it is not an alias. */
     command?: string;
+    /** The read command, after `<command> <profile>`, that opens a ref of each kind: `{ chat: "messages list" }`. */
+    opens?: Partial<Record<RefKindName, string>>;
 }
 /** The seed: what cli-core knows before any CLI has written its entry into the store. */
 export declare const PROVIDERS: readonly ProviderEntry[];

package/dist/domain/providers.js

@@ -1,13 +1,15 @@
 import { CliError } from "@wirecat/cli-base";
+import { REF_KINDS } from "./references.js";
 /** What a search reads; the same names `--only`, `searched` and `skipped` use. */
 export const KINDS = ["messages", "mail", "notes", "documents", "meetings", "events"];
+const MESSENGER_OPENS = { chat: "messages list", message: "messages show", contact: "contacts show" };
 /** The seed: what cli-core knows before any CLI has written its entry into the store. */
 export const PROVIDERS = [
-    { name: "telegram", kind: "messages", aliases: ["tg"], command: "tg" },
+    { name: "telegram", kind: "messages", aliases: ["tg"], command: "tg", opens: MESSENGER_OPENS },
     { name: "telegram-bot", kind: "messages", aliases: ["tg-bot"] },
-    { name: "max", kind: "messages", aliases: [], command: "max" },
+    { name: "max", kind: "messages", aliases: [], command: "max", opens: MESSENGER_OPENS },
     { name: "max-bot", kind: "messages", aliases: [] },
-    { name: "whatsapp", kind: "messages", aliases: ["wa"], command: "wa" },
+    { name: "whatsapp", kind: "messages", aliases: ["wa"], command: "wa", opens: MESSENGER_OPENS },
     { name: "whatsapp-bot", kind: "messages", aliases: ["wa-bot"] },
     { name: "email", kind: "mail", aliases: [] },
     { name: "notes", kind: "notes", aliases: [] },
@@ -58,11 +60,23 @@ const invalid = (message) => {
 const wordOf = (value, what) => typeof value === "string" && WORD.test(value)
     ? value
     : invalid(`${what} is lowercase letters, digits, - and _ — not ${JSON.stringify(value)}`);
+const OPEN_KINDS = new Set(REF_KINDS.map(({ type }) => type).filter((type) => type !== "entity"));
+const COMMAND_WORDS = /^[a-z0-9][a-z0-9_-]*( [a-z0-9][a-z0-9_-]*)*$/;
+/** A kind this build does not know is dropped, not refused: a newer CLI may open kinds added after this release. */
+const opensOf = (value, named) => {
+    if (typeof value !== "object" || value === null || Array.isArray(value))
+        return invalid(`provider ${named}'s opens maps a kind of reference to a command`);
+    const known = Object.entries(value).filter(([kind]) => OPEN_KINDS.has(kind));
+    for (const [kind, command] of known)
+        if (typeof command !== "string" || !COMMAND_WORDS.test(command))
+            invalid(`provider ${named} opens a ${kind} with command words, not ${JSON.stringify(command)}`);
+    return Object.fromEntries(known);
+};
 /** An entry as a CLI or the store gives it, checked: anything else is a `validation_error`. */
 export const providerEntryOf = (value) => {
     if (typeof value !== "object" || value === null || Array.isArray(value))
         return invalid("a provider entry is an object");
-    const { name, kind, aliases = [], command } = value;
+    const { name, kind, aliases = [], command, opens } = value;
     const named = wordOf(name, "a provider's name");
     if (typeof kind !== "string" || !KINDS.includes(kind))
         invalid(`provider ${named}'s kind is one of ${KINDS.join(", ")} — not ${JSON.stringify(kind)}`);
@@ -73,6 +87,7 @@ export const providerEntryOf = (value) => {
         kind: kind,
         aliases: [...new Set(aliases.map((alias) => wordOf(alias, `an alias of ${named}`)))],
         ...(command === undefined ? {} : { command: wordOf(command, `the command of ${named}`) }),
+        ...(opens === undefined ? {} : { opens: opensOf(opens, named) }),
     };
 };
 const describe = ({ name, kind, command }) => `${name} (${kind}${command ? `, from ${command}` : ""})`;
@@ -87,6 +102,7 @@ const joined = (known, entry) => {
             ...same,
             aliases: [...new Set([...same.aliases, ...entry.aliases])],
             ...(entry.command ? { command: entry.command } : {}),
+            ...(entry.opens ? { opens: { ...same.opens, ...entry.opens } } : {}),
         }
         : entry;
     const others = known.filter((one) => one !== same);

package/dist/domain/ref-arguments.js

@@ -5,18 +5,14 @@ const TAKES = {
     chat: "a chat: chat:<provider>/<account>/<chat>, its id or its title",
     message: "a message: msg:<provider>/<account>/<chat>/<message>, or a chat and the message's id",
 };
-const OPENS = {
-    chat: "messages list",
-    message: "messages show",
-    contact: "contacts show",
-};
 const article = (word) => (/^[aeiou]/.test(word) ? "an" : "a");
 const wrongKind = (text, kind, takes) => new CliError("validation_error", `${text} names ${article(kind)} ${kind}; this takes ${TAKES[takes]}`, {
     reason: "ref.wrong-kind",
 });
 const wrongProvider = (text, provider, kind) => {
-    const command = providerNamed(provider)?.command;
-    const opens = OPENS[kind];
+    const entry = providerNamed(provider);
+    const command = entry?.command;
+    const opens = kind === "entity" ? undefined : entry?.opens?.[kind];
     const how = command && opens ? `open it with ${command} <profile> ${opens} ${text}` : "open it with its own CLI";
     const label = providerLabel(provider);
     return new CliError("validation_error", `${text} is ${article(label.toLowerCase())} ${label} ${kind}; ${how}`, {

package/dist/domain/ref-summaries.d.ts

@@ -0,0 +1,56 @@
+import type { RefKindName } from "./references.js";
+export type RefState = "available" | "deleted" | "unavailable";
+/** A message or chat of the `email` provider is mail, so it reads as `email` and `email_thread`. */
+export type RefSummaryKind = RefKindName | "email" | "email_thread" | "unknown";
+/** What a reference names, read from the store in one batch so a page of refs costs one query per kind. */
+export interface RefSummary {
+    /** Canonical spelling; the map key is the text the caller passed. */
+    ref: string;
+    kind: RefSummaryKind;
+    /** One line, at most 120 characters, never a message body. `null` when the store has no title. */
+    title: string | null;
+    /** What holds it, one line: a message's chat title, a task's project, a document's provider label. */
+    in: string | null;
+    /** ISO 8601 UTC. */
+    at: string | null;
+    provider: string | null;
+    /** The external id of the account that holds it, for `ProfilesFor`; `null` when it belongs to no account. */
+    account: string | null;
+    /** The CLI that opens it (`max`, `tg`, `drive`); `null` when no CLI has registered the provider. */
+    tool: string | null;
+    state: RefState;
+    /** Only with `{ excerpt: true }`: at most 280 characters of the body. */
+    excerpt?: string | null;
+}
+export interface RefsStore {
+    /** One query per kind present. Never throws for a bad ref: it comes back `unknown`, `unavailable`. */
+    summaries(refs: readonly string[], options?: {
+        excerpt?: boolean;
+    }): Promise<Map<string, RefSummary>>;
+}
+/** The caller's answer to "which profile opens this": one signed in, or the choices and why there is not one. */
+export type ProfilesFor = (provider: string, account: string | null) => {
+    profile: string;
+} | {
+    why: string;
+    profiles: string[];
+};
+export interface RefOpen {
+    /** Ready to run; contains `<profile>` when `profiles` is not exactly one. `null` when no CLI opens it. */
+    argv: string[] | null;
+    profiles: string[];
+    why: string | null;
+}
+export declare const PROFILE_PLACEHOLDER = "<profile>";
+/** A title from someone else's text, as one line: a newline in it would break every row it is printed in. */
+export declare const oneLine: (text: string) => string;
+/**
+ * The command that opens a ref. A registered provider opens its own kinds; anything else opens with the caller's
+ * `local` words (memo's `notes show`). The profile is never picked: with none or several, `argv` keeps `<profile>`.
+ */
+export declare const openOf: (summary: RefSummary, ports: {
+    profilesFor: ProfilesFor;
+    local?: Partial<Record<RefKindName, string[]>>;
+}) => RefOpen;
+/** `Chat «Сайт + автоматизация» (MAX)`: the one label every review row, status line and `show` prints. */
+export declare const refLabel: (summary: RefSummary) => string;

package/dist/domain/ref-summaries.js

@@ -0,0 +1,63 @@
+import { singleLine } from "@wirecat/cli-base";
+import { providerNamed } from "./providers.js";
+export const PROFILE_PLACEHOLDER = "<profile>";
+/** A title from someone else's text, as one line: a newline in it would break every row it is printed in. */
+export const oneLine = (text) => singleLine(text.replace(/\s+/g, " ").trim());
+/** Mail is a message and a chat to the provider registry: `opens` is keyed by the reference kind. */
+const openKind = (kind) => kind === "email" ? "message" : kind === "email_thread" ? "chat" : kind === "unknown" ? undefined : kind;
+/**
+ * The command that opens a ref. A registered provider opens its own kinds; anything else opens with the caller's
+ * `local` words (memo's `notes show`). The profile is never picked: with none or several, `argv` keeps `<profile>`.
+ */
+export const openOf = (summary, ports) => {
+    const kind = openKind(summary.kind);
+    if (kind === undefined)
+        return { argv: null, profiles: [], why: `${summary.ref} is not a reference` };
+    const entry = summary.provider === null ? undefined : providerNamed(summary.provider);
+    const words = entry?.command === undefined ? undefined : entry.opens?.[kind];
+    if (entry?.command !== undefined && words !== undefined && summary.provider !== null) {
+        const command = [...words.split(" "), summary.ref];
+        const asked = ports.profilesFor(summary.provider, summary.account);
+        return "profile" in asked
+            ? { argv: [entry.command, asked.profile, ...command], profiles: [asked.profile], why: null }
+            : { argv: [entry.command, PROFILE_PLACEHOLDER, ...command], profiles: asked.profiles, why: asked.why };
+    }
+    const local = ports.local?.[kind];
+    if (local !== undefined)
+        return { argv: [...local, summary.ref], profiles: [], why: null };
+    return {
+        argv: null,
+        profiles: [],
+        why: summary.provider === null
+            ? `nothing here opens a ${kind}`
+            : `no CLI has registered ${summary.provider} in this store yet; run its CLI once`,
+    };
+};
+const WORDS = {
+    message: "Message",
+    chat: "Chat",
+    contact: "Contact",
+    folder: "Folder",
+    meeting: "Meeting",
+    event: "Event",
+    note: "Note",
+    document: "Document",
+    person: "Person",
+    organization: "Organization",
+    project: "Project",
+    task: "Task",
+    memory: "Memory",
+    fact: "Fact",
+    bot: "Bot",
+    email: "Email",
+    email_thread: "Email thread",
+    unknown: "Unknown",
+};
+/** `Chat «Сайт + автоматизация» (MAX)`: the one label every review row, status line and `show` prints. */
+export const refLabel = (summary) => {
+    const named = summary.title === null ? summary.ref : `«${oneLine(summary.title)}»`;
+    const notes = [summary.in === null ? null : oneLine(summary.in), summary.state === "available" ? null : summary.state]
+        .filter((one) => one !== null)
+        .join(", ");
+    return `${WORDS[summary.kind]} ${named}${notes === "" ? "" : ` (${notes})`}`;
+};

package/dist/entities/index.d.ts

@@ -4911,6 +4911,7 @@ export declare const ENTITIES: {
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -4925,6 +4926,7 @@ export declare const ENTITIES: {
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -5023,6 +5025,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5037,6 +5040,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5136,6 +5140,7 @@ export declare const ENTITIES: {
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -5150,6 +5155,7 @@ export declare const ENTITIES: {
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -5277,6 +5283,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5291,6 +5298,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5383,6 +5391,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -5397,6 +5406,7 @@ export declare const ENTITIES: {
                 readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
                 readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+                readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
                 readonly confirmed: v.BooleanSchema<undefined>;
@@ -6600,6 +6610,7 @@ export declare const ENTITIES: {
         readonly to: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
         readonly kind: v.PicklistSchema<readonly ["member-of", "related-to"], undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;

package/dist/entities/relationship.d.ts

@@ -6,6 +6,8 @@ export declare const relationship: v.StrictObjectSchema<{
     readonly to: v.SchemaWithPipe<readonly [v.StringSchema<undefined>, v.RegexAction<string, "a reference such as `note:42`">]>;
     readonly kind: v.PicklistSchema<readonly ["member-of", "related-to"], undefined>;
     readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+    /** A purpose from memo's config; `null` means `work`. */
+    readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
     /** An agent's suggestion stays unconfirmed, and `weak`, until the owner confirms it. */
     readonly confirmed: v.BooleanSchema<undefined>;

package/dist/entities/relationship.js

@@ -8,6 +8,8 @@ export const relationship = v.strictObject({
     to: reference,
     kind: v.picklist(RELATION_KINDS),
     role: v.nullable(text),
+    /** A purpose from memo's config; `null` means `work`. */
+    purpose: v.nullable(text),
     evidence: v.nullable(text),
     /** An agent's suggestion stays unconfirmed, and `weak`, until the owner confirms it. */
     confirmed: v.boolean(),

package/dist/entities/task-results.d.ts

@@ -53,6 +53,7 @@ export declare const taskCard: v.StrictObjectSchema<{
         readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
         readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
@@ -67,6 +68,7 @@ export declare const taskCard: v.StrictObjectSchema<{
         readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
         readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
@@ -165,6 +167,7 @@ export declare const taskCreated: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -179,6 +182,7 @@ export declare const taskCreated: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -278,6 +282,7 @@ export declare const taskLinks: v.UnionSchema<[v.StrictObjectSchema<{
         readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
         readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
@@ -292,6 +297,7 @@ export declare const taskLinks: v.UnionSchema<[v.StrictObjectSchema<{
         readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
         readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+        readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
         readonly confirmed: v.BooleanSchema<undefined>;
@@ -419,6 +425,7 @@ export declare const taskMerge: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -433,6 +440,7 @@ export declare const taskMerge: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -525,6 +533,7 @@ export declare const taskUnmerge: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;
@@ -539,6 +548,7 @@ export declare const taskUnmerge: v.StrictObjectSchema<{
             readonly origin: v.PicklistSchema<readonly ["file", "owner", "suggested", "message", "calendar"], undefined>;
             readonly target_text: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly role: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+            readonly purpose: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly evidence: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly provenance: v.NullableSchema<v.StringSchema<undefined>, undefined>;
             readonly confirmed: v.BooleanSchema<undefined>;

package/dist/entities/task-results.js

@@ -15,6 +15,7 @@ const link = v.strictObject({
     origin: v.picklist(LINK_SOURCES),
     target_text: v.nullable(text),
     role: v.nullable(text),
+    purpose: v.nullable(text),
     evidence: v.nullable(text),
     provenance: v.nullable(text),
     confirmed: v.boolean(),

package/dist/errors/reasons.js

@@ -144,6 +144,7 @@ const OTHERS = [
     ],
     validation("name.invalid", "the name is not valid"),
     validation("output.choose-fields", "at a terminal, --json names the fields it prints"),
+    validation("output.conflict", "two output switches ask for different output"),
     validation("output.one-object", "a report is one JSON object; --jsonl streams lists only"),
     validation("output.unknown-field", "the answer has no field by that name"),
     validation("name.taken", "the name is already used"),

package/dist/output-detail.js

@@ -2,13 +2,17 @@ export const DETAILS = ["brief", "full"];
 /** Message fields mail never has and a messenger hit rarely fills; a null one is noise. */
 const RARELY_SET = ["editedAt", "replyTo", "forwardedFrom", "reactions"];
 const BRIEF = ["locator", "chatTitle", "timestamp", "senderName", "excerpt", "score"];
-const isHit = (value) => typeof value === "object" &&
-    value !== null &&
-    typeof value.locator === "string" &&
-    typeof value.text === "string";
+/** A messenger answer's hit (`message.hit`): already cut to an excerpt, so only `brief` changes it. */
+const SNAKE_BRIEF = ["ref", "chat_title", "timestamp", "sender_name", "excerpt", "score"];
+const isRecord = (value) => typeof value === "object" && value !== null;
+const isSnakeHit = (value) => isRecord(value) && typeof value.ref === "string" && typeof value.excerpt === "string";
+const isHit = (value) => isSnakeHit(value) || (isRecord(value) && typeof value.locator === "string" && typeof value.text === "string");
+const picked = (hit, keys) => Object.fromEntries(keys.flatMap((key) => (hit[key] === undefined || hit[key] === null ? [] : [[key, hit[key]]])));
 const shaped = (hit, detail) => {
+    if (isSnakeHit(hit))
+        return detail === "brief" ? picked(hit, SNAKE_BRIEF) : hit;
     if (detail === "brief")
-        return Object.fromEntries(BRIEF.flatMap((key) => (hit[key] === undefined || hit[key] === null ? [] : [[key, hit[key]]])));
+        return picked(hit, BRIEF);
     const { text, providerMetadata, ...rest } = hit;
     for (const key of RARELY_SET)
         if (rest[key] === null)

package/dist/output.d.ts

@@ -14,6 +14,8 @@ export interface OutputOptions {
     hitDetail?: Detail;
     /** Takes the answer as an object in place of printing it — an agent's run (`BaseEnvironment.agent`). */
     capture?: (value: unknown) => void;
+    /** One line per item (WC-OUT-24); anything printed past `renderAnswer` stays JSON. */
+    compact?: boolean;
 }
 /**
  * One place decides the mode, so no command can disagree with another.
@@ -23,9 +25,11 @@ export interface OutputOptions {
  * instead. In every machine mode **stdout carries JSON and nothing else** — diagnostics are on stderr in all modes, which is what makes
  * that contract hold by construction rather than by remembering.
  */
-export declare const resolveOutput: ({ json, jsonl, quiet, streams, tty, color, fields, hitDetail, env, capture, }?: OutputOptions) => {
+export declare const resolveOutput: ({ json, jsonl, quiet, streams, tty, color, fields, hitDetail, env, capture, compact, }?: OutputOptions) => {
     format: "json" | "jsonl" | "pretty";
     color: boolean;
     streams: Streams;
     renderer: Renderer;
+    compact?: boolean | undefined;
+    full?: boolean | undefined;
 };

package/dist/output.js

@@ -1,6 +1,23 @@
-import { createRenderer, processStreams, singleLine, } from "@wirecat/cli-base";
+import { CliError, createRenderer, processStreams, singleLine, } from "@wirecat/cli-base";
+import { COMPACT_FLAG } from "@wirecat/cli-base/standards";
 import { fieldsOf, projectFields } from "./cli/result-fields.js";
 import { atDetail } from "./output-detail.js";
+const refuseCompact = ({ json, jsonl, fields, hitDetail }) => {
+    const other = jsonl
+        ? "--jsonl"
+        : fields !== undefined
+            ? "--json=…"
+            : json
+                ? "--json"
+                : hitDetail === "brief"
+                    ? "--brief"
+                    : "";
+    if (other)
+        throw new CliError("validation_error", `${COMPACT_FLAG} and ${other} ask for different output — pick one`, {
+            reason: "output.conflict",
+            param: COMPACT_FLAG,
+        });
+};
 /**
  * One place decides the mode, so no command can disagree with another.
  *
@@ -9,9 +26,11 @@ import { atDetail } from "./output-detail.js";
  * instead. In every machine mode **stdout carries JSON and nothing else** — diagnostics are on stderr in all modes, which is what makes
  * that contract hold by construction rather than by remembering.
  */
-export const resolveOutput = ({ json, jsonl, quiet, streams = processStreams, tty, color, fields, hitDetail, env = process.env, capture, } = {}) => {
+export const resolveOutput = ({ json, jsonl, quiet, streams = processStreams, tty, color, fields, hitDetail, env = process.env, capture, compact, } = {}) => {
+    if (compact)
+        refuseCompact({ json, jsonl, fields, hitDetail });
     const interactive = tty ?? process.stdout.isTTY === true;
-    const format = jsonl ? "jsonl" : json || !interactive ? "json" : "pretty";
+    const format = jsonl ? "jsonl" : json || compact || !interactive ? "json" : "pretty";
     const painted = format === "pretty" && (color ?? (env.NO_COLOR === undefined && env.TERM !== "dumb" && !env.CI));
     const printing = createRenderer({ format, color: painted, streams });
     const rendered = capture
@@ -37,7 +56,13 @@ export const resolveOutput = ({ json, jsonl, quiet, streams = processStreams, tt
                 stream: (items) => created.stream([...items].map((item) => projectFields(item, paths))),
             }
             : created;
-    return { format, color: painted, streams, renderer: quiet ? silence(renderer) : renderer };
+    return {
+        format,
+        color: painted,
+        streams,
+        renderer: quiet ? silence(renderer) : renderer,
+        ...(compact ? { compact: true, full: hitDetail === "full" } : {}),
+    };
 };
 /** Fields a person writes in paragraphs; every other string is a name, a title, an id or a path. */
 const MULTI_LINE = new Set(["text", "description"]);

package/dist/services/proposals/kinds/relationship-update.d.ts

@@ -0,0 +1,4 @@
+import type { MessageStore } from "../../../store/index.js";
+import type { ProposalKind } from "../types.js";
+/** An agent's change to a relationship's role or purpose; the owner's applies at once and never waits here. */
+export declare const relationshipUpdateKind: (store: Pick<MessageStore, "knowledge" | "proposedActions">) => ProposalKind;