@qilin-agent/experimental-agent-team 0.0.0-stage → 3.1.4

package/lib/typert.remote-client.d.ts

@@ -0,0 +1,30 @@
+/* Generated by @qilin-agent/typert-generator from the Host FaceModel — do not edit. */
+import type {
+  RemoteResult,
+  TypertRemoteContribution,
+} from '@qilin-agent/typert-protocol'
+import type { TeamTaskView } from '@qilin-agent/experimental-agent-team/client'
+import type { CreateTeamTaskRequest, UpdateTeamTaskRequest } from '@qilin-agent/experimental-agent-team/types'
+import type { SessionId } from '@qilin-agent/session/types'
+
+declare module '@qilin-agent/typert-protocol' {
+  interface TypertRemoteNamespace$6167656e745465616d73 {
+    createTask: (agentId: SessionId, request: CreateTeamTaskRequest) => Promise<RemoteResult<TeamTaskView>>
+    updateTask: (agentId: SessionId, request: UpdateTeamTaskRequest) => Promise<RemoteResult<TeamTaskView>>
+  }
+  interface TypertRemoteMap {
+    'agentTeams/createTask': (agentId: SessionId, request: CreateTeamTaskRequest) => Promise<RemoteResult<TeamTaskView>>
+    'agentTeams/updateTask': (agentId: SessionId, request: UpdateTeamTaskRequest) => Promise<RemoteResult<TeamTaskView>>
+  }
+  interface TypertRemoteNamespaceMap {
+    'agentTeams': TypertRemoteNamespace$6167656e745465616d73
+  }
+  interface TypertRemoteScopeMap {
+    'agent:agentTeams/createTask': (request: CreateTeamTaskRequest) => Promise<RemoteResult<TeamTaskView>>
+    'agent:agentTeams/updateTask': (request: UpdateTeamTaskRequest) => Promise<RemoteResult<TeamTaskView>>
+  }
+}
+
+export declare const TYPERT_REMOTE: TypertRemoteContribution
+export default TYPERT_REMOTE
+//# sourceMappingURL=typert.remote-client.d.ts.map

package/lib/typert.remote-client.js

