apcore-js 0.5.0 → 0.7.0

package/README.md

@@ -128,4 +128,4 @@ npm run build
 
 ## License
 
-MIT
+Apache-2.0

package/dist/acl.d.ts

@@ -0,0 +1,27 @@
+/**
+ * ACL (Access Control List) types and implementation for apcore.
+ */
+import type { Context } from './context.js';
+export interface ACLRule {
+    callers: string[];
+    targets: string[];
+    effect: string;
+    description: string;
+    conditions?: Record<string, unknown> | null;
+}
+export declare class ACL {
+    private _rules;
+    private _defaultEffect;
+    private _yamlPath;
+    debug: boolean;
+    constructor(rules: ACLRule[], defaultEffect?: string);
+    static load(yamlPath: string): ACL;
+    check(callerId: string | null, targetId: string, context?: Context | null): boolean;
+    private _matchPattern;
+    private _matchesRule;
+    private _checkConditions;
+    addRule(rule: ACLRule): void;
+    removeRule(callers: string[], targets: string[]): boolean;
+    reload(): void;
+}
+//# sourceMappingURL=acl.d.ts.map

package/dist/acl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"acl.d.ts","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAQ5C,MAAM,WAAW,OAAO;IACtB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC7C;AAsCD,qBAAa,GAAG;IACd,OAAO,CAAC,MAAM,CAAY;IAC1B,OAAO,CAAC,cAAc,CAAS;IAC/B,OAAO,CAAC,SAAS,CAAuB;IACxC,KAAK,EAAE,OAAO,CAAS;gBAEX,KAAK,EAAE,OAAO,EAAE,EAAE,aAAa,GAAE,MAAe;IAQ5D,MAAM,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,GAAG,GAAG;IAqClC,KAAK,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GAAG,OAAO;IAYnF,OAAO,CAAC,aAAa;IAQrB,OAAO,CAAC,YAAY;IAcpB,OAAO,CAAC,gBAAgB;IAmCxB,OAAO,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI;IAI5B,UAAU,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,OAAO,EAAE,MAAM,EAAE,GAAG,OAAO;IAczD,MAAM,IAAI,IAAI;CAQf"}

package/dist/acl.js

