security: remove session.share, add Slack system context and debugging docs

- Remove client.session.share() call that uploaded session content
  (including code context) to opncd.ai — security risk for private repos
- Inject Slack mrkdwn formatting instructions as system-reminder on
  the first prompt of each thread so LLM responses render properly
- Add debugging guide to both README.md and AGENTS.md: log locations,
  failure investigation steps, common failure modes, verbose logging

Signed-off-by: xuezhaojun <xuezhaokeepgoing@gmail.com>

Author: xuezhaojun

AGENTS.md

@@ -134,6 +134,54 @@ Plugins may run in multiple Agent pods simultaneously. Design for this:
 - Session maps are keyed by unique identifiers (e.g., Slack channel + thread timestamp)
 - Bounded collections with eviction to prevent memory leaks
 
+## Debugging Plugins
+
+### Log Locations
+
+OpenCode writes structured logs (session lifecycle, LLM calls, tool execution, errors) to:
+
+```
+~/.local/share/opencode/log/    # macOS/Linux default ($XDG_DATA_HOME/opencode/log/)
+```
+
+Files are named `YYYY-MM-DDTHHMMSS.log` (one per startup, 10 most recent retained). Run `opencode debug paths` to confirm the path on your system.
+
+Plugin `console.log`/`console.warn`/`console.error` output goes to the OpenCode process stdout/stderr — it is **not** captured in the structured log file. Use the `[plugin-name]` prefix convention to make plugin output easy to filter.
+
+### Tracing a Problem
+
+1. **Find the session** — search the log for the session ID or creation event:
+   ```bash
+   grep "ses_XXXXX" ~/.local/share/opencode/log/*.log
+   ```
+
+2. **Check for errors** — LLM failures, processor crashes, permission timeouts:
+   ```bash
+   grep "ERROR.*ses_XXXXX" ~/.local/share/opencode/log/*.log
+   ```
+
+3. **Key log markers**:
+   - `service=session ... created` — session created
+   - `service=session.prompt step=N loop` — prompt loop iteration N
+   - `service=llm ... stream` — LLM call started
+   - `service=llm ... stream error` — LLM call failed (root cause in `error=` JSON)
+   - `service=session.processor ... error=` — processor crash
+   - `service=session.prompt ... exiting loop` — prompt completed normally
+
+### CLI Flags for Debugging
+
+```bash
+opencode serve --print-logs       # logs to stderr instead of file
+opencode serve --log-level DEBUG  # maximum verbosity
+```
+
+Both can also be set in `opencode.json`:
+```json
+{
+  "logLevel": "DEBUG"
+}
+```
+
 ## Repository Structure
 
 ```

opencode-slack-plugin/README.md

@@ -120,7 +120,6 @@ The plugin activates automatically when both `SLACK_BOT_TOKEN` and `SLACK_APP_TO
 - **DM the bot** directly for private conversations
 - **@mention the bot** in a channel to start a threaded conversation
 - Each Slack thread creates a separate OpenCode session with its own context
-- Session share links are posted automatically when a new thread starts
 
 ### Permission Requests
 
@@ -149,6 +148,87 @@ Completed tool calls are posted to the thread in real time:
 *bash* - ran tests
 ```
 
+## Debugging
+
+### Log Locations
+
+The plugin produces two categories of logs:
+
+| Source | Location | Contents |
+|--------|----------|----------|
+| **OpenCode structured log** | `~/.local/share/opencode/log/` | Session lifecycle, LLM calls, tool execution, permission events, errors. File per startup, 10 most recent retained. |
+| **Plugin console output** | OpenCode process stdout/stderr | `[slack-plugin]` prefixed messages: connection status, session creation, typing indicators, prompt results. |
+
+To find the current log directory:
+
+```bash
+opencode debug paths   # prints all paths including "log"
+```
+
+On macOS the default is `~/.local/share/opencode/log/`. On Linux it follows `$XDG_DATA_HOME/opencode/log/`.
+
+### Investigating a Failed Slack Message
+
+When a Slack message gets no reply, follow this sequence:
+
+**1. Find the session ID** — look for `[slack-plugin] Created session` in stdout, or find the session by thread timestamp:
+
+```bash
+grep "Slack thread" ~/.local/share/opencode/log/2026-05-08T*.log
+```
+
+**2. Trace the session in the structured log** — search for the session ID to see the full lifecycle:
+
+```bash
+grep "ses_XXXXX" ~/.local/share/opencode/log/2026-05-08T*.log
+```
+
+Key events to look for:
+
+| Log entry | Meaning |
+|-----------|---------|
+| `service=session ... created` | Session was created successfully |
+| `service=session.prompt step=0 loop` | LLM prompt loop started |
+| `service=llm ... stream` | LLM call initiated |
+| `service=llm ... stream error` | LLM call failed (check `error=` field) |
+| `service=session.processor ... error=` | Processor crashed while handling LLM response |
+| `service=session.prompt ... exiting loop` | Prompt completed normally |
+| `service=permission ... evaluated` | Permission was auto-resolved or user-replied |
+
+**3. Check for LLM provider errors** — filter for ERROR level:
+
+```bash
+grep "ERROR.*ses_XXXXX" ~/.local/share/opencode/log/2026-05-08T*.log
+```
+
+### Common Failure Modes
+
+**Bot shows "is thinking..." but never replies:**
+
+The plugin's `session.prompt()` returned data with no text parts. This happens when the LLM provider fails. Check the structured log for `stream error` — common causes:
+
+- **OAuth token expired** (Google Vertex): `POST https://oauth2.googleapis.com/token` fails. Fix: `gcloud auth application-default login`
+- **Proxy misconfiguration**: The LLM provider's HTTP client inherits `http_proxy`/`https_proxy` env vars. If your proxy is down, LLM calls fail silently.
+- **Rate limiting**: Look for HTTP 429 in the error JSON.
+
+**Bot creates a session but the second message in the thread is ignored:**
+
+The thread requires `@mention` for each message in channel threads (by design — prevents capturing human-to-human conversation). DMs do not require `@mention`.
+
+**"Session idle" appears in stdout but no Slack message:**
+
+This means `session.prompt()` completed but returned empty text parts. Search the structured log for `ERROR` entries on that session ID to find the root cause.
+
+### Enabling Verbose Logging
+
+```bash
+# Print logs to stderr instead of file (useful for local debugging)
+opencode serve --print-logs
+
+# Set log level to DEBUG for maximum detail
+opencode serve --log-level DEBUG
+```
+
 ## KubeOpenCode Integration
 
 When running inside a KubeOpenCode Agent, the plugin additionally:

opencode-slack-plugin/src/index.ts

@@ -13,6 +13,7 @@ type SessionEntry = {
   channel: string
   thread: string
   lastActive: number
+  firstPrompt: boolean // true until the first prompt is sent
   // Per-thread pending permission — avoids cross-thread interference
   // when multiple users chat with the bot simultaneously.
   // Stores both requestId (for new API) and permissionId/sessionId (for v1 fallback).
@@ -33,6 +34,19 @@ const MAX_SESSIONS = 500
 const LOG_PREFIX = "[slack-plugin]"
 const PERMISSION_TIMEOUT_MS = 5 * 60_000 // 5 min — auto-clear stale permission
 
+// Injected as the first message in each new Slack thread session.
+// Tells the LLM it is responding in Slack and should use Slack mrkdwn formatting.
+const SLACK_SYSTEM_CONTEXT = [
+  "This conversation is happening in Slack.",
+  "Format your responses using Slack mrkdwn syntax:",
+  "- *bold*, _italic_, ~strikethrough~, `inline code`",
+  "- ```code blocks``` (no language specifier after backticks)",
+  "- Bulleted lists with •  or -",
+  "- Links: <url|display text>",
+  "- Do NOT use Markdown headings (#, ##), HTML tags, or [text](url) link syntax — they do not render in Slack.",
+  "Keep responses concise and conversational.",
+].join("\n")
+
 // ---------------------------------------------------------------------------
 // PromptQueue: serializes prompt calls per session
 // ---------------------------------------------------------------------------
@@ -355,6 +369,7 @@ const slack = async (input: PluginInput): Promise<Hooks> => {
       channel,
       thread,
       lastActive: Date.now(),
+      firstPrompt: true,
       pendingPermission: null,
     }
     sessions.set(key, entry)
@@ -365,17 +380,6 @@ const slack = async (input: PluginInput): Promise<Hooks> => {
       evictOldestSession()
     }
 
-    // Log session share link (not posted to Slack — too low-level for users).
-    // Visible in OpenCode server logs: look for "[slack-plugin] Session share:"
-    try {
-      const shareResult = await client.session.share({ path: { id: result.data.id } })
-      if (!shareResult.error && shareResult.data?.share?.url) {
-        console.log(`${LOG_PREFIX} Session share: ${shareResult.data.share.url} (thread: ${key})`)
-      }
-    } catch {
-      // Share is optional
-    }
-
     return entry
   }
 
@@ -507,13 +511,22 @@ const slack = async (input: PluginInput): Promise<Hooks> => {
     // Show typing indicator while processing
     setTypingStatus(channel, thread)
 
+    // Prepend Slack formatting context on the first prompt of each thread.
+    // Subsequent messages in the same thread skip this — the LLM already has
+    // the context in its conversation history.
+    let promptText = text
+    if (session.firstPrompt) {
+      promptText = `<system-reminder>\n${SLACK_SYSTEM_CONTEXT}\n</system-reminder>\n\n${text}`
+      session.firstPrompt = false
+    }
+
     // Enqueue the prompt to serialize concurrent messages in the same session.
     // OpenCode silently drops prompt() calls on a busy session (the message is
     // written to DB but runLoop never starts), so we must serialize here.
     promptQueue.enqueue(session.sessionId, async () => {
       const result = await client.session.prompt({
         path: { id: session.sessionId },
-        body: { parts: [{ type: "text", text }] },
+        body: { parts: [{ type: "text", text: promptText }] },
       })
 
       if (result.error) {