@brutalsystems/tincan-opencode 0.8.0 → 0.9.0

package/README.md

@@ -8,7 +8,9 @@ The plugin receives inbound messages delivered to a Unix socket and injects them
 
 ## Requirements
 
-- **opencode** 1.18.31 (verified; other versions untested)
+- **opencode** 1.18.31 (fully verified). **1.18.32** re-verified for the
+  transport contract the plugin depends on — see SPEC.md §3. Other versions
+  untested.
 - **Tin Can** 0.4.0 or later
 
 ## Install
@@ -94,10 +96,10 @@ tail -f "$TINCAN_HOME/opencode-plugin.log"
 
 | Symptom | Cause | Action |
 |---------|-------|--------|
-| **No registry files appear at all** | The plugin is not loading, or initialization failed. | Check the plugin log for `event=selfcheck.failed`. This usually means opencode's private `client._client` field moved due to a version change. Only opencode 1.18.31 is verified. See SPEC.md §3. |
+| **No registry files appear at all** | The plugin is not loading, or initialization failed. | Check the plugin log for `event=selfcheck.failed`. This usually means opencode's private `client._client` field moved due to a version change. `_client` is present and carries `post`/`get`/`getConfig` on both 1.18.31 and 1.18.32; a later version is the thing to suspect. See SPEC.md §3. |
 | **No file appears after `opencode --continue`** | Expected, not a bug. A resumed session is invisible until it next does something. | Send one message to the session (type input or wait for agent activity). The registry file will appear then. See SPEC.md §5. |
 | **`event=bind.failed` mentioning socket path too long** | `TINCAN_HOME` directory nesting is too deep. macOS caps AF_UNIX socket paths near 103 bytes. | Shorten `TINCAN_HOME` or the path to it. For example, move `~/.tincan` to a shallower location. |