@@ -0,0 +1,175 @@
+/**
+ * ACL (Access Control List) types and implementation for apcore.
+ */
+import yaml from 'js-yaml';
+import { ACLRuleError, ConfigNotFoundError } from './errors.js';
+import { matchPattern } from './utils/pattern.js';
+// Lazy-load Node.js built-in modules for browser compatibility
+let _nodeFs = null;
+try {
+    _nodeFs = await import('node:fs');
+}
+catch { /* browser environment */ }
+function parseAclRule(rawRule, index) {
+    if (typeof rawRule !== 'object' || rawRule === null || Array.isArray(rawRule)) {
+        throw new ACLRuleError(`Rule ${index} must be a mapping, got ${typeof rawRule}`);
+    }
+    const ruleObj = rawRule;
+    for (const key of ['callers', 'targets', 'effect']) {
+        if (!(key in ruleObj)) {
+            throw new ACLRuleError(`Rule ${index} missing required key '${key}'`);
+        }
+    }
+    const effect = ruleObj['effect'];
+    if (effect !== 'allow' && effect !== 'deny') {
+        throw new ACLRuleError(`Rule ${index} has invalid effect '${effect}', must be 'allow' or 'deny'`);
+    }
+    const callers = ruleObj['callers'];
+    if (!Array.isArray(callers)) {
+        throw new ACLRuleError(`Rule ${index} 'callers' must be a list, got ${typeof callers}`);
+    }
+    const targets = ruleObj['targets'];
+    if (!Array.isArray(targets)) {
+        throw new ACLRuleError(`Rule ${index} 'targets' must be a list, got ${typeof targets}`);
+    }
+    return {
+        callers: callers,
+        targets: targets,
+        effect,
+        description: ruleObj['description'] ?? '',
+        conditions: ruleObj['conditions'] ?? null,
+    };
+}
+export class ACL {
+    _rules;
+    _defaultEffect;
+    _yamlPath = null;
+    debug = false;
+    constructor(rules, defaultEffect = 'deny') {
+        if (defaultEffect !== 'allow' && defaultEffect !== 'deny') {
+            throw new ACLRuleError(`Invalid default_effect '${defaultEffect}', must be 'allow' or 'deny'`);
+        }
+        this._rules = [...rules];
+        this._defaultEffect = defaultEffect;
+    }
+    static load(yamlPath) {
+        const { existsSync, readFileSync } = _nodeFs;
+        if (!existsSync(yamlPath)) {
+            throw new ConfigNotFoundError(yamlPath);
+        }
+        let data;
+        try {
+            const content = readFileSync(yamlPath, 'utf-8');
+            data = yaml.load(content);
+        }
+        catch (e) {
+            if (e instanceof ConfigNotFoundError)
+                throw e;
+            throw new ACLRuleError(`Invalid YAML in ${yamlPath}: ${e}`);
+        }
+        if (typeof data !== 'object' || data === null || Array.isArray(data)) {
+            throw new ACLRuleError(`ACL config must be a mapping, got ${typeof data}`);
+        }
+        const dataObj = data;
+        if (!('rules' in dataObj)) {
+            throw new ACLRuleError("ACL config missing required 'rules' key");
+        }
+        const rawRules = dataObj['rules'];
+        if (!Array.isArray(rawRules)) {
+            throw new ACLRuleError(`'rules' must be a list, got ${typeof rawRules}`);
+        }
+        const defaultEffect = dataObj['default_effect'] ?? 'deny';
+        const rules = rawRules.map((raw, i) => parseAclRule(raw, i));
+        const acl = new ACL(rules, defaultEffect);
+        acl._yamlPath = yamlPath;
+        return acl;
+    }
+    check(callerId, targetId, context) {
+        const effectiveCaller = callerId === null ? '@external' : callerId;
+        for (const rule of this._rules) {
+            if (this._matchesRule(rule, effectiveCaller, targetId, context ?? null)) {
+                return rule.effect === 'allow';
+            }
+        }
+        return this._defaultEffect === 'allow';
+    }
+    _matchPattern(pattern, value, context) {
+        if (pattern === '@external')
+            return value === '@external';
+        if (pattern === '@system') {
+            return context !== null && context.identity !== null && context.identity.type === 'system';
+        }
+        return matchPattern(pattern, value);
+    }
+    _matchesRule(rule, caller, target, context) {
+        const callerMatch = rule.callers.some((p) => this._matchPattern(p, caller, context));
+        if (!callerMatch)
+            return false;
+        const targetMatch = rule.targets.some((p) => this._matchPattern(p, target, context));
+        if (!targetMatch)
+            return false;
+        if (rule.conditions != null) {
+            if (!this._checkConditions(rule.conditions, context))
+                return false;
+        }
+        return true;
+    }
+    _checkConditions(conditions, context) {
+        if (context === null)
+            return false;
+        if ('identity_types' in conditions) {
+            const types = conditions['identity_types'];
+            if (!Array.isArray(types)) {
+                console.warn('[apcore:acl] identity_types condition must be an array');
+                return false;
+            }
+            if (context.identity === null || !types.includes(context.identity.type))
+                return false;
+        }
+        if ('roles' in conditions) {
+            const roles = conditions['roles'];
+            if (!Array.isArray(roles)) {
+                console.warn('[apcore:acl] roles condition must be an array');
+                return false;
+            }
+            if (context.identity === null)
+                return false;
+            const identityRoles = new Set(context.identity.roles);
+            if (!roles.some((r) => identityRoles.has(r)))
+                return false;
+        }
+        if ('max_call_depth' in conditions) {
+            const maxDepth = conditions['max_call_depth'];
+            if (typeof maxDepth !== 'number') {
+                console.warn('[apcore:acl] max_call_depth condition must be a number');
+                return false;
+            }
+            if (context.callChain.length > maxDepth)
+                return false;
+        }
+        return true;
+    }
+    addRule(rule) {
+        this._rules.unshift(rule);
+    }
+    removeRule(callers, targets) {
+        for (let i = 0; i < this._rules.length; i++) {
+            const rule = this._rules[i];
+            if (JSON.stringify(rule.callers) === JSON.stringify(callers) &&
+                JSON.stringify(rule.targets) === JSON.stringify(targets)) {
+                this._rules.splice(i, 1);
+                return true;
+            }
+        }
+        return false;
+    }
+    reload() {
+        if (this._yamlPath === null) {
+            throw new ACLRuleError('Cannot reload: ACL was not loaded from a YAML file');
+        }
+        const reloaded = ACL.load(this._yamlPath);
+        this._rules = reloaded._rules;
+        this._defaultEffect = reloaded._defaultEffect;
+    }
+}
+//# sourceMappingURL=acl.js.map

package/dist/acl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"acl.js","sourceRoot":"","sources":["../src/acl.ts"],"names":[],"mappings":"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"}

package/dist/approval.d.ts