@@ -0,0 +1,141 @@
+/* Generated by @qilin-agent/typert-generator from the Host FaceModel — do not edit. */
+import { z } from 'zod'
+
+let _qilin_agent_experimental_agent_team_agentTeams_createTask_parameter_0$schema$value
+const _qilin_agent_experimental_agent_team_agentTeams_createTask_parameter_0$schema = () => (_qilin_agent_experimental_agent_team_agentTeams_createTask_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+let _qilin_agent_experimental_agent_team_agentTeams_createTask_parameter_1$schema$value
+const _qilin_agent_experimental_agent_team_agentTeams_createTask_parameter_1$schema = () => (_qilin_agent_experimental_agent_team_agentTeams_createTask_parameter_1$schema$value ??= z.object({
+  'subject': z.string().readonly(),
+  'description': z.string().readonly(),
+  'blockedBy': z.array(z.intersection(z.string(), z.unknown())).readonly().optional(),
+  'writeScopes': z.array(z.string()).readonly().optional(),
+}))
+let _qilin_agent_experimental_agent_team_agentTeams_createTask_result$schema$value
+const _qilin_agent_experimental_agent_team_agentTeams_createTask_result$schema = () => (_qilin_agent_experimental_agent_team_agentTeams_createTask_result$schema$value ??= z.object({
+  'id': z.intersection(z.string(), z.unknown()).readonly(),
+  'revision': z.number().readonly(),
+  'subject': z.string().readonly(),
+  'description': z.string().readonly(),
+  'status': z.union([z.literal("completed"), z.literal("pending"), z.literal("in_progress"), z.literal("deleted")]).readonly(),
+  'blockedBy': z.array(z.intersection(z.string(), z.unknown())).readonly(),
+  'writeScopes': z.array(z.string()).readonly(),
+  'ownerName': z.string().readonly().optional(),
+  'ready': z.boolean().readonly(),
+  'writeScopeWarnings': z.array(z.string()).readonly(),
+}))
+let _qilin_agent_experimental_agent_team_agentTeams_updateTask_parameter_0$schema$value
+const _qilin_agent_experimental_agent_team_agentTeams_updateTask_parameter_0$schema = () => (_qilin_agent_experimental_agent_team_agentTeams_updateTask_parameter_0$schema$value ??= z.intersection(z.string(), z.unknown()))
+let _qilin_agent_experimental_agent_team_agentTeams_updateTask_parameter_1$schema$value
+const _qilin_agent_experimental_agent_team_agentTeams_updateTask_parameter_1$schema = () => (_qilin_agent_experimental_agent_team_agentTeams_updateTask_parameter_1$schema$value ??= z.object({
+  'taskId': z.intersection(z.string(), z.unknown()).readonly(),
+  'expectedRevision': z.number().readonly(),
+  'action': z.union([z.literal("complete"), z.literal("edit"), z.literal("claim"), z.literal("release"), z.literal("set_dependencies"), z.literal("reopen"), z.literal("reassign"), z.literal("delete")]).readonly(),
+  'subject': z.string().readonly().optional(),
+  'description': z.string().readonly().optional(),
+  'blockedBy': z.array(z.intersection(z.string(), z.unknown())).readonly().optional(),
+  'writeScopes': z.array(z.string()).readonly().optional(),
+  'owner': z.string().readonly().optional(),
+}))
+let _qilin_agent_experimental_agent_team_agentTeams_updateTask_result$schema$value
+const _qilin_agent_experimental_agent_team_agentTeams_updateTask_result$schema = () => (_qilin_agent_experimental_agent_team_agentTeams_updateTask_result$schema$value ??= z.object({
+  'id': z.intersection(z.string(), z.unknown()).readonly(),
+  'revision': z.number().readonly(),
+  'subject': z.string().readonly(),
+  'description': z.string().readonly(),
+  'status': z.union([z.literal("completed"), z.literal("pending"), z.literal("in_progress"), z.literal("deleted")]).readonly(),
+  'blockedBy': z.array(z.intersection(z.string(), z.unknown())).readonly(),
+  'writeScopes': z.array(z.string()).readonly(),
+  'ownerName': z.string().readonly().optional(),
+  'ready': z.boolean().readonly(),
+  'writeScopeWarnings': z.array(z.string()).readonly(),
+}))
+
+export const TYPERT_REMOTE = {
+  package: '@qilin-agent/experimental-agent-team',
+  descriptors: [
+    {
+      id: '@qilin-agent/experimental-agent-team#agentTeams/createTask',
+      service: 'agentTeams',
+      namespace: 'agentTeams',
+      method: 'createTask',
+      implementation: 'remoteCreateTask',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qilin-agent/session/types#SessionId',
+            create: _qilin_agent_experimental_agent_team_agentTeams_createTask_parameter_0$schema,
+          },
+        },
+        {
+          name: 'request',
+          wire: 'request',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qilin-agent/experimental-agent-team/types#CreateTeamTaskRequest',
+            create: _qilin_agent_experimental_agent_team_agentTeams_createTask_parameter_1$schema,
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@qilin-agent/experimental-agent-team/client#TeamTaskView',
+        create: _qilin_agent_experimental_agent_team_agentTeams_createTask_result$schema,
+      },
+      sourceLocation: {"file":"packages/experimental/agent-team/src/index.ts","line":244,"column":9},
+    },
+    {
+      id: '@qilin-agent/experimental-agent-team#agentTeams/updateTask',
+      service: 'agentTeams',
+      namespace: 'agentTeams',
+      method: 'updateTask',
+      implementation: 'remoteUpdateTask',
+      invocation: { kind: 'direct' },
+      scope: {
+        context: 'agent',
+        wire: 'agentId',
+      },
+      parameters: [
+        {
+          name: 'agent',
+          wire: 'agentId',
+          source: 'lookup',
+          lookup: 'agent',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qilin-agent/session/types#SessionId',
+            create: _qilin_agent_experimental_agent_team_agentTeams_updateTask_parameter_0$schema,
+          },
+        },
+        {
+          name: 'request',
+          wire: 'request',
+          source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@qilin-agent/experimental-agent-team/types#UpdateTeamTaskRequest',
+            create: _qilin_agent_experimental_agent_team_agentTeams_updateTask_parameter_1$schema,
+          },
+        },
+      ],
+      result: {
+        mode: 'strict',
+        typeSymbol: '@qilin-agent/experimental-agent-team/client#TeamTaskView',
+        create: _qilin_agent_experimental_agent_team_agentTeams_updateTask_result$schema,
+      },
+      sourceLocation: {"file":"packages/experimental/agent-team/src/index.ts","line":264,"column":9},
+    },
+  ],
+}
+
+export default TYPERT_REMOTE

package/lib/types/activity.d.ts

