@patimweb/pi-teams 1.5.1 → 1.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@patimweb/pi-teams",
-  "version": "1.5.1",
+  "version": "1.6.0",
   "description": "Microsoft Teams integration for pi coding agent — acts fully as the signed-in user across multiple accounts and tenants: chats, channels, meetings, presence, with configurable guardrails",
   "keywords": [
     "pi-package",

package/skills/teams-collaboration/SKILL.md

@@ -131,36 +131,91 @@ instead of trying anyway.
 ## How to format a Teams message
 
 A Teams chat is a chat bubble, not a document. What arrives badly is long
-prose: the reader has to hunt for the point, and it reads as if a machine wrote
-it. The body is rendered as HTML — markdown is converted for you, so write
+prose: the answer is buried, the reader has to hunt for it, and it reads as if a
+machine wrote it. "Keep it short" does not fix that on its own — a shape does.
+The body is rendered as HTML, and markdown is converted for you, so write
 markdown and let the tool do the rest.
 
-**Reach for this shape, not for paragraphs:**
+**The shape, which is nearly always this:**
 
 ```
-Kurz: die QA-Umgebung läuft wieder.
+QA läuft wieder.
 
 - Ursache: abgelaufenes Zertifikat
 - Fix: erneuert und neu deployt
 - Offen: Monitoring für 90 Tage
 ```
 
-- **Lead with the answer.** The first line should work as the whole message for
-  someone who reads nothing else.
-- **Three short paragraphs at most.** If it needs more, it is a document — put
-  it in a file or a wiki page and link it.
+Line one is the answer. Then a blank line, then only what the reader needs in
+order to act on it. Five lines is already a long chat message.
+
+**Before and after.** Both versions say the same thing; only one is a chat:
+
+> **So nicht:** Ich habe mir die QA-Umgebung jetzt angeschaut und konnte den
+> Fehler reproduzieren. Das Problem liegt darin, dass das TLS-Zertifikat
+> abgelaufen war, wodurch alle Requests fehlgeschlagen sind. Ich habe es dann
+> erneuert und die Umgebung neu deployt, jetzt läuft wieder alles. Ich würde
+> allerdings noch empfehlen, das Monitoring einzurichten, damit das nicht
+> wieder passiert.
+
+> **So:** QA läuft wieder.
+>
+> - Ursache: abgelaufenes TLS-Zertifikat
+> - Fix: erneuert und neu deployt
+> - Empfehlung: Monitoring auf die Ablaufdaten
+
+**Three skeletons that cover most messages:**
+
+*Antwort auf eine Frage* — the answer, then at most one line of reasoning:
+
+```
+Ja, Freitag passt.
+
+Ich bin bis 14:00 im Workshop, danach jederzeit.
+```
+
+*Status* — outcome first, then what is still open:
+
+```
+Deployment ist durch, Release Notes stehen im Wiki: <Link>
+
+Offen: Smoke-Test auf Produktion, mache ich heute Nachmittag.
+```
+
+*Entscheidung nötig* — the decision, the options, the deadline:
+
+```
+Ich brauche bis morgen eine Entscheidung zum Sync-Intervall.
+
+- 5 Min: schnell, ~3× Last auf dem SAP-System
+- 15 Min: entspannt, dafür Verzögerung im Reporting
+```
+
+**Rules**
+
+- **The first line carries the message.** Someone who reads only that line
+  should know the outcome.
 - **Bullets for anything enumerable** — causes, options, next steps. Three items
-  and up belong in a list, not in a sentence with commas.
+  and up are a list; two are a sentence.
+- **One idea per line.** A line break is free; a clause chain held together by
+  commas is not.
 - **Bold the one thing that must not be missed**, and only that. Bold used
   everywhere is bold nowhere.
 - **Numbers, names and dates exactly as they are.** Do not round a figure or
   paraphrase a deadline into something friendlier.
 - **One question per message.** Two questions get one answer.
+- **No greeting and no closing.** "Hallo zusammen", "Ich habe mir das mal
+  angeschaut", "Kurz zusammengefasst:" and "Sag Bescheid, wenn du Fragen hast"
+  are all noise in a chat. The message starts with the answer and stops when it
+  is done.
+- **Over five lines, it is a document.** Put it in a wiki page or a file and send
+  the link with one sentence around it.
 
 **What Teams renders:** `**bold**`, `*italic*`, `` `code` ``, `~~struck~~`,
-`[label](url)`, `- bullets`, `1. numbered`, ``` fences. A `# heading` arrives as
-a bold line — fine for structure, not for hierarchy. **Tables are not supported
-in a chat**: convert them to bullets, or put the table in a file and link it.
+`[label](url)`, `- bullets`, `1. numbered`, and code fences. A `# heading`
+arrives as a bold line — fine for structure, not for hierarchy. **Tables are not
+supported in a chat**: convert them to bullets, or put the table in a file and
+link it.
 
 **Language and tone:** answer in the language of the conversation, in the
 register of the people in it. Short forms are normal in a chat ("passt", "ok,
@@ -323,9 +378,9 @@ teams_watch:
 2. If an answer is warranted, send it with `teams_send_chat_message` to the
    **chat ID from the prompt** — never re-resolve the chat by name. pi posts as
    the user, so the wrong chat is a wrong statement in the user's name.
-3. Keep it to the shape in *How to format a Teams message*: answer first, three
-   short paragraphs at most, bullets for lists. An unrequested message has to be
-   readable at a glance.
+3. Keep it to the shape in *How to format a Teams message*: the answer on the
+   first line, at most five short lines, bullets for anything enumerable. An
+   unrequested message has to be readable at a glance.
 4. If no answer is warranted, say so in one line and stop. Do not react, do not
    touch other chats, do not post to a channel.
 

package/src/tools/teams-send-channel-message.ts

@@ -10,6 +10,7 @@ import { Type } from "typebox";
 import { replyToChannelMessage, sendChannelMessage } from "../graph/messages.ts";
 import { resolveUserId } from "../graph/me.ts";
 import { auditWrite } from "../safety/audit.ts";
+import { CHAT_MESSAGE_BODY_DESCRIPTION, CHAT_SHAPE_GUIDELINE } from "../utils/chat-style.ts";
 import { applyAiFooter } from "../utils/disclosure.ts";
 import { assertAccess } from "../safety/index.ts";
 import { truncate } from "../utils/formatting.ts";
@@ -58,10 +59,7 @@ async function resolveMentions(
 const sharedParams = {
 	channel: Type.String({ description: "Channel name or ID, or a 'Team/Channel' path" }),
 	team: Type.Optional(Type.String({ description: "Team name or ID (omit when using a path)" })),
-	body: Type.String({
-			description:
-				"Message text as lightweight markdown (bold, italics, code, bullets, numbered lists, links)",
-		}),
+	body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
 	account: AccountParam,
 	tenant: TenantParam,
 	mentions: Type.Optional(
@@ -85,7 +83,7 @@ export const teamsSendChannelMessageTool = {
 	promptGuidelines: [
 		"Write in the user's voice — the post is attributed to them, not to an assistant.",
 		"Show the exact text and the target channel before posting when there is any ambiguity.",
-		"Format for a chat, not for a document: lead with the answer, three short paragraphs at most, bullets for lists. Bold, italics, code, links and bullets are rendered; headings become bold lines and tables are not supported — keep those out.",
+		CHAT_SHAPE_GUIDELINE,
 		"Answer in the language of the conversation you are writing into, and match its register.",
 	],
 
@@ -180,6 +178,7 @@ export const teamsReplyChannelMessageTool = {
 		messageId: Type.String({ description: "ID of the thread's opening message" }),
 	}),
 	promptSnippet: "Reply in a Teams channel thread as the user",
+	promptGuidelines: [CHAT_SHAPE_GUIDELINE],
 
 	async execute(
 		_toolCallId: string,

package/src/tools/teams-send-chat-message.ts

@@ -21,6 +21,7 @@ import { formatGraphError } from "../utils/errors.ts";
 import { resolveUserId } from "../graph/me.ts";
 import { auditWrite } from "../safety/audit.ts";
 import { assertAccess } from "../safety/index.ts";
+import { CHAT_MESSAGE_BODY_DESCRIPTION, CHAT_SHAPE_GUIDELINE } from "../utils/chat-style.ts";
 import { applyAiFooter } from "../utils/disclosure.ts";
 import { truncate } from "../utils/formatting.ts";
 import { requireChat } from "./resolve.ts";
@@ -56,10 +57,7 @@ export const teamsSendChatMessageTool = {
 		"where the mention should appear.",
 	parameters: Type.Object({
 		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
-		body: Type.String({
-			description:
-				"Message text as lightweight markdown (bold, italics, code, bullets, numbered lists, links)",
-		}),
+		body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
 		account: AccountParam,
 		tenant: TenantParam,
 		mentions: Type.Optional(
@@ -79,7 +77,7 @@ export const teamsSendChatMessageTool = {
 		"Write the message in the user's voice — it is sent from their account, not from an assistant.",
 		"Show the user the exact text before sending when the intent is even slightly ambiguous.",
 		"Do not add signatures, or a note that the message was written by an AI: the sending tool appends the configured AI disclosure itself (on by default), so writing one into the body duplicates it.",
-		"Format for a chat, not for a document: lead with the answer, three short paragraphs at most, bullets for lists. Bold, italics, code, links and bullets are rendered; headings become bold lines and tables are not supported — keep those out.",
+		CHAT_SHAPE_GUIDELINE,
 		"Answer in the language of the conversation you are writing into, and match its register.",
 	],
 

package/src/tools/teams-update-message.ts

@@ -14,6 +14,7 @@
 import { Type } from "typebox";
 import { updateMessage } from "../graph/messages.ts";
 import { auditWrite } from "../safety/audit.ts";
+import { CHAT_MESSAGE_BODY_DESCRIPTION, CHAT_SHAPE_GUIDELINE } from "../utils/chat-style.ts";
 import { applyAiFooter } from "../utils/disclosure.ts";
 import { requireChat } from "./resolve.ts";
 import {
@@ -36,7 +37,7 @@ export const teamsUpdateMessageTool = {
 		"Use this instead of deleting a message and sending a corrected copy.",
 	parameters: Type.Object({
 		messageId: Type.String({ description: "ID of the message to edit" }),
-		body: Type.String({ description: "The new message text (lightweight markdown by default)" }),
+		body: Type.String({ description: CHAT_MESSAGE_BODY_DESCRIPTION }),
 		chat: Type.String({ description: "Chat ID, group chat topic, or a participant's name/e-mail" }),
 		html: Type.Optional(Type.Boolean({ description: "Treat 'body' as raw HTML instead of markdown" })),
 		account: AccountParam,
@@ -45,6 +46,7 @@ export const teamsUpdateMessageTool = {
 	promptSnippet: "Edit a message the user sent in Teams",
 	promptGuidelines: [
 		"Use teams_update_message to correct a message the user already sent, rather than deleting it and posting a replacement.",
+		CHAT_SHAPE_GUIDELINE,
 	],
 
 	async execute(

package/src/utils/chat-style.ts

@@ -0,0 +1,65 @@
+/**
+ * The shape of a Teams message.
+ *
+ * A chat bubble is read at a glance, on a phone, between two other things. The
+ * failure mode is well known and it is not a lack of language skill: the model
+ * writes a *document*. It opens with context, builds up to the point, and
+ * closes with a summary — so the reader has to hunt for the answer, which is
+ * exactly the "wall of text" people complain about.
+ *
+ * Telling the model to "be brief" does not fix it. Vague length advice is the
+ * weakest kind of formatting instruction; an explicit shape and a worked
+ * example are the strongest, and they have to sit where the message is being
+ * composed rather than in a document the model may or may not have loaded.
+ *
+ * So one shape, stated the same way in every place that matters:
+ *
+ *   - the `body` parameter description — in context at the moment of writing,
+ *     which is the highest-attention placement available,
+ *   - the per-tool guideline bullet — in context for the whole session, and
+ *     flat in the Guidelines list, so it has to name its tools,
+ *   - the skill and the listen-mode prompt — which carry the worked example
+ *     (`skills/teams-collaboration/SKILL.md`).
+ *
+ * Keeping it in one module is the point. Four tools used to carry their own
+ * copy of one sentence, they had drifted, and the sentence they shared was
+ * "three short paragraphs at most" — which permits prose, and got prose.
+ */
+
+/**
+ * What a message body is, and what shape it has.
+ *
+ * Used as the `body` parameter description on every tool that sends one, so it
+ * is read at the moment the text is written. Kept short on purpose: it is in
+ * the tool schema, and every tool in this package is in context at once.
+ */
+export const CHAT_MESSAGE_BODY_DESCRIPTION =
+	"Message text as lightweight markdown, in chat shape: the answer on the first line, then at most 5 short " +
+	"lines, `- ` bullets for anything enumerable, one idea per line. No greeting, no closing, no summary. " +
+	"Rendered: **bold**, *italic*, `code`, ~~struck~~, [label](url), `- ` bullets, `1. ` numbered, ``` fences. " +
+	"A `#` heading arrives as a bold line; tables are not rendered at all.";
+
+/**
+ * The same shape as one guideline bullet.
+ *
+ * `promptGuidelines` are appended flat to the system prompt's Guidelines
+ * section with no tool-name prefix, so this names every tool it applies to —
+ * otherwise the model cannot tell which "the message body" means. It stays on
+ * one line for the same reason: it is a bullet in someone else's list.
+ */
+export const CHAT_SHAPE_GUIDELINE =
+	"teams_send_chat_message, teams_send_channel_message, teams_reply_channel_message and teams_update_message " +
+	"write chat shape, not a document: the answer on the first line, at most 5 short lines, `- ` bullets for " +
+	"enumerable items, no greeting, no closing summary, no tables.";
+
+/**
+ * The shape as prose, for the listen-mode prompt.
+ *
+ * Listen mode is the case where this matters most: an answer that arrives
+ * unrequested has to be readable at a glance, because the recipient is not
+ * waiting for it and did not ask for it.
+ */
+export const CHAT_SHAPE_FOR_LISTEN_MODE =
+	"Format it as a chat bubble, not a document: the answer on the first line, at most 5 short lines, " +
+	"`- ` bullets for anything enumerable, no greeting and no closing. The recipient is not expecting this " +
+	"message, so it has to be readable at a glance.";

package/src/watch/prompt.ts

@@ -16,6 +16,7 @@
  */
 
 import type { MessageSummary, SignedInUser } from "../types.ts";
+import { CHAT_SHAPE_FOR_LISTEN_MODE } from "../utils/chat-style.ts";
 import type { WatchEvent } from "./loop.ts";
 
 function senderName(message: MessageSummary): string {
@@ -114,9 +115,7 @@ export function composeWatchPrompt(event: WatchEvent, me?: SignedInUser): string
 			"the sending tool appends the configured AI disclosure itself.",
 		"- If it does not: say so in one line and stop.",
 		"",
-		"Format it for a chat bubble, not a document: the answer first, three short paragraphs at most, " +
-			"bullets for anything enumerable, no tables. The recipient is not expecting this message, so it has " +
-			"to be readable at a glance.",
+		CHAT_SHAPE_FOR_LISTEN_MODE,
 		"",
 		"Do not react, do not touch other chats, and do not send anything to a channel.",
 	].join("\n");