taskcheck 1.5.1__tar.gz → 1.6.0__tar.gz

{taskcheck-1.5.1/taskcheck.egg-info → taskcheck-1.6.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskcheck
-Version: 1.5.1
+Version: 1.6.0
 Summary: Automatic scheduler for taskwarrior
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -13,8 +13,6 @@ Requires-Dist: random-unicode-emoji>=2.8
 Requires-Dist: requests>=2.32.3
 Requires-Dist: rich>=13.9.4
 
-![immagine](https://github.com/user-attachments/assets/27b83bb1-7a50-4923-a453-0a958fbe11ed)
-
 A Taskwarrior scheduler for people who want a realistic plan, not a manual to-do list.
 It turns tasks, working hours, and calendar blocks into an actionable schedule — then keeps due dates visible.
 
@@ -23,6 +21,7 @@ Use it if you want to:
 - fit tasks into real availability
 - be sure your long-time plan won't go overdue
 - keep Taskwarrior as the source of truth
+- handle your time across multiple tasks carried on by LLMs
 
 > [!IMPORTANT]
 > This repo is actively maintained again
@@ -30,7 +29,7 @@ Use it if you want to:
 ## Features
 
 - ✨ Auto-schedule tasks from working hours + calendar blocks
-- 🧭 Support complex working-hour maps
+- 🧠 Schedule agent-assisted tasks alongside your own, based on how much supervision they need
 - ⏱️ Consider urgency, due dates, and dependencies
 - 🧪 Persisted dry-run previews for reports and timelines
 - ↩️ Undo the latest schedule update
@@ -41,19 +40,16 @@ Use it if you want to:
 - 🎨 Report styling with emoji and extra attributes
 - 🗓️ Block time with iCal or Google Calendar, including all-day events
 
-## Quick start
+![Dry-run schedule and report](docs/images/dry-run-report.png)
 
-1. `pipx install taskcheck`
-2. `taskcheck --install` ← setup only
-3. add `estimated` + `time_map` UDAs
-4. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
-5. `taskcheck --schedule`
-6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+![Daily timeline](docs/images/timeline-day.png)
 
 ## How it works
 
-Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes back a schedule.
-It respects:
+Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes
+back a schedule. For tasks tagged `+agent`, it treats `estimated` as the agent's work time and
+`agent_weight` as the percentage of that time needing your attention. It respects:
+
 - your working hours
 - task duration estimates
 - calendar events and vacations from iCal / Google Calendar
@@ -64,10 +60,21 @@ It updates Taskwarrior with:
 - `completion_date` → when work is expected to finish
 - a warning when a task will miss its due date
 
+## Quick start
+
+1. `pipx install taskcheck`
+2. `taskcheck --install` ← setup only: registers required Taskwarrior settings  inyour taskwarrior config file and offers to create the
+   config file; it does not schedule tasks.
+3. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
+4. tune your tasks: add `estimated`, `time_map`, `agent_weight` UDAs and the `+agent` tag (`time_map` and `agent_weight` may use the default value defined in the Taskwarrior settings)
+5. `taskcheck --schedule`
+6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+
 ### Required UDAs
 
 - `estimated`: expected duration in hours
 - `time_map`: which working-hour profile applies to the task, for example `work` or `weekend`
+- `agent_weight`: required for `+agent` tasks; the percentage (0–100) of agent work time that needs your attention. It defaults to 25 when using `taskcheck --install`.
 
 Example:
 
@@ -77,6 +84,20 @@ monday = [[9, 12.30], [14, 17]]
 tuesday = [[9, 12.30], [14, 17]]
 ```
 
+### Agent tasks and mixed blocks
+
+Mark a task `+agent` when a computer helper will do the work, and set `agent_weight` to show what
+percentage of its work time needs your attention. For example, `10` means you spend about 10 minutes
+interacting with the agent for each hour the agent works. Taskcheck can plan several agent jobs at
+once, fill the time left with your own tasks, and respect waiting dates and dependencies.
+
+```bash
+task add "Implement API" +agent estimated:5h agent_weight:10
+task add "Review results" estimated:1h
+```
+
+Run `taskcheck --install` to register the `agent_weight` Taskwarrior UDA.
+
 ### Reports and timelines
 
 - `taskcheck -r today` → tasks planned for today
@@ -84,9 +105,15 @@ tuesday = [[9, 12.30], [14, 17]]
 - `taskcheck --timeline 1w` → automatic day/week/month timeline for the next week
 - `taskcheck --timeline eom --zoom week` → weekly timeline through month end
 
-Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report today --dry-run` or `taskcheck --timeline 1w --dry-run`.
+Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it
+saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report
+today --dry-run` or `taskcheck --timeline 1w --dry-run`.
 
-Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most detailed view that fits the terminal width is selected: day, then week, then month. The track uses `▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules separate days, weeks, and months. Project colors are deterministic and adapt to light or dark terminals through OSC 11, with config and environment fallbacks.
+Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most
+detailed view that fits the terminal width is selected: day, then week, then month. The track uses
+`▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules
+separate days, weeks, and months. Project colors are deterministic and adapt to light or dark
+terminals through OSC 11, with config and environment fallbacks.
 
 ## Reference
 

{taskcheck-1.5.1 → taskcheck-1.6.0}/README.md

@@ -1,5 +1,3 @@
-![immagine](https://github.com/user-attachments/assets/27b83bb1-7a50-4923-a453-0a958fbe11ed)
-
 A Taskwarrior scheduler for people who want a realistic plan, not a manual to-do list.
 It turns tasks, working hours, and calendar blocks into an actionable schedule — then keeps due dates visible.
 
@@ -8,6 +6,7 @@ Use it if you want to:
 - fit tasks into real availability
 - be sure your long-time plan won't go overdue
 - keep Taskwarrior as the source of truth
+- handle your time across multiple tasks carried on by LLMs
 
 > [!IMPORTANT]
 > This repo is actively maintained again
@@ -15,7 +14,7 @@ Use it if you want to:
 ## Features
 
 - ✨ Auto-schedule tasks from working hours + calendar blocks
-- 🧭 Support complex working-hour maps
+- 🧠 Schedule agent-assisted tasks alongside your own, based on how much supervision they need
 - ⏱️ Consider urgency, due dates, and dependencies
 - 🧪 Persisted dry-run previews for reports and timelines
 - ↩️ Undo the latest schedule update
@@ -26,19 +25,16 @@ Use it if you want to:
 - 🎨 Report styling with emoji and extra attributes
 - 🗓️ Block time with iCal or Google Calendar, including all-day events
 
-## Quick start
+![Dry-run schedule and report](docs/images/dry-run-report.png)
 
-1. `pipx install taskcheck`
-2. `taskcheck --install` ← setup only
-3. add `estimated` + `time_map` UDAs
-4. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
-5. `taskcheck --schedule`
-6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+![Daily timeline](docs/images/timeline-day.png)
 
 ## How it works
 
-Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes back a schedule.
-It respects:
+Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes
+back a schedule. For tasks tagged `+agent`, it treats `estimated` as the agent's work time and
+`agent_weight` as the percentage of that time needing your attention. It respects:
+
 - your working hours
 - task duration estimates
 - calendar events and vacations from iCal / Google Calendar
@@ -49,10 +45,21 @@ It updates Taskwarrior with:
 - `completion_date` → when work is expected to finish
 - a warning when a task will miss its due date
 
+## Quick start
+
+1. `pipx install taskcheck`
+2. `taskcheck --install` ← setup only: registers required Taskwarrior settings  inyour taskwarrior config file and offers to create the
+   config file; it does not schedule tasks.
+3. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
+4. tune your tasks: add `estimated`, `time_map`, `agent_weight` UDAs and the `+agent` tag (`time_map` and `agent_weight` may use the default value defined in the Taskwarrior settings)
+5. `taskcheck --schedule`
+6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+
 ### Required UDAs
 
 - `estimated`: expected duration in hours
 - `time_map`: which working-hour profile applies to the task, for example `work` or `weekend`
+- `agent_weight`: required for `+agent` tasks; the percentage (0–100) of agent work time that needs your attention. It defaults to 25 when using `taskcheck --install`.
 
 Example:
 
@@ -62,6 +69,20 @@ monday = [[9, 12.30], [14, 17]]
 tuesday = [[9, 12.30], [14, 17]]
 ```
 
+### Agent tasks and mixed blocks
+
+Mark a task `+agent` when a computer helper will do the work, and set `agent_weight` to show what
+percentage of its work time needs your attention. For example, `10` means you spend about 10 minutes
+interacting with the agent for each hour the agent works. Taskcheck can plan several agent jobs at
+once, fill the time left with your own tasks, and respect waiting dates and dependencies.
+
+```bash
+task add "Implement API" +agent estimated:5h agent_weight:10
+task add "Review results" estimated:1h
+```
+
+Run `taskcheck --install` to register the `agent_weight` Taskwarrior UDA.
+
 ### Reports and timelines
 
 - `taskcheck -r today` → tasks planned for today
@@ -69,9 +90,15 @@ tuesday = [[9, 12.30], [14, 17]]
 - `taskcheck --timeline 1w` → automatic day/week/month timeline for the next week
 - `taskcheck --timeline eom --zoom week` → weekly timeline through month end
 
-Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report today --dry-run` or `taskcheck --timeline 1w --dry-run`.
+Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it
+saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report
+today --dry-run` or `taskcheck --timeline 1w --dry-run`.
 
-Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most detailed view that fits the terminal width is selected: day, then week, then month. The track uses `▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules separate days, weeks, and months. Project colors are deterministic and adapt to light or dark terminals through OSC 11, with config and environment fallbacks.
+Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most
+detailed view that fits the terminal width is selected: day, then week, then month. The track uses
+`▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules
+separate days, weeks, and months. Project colors are deterministic and adapt to light or dark
+terminals through OSC 11, with config and environment fallbacks.
 
 ## Reference
 

{taskcheck-1.5.1 → taskcheck-1.6.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "taskcheck"
-version = "1.5.1"
+version = "1.6.0"
 description = "Automatic scheduler for taskwarrior"
 readme = "README.md"
 requires-python = ">=3.11"

{taskcheck-1.5.1 → taskcheck-1.6.0}/taskcheck/__main__.py

@@ -63,6 +63,7 @@ arg_parser.add_argument(
     help="Weight for urgency in scheduling (0.0 to 1.0), overrides config value. When 1.0, the whole Taskwarrior urgency is used for scheduling. When 0.0, the Taskwarrior urgency is reduced to only due urgency.",
 )
 arg_parser.add_argument(
+    "-d",
     "--dry-run",
     action="store_true",
     help="Perform scheduling without modifying the Taskwarrior database, useful for testing.",

taskcheck-1.6.0/taskcheck/agent_blocks.py

@@ -0,0 +1,160 @@
+"""Plan mixed agent/human work inside an ordinary Taskcheck block.
+
+All durations are hours. Agent estimates describe elapsed execution time while
+agent_weight is the percentage of that time needing human interaction. A block
+consumes its full elapsed duration from the calendar, not the sum of the task
+estimates. Internal allocations never create scheduling sub-blocks.
+"""
+
+from datetime import datetime
+from math import isfinite
+
+from taskcheck.common import hours_to_decimal
+
+_EPSILON = 1e-9
+
+
+def get_agent_weight(task):
+    """Return human-interaction fraction for +agent tasks, else None.
+
+    A tagged task must specify a percentage from 0 to 100. In particular,
+    missing weights must not silently imply free, infinite parallelism.
+    """
+    if "agent" not in (task.get("tags") or []):
+        return None
+    try:
+        weight = float(task["agent_weight"])
+    except (KeyError, TypeError, ValueError) as exc:
+        raise ValueError(
+            f"Task {task.get('id', task.get('uuid'))}: +agent requires a numeric agent_weight"
+        ) from exc
+    if not isfinite(weight) or not 0 <= weight <= 100:
+        raise ValueError(
+            f"Task {task.get('id', task.get('uuid'))}: agent_weight must be between 0 and 100"
+        )
+    return weight / 100
+
+
+def _eligible(info, pending, date):
+    if any(dep in pending for dep in info["task"].get("depends", [])):
+        return False
+    wait = info["task"].get("wait")
+    if wait and date <= datetime.strptime(wait, "%Y%m%dT%H%M%SZ").date():
+        return False
+    return True
+
+
+def _max_allocation(info, day_offset, block_hours):
+    return min(
+        float(info["remaining_hours"]),
+        float(info["task_time_map"][day_offset]),
+        block_hours,
+    )
+
+
+def allocate_agent_block(
+    tasks_remaining, sorted_task_ids, day_offset, day_remaining_hours, date, anchor_uuid
+):
+    """Allocate one block anchored by an eligible agent task.
+
+    Returns (elapsed_hours, {uuid: allocated_task_hours}), and mutates the
+    selected task states in-place. None of the individual allocations is a
+    calendar sub-block. All agents run within the same elapsed block; human
+    work consumes interaction time left unused by the agents.
+
+    Tasks which depend on anything pending *at block start* cannot join this
+    same block, even if that prerequisite finishes within it.
+    """
+    anchor = tasks_remaining[anchor_uuid]
+    if get_agent_weight(anchor["task"]) is None:
+        return 0, {}
+    pending = set(tasks_remaining)
+    if not _eligible(anchor, pending, date):
+        return 0, {}
+    block_hours = min(
+        day_remaining_hours,
+        hours_to_decimal(float(anchor["task"].get("min_block", 2))),
+    )
+    if block_hours <= _EPSILON:
+        return 0, {}
+
+    allocations = {}
+    human_budget = block_hours
+    agent_order = [anchor_uuid] + [uuid for uuid in sorted_task_ids if uuid != anchor_uuid]
+    for uuid in agent_order:
+        info = tasks_remaining.get(uuid)
+        if info is None:
+            continue
+        weight = get_agent_weight(info["task"])
+        if weight is None or not _eligible(info, pending, date):
+            continue
+        agent_cap = min(
+            block_hours,
+            hours_to_decimal(float(info["task"].get("min_block", 2))),
+        )
+        duration = _max_allocation(info, day_offset, agent_cap)
+        if weight > 0:
+            duration = min(duration, max(human_budget, 0) / weight)
+        if duration <= _EPSILON:
+            continue
+        allocations[uuid] = duration
+        human_budget = max(0, human_budget - weight * duration)
+
+    # The anchor must have actual execution time; a zero-length block is invalid.
+    if anchor_uuid not in allocations:
+        return 0, {}
+
+    for uuid in sorted_task_ids:
+        info = tasks_remaining.get(uuid)
+        if info is None or get_agent_weight(info["task"]) is not None:
+            continue
+        if not _eligible(info, pending, date):
+            continue
+        # Deliberately allow sub-min_block *allocations*, but only in a mixed
+        # block. Standalone human scheduling stays in the legacy path.
+        # Honor task-specific chunk caps while allowing allocations *smaller*
+        # than that cap only within this mixed block.
+        human_cap = min(
+            human_budget, hours_to_decimal(float(info["task"].get("min_block", 2)))
+        )
+        duration = _max_allocation(info, day_offset, human_cap)
+        if duration <= _EPSILON:
+            continue
+        allocations[uuid] = duration
+        human_budget = max(0, human_budget - duration)
+        if human_budget <= _EPSILON:
+            break
+
+    # Charge only elapsed calendar time actually needed. Otherwise a short
+    # agent finishing alone would artificially consume a whole min_block.
+    # Interaction and human work must fit inside this elapsed interval, while
+    # all agent executions may overlap.
+    interaction_hours = sum(
+        duration * get_agent_weight(tasks_remaining[uuid]["task"])
+        if get_agent_weight(tasks_remaining[uuid]["task"]) is not None
+        else duration
+        for uuid, duration in allocations.items()
+    )
+    elapsed_hours = max(
+        interaction_hours,
+        *(
+            duration
+            for uuid, duration in allocations.items()
+            if get_agent_weight(tasks_remaining[uuid]["task"]) is not None
+        ),
+    )
+
+    date_str = date.isoformat()
+    for uuid, duration in allocations.items():
+        info = tasks_remaining[uuid]
+        if not info["scheduling"]:
+            info["started"] = True
+        info["remaining_hours"] = max(0, info["remaining_hours"] - duration)
+        # Cached time-map lists may be shared by different tasks; the mutable
+        # per-task remaining availability must not alias another task.
+        info["task_time_map"] = list(info["task_time_map"])
+        info["task_time_map"][day_offset] = max(
+            0, info["task_time_map"][day_offset] - duration
+        )
+        info["scheduling"][date_str] = info["scheduling"].get(date_str, 0) + duration
+    return elapsed_hours, allocations

{taskcheck-1.5.1 → taskcheck-1.6.0}/taskcheck/common.py

@@ -148,7 +148,25 @@ def hours_to_pdth(hours):
 def get_long_range_time_map(
     time_maps, time_map_names, days_ahead, calendars, verbose=False
 ):
-    key = ",".join(time_map_names)
+    # The cache must distinguish both the horizon and the input configuration.
+    # Otherwise a previous schedule (possibly with a different time map or
+    # calendar) can silently give tasks stale daily availability.
+    key = (
+        tuple(time_map_names),
+        days_ahead,
+        datetime.today().date(),
+        json.dumps(
+            {name: time_maps[name] for name in time_map_names},
+            sort_keys=True,
+            default=str,
+        ),
+        json.dumps(
+            calendars,
+            sort_keys=True,
+            default=lambda value: value.isoformat()
+            if hasattr(value, "isoformat") else str(value),
+        ),
+    )
     if key in long_range_time_map:
         task_time_map = long_range_time_map[key]
     else:

{taskcheck-1.5.1 → taskcheck-1.6.0}/taskcheck/install.py

@@ -63,6 +63,9 @@ def install():
         ("uda.min_block.type", "numeric"),
         ("uda.min_block.label", "Minimum Time Block"),
         ("uda.min_block.default", "2"),
+        ("uda.agent_weight.type", "numeric"),
+        ("uda.agent_weight.label", "Agent Weight (%)"),
+        ("uda.agent_weight.default", "25"),
         ("recurrence.confirmation", "no"),
     ]
 
@@ -120,7 +123,7 @@ def install():
         """
 _________________________________________________________________________________________
 Required configuration for taskcheck includes:
-- 3 UDA fields 
+- Taskwarrior UDAs, including `agent_weight` for +agent tasks
 - turning off confirmation for recurring tasks 
 
 Do you want to continue? [y/N] """

{taskcheck-1.5.1 → taskcheck-1.6.0}/taskcheck/parallel.py

@@ -6,6 +6,8 @@ from datetime import datetime, timedelta
 
 from rich.table import Table
 
+from taskcheck.agent_blocks import allocate_agent_block, get_agent_weight
+
 from taskcheck.undo import create_undo_backup
 from taskcheck.common import (
     AVOID_STATUS,
@@ -330,11 +332,14 @@ def initialize_task_info(tasks, time_maps, days_ahead, urgency_coefficients, cal
             continue
         if "estimated" not in task or "time_map" not in task:
             continue
+        get_agent_weight(task)  # Validate +agent tasks before scheduling.
         estimated_hours = pdth_to_hours(task["estimated"])
         time_map_names = task["time_map"].split(",")
         task_time_map, today_used_hours = get_long_range_time_map(
             time_maps, time_map_names, days_ahead, calendars
         )
+        # The cache returns a shared list.  Mutations must be task-local.
+        task_time_map = list(task_time_map)
         task_uuid = task["uuid"]
         initial_urgency = float(task.get("urgency", 0))
         estimated_urgency = urgency_estimated(
@@ -415,6 +420,25 @@ def allocate_time_for_day(
                 if verbose:
                     print(f"Skipping task {info['task']['id']} due to wait date {wait}")
                 continue
+            if get_agent_weight(info["task"]) is not None:
+                # Agent tasks overlap in elapsed time.  Charge interactions and
+                # human work to the same block's human-time budget.
+                elapsed, allocations = allocate_agent_block(
+                    tasks_remaining, sorted_task_ids, day_offset,
+                    day_remaining_hours, date, uuid,
+                )
+                if elapsed > 0:
+                    day_remaining_hours -= elapsed
+                    allocated = True
+                    if verbose:
+                        print(f"Allocated mixed block ({elapsed:.2f}h): {allocations}")
+                    for allocated_uuid in allocations:
+                        allocated_info = tasks_remaining[allocated_uuid]
+                        if (allocated_info["remaining_hours"] <= 0
+                            or allocated_info["task_time_map"][day_offset] <= 0):
+                            del tasks_remaining[allocated_uuid]
+                    break
+                continue
             allocation = allocate_time_to_task(info, day_offset, day_remaining_hours)
             if allocation > 0:
                 day_remaining_hours -= allocation

{taskcheck-1.5.1 → taskcheck-1.6.0/taskcheck.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: taskcheck
-Version: 1.5.1
+Version: 1.6.0
 Summary: Automatic scheduler for taskwarrior
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
@@ -13,8 +13,6 @@ Requires-Dist: random-unicode-emoji>=2.8
 Requires-Dist: requests>=2.32.3
 Requires-Dist: rich>=13.9.4
 
-![immagine](https://github.com/user-attachments/assets/27b83bb1-7a50-4923-a453-0a958fbe11ed)
-
 A Taskwarrior scheduler for people who want a realistic plan, not a manual to-do list.
 It turns tasks, working hours, and calendar blocks into an actionable schedule — then keeps due dates visible.
 
@@ -23,6 +21,7 @@ Use it if you want to:
 - fit tasks into real availability
 - be sure your long-time plan won't go overdue
 - keep Taskwarrior as the source of truth
+- handle your time across multiple tasks carried on by LLMs
 
 > [!IMPORTANT]
 > This repo is actively maintained again
@@ -30,7 +29,7 @@ Use it if you want to:
 ## Features
 
 - ✨ Auto-schedule tasks from working hours + calendar blocks
-- 🧭 Support complex working-hour maps
+- 🧠 Schedule agent-assisted tasks alongside your own, based on how much supervision they need
 - ⏱️ Consider urgency, due dates, and dependencies
 - 🧪 Persisted dry-run previews for reports and timelines
 - ↩️ Undo the latest schedule update
@@ -41,19 +40,16 @@ Use it if you want to:
 - 🎨 Report styling with emoji and extra attributes
 - 🗓️ Block time with iCal or Google Calendar, including all-day events
 
-## Quick start
+![Dry-run schedule and report](docs/images/dry-run-report.png)
 
-1. `pipx install taskcheck`
-2. `taskcheck --install` ← setup only
-3. add `estimated` + `time_map` UDAs
-4. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
-5. `taskcheck --schedule`
-6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+![Daily timeline](docs/images/timeline-day.png)
 
 ## How it works
 
-Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes back a schedule.
-It respects:
+Taskcheck reads your pending and waiting tasks, estimates when each one can be worked on, and writes
+back a schedule. For tasks tagged `+agent`, it treats `estimated` as the agent's work time and
+`agent_weight` as the percentage of that time needing your attention. It respects:
+
 - your working hours
 - task duration estimates
 - calendar events and vacations from iCal / Google Calendar
@@ -64,10 +60,21 @@ It updates Taskwarrior with:
 - `completion_date` → when work is expected to finish
 - a warning when a task will miss its due date
 
+## Quick start
+
+1. `pipx install taskcheck`
+2. `taskcheck --install` ← setup only: registers required Taskwarrior settings  inyour taskwarrior config file and offers to create the
+   config file; it does not schedule tasks.
+3. edit `~/.config/task/taskcheck.toml` (see [Reference](#Reference))
+4. tune your tasks: add `estimated`, `time_map`, `agent_weight` UDAs and the `+agent` tag (`time_map` and `agent_weight` may use the default value defined in the Taskwarrior settings)
+5. `taskcheck --schedule`
+6. `taskcheck --undo` restores the scheduling fields changed by the latest run
+
 ### Required UDAs
 
 - `estimated`: expected duration in hours
 - `time_map`: which working-hour profile applies to the task, for example `work` or `weekend`
+- `agent_weight`: required for `+agent` tasks; the percentage (0–100) of agent work time that needs your attention. It defaults to 25 when using `taskcheck --install`.
 
 Example:
 
@@ -77,6 +84,20 @@ monday = [[9, 12.30], [14, 17]]
 tuesday = [[9, 12.30], [14, 17]]
 ```
 
+### Agent tasks and mixed blocks
+
+Mark a task `+agent` when a computer helper will do the work, and set `agent_weight` to show what
+percentage of its work time needs your attention. For example, `10` means you spend about 10 minutes
+interacting with the agent for each hour the agent works. Taskcheck can plan several agent jobs at
+once, fill the time left with your own tasks, and respect waiting dates and dependencies.
+
+```bash
+task add "Implement API" +agent estimated:5h agent_weight:10
+task add "Review results" estimated:1h
+```
+
+Run `taskcheck --install` to register the `agent_weight` Taskwarrior UDA.
+
 ### Reports and timelines
 
 - `taskcheck -r today` → tasks planned for today
@@ -84,9 +105,15 @@ tuesday = [[9, 12.30], [14, 17]]
 - `taskcheck --timeline 1w` → automatic day/week/month timeline for the next week
 - `taskcheck --timeline eom --zoom week` → weekly timeline through month end
 
-Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report today --dry-run` or `taskcheck --timeline 1w --dry-run`.
+Create a preview with `taskcheck --schedule --dry-run`. It does not update Taskwarrior; instead, it
+saves the generated schedule to the Taskwarrior data directory. Reuse it with `taskcheck --report
+today --dry-run` or `taskcheck --timeline 1w --dry-run`.
 
-Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most detailed view that fits the terminal width is selected: day, then week, then month. The track uses `▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules separate days, weeks, and months. Project colors are deterministic and adapt to light or dark terminals through OSC 11, with config and environment fallbacks.
+Timeline rows follow dotted project levels such as `work.client`. Without `--zoom`, the most
+detailed view that fits the terminal width is selected: day, then week, then month. The track uses
+`▶` for a start, `━` for work, `◀` for an end, and `◆` for a deadline. Thin, heavy, and double rules
+separate days, weeks, and months. Project colors are deterministic and adapt to light or dark
+terminals through OSC 11, with config and environment fallbacks.
 
 ## Reference
 

{taskcheck-1.5.1 → taskcheck-1.6.0}/taskcheck.egg-info/SOURCES.txt

@@ -2,6 +2,7 @@ LICENSE
 README.md
 pyproject.toml
 taskcheck/__main__.py
+taskcheck/agent_blocks.py
 taskcheck/common.py
 taskcheck/dry_run.py
 taskcheck/google_calendar.py
@@ -18,6 +19,8 @@ taskcheck.egg-info/dependency_links.txt
 taskcheck.egg-info/entry_points.txt
 taskcheck.egg-info/requires.txt
 taskcheck.egg-info/top_level.txt
+tests/test_agent_blocks.py
+tests/test_agent_scheduler_integration.py
 tests/test_common.py
 tests/test_google_calendar.py
 tests/test_ical.py

taskcheck-1.6.0/tests/test_agent_blocks.py

@@ -0,0 +1,196 @@
+from datetime import date, timedelta
+
+import pytest
+
+from taskcheck.agent_blocks import allocate_agent_block, get_agent_weight
+
+TODAY = date.today()
+
+
+def task(name, *, agent=False, weight=None, hours=2, urgency=10, depends=(), wait=None, daily=8):
+    record = {"uuid": name, "id": name, "estimated": "PT2H", "min_block": 2}
+    if agent:
+        record["tags"] = ["agent"]
+    if weight is not None:
+        record["agent_weight"] = weight
+    if depends:
+        record["depends"] = list(depends)
+    if wait:
+        record["wait"] = wait
+    return {"task": record, "remaining_hours": hours, "task_time_map": [daily],
+            "scheduling": {}, "started": False, "urgency": urgency}
+
+
+def run(items, order=None, block=2):
+    ordered = order or sorted(items, key=lambda name: -items[name]["urgency"])
+    return allocate_agent_block(items, ordered, 0, block, TODAY, ordered[0])
+
+
+def test_mixed_two_agents_and_short_human_tasks():
+    items = {
+        "a": task("a", agent=True, weight=25),
+        "b": task("b", agent=True, weight=35),
+        "h1": task("h1", hours=.5),
+        "h2": task("h2", hours=.5),
+    }
+    elapsed, selected = run(items, ["a", "b", "h1", "h2"])
+    assert elapsed == 2
+    assert selected == pytest.approx({"a": 2, "b": 2, "h1": .5, "h2": .3})
+    assert items["h1"]["remaining_hours"] == pytest.approx(0)
+    assert items["h2"]["remaining_hours"] == pytest.approx(.2)
+    assert all(set(info["scheduling"]) == {TODAY.isoformat()} for info in items.values())
+
+
+def test_short_agent_duration_consumes_only_actual_interaction():
+    items = {"a": task("a", agent=True, weight=25, hours=1),
+             "h": task("h", hours=2)}
+    elapsed, allocation = run(items, ["a", "h"])
+    assert elapsed == 2
+    assert allocation == pytest.approx({"a": 1, "h": 1.75})
+
+
+def test_full_weight_agent_excludes_human():
+    items = {"a": task("a", agent=True, weight=100),
+             "h": task("h", hours=2)}
+    _, selected = run(items, ["a", "h"])
+    assert selected == {"a": 2}
+    assert items["h"]["remaining_hours"] == 2
+
+
+def test_dependencies_cannot_execute_with_agent_in_same_block():
+    items = {"a": task("a", agent=True, weight=25),
+             "h": task("h", hours=1, depends=["a"]),
+             "other": task("other", hours=1)}
+    _, selected = run(items, ["a", "h", "other"])
+    assert "h" not in selected
+    assert selected["other"] == 1
+
+
+def test_waiting_agent_excluded_even_when_urgent():
+    tomorrow = (TODAY + timedelta(days=1)).strftime("%Y%m%dT%H%M%SZ")
+    items = {"a": task("a", agent=True, weight=25),
+             "b": task("b", agent=True, weight=25, wait=tomorrow),
+             "h": task("h", hours=2)}
+    _, selected = run(items, ["a", "b", "h"])
+    assert selected == pytest.approx({"a": 2, "h": 1.5})
+
+
+def test_daily_availability_limits_agent_and_human():
+    items = {"a": task("a", agent=True, weight=50, daily=.5),
+             "h": task("h", hours=2, daily=.75)}
+    elapsed, selected = run(items, ["a", "h"])
+    assert elapsed == pytest.approx(1)
+    assert selected == pytest.approx({"a": .5, "h": .75})
+
+
+def test_agent_capacity_limits_multiple_agents():
+    items = {"a": task("a", agent=True, weight=80),
+             "b": task("b", agent=True, weight=40)}
+    _, selected = run(items, ["a", "b"])
+    assert selected == pytest.approx({"a": 2, "b": 1})
+
+
+@pytest.mark.parametrize("bad", [None, -1, 101, "bad", float("nan")])
+def test_invalid_weight_is_rejected(bad):
+    t = task("a", agent=True, weight=bad)["task"]
+    with pytest.raises(ValueError, match="agent_weight"):
+        get_agent_weight(t)
+
+
+def test_non_agent_does_not_require_weight():
+    assert get_agent_weight(task("h")["task"]) is None
+
+
+def test_no_real_subblocks_appear_in_scheduling():
+    items = {"a": task("a", agent=True, weight=25), "h": task("h", hours=.5)}
+    _, _ = run(items, ["a", "h"])
+    assert items["a"]["scheduling"] == {TODAY.isoformat(): 2}
+    assert items["h"]["scheduling"] == {TODAY.isoformat(): .5}
+
+
+def test_short_lone_agent_does_not_reserve_unused_calendar_time():
+    items = {"a": task("a", agent=True, weight=25, hours=1)}
+    elapsed, selected = run(items, ["a"])
+    assert selected == {"a": 1}
+    assert elapsed == pytest.approx(1)
+
+
+def test_mixed_block_elapsed_reflects_agents_and_supervision_time():
+    items = {"a": task("a", agent=True, weight=25, hours=1),
+             "h": task("h", hours=1)}
+    elapsed, selected = run(items, ["a", "h"])
+    assert selected == pytest.approx({"a": 1, "h": 1})
+    assert elapsed == pytest.approx(1.25)
+
+
+def test_one_minute_human_task_is_valid_inside_mixed_block():
+    # min_block is a bound on *outer* chunks; it does not apply to human
+    # allocations inside a mixed block.
+    items = {"a": task("a", agent=True, weight=10, hours=2),
+             "h": task("h", hours=1 / 60)}
+    elapsed, selected = run(items, ["a", "h"])
+    assert elapsed == pytest.approx(2)
+    assert selected["h"] == pytest.approx(1 / 60)
+    assert items["h"]["remaining_hours"] == pytest.approx(0)
+
+
+def test_one_minute_agent_can_anchor_mixed_block():
+    items = {"a": task("a", agent=True, weight=10, hours=1 / 60),
+             "h": task("h", hours=.5)}
+    elapsed, selected = run(items, ["a", "h"])
+    assert selected == pytest.approx({"a": 1 / 60, "h": .5})
+    assert elapsed == pytest.approx(.5 + 1 / 600)
+
+
+def test_cached_time_map_is_not_mutated_across_tasks():
+    # get_long_range_time_map caches its list by name in the upstream module.
+    # An independent per-task daily cap is required: a task's execution must
+    # not eat another task's cap just because they share the same profile.
+    items = {"a": task("a", agent=True, weight=10, hours=1),
+             "h": task("h", hours=.5)}
+    original_shared_map = [2.0]
+    items["a"]["task_time_map"] = original_shared_map
+    items["h"]["task_time_map"] = original_shared_map
+    elapsed, selected = run(items, ["a", "h"])
+    assert selected == pytest.approx({"a": 1, "h": .5})
+    assert elapsed == pytest.approx(1)
+    assert items["a"]["task_time_map"] == pytest.approx([1])
+    assert items["h"]["task_time_map"] == pytest.approx([1.5])
+    assert original_shared_map == [2.0]
+
+
+def test_many_mixed_blocks_respect_elapsed_and_human_budget():
+    import random
+    rng = random.Random(765421)
+    for _ in range(500):
+        weights = [rng.uniform(0, 100) for _ in range(rng.randint(1, 6))]
+        items = {
+            f"a{i}": task(f"a{i}", agent=True, weight=w,
+                         hours=rng.uniform(.01, 4), daily=rng.uniform(.1, 3))
+            for i, w in enumerate(weights)
+        }
+        for j in range(rng.randint(0, 5)):
+            items[f"h{j}"] = task(f"h{j}", hours=rng.uniform(.01, 4),
+                                 daily=rng.uniform(.1, 3))
+        originals = {name: data['remaining_hours'] for name, data in items.items()}
+        elapsed, selected = run(items, list(items))
+        assert 0 < elapsed <= 2 + 1e-8
+        interaction = sum(selected.get(name, 0) * (get_agent_weight(info['task']) or 0)
+                          if 'agent' in info['task'].get('tags', [])
+                          else selected.get(name, 0)
+                          for name, info in items.items())
+        assert interaction <= elapsed + 1e-8
+        for name, allocated in selected.items():
+            assert allocated <= originals[name] + 1e-8
+            assert items[name]['remaining_hours'] >= -1e-8
+            if get_agent_weight(items[name]['task']) is not None:
+                assert allocated <= elapsed + 1e-8
+
+
+def test_human_custom_chunk_limit_is_respected_inside_mixed_block():
+    items = {"a": task("a", agent=True, weight=10, hours=2),
+             "h": task("h", hours=3)}
+    items['h']['task']['min_block'] = 0.3  # Original hh.mm convention: 30 minutes.
+    elapsed, selected = run(items, ['a', 'h'])
+    assert elapsed == pytest.approx(2)
+    assert selected['h'] == pytest.approx(.5)

taskcheck-1.6.0/tests/test_agent_scheduler_integration.py

@@ -0,0 +1,153 @@
+"""Integration coverage against taskcheck.parallel's day-allocation loop."""
+from datetime import datetime, timedelta
+
+import pytest
+
+from taskcheck.parallel import UrgencyCoefficients, allocate_time_for_day
+
+
+COEFFS = UrgencyCoefficients({"PT2H": 0}, False, 0, 365, 0, 0)
+
+
+def info(name, *, hours=2, urgency=10, agent=False, weight=None, depends=()):
+    t = {"uuid": name, "id": name, "description": name,
+         "estimated": "PT2H", "min_block": 2}
+    if agent:
+        t["tags"] = ["agent"]
+        t["agent_weight"] = weight
+    if depends:
+        t["depends"] = list(depends)
+    return {"task": t, "remaining_hours": hours,
+            "task_time_map": [2.0, 2.0], "today_used_hours": 0,
+            "scheduling": {}, "urgency": urgency,
+            "estimated_urgency": 0, "age_urgency": 0, "due_urgency": 0,
+            "started": False}
+
+
+def schedule(tasks, monkeypatch):
+    monkeypatch.setattr('taskcheck.parallel.recompute_urgencies', lambda *args, **kwargs: None)
+    allocate_time_for_day(tasks, 1, COEFFS, False, 1)
+    return (datetime.today().date() + timedelta(days=1)).isoformat()
+
+
+def test_mixed_allocation_inside_one_calendar_block(monkeypatch):
+    tasks = {"a": info("a", agent=True, weight=25),
+             "b": info("b", agent=True, weight=35, urgency=9),
+             "h": info("h", hours=.8, urgency=8)}
+    day = schedule(tasks, monkeypatch)
+    assert tasks["a"]["scheduling"] == {day: 2}
+    assert tasks["b"]["scheduling"] == {day: 2}
+    assert tasks["h"]["scheduling"] == pytest.approx({day: .8})
+
+
+def test_more_urgent_human_keeps_exclusive_block(monkeypatch):
+    tasks = {"h": info("h", urgency=20),
+             "a": info("a", agent=True, weight=25, urgency=10)}
+    day = schedule(tasks, monkeypatch)
+    assert tasks["h"]["scheduling"] == {day: 2}
+    assert tasks["a"]["scheduling"] == {}
+
+
+def test_dependencies_wait_for_next_block(monkeypatch):
+    tasks = {"a": info("a", agent=True, weight=25, urgency=20),
+             "dependent": info("dependent", hours=.5, urgency=18, depends=("a",)),
+             "h": info("h", hours=.5, urgency=15)}
+    day = schedule(tasks, monkeypatch)
+    assert tasks["dependent"]["scheduling"] == {}
+    assert tasks["h"]["scheduling"] == {day: .5}
+
+
+def test_five_hour_agent_ten_percent_occupies_two_and_half_blocks(monkeypatch):
+    # estimated:5h = execution time, NOT supervision time.
+    monkeypatch.setattr('taskcheck.parallel.recompute_urgencies', lambda *args, **kwargs: None)
+    agent = info('a', hours=5, agent=True, weight=10)
+    agent['task']['estimated'] = 'PT5H'
+    agent['task_time_map'] = [2.0, 2.0, 2.0, 2.0]
+    allocated_days = []
+    for offset in range(1, 4):
+        allocate_time_for_day({'a': agent}, offset, COEFFS, False, 1)
+        day = (datetime.today().date() + timedelta(days=offset)).isoformat()
+        allocated_days.append(agent['scheduling'].get(day, 0))
+    assert allocated_days == pytest.approx([2, 2, 1])
+    assert sum(allocated_days) == pytest.approx(5)
+    assert sum(allocated_days) * .10 == pytest.approx(.5)
+    assert agent['remaining_hours'] == pytest.approx(0)
+
+
+def test_five_hour_agent_and_four_hour_human_fit_in_five_calendar_hours(monkeypatch):
+    """Regression: estimates are agent wall-time, NOT supervision time."""
+    monkeypatch.setattr('taskcheck.parallel.recompute_urgencies', lambda *args, **kwargs: None)
+    a = info('a', hours=5, agent=True, weight=10, urgency=20)
+    a['task']['estimated'] = 'PT5H'
+    h = info('h', hours=4, urgency=10)
+    for item in (a, h):
+        item['task_time_map'] = [0, 5]
+    task_info = {'a': a, 'h': h}
+    allocate_time_for_day(task_info, 1, COEFFS, False, 1)
+    day = (datetime.today().date() + timedelta(days=1)).isoformat()
+    assert a['scheduling'][day] == pytest.approx(5)
+    assert h['scheduling'][day] == pytest.approx(4)
+    assert a['remaining_hours'] == pytest.approx(0)
+    assert h['remaining_hours'] == pytest.approx(0)
+    # 5h elapsed, with 5h*10%=0.5h supervision + 4h independent work.
+    assert a['scheduling'][day] * .10 + h['scheduling'][day] == pytest.approx(4.5)
+
+
+def test_initialize_task_info_does_not_share_cached_availability(monkeypatch):
+    from taskcheck.parallel import initialize_task_info
+    shared = [3., 3.]
+    monkeypatch.setattr('taskcheck.parallel.get_long_range_time_map',
+                        lambda *args: (shared, 0))
+    tasks = [
+        {'id': 1, 'uuid': 'a', 'estimated': 'PT2H', 'time_map': 'work',
+         'tags': ['agent'], 'agent_weight': 25},
+        {'id': 2, 'uuid': 'h', 'estimated': 'PT2H', 'time_map': 'work'},
+    ]
+    states = initialize_task_info(tasks, {}, 2, COEFFS, [])
+    assert states['a']['task_time_map'] is not states['h']['task_time_map']
+    assert states['a']['task_time_map'] is not shared
+    states['a']['task_time_map'][0] -= 2
+    assert states['h']['task_time_map'] == [3., 3.]
+    assert shared == [3., 3.]
+
+
+def test_initialize_task_info_rejects_missing_agent_weight(monkeypatch):
+    from taskcheck.parallel import initialize_task_info
+    tasks = [{'id': 1, 'uuid': 'a', 'estimated': 'PT2H',
+              'time_map': 'work', 'tags': ['agent']}]
+    with pytest.raises(ValueError, match='agent_weight'):
+        initialize_task_info(tasks, {}, 2, COEFFS, [])
+
+
+def test_availability_cache_is_scoped_to_horizon_and_time_map():
+    """A new schedule must not inherit a stale cached horizon or work profile."""
+    from taskcheck.common import get_long_range_time_map, long_range_time_map
+    long_range_time_map.clear()
+    work = {day: [[9, 17]] for day in
+            ('monday', 'tuesday', 'wednesday', 'thursday', 'friday',
+             'saturday', 'sunday')}
+    try:
+        short, _ = get_long_range_time_map({'work': work}, ['work'], 2, [])
+        long, _ = get_long_range_time_map({'work': work}, ['work'], 3, [])
+        assert len(short) == 2
+        assert len(long) == 3
+        shorter_hours = {day: [[9, 12]] for day in work}
+        changed, _ = get_long_range_time_map(
+            {'work': shorter_hours}, ['work'], 3, [])
+        assert changed == [3., 3., 3.]
+    finally:
+        long_range_time_map.clear()
+
+
+def test_install_registers_agent_weight_uda(monkeypatch):
+    from taskcheck import install as install_module
+    from unittest.mock import Mock
+    apply = Mock()
+    monkeypatch.setattr(install_module, 'apply_config', apply)
+    answers = iter(('yes', 'no', 'no'))
+    monkeypatch.setattr('builtins.input', lambda *args: next(answers))
+    install_module.install()
+    applied = [call.args for call in apply.call_args_list]
+    assert ('uda.agent_weight.type', 'numeric') in applied
+    assert ('uda.agent_weight.label', 'Agent Weight (%)') in applied
+    assert ('uda.agent_weight.default', '25') in applied

{taskcheck-1.5.1 → taskcheck-1.6.0}/tests/test_main.py

@@ -101,6 +101,9 @@ class TestArgumentParsing:
         args = arg_parser.parse_args(["--dry-run"])
         assert args.dry_run is True
 
+        args = arg_parser.parse_args(["-d"])
+        assert args.dry_run is True
+
         args = arg_parser.parse_args([])
         assert args.dry_run is False