@@ -0,0 +1,23 @@
+/** One-shot Team change waiters independent of durable state projection. */
+import type { TeamId, TeamWaitResult } from './types.ts';
+/** Owns current Team change waiters and releases each at most once. */
+export declare class TeamActivity {
+    private readonly waiters;
+    private closed;
+    /**
+     * Wait for one later Team-domain or member-status change.
+     * @param id - Team whose next edge wakes the caller.
+     * @param timeoutMs - bounded wait duration from ten seconds through one hour.
+     * @param signal - caller cancellation for this wait only.
+     * @returns whether the wait ended by timeout.
+     */
+    wait(id: TeamId, timeoutMs: number, signal: AbortSignal): Promise<TeamWaitResult>;
+    /**
+     * Wake and remove every current waiter for one Team.
+     * @param id - Team whose current waiters observe the change.
+     */
+    notify(id: TeamId): void;
+    /** Close admission and wake every current waiter during runtime disposal. */
+    close(): void;
+}
+//# sourceMappingURL=activity.d.ts.map

package/lib/types/activity.js

@@ -0,0 +1,85 @@
+/** One-shot Team change waiters independent of durable state projection. */
+import { errorMessage, TeamError } from "./error.js";
+/** Owns current Team change waiters and releases each at most once. */
+export class TeamActivity {
+    waiters = new Map();
+    closed = false;
+    /**
+     * Wait for one later Team-domain or member-status change.
+     * @param id - Team whose next edge wakes the caller.
+     * @param timeoutMs - bounded wait duration from ten seconds through one hour.
+     * @param signal - caller cancellation for this wait only.
+     * @returns whether the wait ended by timeout.
+     */
+    async wait(id, timeoutMs, signal) {
+        if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 10_000 || timeoutMs > 3_600_000) {
+            throw new TeamError('timeoutMs must be an integer from 10000 through 3600000', 'TEAM_INVALID_TIMEOUT');
+        }
+        signal.throwIfAborted();
+        if (this.closed)
+            return { timedOut: false };
+        const changed = await new Promise((resolve, reject) => {
+            let waiters = this.waiters.get(id);
+            if (waiters === undefined) {
+                waiters = new Set();
+                this.waiters.set(id, waiters);
+            }
+            let settled = false;
+            const finish = (settle) => {
+                /* v8 ignore next -- timeout, abort, and notification may race after one winner removes the others. */
+                if (settled)
+                    return;
+                settled = true;
+                clearTimeout(timer);
+                signal.removeEventListener('abort', onAbort);
+                waiters.delete(waiter);
+                if (waiters.size === 0)
+                    this.waiters.delete(id);
+                settle();
+            };
+            const onAbort = () => {
+                finish(() => {
+                    const reason = signal.reason;
+                    reject(reason instanceof Error
+                        ? reason
+                        : new TeamError(`wait_agent aborted: ${errorMessage(reason)}`, 'TEAM_WAIT_ABORTED'));
+                });
+            };
+            const waiter = {
+                resolve: () => {
+                    finish(() => { resolve(true); });
+                },
+            };
+            waiters.add(waiter);
+            const timer = setTimeout(() => { finish(() => { resolve(false); }); }, timeoutMs);
+            signal.addEventListener('abort', onAbort, { once: true });
+            // AbortSignal does not replay an abort that wins between the pre-check and listener registration.
+            /* v8 ignore next -- requires an abort in the synchronous gap between the pre-check and listener registration. */
+            if (signal.aborted)
+                onAbort();
+        });
+        return { timedOut: !changed };
+    }
+    /**
+     * Wake and remove every current waiter for one Team.
+     * @param id - Team whose current waiters observe the change.
+     */
+    notify(id) {
+        const waiters = this.waiters.get(id);
+        if (waiters === undefined)
+            return;
+        this.waiters.delete(id);
+        for (const waiter of waiters)
+            waiter.resolve();
+    }
+    /** Close admission and wake every current waiter during runtime disposal. */
+    close() {
+        this.closed = true;
+        for (const waiters of this.waiters.values()) {
+            for (const waiter of waiters)
+                waiter.resolve();
+        }
+        this.waiters.clear();
+    }
+}
+//# sourceMappingURL=activity.js.map

package/lib/types/client.d.ts

@@ -0,0 +1,8 @@
+/** Client-safe Agent Teams roster and task views plus the `agentTeam` projection vocabulary. */
+/**
+ * Pull the write face's wire failure codes into every client program, so the
+ * `agentTeams` namespace's `RemoteFailure` union names the Team domain codes.
+ */
+export type { TeamRejectedFailureDetails } from './remote.ts';
+export type { TeamMemberPhase, TeamMemberProjection, TeamMemberView, TeamProjection, TeamTaskId, TeamTaskStatus, TeamTaskView, } from './types.ts';
+//# sourceMappingURL=client.d.ts.map