@@ -0,0 +1,85 @@
+/**
+ * Approval system: interfaces, data types, built-in handlers.
+ *
+ * Provides a pluggable gate at Executor Step 4.5, between ACL enforcement
+ * and input validation. When a module declares requiresApproval=true and
+ * an ApprovalHandler is configured, the handler is invoked before execution.
+ */
+import type { Context } from './context.js';
+import type { ModuleAnnotations } from './module.js';
+/**
+ * Carries invocation context to the approval handler.
+ */
+export interface ApprovalRequest {
+    readonly moduleId: string;
+    readonly arguments: Record<string, unknown>;
+    readonly context: Context;
+    readonly annotations: ModuleAnnotations;
+    readonly description: string | null;
+    readonly tags: readonly string[];
+}
+/**
+ * Create a frozen ApprovalRequest.
+ */
+export declare function createApprovalRequest(options: {
+    moduleId: string;
+    arguments: Record<string, unknown>;
+    context: Context;
+    annotations: ModuleAnnotations;
+    description?: string | null;
+    tags?: string[];
+}): ApprovalRequest;
+/**
+ * Carries the approval handler's decision.
+ */
+export interface ApprovalResult {
+    readonly status: 'approved' | 'rejected' | 'timeout' | 'pending';
+    readonly approvedBy: string | null;
+    readonly reason: string | null;
+    readonly approvalId: string | null;
+    readonly metadata: Record<string, unknown> | null;
+}
+/**
+ * Create a frozen ApprovalResult.
+ */
+export declare function createApprovalResult(options: {
+    status: 'approved' | 'rejected' | 'timeout' | 'pending';
+    approvedBy?: string | null;
+    reason?: string | null;
+    approvalId?: string | null;
+    metadata?: Record<string, unknown> | null;
+}): ApprovalResult;
+/**
+ * Protocol for pluggable approval handlers.
+ *
+ * Implementations receive an ApprovalRequest and return an ApprovalResult.
+ * Both methods are asynchronous.
+ */
+export interface ApprovalHandler {
+    requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
+    checkApproval(approvalId: string): Promise<ApprovalResult>;
+}
+/**
+ * Built-in handler that always rejects. Safe default for enforcement.
+ */
+export declare class AlwaysDenyHandler implements ApprovalHandler {
+    requestApproval(_request: ApprovalRequest): Promise<ApprovalResult>;
+    checkApproval(_approvalId: string): Promise<ApprovalResult>;
+}
+/**
+ * Built-in handler that always approves. For testing and development.
+ */
+export declare class AutoApproveHandler implements ApprovalHandler {
+    requestApproval(_request: ApprovalRequest): Promise<ApprovalResult>;
+    checkApproval(_approvalId: string): Promise<ApprovalResult>;
+}
+/**
+ * Built-in handler that delegates to a user-provided async callback.
+ */
+export declare class CallbackApprovalHandler implements ApprovalHandler {
+    private _callback;
+    constructor(callback: (request: ApprovalRequest) => Promise<ApprovalResult>);
+    requestApproval(request: ApprovalRequest): Promise<ApprovalResult>;
+    checkApproval(_approvalId: string): Promise<ApprovalResult>;
+}
+//# sourceMappingURL=approval.d.ts.map

package/dist/approval.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.d.ts","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,aAAa,CAAC;AAErD;;GAEG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,QAAQ,CAAC,WAAW,EAAE,iBAAiB,CAAC;IACxC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,EAAE,iBAAiB,CAAC;IAC/B,WAAW,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,CAAC,EAAE,MAAM,EAAE,CAAC;CACjB,GAAG,eAAe,CASlB;AAED;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;IACjE,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CACnD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE;IAC5C,MAAM,EAAE,UAAU,GAAG,UAAU,GAAG,SAAS,GAAG,SAAS,CAAC;IACxD,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;CAC3C,GAAG,cAAc,CAQjB;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;IACnE,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC;CAC5D;AAED;;GAEG;AACH,qBAAa,iBAAkB,YAAW,eAAe;IACjD,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAInE,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAGlE;AAED;;GAEG;AACH,qBAAa,kBAAmB,YAAW,eAAe;IAClD,eAAe,CAAC,QAAQ,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAInE,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAGlE;AAED;;GAEG;AACH,qBAAa,uBAAwB,YAAW,eAAe;IAC7D,OAAO,CAAC,SAAS,CAAwD;gBAE7D,QAAQ,EAAE,CAAC,OAAO,EAAE,eAAe,KAAK,OAAO,CAAC,cAAc,CAAC;IAIrE,eAAe,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAIlE,aAAa,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,CAAC;CAMlE"}

package/dist/approval.js

