[EPIC][module-runtime] Supervised module runs, jobs, cancellation, evidence, and typed session handles #194

New issue

Open

opened 2026-09-05 08:07:21 +00:00 by nsaspy · 0 comments

nsaspy commented

2026-09-05 08:07:21 +00:00

Owner

Parent: #192

Mission

Implement the canonical runtime lifecycle for Hackmode native modules: foreground/background runs, supervised jobs, cancellation, typed results/evidence, and long-lived session handles where a provider genuinely exposes an interactive authorized capability.

This should capture the useful operator concepts of Metasploit jobs/sessions without creating an unrestricted shell/payload subsystem.

Run lifecycle

A module run should have stable typed state equivalent to:

created
validated
admitted | denied
queued
running
waiting
succeeded | failed | cancelled | blocked
finalized

Every transition is operation/module/run attributed and inspectable.

Jobs

Background work should use the existing StarLang/actor supervision model.

Required capabilities:

start foreground/background module run;
enumerate jobs by operation/module/status;
inspect progress/status/current capability request;
cancel cooperatively;
enforce deadlines/budgets;
surface provider failure/restart as structured run state;
prevent cancelled jobs from producing later admitted effects;
retain final typed evidence/result references.

Do not reproduce ad-hoc process/thread bookkeeping if an existing supervisor/actor abstraction can own it.

Typed session handles

Some authorized providers may expose a longer-lived interactive or stateful capability. Represent that as a typed Hackmode session handle, not raw ambient process authority.

A session handle should include at minimum:

stable session ID + generation/version;
owning operation + originating run/module;
provider/capability identity;
authority/scope binding;
lifecycle/status;
allowed typed operations/capabilities;
created/last-used/expiry metadata;
evidence/provenance links.

Stale/closed/replaced handles must fail deterministically.

Evidence and results

Runs emit typed facts/events including:

admission/denial;
provider call/result;
observations/findings;
artifacts;
session creation/closure;
warnings/errors;
cancellation/budget stop reason;
cleanup/finalization outcome.

Canonical state mutation continues through Hackmode APIs. A module does not write directly to Tek9.

Hackpert integration

Hackpert may start/observe/cancel module runs through typed actions in active mode. Passive mode may inspect run/evidence state but cannot dispatch effectful modules.

Reasoning strategy changes do not alter run authority.

Acceptance

stable module run object/state machine exists;
foreground and background runs use the same core runtime semantics;
background runs are supervised through StarLang/actor infrastructure;
cancellation prevents later effects and produces a structured terminal result;
budget/deadline/provider failures become typed stop reasons;
results and evidence are linked to operation/module/run identity;
typed session handles are capability-scoped and generation-safe;
closing/replacing a session invalidates stale handles;
passive Hackpert cannot start effectful runs;
active Hackpert still crosses canonical admission for each effectful action;
deterministic fixtures prove start -> inspect -> cancel and start -> result/evidence paths;
no unrestricted shell/session authority is introduced by this epic.

Non-goals

No generic malware payload runtime.
No unscoped remote-shell primitive.
No second actor scheduler.
No session-owned scope or credentials outside canonical Hackmode policy.

First slice

Implement one synthetic background module run under StarLang supervision with stable run/job IDs, progress inspection, cancellation, and a typed final evidence record. Add session handles only after the base run lifecycle is green.

Parent: #192 ## Mission Implement the canonical runtime lifecycle for Hackmode native modules: foreground/background runs, supervised jobs, cancellation, typed results/evidence, and long-lived session handles where a provider genuinely exposes an interactive authorized capability. This should capture the useful operator concepts of Metasploit jobs/sessions without creating an unrestricted shell/payload subsystem. ## Run lifecycle A module run should have stable typed state equivalent to: ```text created validated admitted | denied queued running waiting succeeded | failed | cancelled | blocked finalized ``` Every transition is operation/module/run attributed and inspectable. ## Jobs Background work should use the existing StarLang/actor supervision model. Required capabilities: - start foreground/background module run; - enumerate jobs by operation/module/status; - inspect progress/status/current capability request; - cancel cooperatively; - enforce deadlines/budgets; - surface provider failure/restart as structured run state; - prevent cancelled jobs from producing later admitted effects; - retain final typed evidence/result references. Do not reproduce ad-hoc process/thread bookkeeping if an existing supervisor/actor abstraction can own it. ## Typed session handles Some authorized providers may expose a longer-lived interactive or stateful capability. Represent that as a typed Hackmode session handle, not raw ambient process authority. A session handle should include at minimum: - stable session ID + generation/version; - owning operation + originating run/module; - provider/capability identity; - authority/scope binding; - lifecycle/status; - allowed typed operations/capabilities; - created/last-used/expiry metadata; - evidence/provenance links. Stale/closed/replaced handles must fail deterministically. ## Evidence and results Runs emit typed facts/events including: - admission/denial; - provider call/result; - observations/findings; - artifacts; - session creation/closure; - warnings/errors; - cancellation/budget stop reason; - cleanup/finalization outcome. Canonical state mutation continues through Hackmode APIs. A module does not write directly to Tek9. ## Hackpert integration Hackpert may start/observe/cancel module runs through typed actions in active mode. Passive mode may inspect run/evidence state but cannot dispatch effectful modules. Reasoning strategy changes do not alter run authority. ## Acceptance - [ ] stable module run object/state machine exists; - [ ] foreground and background runs use the same core runtime semantics; - [ ] background runs are supervised through StarLang/actor infrastructure; - [ ] cancellation prevents later effects and produces a structured terminal result; - [ ] budget/deadline/provider failures become typed stop reasons; - [ ] results and evidence are linked to operation/module/run identity; - [ ] typed session handles are capability-scoped and generation-safe; - [ ] closing/replacing a session invalidates stale handles; - [ ] passive Hackpert cannot start effectful runs; - [ ] active Hackpert still crosses canonical admission for each effectful action; - [ ] deterministic fixtures prove start -> inspect -> cancel and start -> result/evidence paths; - [ ] no unrestricted shell/session authority is introduced by this epic. ## Non-goals - No generic malware payload runtime. - No unscoped remote-shell primitive. - No second actor scheduler. - No session-owned scope or credentials outside canonical Hackmode policy. ## First slice Implement one synthetic background module run under StarLang supervision with stable run/job IDs, progress inspection, cancellation, and a typed final evidence record. Add session handles only after the base run lifecycle is green.

nsaspy referenced this issue

2026-09-05 08:18:47 +00:00

[EPIC][module-framework] Native Hackmode security module framework with Metasploit-inspired concepts #197