package/lib/types/client.js

@@ -0,0 +1,3 @@
+/** Client-safe Agent Teams roster and task views plus the `agentTeam` projection vocabulary. */
+export {};
+//# sourceMappingURL=client.js.map

package/lib/types/error.d.ts

@@ -0,0 +1,13 @@
+/** Typed Agent Teams failures. */
+import { HarnessError } from '@qilin-agent/llm';
+/** Stable failure raised by the Team domain. */
+export declare class TeamError extends HarnessError {
+    constructor(message: string, code: string, options?: ErrorOptions);
+}
+/**
+ * Render an arbitrary thrown value without replacing the original rejection.
+ * @param error - caught value used in a diagnostic or durable failure record.
+ * @returns one bounded single-line description.
+ */
+export declare function errorMessage(error: unknown): string;
+//# sourceMappingURL=error.d.ts.map

package/lib/types/error.js

@@ -0,0 +1,23 @@
+/** Typed Agent Teams failures. */
+import { inspect } from 'node:util';
+import { HarnessError } from '@qilin-agent/llm';
+/** Stable failure raised by the Team domain. */
+export class TeamError extends HarnessError {
+    constructor(message, code, options) {
+        super(message, code, options);
+        this.name = 'TeamError';
+    }
+}
+/**
+ * Render an arbitrary thrown value without replacing the original rejection.
+ * @param error - caught value used in a diagnostic or durable failure record.
+ * @returns one bounded single-line description.
+ */
+export function errorMessage(error) {
+    if (error instanceof Error)
+        return error.message;
+    if (typeof error === 'string')
+        return error;
+    return inspect(error, { breakLength: Infinity, compact: true, depth: 4 });
+}
+//# sourceMappingURL=error.js.map

package/lib/types/index.d.ts

