residual/.agent

Watch

Fork 0

core/lib/ipc: generalize for multi-tool use #20

New issue

Open

opened 2026-08-08 13:08:36 +00:00 by agent · 0 comments

agent commented

2026-08-08 13:08:36 +00:00

Member

IPC library generalization

The core/lib/ipc library is currently tightly coupled to residual-init's use case. It needs to become a general-purpose IPC library that other tools (res-playbook, res-code plugins, res-console plugins) can use with program-specific wrappers.

current state

core/lib/ipc provides:

Message{Type, Payload, ID} — wire format
Server — UDS listener with handler dispatch
Client — UDS connector with Call/Notify

This works for residual-init but has limitations for other use cases:

No ReadMessage() on Client for handshake/declare patterns
No simplified helpers for common patterns (typed request/response)
No program-specific abstraction layer

goal

Make core/lib/ipc a generic foundation, with program-specific wrappers living in each tool's own packages.

plan

Phase 1: Core improvements

Add ReadMessage() to ipc.Client — reads one raw message from the connection (for handshake/declare patterns)
Add ReadMessage() to ipc.Server conn handler — allows server-side reading of client-initiated messages
Keep the existing API surface (Handle, Call, Notify) unchanged

Phase 2: Simplified helpers (optional, low priority)

Typed request/response helpers:

// Simplified call with automatic marshal/unmarshal
func CallTyped[Req, Resp any](ctx context.Context, client *Client, msgType string, req Req) (Resp, error)

This is syntactic sugar — the raw API still works

Phase 3: Program-specific wrappers
Each tool implements its own wrappers on top of the generic library:

res-playbook/internal/playbook/langs/ — runtime client/server
res-code/internal/code/plugin/ — plugin client/server (future)
res-console/internal/libs/console/plugin/ — plugin client/server (future)

design principle

Follow the pattern from core/lib/script:

Core library is generic and reusable
Program-specific logic lives in the program's own packages
No program depends on another program's wrappers

files to change

core/lib/ipc/client.go — add ReadMessage()
core/lib/ipc/ipc_test.go — add tests for new functionality

verification

cd core && go build ./... && go test ./...
Existing residual-init IPC continues to work unchanged
res-playbook uses the new ReadMessage() for declare handshake

labels

proj-core-lib, tier-2-medium

## IPC library generalization The `core/lib/ipc` library is currently tightly coupled to `residual-init`'s use case. It needs to become a general-purpose IPC library that other tools (res-playbook, res-code plugins, res-console plugins) can use with program-specific wrappers. ### current state `core/lib/ipc` provides: - `Message{Type, Payload, ID}` — wire format - `Server` — UDS listener with handler dispatch - `Client` — UDS connector with Call/Notify This works for `residual-init` but has limitations for other use cases: 1. No `ReadMessage()` on Client for handshake/declare patterns 2. No simplified helpers for common patterns (typed request/response) 3. No program-specific abstraction layer ### goal Make `core/lib/ipc` a generic foundation, with program-specific wrappers living in each tool's own packages. ### plan **Phase 1: Core improvements** 1. Add `ReadMessage()` to `ipc.Client` — reads one raw message from the connection (for handshake/declare patterns) 2. Add `ReadMessage()` to `ipc.Server` conn handler — allows server-side reading of client-initiated messages 3. Keep the existing API surface (Handle, Call, Notify) unchanged **Phase 2: Simplified helpers (optional, low priority)** 1. Typed request/response helpers: ```go // Simplified call with automatic marshal/unmarshal func CallTyped[Req, Resp any](ctx context.Context, client *Client, msgType string, req Req) (Resp, error) ``` 2. This is syntactic sugar — the raw API still works **Phase 3: Program-specific wrappers** Each tool implements its own wrappers on top of the generic library: - `res-playbook/internal/playbook/langs/` — runtime client/server - `res-code/internal/code/plugin/` — plugin client/server (future) - `res-console/internal/libs/console/plugin/` — plugin client/server (future) ### design principle Follow the pattern from `core/lib/script`: - Core library is generic and reusable - Program-specific logic lives in the program's own packages - No program depends on another program's wrappers ### files to change - `core/lib/ipc/client.go` — add `ReadMessage()` - `core/lib/ipc/ipc_test.go` — add tests for new functionality ### verification 1. `cd core && go build ./... && go test ./...` 2. Existing `residual-init` IPC continues to work unchanged 3. `res-playbook` uses the new `ReadMessage()` for declare handshake ### labels `proj-core-lib`, `tier-2-medium`

agent added the

proj-core-lib

tier-2-medium

labels

2026-08-08 13:09:02 +00:00

No milestone

No project

No assignees

1 participant

Notifications

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

residual/.agent#20

No description provided.

Rows
Columns