@@ -0,0 +1,73 @@
+/**
+ * Approval system: interfaces, data types, built-in handlers.
+ *
+ * Provides a pluggable gate at Executor Step 4.5, between ACL enforcement
+ * and input validation. When a module declares requiresApproval=true and
+ * an ApprovalHandler is configured, the handler is invoked before execution.
+ */
+/**
+ * Create a frozen ApprovalRequest.
+ */
+export function createApprovalRequest(options) {
+    return Object.freeze({
+        moduleId: options.moduleId,
+        arguments: options.arguments,
+        context: options.context,
+        annotations: options.annotations,
+        description: options.description ?? null,
+        tags: Object.freeze([...(options.tags ?? [])]),
+    });
+}
+/**
+ * Create a frozen ApprovalResult.
+ */
+export function createApprovalResult(options) {
+    return Object.freeze({
+        status: options.status,
+        approvedBy: options.approvedBy ?? null,
+        reason: options.reason ?? null,
+        approvalId: options.approvalId ?? null,
+        metadata: options.metadata ?? null,
+    });
+}
+/**
+ * Built-in handler that always rejects. Safe default for enforcement.
+ */
+export class AlwaysDenyHandler {
+    async requestApproval(_request) {
+        return createApprovalResult({ status: 'rejected', reason: 'Always denied' });
+    }
+    async checkApproval(_approvalId) {
+        return createApprovalResult({ status: 'rejected', reason: 'Always denied' });
+    }
+}
+/**
+ * Built-in handler that always approves. For testing and development.
+ */
+export class AutoApproveHandler {
+    async requestApproval(_request) {
+        return createApprovalResult({ status: 'approved', approvedBy: 'auto' });
+    }
+    async checkApproval(_approvalId) {
+        return createApprovalResult({ status: 'approved', approvedBy: 'auto' });
+    }
+}
+/**
+ * Built-in handler that delegates to a user-provided async callback.
+ */
+export class CallbackApprovalHandler {
+    _callback;
+    constructor(callback) {
+        this._callback = callback;
+    }
+    async requestApproval(request) {
+        return this._callback(request);
+    }
+    async checkApproval(_approvalId) {
+        return createApprovalResult({
+            status: 'rejected',
+            reason: 'Phase B not supported by callback handler',
+        });
+    }
+}
+//# sourceMappingURL=approval.js.map