-| **Messages accepted but nothing happens; `event=transport-broken detail=html response`** | The `/api/` prefix was lost in the request path. The opencode server falls back to its web UI and returns 200 with HTML instead of JSON, making an invalid request look like success. | Verify you are running opencode 1.18.31. Check the plugin source to ensure `POST /api/session/{sessionID}/prompt` is the exact path. |
+| **Messages accepted but nothing happens; `event=transport-broken detail=html response`** | The `/api/` prefix was lost in the request path. The opencode server falls back to its web UI and returns 200 with HTML instead of JSON, making an invalid request look like success. | Verify you are running opencode 1.18.31 or 1.18.32. Check the plugin source to ensure `POST /api/session/{sessionID}/prompt` is the exact path. |
 | **`event=rejected status=409`** | The same `message_id` was re-sent with different content. opencode treats this as a mismatched re-submit. | This is not a retryable failure. Check the Tin Can side to ensure message IDs are not being duplicated. |
 | **`event=dropped detail="missing envelope"`** | The `text` on the wire did not carry Tin Can's `<peer_message …>` envelope. | The envelope is the only thing marking an injected prompt as a peer's words rather than the operator's, so the plugin requires it. A hand-rolled sender must include it; from Tin Can itself this means a bug on the sending side. See SPEC.md §7. |
 | **`event=dropped detail=unknown session`** | A message arrived for a session ID this plugin never heard announced. | Expected right after `opencode --continue` if messages arrive before the session is active. Send the message again; the session will be registered on its next activity. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@brutalsystems/tincan-opencode",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "opencode plugin for Tin Can — the receive half, so an opencode session can be messaged by a live Claude Code, Codex or opencode peer.",
   "keywords": [
     "opencode",

package/tincan-lib/caller.ts

@@ -1,3 +1,4 @@
+import { unlink } from 'node:fs/promises';
 import { join } from 'node:path';
 import { isoStamp, writeJsonAtomic, type RecordContext } from './registry.js';
 
@@ -47,3 +48,69 @@ export function composeCaller(sessionID: string, toolID: string, ctx: RecordCont
 export async function writeCaller(dir: string, rec: CallerRecord): Promise<void> {
   await writeJsonAtomic(callerFile(dir, rec.instance_id), rec);
 }
+
+/**
+ * A per-call ticket, written when a Tin Can tool starts and removed when it
+ * ends. Tin Can reads these to identify the calling session *certainly*
+ * rather than by recency: its own call is in flight by definition, so exactly
+ * one fresh ticket for our pid can only be ours (#3).
+ *
+ * Kept ALONGSIDE the single caller file above, not instead of it. The plugin
+ * installs separately from the core, so an older core that only knows
+ * `inst-<id>.caller.json` must keep working exactly as it does today. The
+ * distinct `.call.json` suffix also keeps these invisible to that core's
+ * `.caller.json` glob.
+ *
+ * They still carry `instance_id`, so `dispose` and the orphan sweep reclaim
+ * them by the same path as every other file here.
+ */
+export interface CallTicket extends CallerRecord {
+  call_id: string;
+}
+
+/**
+ * opencode's callID is an opaque host string and this makes it a path
+ * segment, so it is constrained rather than trusted: anything outside
+ * `[A-Za-z0-9_-]` becomes `-`, and the result is capped. A `.` would collide
+ * with the suffix scheme and `/` or `..` would escape the directory.
+ */
+export function sanitizeCallId(callID: string): string {
+  const safe = callID.replace(/[^A-Za-z0-9_-]/g, '-').slice(0, 64);
+  return safe.length > 0 ? safe : 'anon';
+}
+
+/** Distinct from `<instance>.caller.json`, which an older core still reads. */
+export function callTicketFile(dir: string, instanceID: string, callID: string): string {
+  return join(dir, `${instanceID}.${sanitizeCallId(callID)}.call.json`);
+}
+
+export function composeCallTicket(
+  sessionID: string,
+  toolID: string,
+  callID: string,
+  ctx: RecordContext,
+): CallTicket {
+  return { ...composeCaller(sessionID, toolID, ctx), call_id: sanitizeCallId(callID) };
+}
+
+export async function writeCallTicket(dir: string, rec: CallTicket): Promise<void> {
+  await writeJsonAtomic(callTicketFile(dir, rec.instance_id, rec.call_id), rec);
+}
+
+/**
+ * opencode fires `tool.execute.after` only when the call succeeded — an error,
+ * a denied permission or an abort skip it entirely [verified, 1.18.32], so
+ * tickets leak by design and the reader expires them. This is the tidy path,
+ * not the guarantee.
+ */
+export async function removeCallTicket(
+  dir: string,
+  instanceID: string,
+  callID: string,
+): Promise<void> {
+  try {
+    await unlink(callTicketFile(dir, instanceID, callID));
+  } catch {
+    // Already gone: a sweep, a dispose, or never written.
+  }
+}

package/tincan-lib/plugin.ts

@@ -1,4 +1,11 @@
-import { composeCaller, isTincanTool, writeCaller } from './caller.js';
+import {
+  composeCallTicket,
+  composeCaller,
+  isTincanTool,
+  removeCallTicket,
+  writeCallTicket,
+  writeCaller,
+} from './caller.js';
 import { deliver } from './delivery.js';
 import { effectOf } from './events.js';
 import { makeLogger, swallow, type Logger } from './log.js';
@@ -9,7 +16,7 @@ import {
 } from './registry.js';
 import { listenLines, probeSocket, type ServerHandle } from './server.js';
 import { PLUGIN_VERSION, type RegistryRecord, type SessionInfo, type SessionState, type Transport } from './types.js';
-import { parseLine } from './wire.js';
+import { parseLine, renderAck, type Ack } from './wire.js';
 
 export interface LineHandlerDeps {
   transport: Transport;
@@ -19,16 +26,21 @@ export interface LineHandlerDeps {
   log: Logger;
 }
 
-export function makeLineHandler(deps: LineHandlerDeps): (line: string) => Promise<void> {
+/**
+ * Returns the ack the sender gets back. Every `return` here is a sender-visible
+ * answer, not just a log line — until 0.9.0 the only signal was "the bytes
+ * arrived", so a drop and a delivery were indistinguishable to Tin Can (#9).
+ */
+export function makeLineHandler(deps: LineHandlerDeps): (line: string) => Promise<Ack> {
   // Wrapped once, here, because deps.log is caller-supplied; called bare
   // everywhere below. SPEC §8.1.
   const log = swallow(deps.log);
-  return async (line: string): Promise<void> => {
+  return async (line: string): Promise<Ack> => {
     try {
       const parsed = parseLine(line);
       if (!parsed.ok) {
         log({ event: 'dropped', detail: parsed.reason });
-        return;
+        return { ok: false, reason: `malformed frame: ${parsed.reason}` };
       }
       const msg = parsed.message;
       if (!deps.known.has(msg.to_session)) {
@@ -39,7 +51,11 @@ export function makeLineHandler(deps: LineHandlerDeps): (line: string) => Promis
           message_id: msg.message_id,
           detail: 'unknown session',
         });
-        return;
+        return {
+          ok: false,
+          message_id: msg.message_id,
+          reason: `unknown session ${msg.to_session} on this opencode instance`,
+        };
       }
       const outcome = await deliver(deps.transport, msg, deps.sent);
       log({
@@ -54,9 +70,29 @@ export function makeLineHandler(deps: LineHandlerDeps): (line: string) => Promis
           : outcome.kind === 'transport-broken' ? outcome.detail
           : undefined,
       });
+      if (outcome.kind === 'delivered') {
+        return {
+          ok: true,
+          message_id: msg.message_id,
+          status: outcome.replay ? 'replay' : 'delivered',
+        };
+      }
+      return {
+        ok: false,
+        message_id: msg.message_id,
+        reason:
+          outcome.kind === 'rejected'
+            ? `opencode refused the prompt (status ${String(outcome.status)}${
+                outcome.tag === undefined ? '' : `: ${outcome.tag}`
+              })`
+            : `opencode transport failed: ${outcome.detail}`,
+      };
     } catch (e) {
-      // Nothing here may reach the host. SPEC §8.1.
+      // Nothing here may reach the host. SPEC §8.1. The sender is told the
+      // message did not land rather than being left to infer it from a
+      // closed socket, which would read as success.
       log({ event: 'handler.failed', detail: String(e) });
+      return { ok: false, reason: `plugin handler failed: ${String(e)}` };
     }
   };
 }
@@ -73,6 +109,7 @@ export interface PluginDeps {
 export interface PluginHooks {
   event: (input: { event: unknown }) => Promise<void>;
   'tool.execute.before': (input: unknown) => Promise<void>;
+  'tool.execute.after': (input: unknown) => Promise<void>;
   dispose: () => Promise<void>;
 }
 
@@ -94,6 +131,25 @@ async function selfCheck(transport: Transport, log: Logger): Promise<boolean> {
   }
 }
 
+/**
+ * The fields both tool hooks need, or `undefined` when this is not a Tin Can
+ * tool call worth recording. Shared so the two hooks cannot drift into
+ * disagreeing about what counts — a ticket written by one and not removed by
+ * the other is a leak the reader then has to expire.
+ */
+function tincanToolCall(
+  input: unknown,
+): { tool: string; sessionID: string; callID?: string } | undefined {
+  const i = (typeof input === 'object' && input !== null ? input : {}) as Record<string, unknown>;
+  if (typeof i.tool !== 'string' || typeof i.sessionID !== 'string') return undefined;
+  if (!isTincanTool(i.tool)) return undefined;
+  return {
+    tool: i.tool,
+    sessionID: i.sessionID,
+    ...(typeof i.callID === 'string' && i.callID.length > 0 && { callID: i.callID }),
+  };
+}
+
 export async function startPlugin(deps: PluginDeps): Promise<PluginHooks> {
   const log = makeLogger(deps.sink);
   const known = new Map<string, RegistryRecord>();
@@ -117,7 +173,7 @@ export async function startPlugin(deps: PluginDeps): Promise<PluginHooks> {
       if (swept.length > 0) log({ event: 'swept', detail: swept.join(',') });
       server = await listenLines({
         path: sock,
-        onLine: (line) => { void handleLine(line); },
+        onLine: (line) => handleLine(line).then(renderAck),
         onError: (e) => log({ event: 'socket.error', detail: String(e) }),
       });
       log({ event: 'bound', detail: sock });
@@ -205,10 +261,36 @@ export async function startPlugin(deps: PluginDeps): Promise<PluginHooks> {
     'tool.execute.before': async (input: unknown): Promise<void> => {
       if (!server) return; // No delivery path, so no session worth excluding.
       try {
-        const i = (typeof input === 'object' && input !== null ? input : {}) as Record<string, unknown>;
-        if (typeof i.tool !== 'string' || typeof i.sessionID !== 'string') return;
-        if (!isTincanTool(i.tool)) return;
+        const i = tincanToolCall(input);
+        if (i === undefined) return;
+        // Both, deliberately. The caller file is what an older core reads,
+        // and the plugin installs separately from the core so that skew is
+        // normal. The ticket is what a current core prefers.
         await writeCaller(deps.dir, composeCaller(i.sessionID, i.tool, ctx));
+        if (i.callID !== undefined) {
+          await writeCallTicket(deps.dir, composeCallTicket(i.sessionID, i.tool, i.callID, ctx));
+        }
+      } catch (e) {
+        log({ event: 'caller.failed', detail: String(e) });
+      }
+    },
+
+    /**
+     * The tidy path only. opencode reaches this hook by falling off the end of
+     * a successful call — an error, a denied permission or an abort skip it
+     * [verified against 1.18.32's MCP tool wrapper, which has no `finally`].
+     * So a leaked ticket is expected, not exceptional, and the reader expires
+     * tickets rather than trusting this to have run.
+     *
+     * The caller file is deliberately NOT removed here: it is the older core's
+     * only signal, and it is overwritten rather than cleared by design.
+     */
+    'tool.execute.after': async (input: unknown): Promise<void> => {
+      if (!server) return;
+      try {
+        const i = tincanToolCall(input);
+        if (i?.callID === undefined) return;
+        await removeCallTicket(deps.dir, deps.instanceId, i.callID);
       } catch (e) {
         log({ event: 'caller.failed', detail: String(e) });
       }

package/tincan-lib/server.ts

@@ -19,7 +19,12 @@ export const IDLE_TIMEOUT_MS = 30_000;
 
 export interface ListenOptions {
   path: string;
-  onLine: (line: string) => void;
+  /**
+   * Resolves to the line to write back. A handler that answers nothing — or
+   * is not async at all — is still valid: the socket is closed either way,
+   * so a sender never waits on a listener that has nothing to say.
+   */
+  onLine: (line: string) => void | Promise<string | undefined>;
   onError: (err: unknown) => void;
   /** Overridable so tests need not wait out the real one. */
   idleTimeoutMs?: number;
@@ -35,7 +40,7 @@ export interface ServerHandle {
  * inside a try that reports to `onError` rather than being swallowed.
  */
 interface Handlers {
-  onLine: (line: string) => void;
+  onLine: (line: string) => void | Promise<string | undefined>;
   onError: (err: unknown) => void;
 }
 
@@ -43,17 +48,45 @@ function frame(socket: Socket, handlers: Handlers): void {
   socket.setEncoding('utf8');
   let buf = '';
   let overflowed = false;
+  // A sender writes one line and half-closes, so one connection carries one
+  // message and earns one answer. `answered` also guarantees we end the
+  // socket exactly once: the server runs with allowHalfOpen, so nothing
+  // closes our side for us any more.
+  let answered = false;
+  let handled = 0;
 
-  const emit = (line: string) => {
-    if (line.length === 0) return;
+  const reply = (line: string | undefined) => {
+    if (answered) return;
+    answered = true;
     try {
-      handlers.onLine(line);
+      if (socket.writableEnded || socket.destroyed) return;
+      if (line === undefined) socket.end();
+      else socket.end(`${line}\n`);
     } catch (e) {
-      // A handler failure must never reach the host. SPEC §8.1.
+      // An old Tin Can stops reading and destroys the connection as soon as
+      // our side closes, so writing into it can EPIPE. That is the expected
+      // shape of version skew, not a fault. SPEC §8.1.
       handlers.onError(e);
     }
   };
 
+  const emit = (line: string) => {
+    if (line.length === 0) return;
+    handled++;
+    void (async () => {
+      let answer: string | undefined;
+      try {
+        const r = await handlers.onLine(line);
+        answer = typeof r === 'string' ? r : undefined;
+      } catch (e) {
+        // A handler failure must never reach the host. SPEC §8.1. The sender
+        // still gets its side closed, so it falls back rather than waiting.
+        handlers.onError(e);
+      }
+      reply(answer);
+    })();
+  };
+
   socket.on('data', (chunk: string) => {
     buf += chunk;
     let i: number;
@@ -77,6 +110,8 @@ function frame(socket: Socket, handlers: Handlers): void {
   socket.on('end', () => {
     if (!overflowed && buf.length > 0) emit(buf);
     buf = '';
+    // Nothing to answer and, with allowHalfOpen, nothing to close us either.
+    if (handled === 0) reply(undefined);
   });
   socket.on('error', (e) => handlers.onError(e));
 }
@@ -106,7 +141,13 @@ export async function listenLines(opts: ListenOptions): Promise<ServerHandle> {
   // never propagate out of a synchronous EventEmitter callback — SPEC §8.1
   // is absolute, and this module is its strictest instance.
   const handlers: Handlers = { onLine: opts.onLine, onError: swallow(opts.onError) };
-  const server: Server = createServer((socket) => {
+  // allowHalfOpen is what makes an answer possible at all. Without it Node
+  // ends our writable side automatically the moment the sender's FIN lands —
+  // and the sender FINs immediately after writing its line, so by the time we
+  // have something to say the socket is already closing. The cost is that
+  // every path out of `frame` must end the socket itself; `reply` is that
+  // single exit, and the idle timeout below is the backstop.
+  const server: Server = createServer({ allowHalfOpen: true }, (socket) => {
     sockets.add(socket);
     socket.on('close', () => sockets.delete(socket));
     // A sender writes one line and closes. Anything still idle after this

package/tincan-lib/types.ts

@@ -9,7 +9,7 @@
 
 /** Tracks the Tin Can package version: every registry record reports it,
  *  and a number matching no release tells an operator nothing. */
-export const PLUGIN_VERSION = '0.8.0';
+export const PLUGIN_VERSION = '0.9.0';
 export const OPENCODE_TESTED_VERSION = '1.18.31';
 
 /** Server-enforced: sessionID must match ^ses, message id must match ^msg_. */

package/tincan-lib/wire.ts

@@ -71,3 +71,30 @@ export function parseLine(line: string): ParseResult {
     },
   };
 }
+
+/**
+ * What the plugin writes back on the same connection before closing it.
+ *
+ * Until 0.9.0 the plugin answered nothing, so Tin Can counted a message as
+ * delivered the moment the bytes reached the socket — an unknown session, a
+ * malformed frame, a missing envelope and a 404 from opencode all looked
+ * identical to success (#9). `ok` is the difference between "we received it"
+ * and "we ran it".
+ *
+ * A refusal is a FAILURE here, not a success with a note. opencode has no
+ * equivalent of the Claude inbox's hold — where a human may still release the
+ * message, so `delivered: true` is honest — and a message this plugin refused
+ * will never be acted on by anyone.
+ */
+export interface Ack {
+  ok: boolean;
+  message_id?: string;
+  /** Present when `ok`: `replay` means this id had already been delivered. */
+  status?: 'delivered' | 'replay';
+  /** Present when not `ok`: why, in terms a sender can act on. */
+  reason?: string;
+}
+
+export function renderAck(ack: Ack): string {
+  return JSON.stringify(ack);
+}