0 Fork 0

Table of Contents

Roadmap

WP-1 · Skeleton and first tool
WP-2 · Client hardening
WP-3 · Read tools
WP-4 · Write tools — wall and comments
WP-5 · Write tools — members and moderation
WP-6 · Media upload
WP-7 · Board, market, messages-send, infrastructure
WP-8 · LongPoll bridge
WP-9 · Moderation engine
WP-10 · Policy and audit
WP-11 · Prompt section and skill
WP-12 · UI
WP-13 · Tests, docs, publishing
Dependency graph
Estimate

Roadmap

Implementation order, one work package per issue. Each package is independently reviewable and leaves the plugin in a loadable state.

WP-1 · Skeleton and first tool

Deliverable: plugin loads in a Web profile, vk_community_info is visible to the model and returns real data.

package.json with dsh.bundle, engines.dsh, peer deps
cordis.patch.yml
src/config.ts — full Schemastery schema with defaults
src/vk/client.ts — minimal fetch wrapper with v param, {response}/{error} unwrapping
src/vk/errors.ts — the error hierarchy, codes 5/6/7/9/14/15/100/203
src/tools/community.ts — vk_community_info only
src/index.ts — apply, register the one tool

Acceptance: dsh --profile web --dump-config shows the layer; a prompt asking the agent about the community returns real name, member count and adminLevel.

WP-2 · Client hardening

Deliverable: the client can survive real VK traffic.

Token bucket (rps, burst, maxConcurrent)
Retry with exponential backoff over retry.retryOn
execute batching helper (≤25 sub-calls)
exec.signal propagation to every request
Typed error mapping for every code in the table
Unit tests to the coverage target

Acceptance: all tests/client.test.ts cases green; a 500-id batch ban issues 20 HTTP requests, not 500.

WP-3 · Read tools

Deliverable: the agent can inspect everything.

vk_members_list, vk_ban_list, vk_requests_list, vk_managers_list, vk_wall_list, vk_comments_list, vk_messages_list, vk_stats_get, vk_shortlink, vk_member_status.

Every list tool returns { items, total, offset, count, hasMore } and clamps count to the method maximum.

Acceptance: contract tests green for all 10; vk_stats_get and vk_members_list return VK_SCOPE_MISSING without a user token.

WP-4 · Write tools — wall and comments

Deliverable: posting and comment management.

vk_wall_post, vk_wall_edit, vk_wall_delete, vk_wall_pin, vk_comment_manage.

Includes guid idempotency on post, diff cards on post/edit, ask gate on delete.

Acceptance: post → edit → pin → delete lifecycle passes against the mock; replay test shows identical diff cards.

WP-5 · Write tools — members and moderation

Deliverable: people management.

vk_members_manage, vk_ban_manage, vk_requests_handle, vk_manager_set.

Batch semantics: per-id results, partial failures surfaced, execute batching.

Acceptance: 500-id ban with 3 deliberately invalid ids returns 497 successes and 3 typed failures.

WP-6 · Media upload

Deliverable: vk_media_upload for photo_wall, photo_message, doc, video, story.

Two/three-step upload, single-use URL, restart-from-step-1 on failure
File path and URL sources
attachment string construction
ctx.jobs for large uploads

Acceptance: each type produces the correct attachment format; a forced upload failure retries from getUploadServer.

WP-7 · Board, market, messages-send, infrastructure

Deliverable: the remaining write surface.

vk_board_topic, vk_board_comment, vk_market_manage, vk_messages_send, vk_community_update, vk_callback_manage, vk_longpoll_control, vk_api_raw.

Acceptance: all 30 tools registered; contract tests green; vk_api_raw denied with the default config.

WP-8 · LongPoll bridge

Deliverable: inbound events reach the agent.

groups.getLongPollServer, session loop, ts/key/server persistence in ctx.storage
failed:1/2/3 recovery, backoff, stop-on-auth-failure
Batching over batchMs
agent.followup() delivery with source: {kind: 'vk-inbound'}
vk_longpoll_control wired to the job

Acceptance: mock server emits 20 events in 1 second → the agent receives one batched message; failed:2 triggers a full re-request; job stop aborts the in-flight poll.

WP-9 · Moderation engine

Deliverable: rules act without the model.

Rule schema and validation
Six match types
Warn counters and threshold
Inbound and outbound entry points
vk_moderation_rules tool
Dry-run mode

Acceptance: the example rule set from the wiki behaves as documented; staff are never acted on; dry-run audits without writing.

WP-10 · Policy and audit

Deliverable: the safety layer.

tools/pre-execute listener: scope check, tier check, destructive → ask, raw-api allowlist
ctx.tools.guard(): monotonic tier denial
tools/result observer: audit record per mutating call
ctx.tools.execute wrapper: per-tool metrics
Tier resolution from admin_level at load, re-check on demand

Acceptance: every case in tests/policy.test.ts green; a tier-1 token cannot issue a single write request.

WP-11 · Prompt section and skill

Deliverable: the agent knows how to operate.

ctx.systemPrompt.section() — community name, member count, tier, moderation mode
skill/vk-group-ops/SKILL.md — playbooks: daily digest, moderation triage, post scheduling, incident response, and the inbound-content rule

Acceptance: a fresh session answers "what can you do with this community" accurately without being told.

WP-12 · UI

Deliverable: the Web client shows VK state.

Settings panel (read config, show tier and token scopes, LongPoll status)
ConversationNodeDefinition cards: post card, moderation queue row
Status card: events received, errors, last event

Acceptance: cards render live and on replay; the settings panel reflects a config change after HMR.

WP-13 · Tests, docs, publishing

Deliverable: shippable.

Full test suite to the per-area coverage targets
npm run test:live against a real test community
README, wiki sync, CHANGELOG
npm pack tarball; verify dsh plugin add ./dsh-vk-group-0.1.0.tgz on a clean profile
prepare script for git installs; document the pnpm allowBuilds step

Acceptance: a clean profile installs from the tarball and from git; dsh --dump-config shows the layer both ways.

Dependency graph

WP-1 → WP-2 → WP-3 ─┬→ WP-4 ─┐
                    ├→ WP-5 ─┤
                    ├→ WP-6 ─┼→ WP-7 → WP-8 → WP-9 → WP-10 → WP-11 → WP-12 → WP-13
                    └────────┘

WP-10 (policy) technically can land before WP-8; it is sequenced after because the audit log is more useful once there is traffic to audit. WP-11/12 can run in parallel with WP-10.

Estimate

WP	Scope	Rough size
1	skeleton	S
2	client	M
3	10 read tools	L
4	5 write tools	M
5	4 batch write tools	M
6	media	M
7	8 mixed tools	L
8	LongPoll	M
9	moderation	L
10	policy/audit	M
11	prompt/skill	S
12	UI	L
13	tests/docs/publish	L

13 work packages, ~30 tools, 3 subsystems (client, events, moderation) plus policy, skill and UI.