package/dist/approval.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"approval.js","sourceRoot":"","sources":["../src/approval.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAiBH;;GAEG;AACH,MAAM,UAAU,qBAAqB,CAAC,OAOrC;IACC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,OAAO,EAAE,OAAO,CAAC,OAAO;QACxB,WAAW,EAAE,OAAO,CAAC,WAAW;QAChC,WAAW,EAAE,OAAO,CAAC,WAAW,IAAI,IAAI;QACxC,IAAI,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC,CAAC;KAC/C,CAAC,CAAC;AACL,CAAC;AAaD;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAMpC;IACC,OAAO,MAAM,CAAC,MAAM,CAAC;QACnB,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;QACtC,MAAM,EAAE,OAAO,CAAC,MAAM,IAAI,IAAI;QAC9B,UAAU,EAAE,OAAO,CAAC,UAAU,IAAI,IAAI;QACtC,QAAQ,EAAE,OAAO,CAAC,QAAQ,IAAI,IAAI;KACnC,CAAC,CAAC;AACL,CAAC;AAaD;;GAEG;AACH,MAAM,OAAO,iBAAiB;IAC5B,KAAK,CAAC,eAAe,CAAC,QAAyB;QAC7C,OAAO,oBAAoB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;IAC/E,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,WAAmB;QACrC,OAAO,oBAAoB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,eAAe,EAAE,CAAC,CAAC;IAC/E,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,kBAAkB;IAC7B,KAAK,CAAC,eAAe,CAAC,QAAyB;QAC7C,OAAO,oBAAoB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1E,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,WAAmB;QACrC,OAAO,oBAAoB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,EAAE,CAAC,CAAC;IAC1E,CAAC;CACF;AAED;;GAEG;AACH,MAAM,OAAO,uBAAuB;IAC1B,SAAS,CAAwD;IAEzE,YAAY,QAA+D;QACzE,IAAI,CAAC,SAAS,GAAG,QAAQ,CAAC;IAC5B,CAAC;IAED,KAAK,CAAC,eAAe,CAAC,OAAwB;QAC5C,OAAO,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACjC,CAAC;IAED,KAAK,CAAC,aAAa,CAAC,WAAmB;QACrC,OAAO,oBAAoB,CAAC;YAC1B,MAAM,EAAE,UAAU;YAClB,MAAM,EAAE,2CAA2C;SACpD,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/async-task.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Async task manager for background module execution.
+ */
+import type { Context } from './context.js';
+import type { Executor } from './executor.js';
+export declare enum TaskStatus {
+    PENDING = "pending",
+    RUNNING = "running",
+    COMPLETED = "completed",
+    FAILED = "failed",
+    CANCELLED = "cancelled"
+}
+export interface TaskInfo {
+    readonly taskId: string;
+    readonly moduleId: string;
+    readonly status: TaskStatus;
+    readonly submittedAt: number;
+    readonly startedAt: number | null;
+    readonly completedAt: number | null;
+    readonly result: Record<string, unknown> | null;
+    readonly error: string | null;
+}
+/**
+ * Manages background execution of modules via Promises.
+ *
+ * Uses a simple counter-based concurrency limiter instead of a semaphore.
+ */
+export declare class AsyncTaskManager {
+    private readonly _executor;
+    private readonly _maxConcurrent;
+    private readonly _maxTasks;
+    private readonly _tasks;
+    private _runningCount;
+    private readonly _waitQueue;
+    constructor(executor: Executor, maxConcurrent?: number, maxTasks?: number);
+    /**
+     * Submit a module for background execution.
+     *
+     * Returns the generated task_id immediately.
+     */
+    submit(moduleId: string, inputs: Record<string, unknown>, context?: Context | null): string;
+    /**
+     * Return the TaskInfo for a task, or null if not found.
+     */
+    getStatus(taskId: string): TaskInfo | null;
+    /**
+     * Return the result of a completed task.
+     *
+     * Throws if the task is not found or not in COMPLETED status.
+     */
+    getResult(taskId: string): Record<string, unknown>;
+    /**
+     * Cancel a running or pending task.
+     *
+     * Sets the cancelled flag and updates status immediately.
+     * The underlying execution may still be in-flight but its result
+     * will be discarded when it completes.
+     *
+     * Returns true if the task was successfully marked as cancelled.
+     */
+    cancel(taskId: string): boolean;
+    /**
+     * Return all tasks, optionally filtered by status.
+     */
+    listTasks(status?: TaskStatus): TaskInfo[];
+    /**
+     * Remove terminal-state tasks older than maxAgeSeconds seconds.
+     *
+     * Terminal states: COMPLETED, FAILED, CANCELLED.
+     * Returns the number of tasks removed.
+     */
+    cleanup(maxAgeSeconds?: number): number;
+    /**
+     * Cancel all pending and running tasks.
+     */
+    shutdown(): void;
+    /**
+     * Acquire a concurrency slot. Resolves when a slot is available.
+     */
+    private _acquireSlot;
+    /**
+     * Release a concurrency slot and notify the next waiter.
+     */
+    private _releaseSlot;
+    /**
+     * Enqueue the task for execution under the concurrency limit.
+     */
+    private _enqueue;
+}
+//# sourceMappingURL=async-task.d.ts.map

package/dist/async-task.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"async-task.d.ts","sourceRoot":"","sources":["../src/async-task.ts"],"names":[],"mappings":"AAAA;;GAEG;AAGH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,oBAAY,UAAU;IACpB,OAAO,YAAY;IACnB,OAAO,YAAY;IACnB,SAAS,cAAc;IACvB,MAAM,WAAW;IACjB,SAAS,cAAc;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,WAAW,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,IAAI,CAAC;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;CAC/B;AAWD;;;;GAIG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAW;IACrC,OAAO,CAAC,QAAQ,CAAC,cAAc,CAAS;IACxC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAwC;IAC/D,OAAO,CAAC,aAAa,CAAa;IAClC,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyB;gBAExC,QAAQ,EAAE,QAAQ,EAAE,aAAa,GAAE,MAAW,EAAE,QAAQ,GAAE,MAAa;IAMnF;;;;OAIG;IACH,MAAM,CACJ,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC/B,OAAO,CAAC,EAAE,OAAO,GAAG,IAAI,GACvB,MAAM;IAiCT;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,GAAG,IAAI;IAK1C;;;;OAIG;IACH,SAAS,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC;IAWlD;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO;IAe/B;;OAEG;IACH,SAAS,CAAC,MAAM,CAAC,EAAE,UAAU,GAAG,QAAQ,EAAE;IAM1C;;;;;OAKG;IACH,OAAO,CAAC,aAAa,GAAE,MAAa,GAAG,MAAM;IAiB7C;;OAEG;IACH,QAAQ,IAAI,IAAI;IAQhB;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;OAEG;IACH,OAAO,CAAC,YAAY;IAQpB;;OAEG;IACH,OAAO,CAAC,QAAQ;CAgDjB"}