@@ -0,0 +1,148 @@
+/** Agent Teams service façade over roster, messaging, task, and runtime lifecycle owners. */
+import { Context } from '@qilin-agent/kylin';
+import z from '@qilin-agent/schemastery';
+import type { Agent } from '@qilin-agent/agent';
+import { TypertRemoteService } from '@qilin-agent/typert-protocol';
+import type { TeamMembership } from './roster.ts';
+import { TeamTaskId } from './types.ts';
+import type { Config, CreateTeamTaskRequest, SendTeamMessageRequest, SendTeamMessageResult, SpawnTeammateRequest, SpawnTeammateResult, TeamMemberView, TeamTaskView, TeamWaitResult, UpdateTeamTaskRequest } from './types.ts';
+export type * from './types.ts';
+export type { TeamMembership } from './roster.ts';
+export { TeamId, TeamMessageId, TeamTaskId } from './types.ts';
+export { TeamError } from './error.ts';
+declare module '@qilin-agent/kylin' {
+    interface Context {
+        agentTeams: TeamService;
+    }
+}
+/**
+ * Agent Teams service backed by the exact live Lead Session log. `createTask`
+ * and `updateTask` also carry the browser write bridge through the `agentTeams`
+ * Typert Remote namespace; the wire faces map domain failures onto the shared
+ * Remote failure vocabulary without changing the domain methods' contracts.
+ */
+export declare class TeamService extends TypertRemoteService {
+    static inject: string[];
+    static Config: z<Config>;
+    /** Validated deployment limits used by every Team operation. */
+    private readonly config;
+    private readonly activity;
+    private readonly lifecycle;
+    private readonly journal;
+    private readonly roster;
+    private readonly tasks;
+    constructor(ctx: Context, config?: Config);
+    /**
+     * Resolve one exact live Agent's Team role.
+     * @param agent - exact live Agent used as the authority credential.
+     * @returns its root, Team identity, role, and model-facing name.
+     */
+    membership(agent: Agent): TeamMembership;
+    /**
+     * List the runtime-enriched roster visible to one Team member.
+     * @param agent - exact live Team member.
+     * @returns Lead and teammate rows in creation order.
+     */
+    listMembers(agent: Agent): TeamMemberView[];
+    /**
+     * Create one named, continuable direct child of the Team Lead.
+     * @param caller - exact live Lead Agent.
+     * @param request - immutable name, description, prompt, context mode, provider, and cancellation.
+     * @returns the active roster row.
+     */
+    spawnTeammate(caller: Agent, request: SpawnTeammateRequest): Promise<SpawnTeammateResult>;
+    /**
+     * Steer one peer message into the target inbox or reject the attempt.
+     * @param caller - exact live sending Team member.
+     * @param request - target name, content, and cancellation before acceptance.
+     * @returns accepted inbox identity; acceptance follows normal Agent persistence and does not await model processing.
+     */
+    sendMessage(caller: Agent, request: SendTeamMessageRequest): Promise<SendTeamMessageResult>;
+    /**
+     * Admit one peer message and steer it into the target's inbox.
+     * @param caller - exact live sending Team member.
+     * @param request - target name, content, and signal already joined with runtime cancellation.
+     * @returns the durable message identity carried by the delivered source.
+     */
+    private sendAdmitted;
+    /**
+     * Create one unowned pending task in the Team Lead log.
+     * @param caller - exact live Team member creating the task.
+     * @param request - task text, blockers, and advisory write scopes.
+     * @returns the revision-one task view.
+     */
+    createTask(caller: Agent, request: CreateTeamTaskRequest): Promise<TeamTaskView>;
+    /**
+     * Return one task, including a deleted tombstone.
+     * @param caller - exact live Team member reading the task.
+     * @param id - Team-local task identity.
+     * @returns the latest task value and derived readiness diagnostics.
+     */
+    getTask(caller: Agent, id: TeamTaskId): TeamTaskView;
+    /**
+     * List current non-deleted tasks in numeric creation order.
+     * @param caller - exact live Team member reading the board.
+     * @returns detached current task views.
+     */
+    listTasks(caller: Agent): TeamTaskView[];
+    /**
+     * Compare-and-set one authorized task transition.
+     * @param caller - exact live Team member authorizing the mutation.
+     * @param request - task identity, expected revision, action, and action fields.
+     * @returns the committed next task revision.
+     */
+    updateTask(caller: Agent, request: UpdateTeamTaskRequest): Promise<TeamTaskView>;
+    /**
+     * Wire face of {@link TeamService.createTask}: create one shared task on a
+     * person's behalf through the browser write bridge.
+     * @param agent - exact live Team member resolved from the wire identity.
+     * @param request - subject, description, optional blockers, and optional write scopes.
+     * @returns the revision-one task view.
+     * @throws {RemoteError} `agent-team/not-a-member` when the identity is not a Team member, and
+     *   `agent-team/rejected` when the domain refuses the request.
+     */
+    remoteCreateTask(agent: Agent, request: CreateTeamTaskRequest): Promise<TeamTaskView>;
+    /**
+     * Wire face of {@link TeamService.updateTask}: commit one compare-and-set
+     * task transition on a person's behalf. A committed mutation is durable and
+     * never undone by a later wire cancellation.
+     * @param agent - exact live Team member resolved from the wire identity.
+     * @param request - task identity, expected revision, action, and action fields.
+     * @returns the committed next task view.
+     * @throws {RemoteError} `agent-team/not-a-member` when the identity is not a Team member,
+     *   `agent-team/stale-revision` when the expected revision no longer matches, and
+     *   `agent-team/rejected` when the domain refuses the transition.
+     */
+    remoteUpdateTask(agent: Agent, request: UpdateTeamTaskRequest): Promise<TeamTaskView>;
+    /**
+     * Wait for the next Team-domain or member-status change.
+     * @param caller - exact live Team member waiting for activity.
+     * @param timeoutMs - bounded wait duration from ten seconds through one hour.
+     * @param signal - caller cancellation for the wait only.
+     * @returns one observed change or a timeout result.
+     */
+    waitForChange(caller: Agent, timeoutMs: number, signal: AbortSignal): Promise<TeamWaitResult>;
+    /**
+     * Interrupt one live teammate turn without clearing its pending inbox.
+     * @param caller - exact live Lead Agent.
+     * @param targetName - durable teammate name.
+     * @returns the target status sampled before cancellation.
+     */
+    interrupt(caller: Agent, targetName: string): {
+        previousStatus: 'running' | 'inactive';
+    };
+    /**
+     * Resolve a caller without throwing, used by scoped-tool installation and observers.
+     * @param agent - candidate exact live Agent.
+     * @returns Team membership, or undefined for non-Team subagents and stale identities.
+     */
+    tryMembership(agent: Agent): TeamMembership | undefined;
+    /** Queue one contained recovery pass after publication has unwound. */
+    private scheduleRecovery;
+    /** Reconcile roster provisioning when one Team member Session starts. */
+    private recoverFor;
+    /** Stop Team-owned live branches and release every waiter before service disposal completes. */
+    private disposeRuntime;
+}
+export default TeamService;
+//# sourceMappingURL=index.d.ts.map